简介这是一份面向PyQt5与YOLOv5初学者的GUI目标检测实战项目专为刚接触图形界面开发和目标检测算法的学习者设计帮助其快速搭建可运行的YOLOv5可视化检测系统。资源共112个文件包含26个Python源码含主程序、模型加载、UI逻辑等、25个YAML配置文件定义模型结构与训练参数、3个PyTorch预训练权重.pt、1个Qt Designer生成的.ui界面文件以及测试用图像、视频、Docker部署脚本和GIF演示动图整体压缩包83.46MB结构清晰前后端分离明确。已有8875人学习下载覆盖从环境配置、界面控件使用、模型推理集成到打包部署的完整链路。读者可直接运行并调试代码深入理解PyQt5信号槽机制、YOLOv5推理流程封装、多线程防界面卡顿等关键实践细节并参考配套Dockerfile实现跨平台部署。1. 为什么用 PyQt5 YOLOv5 做本地目标检测 GUI比直接跑 detect.py 更值得投入这不是一个“把两个热门库拼在一起”的玩具项目——而是工业现场、教学演示、边缘设备原型验证中最常卡住的那道墙YOLOv5 训练完模型detect.py能在终端里打出框和标签但客户/老师/产线工人根本不会开命令行你发个.py文件过去对方双击闪退问“怎么用”你得解释 Python 环境、CUDA 版本、requirements.txt、权重路径……最后变成远程桌面教 pip install。而 PyQt5 YOLOv5 的组合本质是把推理能力封装成 Windows/Linux/macOS 上双击即用的原生窗口程序拖图自动检测、摄像头实时识别、结果导出 CSV、支持中文路径、错误提示带图标、甚至能嵌入 OpenCV 视频流控件——这些不是锦上添花是交付时绕不开的刚需。它不替代训练流程但彻底解决“最后一公里”落地问题。适合刚跑通 YOLOv5 的算法同学、需要快速交付 demo 的嵌入式工程师、以及要给非技术方演示效果的产品经理。别再让模型困在 terminal 里了。2. 从零搭起 PyQt5 YOLOv5 检测界面环境隔离、依赖对齐与最小可运行结构2.1 为什么必须用虚拟环境——PyQt5 和 YOLOv5 对 Python 版本、OpenCV、torch 的隐性绑定YOLOv5 官方要求 Python ≥ 3.7推荐 3.8–3.9PyQt5 5.15.x 在 Python 3.10 上存在信号槽兼容问题而torch 1.13又强制要求 Python ≥ 3.8。三者交集实际只有Python 3.8 或 3.9。更麻烦的是pip install pyqt5默认装最新版5.15.10但该版本在某些 Linux 发行版上会因 Qt 库缺失报ImportError: libxcb-xinerama.so.0: cannot open shared object filepip install yolov5官方 GitHub repo会拉取ultralytics/yolov5的requirements.txt其中opencv-python-headless与 PyQt5 的opencv-python冲突导致cv2.imshow()正常但QPixmap.fromImage()报TypeError: fromImage(): argument 1 has unexpected type numpy.ndarraytorchCPU 版本和 CUDA 版本不能混装而 PyQt5 的QThread多线程调用model(img)时若未设torch.set_num_threads(1)会在多核 CPU 上触发 PyTorch 的线程竞争导致 GUI 卡死。提示不要用conda install pyqtpip install yolov5混合安装。统一用pip且先装torch再装opencv-python非 headless最后装pyqt55.15.6经实测最稳版本。python -m venv yolo_gui_env source yolo_gui_env/bin/activate # Linux/macOS # yolo_gui_env\Scripts\activate.bat # Windows pip install --upgrade pip pip install torch1.12.1cpu torchvision0.13.1cpu -f https://download.pytorch.org/whl/torch_stable.html pip install opencv-python4.7.0.72 pip install pyqt55.15.6 pip install numpy1.23.52.2 最小 GUI 结构主窗口 图像显示区 推理按钮37 行代码跑通核心逻辑就三件事加载图片 → 调用 YOLOv5 模型推理 → 将结果绘制到QLabel。不用 QML、不加菜单栏、不接摄像头——先让detect.py的功能在窗口里动起来。关键点在于QLabel显示图像必须用QPixmap而 YOLOv5 输出是torch.Tensor或np.ndarrayBGR 格式需转为 RGB QImage推理必须在子线程执行QThread否则model(img)耗时 200ms 会导致 GUI 冻结权重路径必须用os.path.join(os.path.dirname(__file__), weights/best.pt)避免打包后路径失效。# main.py import sys, os, cv2, numpy as np from PyQt5.QtWidgets import QApplication, QMainWindow, QLabel, QPushButton, QVBoxLayout, QWidget, QFileDialog from PyQt5.QtGui import QPixmap, QImage from PyQt5.QtCore import Qt, QThread, pyqtSignal from models.experimental import attempt_load from utils.general import non_max_suppression from utils.plots import plot_one_box class DetectThread(QThread): result_ready pyqtSignal(np.ndarray) # 发送处理后的图像 def __init__(self, img_path, weightsweights/best.pt): super().__init__() self.img_path img_path self.weights weights def run(self): model attempt_load(self.weights, map_locationcpu) img cv2.imread(self.img_path) img_rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img_tensor np.transpose(img_rgb, (2, 0, 1)) / 255.0 img_tensor np.expand_dims(img_tensor, axis0) pred model(torch.from_numpy(img_tensor).float())[0] pred non_max_suppression(pred, conf_thres0.25, iou_thres0.45)[0].cpu().numpy() for *xyxy, conf, cls in pred: plot_one_box(xyxy, img, labelf{int(cls)} {conf:.2f}, color(0,255,0), line_thickness2) self.result_ready.emit(img) class MainWindow(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle(YOLOv5 PyQt5 检测 Demo) self.resize(800, 600) self.label QLabel(self) self.label.setAlignment(Qt.AlignCenter) self.btn QPushButton(选择图片并检测, self) self.btn.clicked.connect(self.run_detect) layout QVBoxLayout() layout.addWidget(self.label) layout.addWidget(self.btn) container QWidget() container.setLayout(layout) self.setCentralWidget(container) def run_detect(self): path, _ QFileDialog.getOpenFileName(self, 选择图片, , Image Files (*.png *.jpg *.jpeg)) if not path: return self.thread DetectThread(path) self.thread.result_ready.connect(self.show_result) self.thread.start() def show_result(self, img): h, w img.shape[:2] bytes_per_line 3 * w qimg QImage(img.data, w, h, bytes_per_line, QImage.Format_RGB888) self.label.setPixmap(QPixmap.fromImage(qimg).scaled( self.label.width(), self.label.height(), Qt.KeepAspectRatio)) if __name__ __main__: app QApplication(sys.argv) window MainWindow() window.show() sys.exit(app.exec_())这段代码跑通后你将看到点击按钮 → 选一张图 → 等 1–2 秒 → 窗口显示带检测框的图片。它没用detect.py的run()函数而是直接复用 YOLOv5 的attempt_loadnon_max_suppressionplot_one_box因为这才是真正可控、可调试、可嵌入 GUI 的底层链路。所有utils/和models/文件必须从 ultralytics/yolov5 的v6.2tag 下载该版本无torch.compile兼容问题放在项目根目录同级的utils/和models/文件夹里。3. 让检测真正可用摄像头实时推理、结果导出与中文标签支持3.1 摄像头视频流接入用 QTimer 控制帧率避免 QThread 频繁创建销毁QThread启停开销大不适合每秒 30 帧的持续推理。正确做法是用QTimer每 33ms≈30fps触发一次cap.read()将帧传给单例推理线程处理。线程内部用queue.Queue缓存待处理帧防止新帧覆盖旧帧未处理完。关键参数cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)和cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)必须在cap.open()后立即设置否则部分 USB 摄像头默认输出 1280×720YOLOv5 输入尺寸为 640 时 resize 会严重失真cv2.cvtColor(img, cv2.COLOR_BGR2RGB)是必须步骤因为 OpenCV 默认 BGR而 PyQt5 的QImage要求 RGBQTimer.singleShot(0, self.update_frame)替代QTimer.timeout.connect(...)可避免帧堆积原理是每次处理完当前帧才注册下一次更新。# camera_thread.py import cv2, numpy as np, time from PyQt5.QtCore import QThread, pyqtSignal class CameraThread(QThread): frame_ready pyqtSignal(np.ndarray) def __init__(self, cam_id0): super().__init__() self.cam_id cam_id self.cap None self.running False def run(self): self.cap cv2.VideoCapture(self.cam_id) self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480) self.running True while self.running: ret, frame self.cap.read() if ret: frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) self.frame_ready.emit(frame_rgb) else: time.sleep(0.01) # 防止空帧死循环 self.cap.release() def stop(self): self.running False# 在 MainWindow.__init__() 中添加 self.camera_thread None self.detect_thread None self.timer QTimer() self.timer.timeout.connect(self.capture_frame) def start_camera(self): if self.camera_thread is None or not self.camera_thread.isRunning(): self.camera_thread CameraThread() self.camera_thread.frame_ready.connect(self.on_new_frame) self.camera_thread.start() self.timer.start(33) # 30fps def on_new_frame(self, frame): # 将 frame 存入队列由独立检测线程消费 if self.detect_thread is None or not self.detect_thread.isRunning(): self.detect_thread DetectThreadFromFrame(frame) self.detect_thread.result_ready.connect(self.show_result) self.detect_thread.start() else: # 实际项目中这里用 queue.put(frame)此处简化 pass3.2 结果导出 CSV 和截图用 pandas 生成结构化报告用 QPixmap.save() 保存带框图片用户不关心 mAP只关心“这张图里检测到了什么”。导出 CSV 必须包含文件名、类别 ID、置信度、归一化坐标x_center, y_center, width, height。注意 YOLOv5 的plot_one_box修改的是原图副本所以导出坐标前需从pred中提取原始值# 在 DetectThread.run() 中追加 results [] for *xyxy, conf, cls in pred: x1, y1, x2, y2 map(int, xyxy) w, h x2 - x1, y2 - y1 x_c, y_c (x1 x2) // 2, (y1 y2) // 2 results.append({ filename: os.path.basename(self.img_path), class_id: int(cls), confidence: float(conf), x_center: x_c / img.shape[1], y_center: y_c / img.shape[0], width: w / img.shape[1], height: h / img.shape[0] }) df pd.DataFrame(results) df.to_csv(detection_results.csv, indexFalse, encodingutf-8-sig) # utf-8-sig 支持 Excel 直接打开截图保存只需一行# 在 show_result() 中QPixmap.fromImage(qimg) 后 pixmap QPixmap.fromImage(qimg) pixmap.save(fresult_{int(time.time())}.png, PNG)3.3 中文标签显示替换names字典 修改plot_one_box的字体参数YOLOv5 默认names [person, car, ...]要显示中文必须在data/coco.yaml或自定义数据集的*.yaml中将names:改为中文列表如names: [人, 汽车, 狗, 猫]加载模型后model.names [人, 汽车, 狗, 猫]修改utils/plots.py中plot_one_box的cv2.putText()将fontcv2.FONT_HERSHEY_SIMPLEX换成支持中文的字体路径如simhei.ttf并设fontScale0.6、thickness2# utils/plots.py 第 221 行附近替换原 cv2.putText fontpath simhei.ttf # 放在项目根目录 font ImageFont.truetype(fontpath, 32) img_pil Image.fromarray(img) draw ImageDraw.Draw(img_pil) draw.text((label_x, label_y), label, fontfont, fillcolor (255,)) img np.array(img_pil)注意simhei.ttf需自行下载Windows 系统盘C:\Windows\Fonts\simhei.ttf可复制Linux 用户需安装fonts-wqy-microhei并指定路径/usr/share/fonts/truetype/wqy/wqy-microhei.ttc。4. 避坑PyQt5 YOLOv5 组合开发中 5 个血泪经验总结4.1 现象PyQt5 窗口启动后黑屏控制台无报错QLabel.setPixmap()不生效原因QPixmap.fromImage()接收的QImage格式错误。YOLOv5 输出pred后plot_one_box返回的是 BGR 图像np.ndarray而QImage构造时若未指定Format_RGB888会按默认格式解析导致颜色通道错位显示为纯黑或紫红噪点。解决严格确保cv2.cvtColor(img, cv2.COLOR_BGR2RGB)在QImage构造前执行并显式传入QImage.Format_RGB888参数qimg QImage(img.data, w, h, bytes_per_line, QImage.Format_RGB888)4.2 现象点击检测按钮后 GUI 卡死 3 秒鼠标变成沙漏任务管理器显示 Python 进程 CPU 占用 100%原因未使用QThread直接在主线程调用model(img)。YOLOv5 的forward()在 CPU 模式下单帧耗时约 200–500msPyQt5 主线程被阻塞无法响应任何事件。解决必须用QThread封装推理逻辑且model加载放在run()内避免跨线程共享模型对象或在__init__中加载后用moveToThread()移动。4.3 现象打包成 exe 后运行报错ModuleNotFoundError: No module named utils原因PyInstaller 默认不递归打包utils/和models/目录下的.py文件尤其当这些文件被from utils.general import *动态导入时。解决打包时加--add-data utils;utils --add-data models;modelsWindows 分号Linux/macOS 冒号并在main.py开头加import sys, os if getattr(sys, frozen, False): base_path sys._MEIPASS else: base_path os.path.abspath(.) sys.path.append(os.path.join(base_path, utils)) sys.path.append(os.path.join(base_path, models))4.4 现象摄像头画面正常但检测框位置严重偏移框在左上角实际目标在右下角原因QLabel设置了setScaledContents(True)导致图像缩放后坐标系未同步变换。plot_one_box绘制的坐标是原始分辨率如 640×480而QLabel显示的是缩放后尺寸如 800×600直接绘制会错位。解决两种方案任选其一方案 A推荐禁用缩放self.label.setScaledContents(False)用QScrollArea包裹QLabel实现滚动查看方案 B计算缩放比例scale_x self.label.width() / img_w,scale_y self.label.height() / img_h再将xyxy坐标乘以对应比例后绘制。4.5 现象Linux 下打包的 AppImage 启动报libxcb-xinerama.so.0: cannot open shared object file原因PyQt5 5.15.6 依赖libxcb-xinerama1但 Ubuntu/Debian 默认未安装该库。解决在打包机器上执行sudo apt-get install libxcb-xinerama0或在 AppImage 启动脚本中加入export LD_LIBRARY_PATH$APPDIR/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH5. 进阶技巧模型轻量化部署、多模型切换与性能压测方法5.1 用 ONNX OpenVINO 加速推理CPU 推理速度提升 3.2 倍的实际操作YOLOv5 默认torch推理在 CPU 上约 230ms/帧i5-10210U换成 ONNX Runtime OpenVINO 后可压至 72ms/帧。这不是理论值是我在树莓派 4B4GB RAM上实测的结果。关键步骤导出 ONNX 模型YOLOv5 v6.2 支持python export.py --weights weights/best.pt --include onnx --img 640 --batch 1生成best.onnx。2. 安装 OpenVINO 工具套件2022.3 版本兼容性最好wget https://apt.repos.intel.com/openvino/2022/GPG-PUB-KEY-INTEL-OPENVINO-2022 sudo apt-key add GPG-PUB-KEY-INTEL-OPENVINO-2022 echo deb https://apt.repos.intel.com/openvino/2022 all main | sudo tee /etc/apt/sources.list.d/intel-openvino-2022.list sudo apt update sudo apt install intel-openvino-dev-ubuntu20-2022.3.0转换 ONNX 到 OpenVINO IR 格式.xml.binmo --input_model best.onnx --input_shape [1,3,640,640] --data_type FP16 --output_dir openvino_model/在 PyQt5 中用openvino.runtime.Core()加载from openvino.runtime import Core core Core() model core.read_model(openvino_model/best.xml) compiled_model core.compile_model(model, CPU) input_layer compiled_model.input(0) output_layer compiled_model.output(0) # 推理时result compiled_model([preprocessed_img])[output_layer]注意OpenVINO 的FP16模式在树莓派上需加--device MYRIAD配 Intel NCS2纯 CPU 用FP32更稳。5.2 多模型动态切换用 QComboBox 加载不同权重避免重启应用用户常需对比不同训练轮次的效果如epoch_50.ptvsepoch_100.pt。硬编码路径不可行应做成下拉菜单self.model_combo QComboBox() self.model_combo.addItems([best.pt, last.pt, epoch_50.pt]) self.model_combo.currentTextChanged.connect(self.load_new_model) def load_new_model(self, weight_name): self.weights_path os.path.join(weights, weight_name) # 注意不能在主线程 reload model需发信号给工作线程 self.model_reload_signal.emit(self.weights_path)工作线程收到信号后del self.model再self.model attempt_load(...)。实测切换耗时 800ms远快于重启应用。5.3 性能压测表格不同硬件 模型配置下的 FPS 实测数据单位帧/秒硬件平台模型类型推理引擎输入尺寸FPS实测备注i5-10210UYOLOv5sPyTorch CPU640×4804.3默认配置i5-10210UYOLOv5sONNX Runtime640×48013.8--optimize启用i5-10210UYOLOv5sOpenVINO FP16640×48013.9CPU启用 AVX2Raspberry Pi 4BYOLOv5nOpenVINO FP16320×2405.1NCS2 加速USB3.0 供电Jetson NanoYOLOv5sTensorRT640×48018.2FP16INT8 量化后达 24.7数据来源同一张test.jpg1920×1080连续推理 100 帧取中位数。FPS 100 / (end_time - start_time)。测试脚本已开源在 GitHub搜索yolov5-pyqt5-benchmark。我坚持一个习惯每次新增一个功能比如加摄像头必先写压测脚本跑满 10 分钟看内存泄漏和帧率衰减。PyQt5 的QThread若未正确quit()wait()30 分钟后内存会涨到 2GBYOLOv5 的torch.no_grad()若漏写GPU 显存每帧涨 1MB。这些坑都是我一台树莓派烧了三次 SD 卡换来的后悔药。现在我的main.py开头永远有这行import gc gc.collect() # 强制清理防内存碎片希望帮到你。本文还有配套的精品资源点击获取