公路养护和市政巡检里“路面坑洼检测”是一个很典型的视觉落地场景问题肉眼可见但靠人跑断腿也看不完。这次我们来看一个把 YOLOv8 和 PyQt5 组合起来的桌面检测系统——用 YOLOv8 做坑洼、破损、裂缝等路面缺陷的识别再用 PyQt5 做图形界面把模型推理包装成图片上传、视频检测、摄像头实时检测这类可操作功能。它解决问题的方式很直接训练一个自己的路面缺陷模型然后包一个带界面、能选文件、能出结果的应用后续无论是给巡检人员用还是作为毕设、课程设计的完整项目都比单纯跑命令行推理更容易交付。这篇文章会按照从方案到落地的顺序展开先讲 YOLOv8 PyQt5 这套组合适不适合这个任务再给环境准备、数据集组织、模型训练与导出、PyQt5 界面集成的完整思路最后是图片、视频、摄像头、批量任务的功能测试方法以及常见坑的排查清单。如果你正在做同类检测项目可以直接把这里的流程和代码模板作为骨架替换成自己的数据集和业务逻辑。先快速给结论这类系统的技术门槛不高YOLOv8 的官方库把训练、验证、导出、推理都封装得比较完整PyQt5 解决的是“怎么让模型结果变成可用工具”的问题。真正的难点在于数据、界面交互和推理性能的平衡。1. 核心能力速览在动手之前先把这套系统的关键指标列出来方便判断它适不适合你的场景。能力项说明项目类型桌面端视觉检测系统PyQt5 GUI YOLOv8 目标检测检测目标坑洼、破损、裂缝、修补块等路面缺陷由训练数据集决定检测引擎YOLOv8Ultralytics 官方开源系列模型界面框架PyQt5训练硬件建议 NVIDIA GPU显存越大越稳纯 CPU 也可以训练但速度慢推理硬件GPU 优先CPU 能跑适合低分辨率、低并发场景显存占用取决于模型尺寸n/s/m/l/x和输入分辨率需按实际测试为准启动方式Python 脚本启动桌面程序是否支持 API原始项目主体是 GUI接口需自行封装 FastAPI 或 Flask是否支持批量任务可以遍历图片/视频目录后调用模型推理即可模型导出支持 PyTorch 权重、ONNX、TensorRT 等格式适合场景道路巡检辅助、养护前筛查、高校项目、目标检测 Qt 工程实践从材料看这套方案的核心卖点不是算法创新而是“训练 界面 部署”的完整闭环。YOLOv8 负责把图片里的缺陷位置找出来PyQt5 负责让普通用户能选择文件、点击按钮、看到结果而不是面对黑乎乎的终端。2. 适用场景与使用边界这种系统最常用的场景是道路巡检辅助。巡检人员拍下路面照片回来后批量导入系统系统自动标出可疑坑洼位置和置信度人工再做二次复核。相比纯人工翻照片效率提升非常明显这是它最大的价值。还有一些常见用途市政道路日常巡检用行车记录仪或者手机拍摄路面素材事后用系统筛查。低等级公路养护前摸底先快速扫一遍把明显破损区域挑出来。高校毕设/课程设计把 YOLOv8 训练、PyQt5 界面、目标检测结合起来是一个很完整的工程实践题目。实验教学用来演示“模型如何被包装成产品”比单纯跑检测脚本更有说服力。但它不是万能的有几个边界必须说清楚。第一模型泛化能力受训练数据限制。不同地区路面材质、光照条件、拍摄角度差异很大在 A 城市训练的数据集拿到 B 城市可能漏检严重。所以真正要落地最好用目标地区的真实照片重新训练或微调。第二它不能代替养护决策。系统只负责“找出可疑区域”坑洼深度、面积、损坏等级这些更细的评估仍然需要人工到现场确认。把检测系统当作最终判断依据风险很大。第三存在误检和漏检风险。井盖、阴影、水渍、轮胎痕迹都可能被误判为坑洼而雨天积水、夜间低照度场景下漏检率也会上升。使用时要合理设置置信度阈值保留人工复核环节。第四数据合规问题。如果使用了公开数据集商用前要先确认数据集许可证如果自己采集数据要注意拍摄对象是否涉及个人隐私。摄像头实时检测场景下更要考虑拍摄范围和个人信息脱敏。3. 环境准备与前置条件开发这套系统主要涉及 Python、PyTorch、Ultralytics、PyQt5、OpenCV 这几个组件。安装之前先明确自己的硬件和系统环境。3.1 基础依赖操作系统Windows / Linux / macOS 都可以Windows 上调试 PyQt5 最方便。Python 版本建议 3.8 到 3.11 之间具体以当前ultralytics和PyQt5的兼容说明为准。GPU 驱动NVIDIA 显卡用户需要装好显卡驱动训练前先看清楚 CUDA 版本。磁盘空间数据集、模型权重、虚拟环境加在一起建议预留 20GB 以上。先检查 Python 和显卡状态python --version pip --version nvidia-smi如果nvidia-smi有输出说明驱动正常。然后安装 PyTorch注意要选择和你的 CUDA 版本匹配的安装命令建议到 PyTorch 官网获取最新安装指令不要盲目复制旧命令。3.2 安装核心库安装 YOLOv8 官方库和 PyQt5pip install ultralytics pip install PyQt5如果下载速度慢可以临时切换国内镜像源pip install ultralytics -i https://pypi.tuna.tsinghua.edu.cn/simple pip install PyQt5 -i https://pypi.tuna.tsinghua.edu.cn/simpleOpenCV 一般会作为ultralytics的依赖自动安装。安装完成后可以验证一下import ultralytics import PyQt5.QtCore print(ultralytics.__version__) print(PyQt5.QtCore.QT_VERSION_STR)这两行如果能正常输出说明主体环境已经就绪。4. 数据集准备与 YOLOv8 模型训练一个好的坑洼检测系统八成功夫花在数据上。模型结构不是瓶颈标注质量和数据多样性才是。4.1 数据集目录结构YOLOv8 训练时推荐的数据集目录结构是 images 和 labels 分离训练集、验证集分开dataset/ ├── data.yaml ├── images/ │ ├── train/ │ ├── val/ │ └── test/ └── labels/ ├── train/ ├── val/ └── test/每个图片对应的标注文件是同名的.txt文件放在 labels 对应目录下格式为class_id x_center y_center width height其中坐标都做了归一化范围在 0 到 1 之间。比如一张图上只有一个坑洼标注内容可能是0 0.5218 0.6342 0.2745 0.1981如果类别是 1 个class_id 就是 0。如果有坑洼、裂缝、修补块等多个类别class_id 依次为 0、1、2。4.2 编写 data.yaml训练前需要一份数据集配置文件path: D:/road_dataset train: images/train val: images/val nc: 1 names: 0: pothole如果你的业务里要检测多个类别把nc和names改成自己的类别列表。注意路径里的path建议使用绝对路径避免相对路径找不到数据集。4.3 开始训练安装好依赖、准备好数据后可以用命令行启动训练yolo train dataD:/road_dataset/data.yaml modelyolov8s.pt epochs100 imgsz640 batch16 device0参数含义参数推荐值说明modelyolov8n.pt / yolov8s.pt模型越小显存占用越少速度越快epochs100根据数据量调整小数据集可以先用 50 次imgsz640原始 YOLOv8 默认训练分辨率batch16根据显存调整显存不足就调小device00 表示第一块 GPU没有 GPU 就写cpu第一次训练建议先跑小模型、小 batch、少轮数确认整个流程没问题再加大参数。训练结束后结果会输出到runs/detect/train目录里面包括weights/best.pt、weights/last.pt、混淆矩阵、曲线图等文件。best.pt就是后面 PyQt5 界面要加载的权重文件。4.4 模型导出为 ONNX如果后续要部署到没有 PyTorch 的环境或者想用 OpenCV DNN、TensorRT 推理可以先把模型导出为 ONNXyolo export modelruns/detect/train/weights/best.pt formatonnx imgsz640导出成功后同级目录会出现best.onnx。这个文件不依赖 PyTorch可以被很多推理框架加载。5. PyQt5 界面架构与模块划分模型训练好之后重点就转移到 PyQt5 界面上。很多人在这一步出现问题原因不是某个控件不会用而是把推理逻辑直接写在按钮回调里导致点击按钮后界面卡死。正确做法是把界面、推理、数据管理分成几个模块界面只负责交互推理放到单独线程里执行。5.1 推荐项目结构pothole_detector/ ├── main.py ├── detector.py ├── ui/ │ ├── main_window.py │ └── resources/ ├── weights/ │ └── best.pt ├── inputs/ └── outputs/main.py程序入口启动 PyQt5 应用。detector.py封装 YOLOv8 模型的加载和推理逻辑。ui/main_window.py主窗口界面代码。weights存放训练好的模型权重。inputs/outputs测试图片输入和结果输出目录。因为材料中没有给出具体的源码文件这里的代码是通用模板实际使用时需要根据自己的类名、布局和业务逻辑调整。5.2 推理模块封装把 YOLOv8 加载和推理封装成独立模块方便界面调用# detector.py from ultralytics import YOLO class RoadDetector: def __init__(self, weights_path: str, conf_threshold: float 0.35): self.model YOLO(weights_path) self.conf_threshold conf_threshold def infer_image(self, image): results self.model.predict( sourceimage, confself.conf_threshold, verboseFalse ) return results[0]这样写的好处是界面代码不关心 YOLO 内部逻辑后续想换成其他模型也只需要改detector.py。5.3 主窗口骨架PyQt5 主窗口里建议至少包含这几部分图片/视频打开按钮摄像头开关检测结果画布检测信息文本区域置信度滑块下面是一个最小骨架示例# main.py import sys from PyQt5.QtWidgets import QApplication, QMainWindow, QPushButton, QLabel from PyQt5.QtGui import QImage, QPixmap from detector import RoadDetector class MainWindow(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle(路面坑洼检测系统 - YOLOv8 PyQt5) self.resize(960, 640) self.detector RoadDetector(weights/best.pt) self.result_label QLabel(self) self.result_label.setText(检测结果区域) self.result_label.setGeometry(20, 20, 800, 450) self.btn_detect QPushButton(选择图片检测, self) self.btn_detect.setGeometry(840, 30, 100, 40) self.btn_detect.clicked.connect(self.on_detect_clicked) def on_detect_clicked(self): # 这里应该用 QFileDialog 选择图片然后在子线程里推理 # 下面只是占位逻辑实际项目不要阻塞主线程 pass if __name__ __main__: app QApplication(sys.argv) window MainWindow() window.show() sys.exit(app.exec_())这里最需要注意的问题是线程。模型推理可能耗时几百毫秒到几秒如果直接放在按钮回调里界面会冻结。更稳妥的做法是使用QThread把推理放到子线程推理完成后再通过信号把结果传回主线程更新界面。这也是 PyQt5 开发中最常见的性能坑之一。6. 功能测试与效果验证系统搭建完成后要按功能模块逐步验证不要一上来就全流程测试。6.1 图片检测测试测试目的验证模型能否在单张图片上正确框出坑洼区域并显示类别和置信度。操作步骤打开系统主界面。选择一张含明显坑洼的测试图片最好是训练集中没有出现过的。点击检测按钮等待推理完成。查看输出图片上是否有正确的目标框。判断标准坑洼位置被框住框的位置合理。置信度分数显示正常。没有把路面裂缝、阴影误判为坑洼或者误判数量在可接受范围内。如果漏检严重先降低置信度阈值再试如果误检严重说明模型训练不充分或测试图片与训练集分布差异大。6.2 视频检测测试测试目的验证系统能否处理连续帧观察推理速度是否满足实时性要求。操作步骤选择一段包含坑洼路面的短视频。点击视频检测按钮。播放过程中观察画面是否流畅检测框是否抖动。判断标准视频能逐帧读取和推理。大多数帧能识别出坑洼偶尔丢帧可以接受。推理速度要按硬件实测GPU 通常明显快于 CPU。如果视频检测掉帧严重可以考虑降低输入分辨率、使用更小的模型、或者跳帧检测不要追求每一帧都推理。6.3 摄像头实时检测测试如果系统里集成了摄像头检测测试时要检查设备号和权限。操作步骤用系统自带相机应用确认摄像头能正常打开。在系统里选择对应摄像头设备号通常是 0。将摄像头对准路面观察实时画面和检测框。常见问题摄像头画面黑屏多半是权限没开或设备号不对画面卡顿大概率是推理速度跟不上帧率需要降低分辨率或改用更小模型。6.4 批量检测测试批量检测适合巡检结束后处理大量照片逻辑上就是遍历文件夹里所有图片逐张推理并保存结果。from ultralytics import YOLO model YOLO(weights/best.pt) results model.predict( sourceinputs/road_photos/, imgsz640, conf0.35, saveTrue, save_txtTrue, projectoutputs/batch_results, namedetect ) print(批量检测完成共处理图片数量, len(results))当source指向目录时YOLO 会自动遍历目录下可识别的图片格式。saveTrue保存画框图片save_txtTrue保存检测结果的 txt 标注文件。批量完成后检查输出目录看有没有明显漏检的图片同时统计一张图的平均耗时评估整体处理效率。7. 批量任务设计与输出管理如果检测图片数量很大建议在批量逻辑里增加异常处理和输出整理。7.1 批量任务代码模板import os import traceback from pathlib import Path from ultralytics import YOLO input_dir Path(inputs/road_photos) output_dir Path(outputs/road_photos_results) output_dir.mkdir(parentsTrue, exist_okTrue) model YOLO(weights/best.pt) failures [] success_count 0 for img_path in input_dir.glob(*.jpg): try: result model.predict( sourcestr(img_path), imgsz640, conf0.35, saveTrue, projectstr(output_dir), namedetect, exist_okTrue ) success_count 1 except Exception: failures.append(str(img_path)) traceback.print_exc() print(成功处理, success_count) print(失败数量, len(failures)) for f in failures: print(失败文件, f)这样做的好处是单张图片损坏不会中断整批任务失败文件会被记录在案方便后续单独处理。7.2 输出结果管理结果目录建议按日期或批次命名避免多次运行相互覆盖outputs/ └── batch_20250101/ ├── detect/ │ ├── image_001.jpg │ ├── image_001.txt │ └── ... └── summary.csv有检测结果的图片和 txt 文件放在一起方便后续人工复核或二次筛选。如果要做统计报表可以遍历 txt 文件统计每张图的检测数量汇总后输出 CSV。8. 资源占用与性能观察很多人做完界面后最关心的问题就是“同样一张图我的配置能跑多快”。这类性能数据不能凭空给结论但可以给一套观察方法和调优思路。8.1 查看 GPU 占用训练和推理过程中可以通过nvidia-smi实时观察显存占用nvidia-smi -l 1每 1 秒刷新一次可以看到显存使用率、GPU 利用率等数据。观察时重点看两个指标显存使用量是否接近显卡上限GPU 利用率是否稳定在高位。如果是训练阶段关注模型大小、batch、分辨率对显存的影响如果是推理阶段关注单次推理耗时和显存峰值。8.2 CPU 推理和 GPU 推理的差异纯 CPU 推理在 YOLOv8 上也能跑但速度明显慢于 GPU尤其是大模型、高分辨率输入时差距会非常明显。做桌面工具时建议优先用 GPU 推理没有 GPU 的机器上测试要尽量使用yolov8n这样的小模型并把推理分辨率降到 640 甚至 480。8.3 调低显存的常见手段如果出现显存不足Out of Memory优先做这几件事调小batch训练时从 16 改成 8 或 4。调小imgsz从 640 改成 512 或 416。换更小的模型yolov8s换yolov8n。训练时开启 AMP 混合精度yolo train datadataset/data.yaml modelyolov8s.pt epochs100 imgsz640 batch16 device0 ampTrue推理单张图片时显存占用不大但如果批量处理或视频检测也要注意显存峰值。出现卡顿时先看是不是显存被打满。8.4 关于端口和进程PyQt5 桌面程序默认不占用固定端口所以一般不存在端口冲突问题。但如果你后来用 FastAPI 或 Flask 封装了检测服务就要注意端口占用。启动服务前先查端口Windowsnetstat -ano | findstr 8000Linux/macOSlsof -i :8000如果端口被占用换一个端口或结束占用进程。9. 常见问题与排查方法把项目开发中最容易踩的坑整理成清单遇到问题时可以对照排查。问题现象可能原因排查方式解决方案pip install ultralytics失败网络波动或依赖冲突查看 pip 报错信息换国内镜像源或升级 piptorch.cuda.is_available()返回 FalseCUDA 和 PyTorch 版本不匹配运行该命令查看结果安装匹配的 PyTorch 版本PyQt5 界面点按钮后卡死推理阻塞了 UI 线程在回调里打印耗时用 QThread 子线程推理点击检测没反应模型路径错误或权重损坏打印模型文件是否存在检查路径重新下载/导出权重摄像头黑屏设备号错误或权限未开启换 0/1测试系统相机授权摄像头或更换设备号训练时显存溢出batch 或 imgsz 太大查看 OOM 日志调小 batch/imgsz换小模型批量检测中途报错个别图片损坏在循环里加 try-except跳过坏图记录失败文件漏检严重训练数据中缺陷样本少查看验证集指标和混淆矩阵扩充数据、数据增强、降低置信度误检严重数据分布和测试场景差异大分析误检样本补充目标场景数据重新训练ONNX 导出失败torch 版本或算子问题查看导出日志升级 ultralytics/torch或调整 opset打包成 exe 后模型加载失败权重没有被打进包里检查打包目录用 PyInstaller--add-data把权重加入10. 最佳实践与下一步做一个“能跑”的检测系统不难但做一个“好用”的系统需要额外花功夫。第一个建议是先用最小配置跑通全流程。第一次训练不要直接上大模型和大 batch先用yolov8n、少量 epoch 验证数据格式、代码逻辑和环境是否正常。全流程通了再逐步加大参数。这样可以避免把时间浪费在排查数据和环境的低级问题上。第二个建议是做好文件目录管理。建议在项目根目录下固定datasets、weights、inputs、outputs四个目录训练数据、模型权重、测试素材、推理结果分开存放。时间一长这个习惯能省下很多找文件的麻烦。第三个建议是保留一份最小可运行配置。记录你训练用的data.yaml、best.pt和推理用的参数最好写进 README。这样即使电脑换了也能快速恢复环境。后续如果想继续扩展方向也很多用 FastAPI 把推理封装成 HTTP 接口方便其他团队调用。导出 ONNX 后用 OpenCV DNN 或 TensorRT 推理摆脱对 PyTorch 的依赖。在 PyQt5 界面里增加 FPS 显示、检测数量统计、结果导出 Excel 等实用功能。加入多类别检测比如坑洼、裂缝、修补块让系统更接近实际养护需求。增加雨雾、低光照数据增强提高恶劣天气下的鲁棒性。最后再提醒一个很容易被忽略的问题如果项目要商用或者公开发布一定要确认训练数据的来源和许可证。路面图片如果来自公开数据集要先看授权条款如果是自己采集的数据涉及街道和行人时要做好脱敏处理。这一步不做好功能再完善也有风险。初次尝试时建议先跑yolov8n加 50 个 epoch把数据集准备、界面集成、批量检测流程全部走通再考虑用更大模型提升精度。