简介这是一份面向刚接触PyQt5与YOLO算法的初学者的PyQt5YOLOv5多目标检测GUI项目包解决从算法到界面落地的困惑适合希望用现成项目练手、快速体验完整开发流程的人。压缩包共112个文件、约83.46MB主要包含Python源码、YAML模型配置、PyTorch预训练权重、UI界面文件、测试图片与视频、Dockerfile等分别对应逻辑实现、参数调整、模型加载、界面布局和运行环境结构清晰便于按需取用。项目重点演示界面设计与后端逻辑分离沿PyQt5常见控件的交互逻辑展开可学到从按键事件、文件选择到推理结果展示的完整链路同时提供GIF和截图预览方便对照效果排查问题。其中YOLOv5算法源码可直接阅读帮助初学者理解检测模型如何被GUI调用。目前已有8875人浏览学习适合想通过完整项目快速入门的开发者。1. pyqt5yolov5python 组合从「能跑」到「能交付」差在哪把 PyQt5、YOLOv5 和 Python 三个词拼到一起很多人第一反应是目标检测套个 GUI 壳而已。真上手你会发现命令行里跑得飞起的 YOLOv5 一进 PyQt5 界面就卡成幻灯片摄像头能开但一点检测就白屏模型明明在 GPU 上显存却只涨不降。这些都不是哪行代码写错而是 Python 桌面应用和深度学习推理在架构上先天冲突。这篇笔记专注解决一件事怎么用 PyQt5 把 YOLOv5 包成一个能交付的桌面检测工具——推理放后台线程、界面实时刷新、置信度和 IOU 随手可调、运行中能换权重、结果能落盘。适合要给检测算法做演示工具、内部标注辅助或现场小工具的开发者也特别适合被「界面卡死」和「摄像头黑屏」折腾过的新手照着思路走能少走不少弯路。2. 环境选型与整体架构PyQt5 和 YOLOv5 怎么搭才不互相打架2.1 版本组合与 Python 解释器选择PyQt5 对 Python 版本的宽容度其实很高真正卡脖子的是 torch 那一侧。我一般会把基准环境定在 Python 3.8 或 3.9YOLOv5 在这两个版本上被验证得最充分torch 的预编译 wheel 覆盖也最全。3.10 甚至 3.11 也能跑但某些依赖 CUDA 的 torch 版本会缺对应轮子装完经常被静默降级成 CPU 版推理速度差出一个数量级。这里的血泪经验只有一条别追新追「被验证过的组合」。组件推荐版本选型理由Python3.8 / 3.9torch 预编译包覆盖最全YOLOv5 兼容性验证最充分PyQt55.15.xAPI 稳定QThread 与信号槽行为成熟资料最多torch torchvision与 CUDA 匹配的官方稳定版先用 CPU 版跑通流程再换 GPU 版验证加速opencv-python4.x摄像头读取、画框、颜色转换一条龙numpy1.x避开 numpy 2.x 与旧版 torch 的 ABI 兼容问题选完版本还有一个容易忽略的点PyQt5 的 wheel 自带 Qt 运行库不需要单独再装 Qt但 OpenCV 的 GUI 窗口和 Qt 的事件循环在某些 Linux 发行版上会互相抢占所以做桌面工具时我从不调用 cv2.imshow所有画面都走 Qt 的 QLabel 显示这一点在后面的代码里会贯彻到底。另外提醒一句torch 版本和 CUDA 驱动不匹配时torch.cuda.is_available() 会静默返回 False这不是代码问题是环境问题。装完第一时间验证比 debug 三天再回头查环境划算得多。2.2 最小依赖安装与三个验证命令搭建环境的最小命令就两条不用折腾虚拟环境以外的额外配置pip install pyqt5 opencv-python numpy pip install torch torchvision装完后我习惯用三条命令做冒烟验证确认 PyQt5 的版本、OpenCV 和 torch 是否真的可用python -c from PyQt5.QtCore import PY_VERSION; print(PyQt5, PY_VERSION) python -c import cv2; print(opencv, cv2.__version__) python -c import torch; print(torch, torch.__version__); print(cuda, torch.cuda.is_available())第一条验证 PyQt5 能正常 import输出类似 5.15 的版本字符串第二条确认 OpenCV 安装成功第三条最关键cuda 项返回 True 才说明 GPU 版装对了返回 False 就回头查 CUDA 驱动和 torch 版本的匹配关系别急着往下写代码。验证的逻辑是GUI 组件、图像处理、深度学习推理三块基础都通了再开始搭界面否则后面排错时根本分不清是哪一个环节挂了。2.3 架构为什么 detect.py 不能直接塞进界面YOLOv5 官方脚本 detect.py 的定位是命令行批处理它的执行模型是「读一帧、推理、写结果、循环」全程占用当前进程。Qt 桌面程序恰恰相反主线程必须不停处理窗口事件一旦把 detect.py 的逻辑原样塞进去推理耗时直接卡住事件循环界面立刻无响应。更隐蔽的是 GIL 的存在即使你把推理丢到 Python 线程里密集计算仍然会抢占 GIL主线程照样喘不过气。常见做法是两层拆分界面线程只管事件和绘图工作线程负责摄像头读取、推理和画框两线程之间用信号槽传递已经画好的 QImage。推理和画框都放在工作线程里主线程只做一次 QPixmap 赋值把主线程的工作量压到最低。这样做的另一个好处是摄像头读取的阻塞也隔离了——cv2.VideoCapture.read() 在设备异常时会卡住几百毫秒放主线程里就是一次肉眼可见的掉帧。帧率高起来之后信号槽队列会积压旧帧。我一般会让工作线程在有新帧产生时主动丢弃还没处理的中间帧保证界面永远显示最新一帧而不是排队消费旧帧这样视频流延迟可以压在一帧以内。架构定下来之后顺序就清晰了先写可复用的检测工作线程再写界面最后处理切换模型和导出。下一章先把工作线程写出来这是整个工具的地基。3. 把 YOLOv5 封装成线程安全的检测服务QThread 与信号槽3.1 用 QThread 起一个常驻推理线程很多教程教你用 QThread 配合 moveToThread但对检测工具这种「一个线程长期跑循环」的场景直接继承 QThread 重写 run() 更直观坑也更少。下面是工作线程的完整骨架# worker.py推理工作线程 import cv2 import torch from PyQt5.QtCore import QThread, pyqtSignal from PyQt5.QtGui import QImage class DetectWorker(QThread): frame_ready pyqtSignal(object) # 已画框的 QImage交给界面刷新 log pyqtSignal(str) # 日志文本 fps_changed pyqtSignal(float) # 实时帧率 def __init__(self, model, capture, conf0.25, iou0.45): super().__init__() self.model model # 已加载的 YOLOv5 模型 self.capture capture # 已打开的 cv2.VideoCapture self.conf conf # 置信度阈值0.25 是 YOLOv5 默认值 self.iou iou # NMS 的 IOU 阈值 self._running True self._frame_skip 0 # 每隔 N 帧推理一次0 表示每帧都推理 self._skip 0 def run(self): # 线程入口。不要直接调用 run()用 start() 启动 while self._running: ret, frame self.capture.read() if not ret: self.log.emit(输入源读取失败线程退出) break self._skip 1 if self._skip % (self._frame_skip 1) ! 0: continue t0 cv2.getTickCount() with torch.no_grad(): # 关闭梯度防止显存累积 results self.model(frame, size640) # 推理 NMS annotated self._draw(frame, results) # 在 numpy 帧上画框 self.frame_ready.emit(self._to_qimage(annotated)) dt (cv2.getTickCount() - t0) / cv2.getTickFrequency() self.fps_changed.emit(1.0 / dt) def stop(self): self._running False self.wait(3000) # 最多等 3 秒避免杀线程导致资源没释放 def set_conf(self, value): self.conf value # 界面滑杆直接改这个属性下一帧生效几个关键点要解释清楚。第一pyqtSignal 的跨线程发射是安全的工作线程里 emit 后主线程的槽函数会在事件循环里被执行不需要自己加锁第二model(frame) 默认走 YOLOv5 内部的预处理和 NMS返回的 Results 对象里 xyxy[0] 是形状为 (N, 6) 的张量六列分别是 x1、y1、x2、y2、置信度、类别第三stop() 用标志位配合 wait()不要用 terminate()否则摄像头资源可能来不及释放。这里的 _frame_skip 参数是给低配机器留的后门检测耗时 200ms 而界面只要 30fps 时每 3 帧推理一次就能把画面流畅度拉回来代价是检测结果有最多 2 帧的延迟。模型推理用 torch.no_grad() 包住是防止显存只涨不降的关键后面避坑章节还会再展开。3.2 输入源统一图片、视频文件、摄像头界面要给用户三种选择单张图片、视频文件、摄像头。视频和摄像头都是连续帧区别只在打开方式图片则要包装成「只吐一帧的输入源」让工作线程不用区分。我一般用一个小函数做统一入口def open_source(source_type, source_path): # source_type: image / video / camera if source_type camera: cap cv2.VideoCapture(int(source_path)) # 0 是默认摄像头 else: cap cv2.VideoCapture(source_path) if not cap.isOpened(): raise RuntimeError(无法打开输入源: %s % source_path) if source_type image: ret, frame cap.read() cap.release() if not ret: raise RuntimeError(图片读取失败) return SingleFrameSource(frame) return capvideo 和 camera 共用同一套读取循环camera 的 source_path 传摄像头索引默认 0 就是笔记本内置摄像头。SingleFrameSource 是十几行的包装类内部存住那帧图片read() 第一轮返回它之后返回 (False, None)接口和 cv2.VideoCapture 对齐工作线程里不用区分。这样 run() 里不用写三套分支后续想加网络流输入也只要在 open_source 里多接一个分支就行。打开输入源后建议顺手把分辨率设到合理值。我用 cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280) 和 cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 720) 强制设置因为部分摄像头默认输出 640 宽检测小目标时框都画不准。3.3 画框与 QImage 转换别踩 BGR 的坑YOLOv5 的推理结果画框要在 numpy 帧上做因为工作线程拿到的是 cv2 的 BGR 帧而 Qt 显示需要的是 RGB。转换顺序错了框和文字的位置也会跟着错位这是新手最容易翻车的地方def _draw(self, frame, results): names self.model.names for det in results.xyxy[0].tolist(): x1, y1, x2, y2, conf, cls det x1, y1, x2, y2 map(int, (x1, y1, x2, y2)) label %s %.2f % (names[int(cls)], conf) cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(frame, label, (x1, max(0, y1 - 8)), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2) return frame def _to_qimage(self, bgr_frame): rgb cv2.cvtColor(bgr_frame, cv2.COLOR_BGR2RGB) h, w, ch rgb.shape qimg QImage(rgb.data, w, h, ch * w, QImage.Format_RGB888) return qimg.copy() # 必须 copy否则 numpy 内存失效后画面花掉results.xyxy[0].tolist() 把张量落回 Python 列表避免在 torch 张量上反复做索引坐标转成 int 是因为 cv2.rectangle 不接收浮点坐标。QImage 构造的第三个参数是每行字节数BGR 转 RGB 后每像素 3 字节所以是 ch*w最后一个坑是 copy()QImage 只持有原始数据的指针不拷贝数据如果 numpy 数组被回收再分配界面上的图就会花掉。实测里九成的「画面闪烁变花」都是这里漏了 copy()。4. PyQt5 界面交互落地实时预览、参数调节与模型热切换4.1 界面骨架预览区、控制区、日志区界面我习惯用三段式顶部是图像预览区中间是控制条底部是日志区。预览区用 QLabel 放大显示 QPixmap控制条放启动/停止按钮和置信度、IOU 滑杆日志区用 QPlainTextEdit 接收工作线程的日志信号。这样布局的好处是摄像头画面不动时操作区和日志区不遮挡现场演示时信息密度刚好。class MainWindow(QMainWindow): def __init__(self, worker): super().__init__() self.worker worker self.preview QLabel(等待输入源) self.preview.setMinimumSize(960, 540) self.preview.setAlignment(Qt.AlignCenter) self.preview.setStyleSheet(background:#1e1e1e;color:#aaa;) self.btn_start QPushButton(开始) self.btn_stop QPushButton(停止) self.slider_conf QSlider(Qt.Horizontal) self.slider_conf.setRange(1, 99) self.slider_conf.setValue(25) self.label_conf QLabel(置信度 0.25) self.log_view QPlainTextEdit() self.log_view.setReadOnly(True) control QHBoxLayout() control.addWidget(self.btn_start) control.addWidget(self.btn_stop) control.addWidget(self.label_conf) control.addWidget(self.slider_conf) layout QVBoxLayout() layout.addWidget(self.preview) layout.addLayout(control) layout.addWidget(self.log_view, stretch1) container QWidget() container.setLayout(layout) self.setCentralWidget(container)滑杆的值域设成 1 到 99 而不是 0 到 1是因为 QSlider 只接受整数在主线程里做百分比的整数运算也最干净后面再除以 100 还原成浮点阈值。日志区放在 QPlainTextEdit 里用 appendPlainText 接收比 QTextEdit 更省内存长时间跑视频不会越来越卡。4.2 信号槽联动让置信度、IOU 实时生效工作线程的属性在设计上就允许被外部改滑杆只要在 valueChanged 信号里更新 worker.conf 即可下一帧推理就会用新阈值不需要重启线程。这个「热改参数」的实现成本几乎为零但对交付体验的提升非常明显——现场调阈值不用改代码重跑。self.btn_start.clicked.connect(self.worker.start) self.btn_stop.clicked.connect(self.worker.stop) self.slider_conf.valueChanged.connect(self._on_conf_changed) self.worker.frame_ready.connect(self._show_frame) self.worker.log.connect(self.log_view.appendPlainText) self.worker.fps_changed.connect(self._update_fps) def _on_conf_changed(self, value): conf value / 100.0 self.worker.conf conf self.label_conf.setText(置信度 %.2f % conf) def _show_frame(self, qimg): self.preview.setPixmap(QPixmap.fromImage(qimg)) def _update_fps(self, fps): self.setWindowTitle(检测工具 - %.1f FPS % fps)这里有个细节改的是 worker.conf但推理循环里每帧都读取这个属性所以属性赋值发生在任意时刻都能在下一帧生效不用加锁。IOU 滑杆的接线方式完全一样只是把目标属性换成 worker.iou。fps_changed 信号直接写进窗口标题实测比在界面上放一个只读文本框更直观还不占布局空间。4.3 运行中热切换模型权重现场可能要在通用模型和专用模型之间切换比如先跑通用检测再看某类目标的细粒度模型。直接在推理循环里换 model 引用是危险操作——工作线程正在用旧模型推理时你把属性换掉轻则报张量维度错误重则直接崩溃。安全做法是先停线程换模型清显存再启线程。def load_det_model(weights_path, devicecpu): # 加载 YOLOv5 .pt 权重device 传 cuda:0 可切 GPU import sys sys.path.append(yolov5) # 改成你本地 YOLOv5 源码目录 from models.experimental import attempt_load model attempt_load(weights_path, map_locationdevice) model.eval() return model def reload_model(self, weights_path): self.worker.stop() # 1. 先停推理线程 old_model self.worker.model self.worker.model load_det_model(weights_path) # 2. 换新权重 del old_model # 3. 释放旧模型 if torch.cuda.is_available(): torch.cuda.empty_cache() # 4. 清空显存缓存 self.worker.start() # 5. 重新启动不要为了省事新建一个 QThread 实例替换旧的新线程要重新连接所有信号摄像头也要重新打开中间任何一步遗漏都会变成诡异的偶发问题。保留同一个工作线程实例只换内部的 model 引用信号连接全部原样保留是最稳的路径。加载完记得 model.eval() 关掉 dropout 和 batchnorm 的训练态否则推理结果会整体偏移。5. 避坑手册PyQt5 跑 YOLOv5 的 5 个高频翻车现场5.1 界面卡成幻灯片点哪都没反应现象启动检测后窗口标题一直转圈移动鼠标都卡顿甚至弹出「程序未响应」。原因最常见的是推理或 cv2.VideoCapture.read() 被放在了主线程。detect.py 的循环体原样搬进界面代码主线程被推理阻塞Qt 的事件循环得不到执行机会。解决把读取、推理、画框全部搬进 QThread 的 run() 循环主线程只接收 frame_ready 信号做 QPixmap 赋值。如果画面还是卡优先检查是不是在 _show_frame 里做了耗时操作比如把 QImage 转 numpy——这个转换应该放在工作线程完成。5.2 摄像头能打开但画面全黑或者偶发花屏现象cv2.VideoCapture(0) 返回 True但 read() 出来的帧全黑换一个摄像头索引又报错。原因Windows 上默认的视频后端对部分摄像头驱动兼容性差另一个常见原因是笔记本有多个摄像头前置、USB 外接索引 0 不是你以为的那个设备。解决Windows 下显式指定 DirectShow 后端打开后打印分辨率确认。代码上就是 open_source 里 camera 分支改成 cv2.VideoCapture(int(source_path), cv2.CAP_DSHOW)黑屏还在就用系统设备管理器确认摄像头索引或者把 source_path 开放给用户在界面上输入。分辨率问题用 cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280) 强制设置。5.3 显存只涨不降跑十分钟后 CUDA out of memory现象GPU 显存占用随时间缓慢上涨最终推理报 CUDA out of memory。原因推理循环里没有把计算包在 torch.no_grad() 里autograd 图每帧累积另一种是热切换模型后没有释放旧模型引用旧权重一直占着显存。解决推理循环里用 with torch.no_grad(): 包住 model(frame)这是根治手段热切换模型按 4.3 的顺序先 del 旧模型再 empty_cache。注意 torch.cuda.empty_cache() 不是银弹它只释放缓存块真正的泄漏要靠 no_grad 解决。如果还在涨把 _frame_skip 打开缩短每帧张量的生命周期。5.4 PyInstaller 打包后体积巨大换机器提示缺 DLL现象打包出的 exe 将近 1GB换到一台没有 Python 的机器双击运行提示找不到 cudnn64_8.dll 或 Qt 平台插件。原因torch 全家桶和 CUDA 运行库被打进了包PyInstaller 对动态加载的部分依赖识别不全Qt 的 platform 插件也没有被完整收进去。解决用 PyInstaller 时明确收集 torch、torchvision、PyQt5 全部子模块同时排除用不到的 CUDA 能力。体积控制在 600MB 到 900MB 是常态别指望它变小更省事的做法是交付时带一个虚拟环境目录加启动脚本而不是单文件 exe。单文件模式启动时要解压到临时目录检测工具这种长驻程序不建议用 --onefile。5.5 界面画面颜色发蓝发红检测框和画面错位现象预览区的图像像老式相机偏色或者框的位置和实际物体对不上。原因cv2 读进来是 BGRQImage.Format_RGB888 期望 RGB没做 cvtColor 就把 BGR 数据直接送进 QImage错位则是 QImage 的 bytesPerLine 参数写错比如用了错误的通道数。解决严格按 3.3 的顺序先 cvtColor 再构造 QImagebytesPerLine 传 ch * w。BGR 和 RGB 的混用是 OpenCV 生态里最反复出现的低级错误排查时先打印一下帧的第一个像素值再对照 QImage 里同样位置的像素正常时三通道分量应该一致。6. 结果导出与长时间压测交付前最后两个动作界面能跑、参数能调离「能交付」还差两步结果要能落盘稳定性要经得起长时间跑。结果导出我用 JSON检测记录带时间戳、类别、置信度、坐标后续无论是做统计还是接其他系统都方便import json, time def export_frame_result(results, names, save_path): items [] for det in results.xyxy[0].tolist(): items.append({ time: time.time(), class: names[int(det[5])], conf: round(det[4], 3), box: [round(v, 1) for v in det[:4]], }) with open(save_path, a, encodingutf-8) as f: f.write(json.dumps(items, ensure_asciiFalse) \n)追加写入而不是覆盖写入是因为长时间检测会产生大量记录断点续跑不至于丢数据每帧都写一次文件会拖慢工作线程我一般用队列把导出任务丢给后台累积批量写或者攒 10 帧写一次。压测的验证方法也很固定拿一段 10 分钟、目标出现密集的视频文件跑一遍不碰摄像头和界面操作只看三个指标——FPS 平均值、显存占用曲线、界面是否卡顿。FPS 平均值别用前 5 秒的数据torch 的 cuDNN 自动调优会让前十几帧慢不少等预热 30 秒后再统计更准确。显存曲线我一般直接盯任务管理器如果从 2GB 慢慢涨到 4GB说明还有引用没释放回 5.3 排查。界面卡顿只要出现一次就说明主线程被不该有的耗时操作侵入了回头查所有信号槽槽函数里有没有做图像转换。最后说一个我自己的习惯检测工具交付前一定在目标机器上用真机跑三分钟开机自检重点确认冷启动时模型加载不超时、摄像头热插拔不崩、关窗时线程能干净退出——这三个场景用模拟器测不出来。界面代码少用奇技淫巧多留日志出口现场出了问题靠日志定位比靠猜快十倍。希望帮到你。本文还有配套的精品资源点击获取
简介这是一份面向刚接触PyQt5与YOLO算法的初学者的PyQt5YOLOv5多目标检测GUI项目包解决从算法到界面落地的困惑适合希望用现成项目练手、快速体验完整开发流程的人。压缩包共112个文件、约83.46MB主要包含Python源码、YAML模型配置、PyTorch预训练权重、UI界面文件、测试图片与视频、Dockerfile等分别对应逻辑实现、参数调整、模型加载、界面布局和运行环境结构清晰便于按需取用。项目重点演示界面设计与后端逻辑分离沿PyQt5常见控件的交互逻辑展开可学到从按键事件、文件选择到推理结果展示的完整链路同时提供GIF和截图预览方便对照效果排查问题。其中YOLOv5算法源码可直接阅读帮助初学者理解检测模型如何被GUI调用。目前已有8875人浏览学习适合想通过完整项目快速入门的开发者。1. pyqt5yolov5python 组合从「能跑」到「能交付」差在哪把 PyQt5、YOLOv5 和 Python 三个词拼到一起很多人第一反应是目标检测套个 GUI 壳而已。真上手你会发现命令行里跑得飞起的 YOLOv5 一进 PyQt5 界面就卡成幻灯片摄像头能开但一点检测就白屏模型明明在 GPU 上显存却只涨不降。这些都不是哪行代码写错而是 Python 桌面应用和深度学习推理在架构上先天冲突。这篇笔记专注解决一件事怎么用 PyQt5 把 YOLOv5 包成一个能交付的桌面检测工具——推理放后台线程、界面实时刷新、置信度和 IOU 随手可调、运行中能换权重、结果能落盘。适合要给检测算法做演示工具、内部标注辅助或现场小工具的开发者也特别适合被「界面卡死」和「摄像头黑屏」折腾过的新手照着思路走能少走不少弯路。2. 环境选型与整体架构PyQt5 和 YOLOv5 怎么搭才不互相打架2.1 版本组合与 Python 解释器选择PyQt5 对 Python 版本的宽容度其实很高真正卡脖子的是 torch 那一侧。我一般会把基准环境定在 Python 3.8 或 3.9YOLOv5 在这两个版本上被验证得最充分torch 的预编译 wheel 覆盖也最全。3.10 甚至 3.11 也能跑但某些依赖 CUDA 的 torch 版本会缺对应轮子装完经常被静默降级成 CPU 版推理速度差出一个数量级。这里的血泪经验只有一条别追新追「被验证过的组合」。组件推荐版本选型理由Python3.8 / 3.9torch 预编译包覆盖最全YOLOv5 兼容性验证最充分PyQt55.15.xAPI 稳定QThread 与信号槽行为成熟资料最多torch torchvision与 CUDA 匹配的官方稳定版先用 CPU 版跑通流程再换 GPU 版验证加速opencv-python4.x摄像头读取、画框、颜色转换一条龙numpy1.x避开 numpy 2.x 与旧版 torch 的 ABI 兼容问题选完版本还有一个容易忽略的点PyQt5 的 wheel 自带 Qt 运行库不需要单独再装 Qt但 OpenCV 的 GUI 窗口和 Qt 的事件循环在某些 Linux 发行版上会互相抢占所以做桌面工具时我从不调用 cv2.imshow所有画面都走 Qt 的 QLabel 显示这一点在后面的代码里会贯彻到底。另外提醒一句torch 版本和 CUDA 驱动不匹配时torch.cuda.is_available() 会静默返回 False这不是代码问题是环境问题。装完第一时间验证比 debug 三天再回头查环境划算得多。2.2 最小依赖安装与三个验证命令搭建环境的最小命令就两条不用折腾虚拟环境以外的额外配置pip install pyqt5 opencv-python numpy pip install torch torchvision装完后我习惯用三条命令做冒烟验证确认 PyQt5 的版本、OpenCV 和 torch 是否真的可用python -c from PyQt5.QtCore import PY_VERSION; print(PyQt5, PY_VERSION) python -c import cv2; print(opencv, cv2.__version__) python -c import torch; print(torch, torch.__version__); print(cuda, torch.cuda.is_available())第一条验证 PyQt5 能正常 import输出类似 5.15 的版本字符串第二条确认 OpenCV 安装成功第三条最关键cuda 项返回 True 才说明 GPU 版装对了返回 False 就回头查 CUDA 驱动和 torch 版本的匹配关系别急着往下写代码。验证的逻辑是GUI 组件、图像处理、深度学习推理三块基础都通了再开始搭界面否则后面排错时根本分不清是哪一个环节挂了。2.3 架构为什么 detect.py 不能直接塞进界面YOLOv5 官方脚本 detect.py 的定位是命令行批处理它的执行模型是「读一帧、推理、写结果、循环」全程占用当前进程。Qt 桌面程序恰恰相反主线程必须不停处理窗口事件一旦把 detect.py 的逻辑原样塞进去推理耗时直接卡住事件循环界面立刻无响应。更隐蔽的是 GIL 的存在即使你把推理丢到 Python 线程里密集计算仍然会抢占 GIL主线程照样喘不过气。常见做法是两层拆分界面线程只管事件和绘图工作线程负责摄像头读取、推理和画框两线程之间用信号槽传递已经画好的 QImage。推理和画框都放在工作线程里主线程只做一次 QPixmap 赋值把主线程的工作量压到最低。这样做的另一个好处是摄像头读取的阻塞也隔离了——cv2.VideoCapture.read() 在设备异常时会卡住几百毫秒放主线程里就是一次肉眼可见的掉帧。帧率高起来之后信号槽队列会积压旧帧。我一般会让工作线程在有新帧产生时主动丢弃还没处理的中间帧保证界面永远显示最新一帧而不是排队消费旧帧这样视频流延迟可以压在一帧以内。架构定下来之后顺序就清晰了先写可复用的检测工作线程再写界面最后处理切换模型和导出。下一章先把工作线程写出来这是整个工具的地基。3. 把 YOLOv5 封装成线程安全的检测服务QThread 与信号槽3.1 用 QThread 起一个常驻推理线程很多教程教你用 QThread 配合 moveToThread但对检测工具这种「一个线程长期跑循环」的场景直接继承 QThread 重写 run() 更直观坑也更少。下面是工作线程的完整骨架# worker.py推理工作线程 import cv2 import torch from PyQt5.QtCore import QThread, pyqtSignal from PyQt5.QtGui import QImage class DetectWorker(QThread): frame_ready pyqtSignal(object) # 已画框的 QImage交给界面刷新 log pyqtSignal(str) # 日志文本 fps_changed pyqtSignal(float) # 实时帧率 def __init__(self, model, capture, conf0.25, iou0.45): super().__init__() self.model model # 已加载的 YOLOv5 模型 self.capture capture # 已打开的 cv2.VideoCapture self.conf conf # 置信度阈值0.25 是 YOLOv5 默认值 self.iou iou # NMS 的 IOU 阈值 self._running True self._frame_skip 0 # 每隔 N 帧推理一次0 表示每帧都推理 self._skip 0 def run(self): # 线程入口。不要直接调用 run()用 start() 启动 while self._running: ret, frame self.capture.read() if not ret: self.log.emit(输入源读取失败线程退出) break self._skip 1 if self._skip % (self._frame_skip 1) ! 0: continue t0 cv2.getTickCount() with torch.no_grad(): # 关闭梯度防止显存累积 results self.model(frame, size640) # 推理 NMS annotated self._draw(frame, results) # 在 numpy 帧上画框 self.frame_ready.emit(self._to_qimage(annotated)) dt (cv2.getTickCount() - t0) / cv2.getTickFrequency() self.fps_changed.emit(1.0 / dt) def stop(self): self._running False self.wait(3000) # 最多等 3 秒避免杀线程导致资源没释放 def set_conf(self, value): self.conf value # 界面滑杆直接改这个属性下一帧生效几个关键点要解释清楚。第一pyqtSignal 的跨线程发射是安全的工作线程里 emit 后主线程的槽函数会在事件循环里被执行不需要自己加锁第二model(frame) 默认走 YOLOv5 内部的预处理和 NMS返回的 Results 对象里 xyxy[0] 是形状为 (N, 6) 的张量六列分别是 x1、y1、x2、y2、置信度、类别第三stop() 用标志位配合 wait()不要用 terminate()否则摄像头资源可能来不及释放。这里的 _frame_skip 参数是给低配机器留的后门检测耗时 200ms 而界面只要 30fps 时每 3 帧推理一次就能把画面流畅度拉回来代价是检测结果有最多 2 帧的延迟。模型推理用 torch.no_grad() 包住是防止显存只涨不降的关键后面避坑章节还会再展开。3.2 输入源统一图片、视频文件、摄像头界面要给用户三种选择单张图片、视频文件、摄像头。视频和摄像头都是连续帧区别只在打开方式图片则要包装成「只吐一帧的输入源」让工作线程不用区分。我一般用一个小函数做统一入口def open_source(source_type, source_path): # source_type: image / video / camera if source_type camera: cap cv2.VideoCapture(int(source_path)) # 0 是默认摄像头 else: cap cv2.VideoCapture(source_path) if not cap.isOpened(): raise RuntimeError(无法打开输入源: %s % source_path) if source_type image: ret, frame cap.read() cap.release() if not ret: raise RuntimeError(图片读取失败) return SingleFrameSource(frame) return capvideo 和 camera 共用同一套读取循环camera 的 source_path 传摄像头索引默认 0 就是笔记本内置摄像头。SingleFrameSource 是十几行的包装类内部存住那帧图片read() 第一轮返回它之后返回 (False, None)接口和 cv2.VideoCapture 对齐工作线程里不用区分。这样 run() 里不用写三套分支后续想加网络流输入也只要在 open_source 里多接一个分支就行。打开输入源后建议顺手把分辨率设到合理值。我用 cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280) 和 cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 720) 强制设置因为部分摄像头默认输出 640 宽检测小目标时框都画不准。3.3 画框与 QImage 转换别踩 BGR 的坑YOLOv5 的推理结果画框要在 numpy 帧上做因为工作线程拿到的是 cv2 的 BGR 帧而 Qt 显示需要的是 RGB。转换顺序错了框和文字的位置也会跟着错位这是新手最容易翻车的地方def _draw(self, frame, results): names self.model.names for det in results.xyxy[0].tolist(): x1, y1, x2, y2, conf, cls det x1, y1, x2, y2 map(int, (x1, y1, x2, y2)) label %s %.2f % (names[int(cls)], conf) cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(frame, label, (x1, max(0, y1 - 8)), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2) return frame def _to_qimage(self, bgr_frame): rgb cv2.cvtColor(bgr_frame, cv2.COLOR_BGR2RGB) h, w, ch rgb.shape qimg QImage(rgb.data, w, h, ch * w, QImage.Format_RGB888) return qimg.copy() # 必须 copy否则 numpy 内存失效后画面花掉results.xyxy[0].tolist() 把张量落回 Python 列表避免在 torch 张量上反复做索引坐标转成 int 是因为 cv2.rectangle 不接收浮点坐标。QImage 构造的第三个参数是每行字节数BGR 转 RGB 后每像素 3 字节所以是 ch*w最后一个坑是 copy()QImage 只持有原始数据的指针不拷贝数据如果 numpy 数组被回收再分配界面上的图就会花掉。实测里九成的「画面闪烁变花」都是这里漏了 copy()。4. PyQt5 界面交互落地实时预览、参数调节与模型热切换4.1 界面骨架预览区、控制区、日志区界面我习惯用三段式顶部是图像预览区中间是控制条底部是日志区。预览区用 QLabel 放大显示 QPixmap控制条放启动/停止按钮和置信度、IOU 滑杆日志区用 QPlainTextEdit 接收工作线程的日志信号。这样布局的好处是摄像头画面不动时操作区和日志区不遮挡现场演示时信息密度刚好。class MainWindow(QMainWindow): def __init__(self, worker): super().__init__() self.worker worker self.preview QLabel(等待输入源) self.preview.setMinimumSize(960, 540) self.preview.setAlignment(Qt.AlignCenter) self.preview.setStyleSheet(background:#1e1e1e;color:#aaa;) self.btn_start QPushButton(开始) self.btn_stop QPushButton(停止) self.slider_conf QSlider(Qt.Horizontal) self.slider_conf.setRange(1, 99) self.slider_conf.setValue(25) self.label_conf QLabel(置信度 0.25) self.log_view QPlainTextEdit() self.log_view.setReadOnly(True) control QHBoxLayout() control.addWidget(self.btn_start) control.addWidget(self.btn_stop) control.addWidget(self.label_conf) control.addWidget(self.slider_conf) layout QVBoxLayout() layout.addWidget(self.preview) layout.addLayout(control) layout.addWidget(self.log_view, stretch1) container QWidget() container.setLayout(layout) self.setCentralWidget(container)滑杆的值域设成 1 到 99 而不是 0 到 1是因为 QSlider 只接受整数在主线程里做百分比的整数运算也最干净后面再除以 100 还原成浮点阈值。日志区放在 QPlainTextEdit 里用 appendPlainText 接收比 QTextEdit 更省内存长时间跑视频不会越来越卡。4.2 信号槽联动让置信度、IOU 实时生效工作线程的属性在设计上就允许被外部改滑杆只要在 valueChanged 信号里更新 worker.conf 即可下一帧推理就会用新阈值不需要重启线程。这个「热改参数」的实现成本几乎为零但对交付体验的提升非常明显——现场调阈值不用改代码重跑。self.btn_start.clicked.connect(self.worker.start) self.btn_stop.clicked.connect(self.worker.stop) self.slider_conf.valueChanged.connect(self._on_conf_changed) self.worker.frame_ready.connect(self._show_frame) self.worker.log.connect(self.log_view.appendPlainText) self.worker.fps_changed.connect(self._update_fps) def _on_conf_changed(self, value): conf value / 100.0 self.worker.conf conf self.label_conf.setText(置信度 %.2f % conf) def _show_frame(self, qimg): self.preview.setPixmap(QPixmap.fromImage(qimg)) def _update_fps(self, fps): self.setWindowTitle(检测工具 - %.1f FPS % fps)这里有个细节改的是 worker.conf但推理循环里每帧都读取这个属性所以属性赋值发生在任意时刻都能在下一帧生效不用加锁。IOU 滑杆的接线方式完全一样只是把目标属性换成 worker.iou。fps_changed 信号直接写进窗口标题实测比在界面上放一个只读文本框更直观还不占布局空间。4.3 运行中热切换模型权重现场可能要在通用模型和专用模型之间切换比如先跑通用检测再看某类目标的细粒度模型。直接在推理循环里换 model 引用是危险操作——工作线程正在用旧模型推理时你把属性换掉轻则报张量维度错误重则直接崩溃。安全做法是先停线程换模型清显存再启线程。def load_det_model(weights_path, devicecpu): # 加载 YOLOv5 .pt 权重device 传 cuda:0 可切 GPU import sys sys.path.append(yolov5) # 改成你本地 YOLOv5 源码目录 from models.experimental import attempt_load model attempt_load(weights_path, map_locationdevice) model.eval() return model def reload_model(self, weights_path): self.worker.stop() # 1. 先停推理线程 old_model self.worker.model self.worker.model load_det_model(weights_path) # 2. 换新权重 del old_model # 3. 释放旧模型 if torch.cuda.is_available(): torch.cuda.empty_cache() # 4. 清空显存缓存 self.worker.start() # 5. 重新启动不要为了省事新建一个 QThread 实例替换旧的新线程要重新连接所有信号摄像头也要重新打开中间任何一步遗漏都会变成诡异的偶发问题。保留同一个工作线程实例只换内部的 model 引用信号连接全部原样保留是最稳的路径。加载完记得 model.eval() 关掉 dropout 和 batchnorm 的训练态否则推理结果会整体偏移。5. 避坑手册PyQt5 跑 YOLOv5 的 5 个高频翻车现场5.1 界面卡成幻灯片点哪都没反应现象启动检测后窗口标题一直转圈移动鼠标都卡顿甚至弹出「程序未响应」。原因最常见的是推理或 cv2.VideoCapture.read() 被放在了主线程。detect.py 的循环体原样搬进界面代码主线程被推理阻塞Qt 的事件循环得不到执行机会。解决把读取、推理、画框全部搬进 QThread 的 run() 循环主线程只接收 frame_ready 信号做 QPixmap 赋值。如果画面还是卡优先检查是不是在 _show_frame 里做了耗时操作比如把 QImage 转 numpy——这个转换应该放在工作线程完成。5.2 摄像头能打开但画面全黑或者偶发花屏现象cv2.VideoCapture(0) 返回 True但 read() 出来的帧全黑换一个摄像头索引又报错。原因Windows 上默认的视频后端对部分摄像头驱动兼容性差另一个常见原因是笔记本有多个摄像头前置、USB 外接索引 0 不是你以为的那个设备。解决Windows 下显式指定 DirectShow 后端打开后打印分辨率确认。代码上就是 open_source 里 camera 分支改成 cv2.VideoCapture(int(source_path), cv2.CAP_DSHOW)黑屏还在就用系统设备管理器确认摄像头索引或者把 source_path 开放给用户在界面上输入。分辨率问题用 cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280) 强制设置。5.3 显存只涨不降跑十分钟后 CUDA out of memory现象GPU 显存占用随时间缓慢上涨最终推理报 CUDA out of memory。原因推理循环里没有把计算包在 torch.no_grad() 里autograd 图每帧累积另一种是热切换模型后没有释放旧模型引用旧权重一直占着显存。解决推理循环里用 with torch.no_grad(): 包住 model(frame)这是根治手段热切换模型按 4.3 的顺序先 del 旧模型再 empty_cache。注意 torch.cuda.empty_cache() 不是银弹它只释放缓存块真正的泄漏要靠 no_grad 解决。如果还在涨把 _frame_skip 打开缩短每帧张量的生命周期。5.4 PyInstaller 打包后体积巨大换机器提示缺 DLL现象打包出的 exe 将近 1GB换到一台没有 Python 的机器双击运行提示找不到 cudnn64_8.dll 或 Qt 平台插件。原因torch 全家桶和 CUDA 运行库被打进了包PyInstaller 对动态加载的部分依赖识别不全Qt 的 platform 插件也没有被完整收进去。解决用 PyInstaller 时明确收集 torch、torchvision、PyQt5 全部子模块同时排除用不到的 CUDA 能力。体积控制在 600MB 到 900MB 是常态别指望它变小更省事的做法是交付时带一个虚拟环境目录加启动脚本而不是单文件 exe。单文件模式启动时要解压到临时目录检测工具这种长驻程序不建议用 --onefile。5.5 界面画面颜色发蓝发红检测框和画面错位现象预览区的图像像老式相机偏色或者框的位置和实际物体对不上。原因cv2 读进来是 BGRQImage.Format_RGB888 期望 RGB没做 cvtColor 就把 BGR 数据直接送进 QImage错位则是 QImage 的 bytesPerLine 参数写错比如用了错误的通道数。解决严格按 3.3 的顺序先 cvtColor 再构造 QImagebytesPerLine 传 ch * w。BGR 和 RGB 的混用是 OpenCV 生态里最反复出现的低级错误排查时先打印一下帧的第一个像素值再对照 QImage 里同样位置的像素正常时三通道分量应该一致。6. 结果导出与长时间压测交付前最后两个动作界面能跑、参数能调离「能交付」还差两步结果要能落盘稳定性要经得起长时间跑。结果导出我用 JSON检测记录带时间戳、类别、置信度、坐标后续无论是做统计还是接其他系统都方便import json, time def export_frame_result(results, names, save_path): items [] for det in results.xyxy[0].tolist(): items.append({ time: time.time(), class: names[int(det[5])], conf: round(det[4], 3), box: [round(v, 1) for v in det[:4]], }) with open(save_path, a, encodingutf-8) as f: f.write(json.dumps(items, ensure_asciiFalse) \n)追加写入而不是覆盖写入是因为长时间检测会产生大量记录断点续跑不至于丢数据每帧都写一次文件会拖慢工作线程我一般用队列把导出任务丢给后台累积批量写或者攒 10 帧写一次。压测的验证方法也很固定拿一段 10 分钟、目标出现密集的视频文件跑一遍不碰摄像头和界面操作只看三个指标——FPS 平均值、显存占用曲线、界面是否卡顿。FPS 平均值别用前 5 秒的数据torch 的 cuDNN 自动调优会让前十几帧慢不少等预热 30 秒后再统计更准确。显存曲线我一般直接盯任务管理器如果从 2GB 慢慢涨到 4GB说明还有引用没释放回 5.3 排查。界面卡顿只要出现一次就说明主线程被不该有的耗时操作侵入了回头查所有信号槽槽函数里有没有做图像转换。最后说一个我自己的习惯检测工具交付前一定在目标机器上用真机跑三分钟开机自检重点确认冷启动时模型加载不超时、摄像头热插拔不崩、关窗时线程能干净退出——这三个场景用模拟器测不出来。界面代码少用奇技淫巧多留日志出口现场出了问题靠日志定位比靠猜快十倍。希望帮到你。本文还有配套的精品资源点击获取
