一、项目整体概述

1. 项目目标

针对工业电路板 6 大类常见缺陷实现自动化视觉检测，数据集采用 PKU-Market-PCB 工业电路板缺陷数据集，固定检测 6 类缺陷：漏孔（missing_hole）、鼠咬（mouse_bite）、开路（open_circuit）、短路（short）、毛刺（spur）、杂铜（spurious_copper）。整套项目完成数据集处理→YOLOv8 模型训练→模型测试验证→ONNX 量化加速→PySide6 可视化 GUI 系统开发全链路落地，用机器视觉替代人工肉眼质检，实现缺陷自动定位、分类、尺寸测算、批量检测、检测结果归档，可部署在 Windows 工业工控电脑使用。

2. 整体技术栈

• 目标检测算法：YOLOv8，GPU 硬件：RTX3090Ti；深度学习框架：PyTorch、Ultralytics
• 模型加速方案：ONNX Runtime，将 PyTorch 模型导出为 ONNX 格式完成轻量化推理加速
• 桌面可视化软件：Python+PySide6，深色赛博科技 UI，对标 YOLO SHOW 工业检测软件布局
• 数据处理工具：OpenCV、Numpy；报表归档：CSV 文件；运行环境：Anaconda 独立 conda 虚拟环境

3. 项目全链路拆分

1. 数据集预处理、格式转换、数据集划分；
2. YOLOv8 模型训练、参数调优、收敛效果优化；
3. 测试集精度量化评估，统计漏检、误检情况；
4. 模型导出 ONNX，完成 GPU、CPU 双端推理加速验证；
5. PySide6 桌面 GUI 软件开发，实现检测可视化；
6. 功能迭代、UI 美化、交互逻辑 BUG 全量修复；
7. 最终功能闭环交付，支持日常调试与产线稳定使用。

二、分阶段完整项目历程

阶段 1：环境搭建与数据集预处理

1. 搭建独立yolov8专属 conda 虚拟环境，隔离所有依赖，安装 PyTorch、CUDA、Ultralytics、OpenCV、PySide6、ONNX Runtime 全套库，规避多项目版本冲突；
2. 获取 6 类工业缺陷数据集，将原始标注批量转换为 YOLO 标准 txt 标签格式，按照比例划分训练集、验证集、测试集；
3. 编写数据集可视化校验脚本，核对图片与标注一一对应，剔除破损图片、标注错误脏数据，保障训练数据质量。

阶段 2：YOLOv8 模型训练与多轮调参

1. 编写 YOLO 类别配置 yaml 文件，固定 6 类缺陷名称，配置推理输入分辨率、批次大小、学习率、总迭代轮次；依托 RTX3090Ti 开启 FP16 半精度加速训练，缩短训练耗时；
2. 多轮迭代调参：调整 IOU 阈值、置信阈值，新增翻转、缩放、色域扰动等数据增强手段，解决微小缺陷漏检、密集缺陷互相错检问题；针对电路板缺陷长宽特点优化锚框，提升小缺陷召回能力；
3. 训练全程记录损失曲线、精度曲线（Precision、Recall、mAP@0.5、mAP@0.5:0.95），保存最优迭代权重best.pt；
4. 针对过拟合问题，降低学习率、增加正则化、扩充训练样本，提升模型泛化能力。

阶段 3：模型测试评估与 ONNX 部署加速

1. 使用独立测试集批量推理，统计 6 类缺陷各自 AP 值、整体 mAP，汇总误检、漏检样本，反向优化训练数据集；
2. 完成轻量化部署方案：将训练最优 pt 权重导出为 ONNX 格式；
3. 使用 ONNX Runtime 完成 GPU、CPU 双端推理速度对比，验证 ONNX 可显著降低推理耗时，适配无独立显卡的普通工控机；
4. 编写批量推理测试脚本，自动计算缺陷像素宽、高、面积、坐标，为 GUI 表格字段提供标准化计算逻辑。

阶段 4：初代 GUI 桌面软件开发（基础功能落地）

1. 基于 PySide6 开发 Windows 桌面软件，初期采用简约白底布局，实现单张图片检测、批量文件夹图片检测两大核心能力；
2. 表格标准化记录：图片文件名、良品 / 缺陷判定、缺陷类别、置信度、xyxy 像素坐标、像素宽高、缺陷面积、单图推理耗时；
3. 顶部状态栏展示总缺陷类别数量、实时检测缺陷总数 Targets、推理 FPS、当前加载模型名称；支持一键导出全部检测记录为 CSV 文件；
4. 支持手动选择任意 YOLO pt 权重文件，模型自动读取内置类别，无需手动修改代码内类别数组，兼容多版本训练模型。

阶段 5：交互逻辑与界面多轮整改优化

1. 路径问题整改：舍弃不稳定的相对路径，设置默认模型绝对路径，新增「选择 YOLO 模型」按钮可自由浏览挑选权重，解决权重文件找不到导致程序闪退问题；彻底去除硬编码固定类别，每次加载模型自动读取类别名称与数量；
2. 交互逻辑重大重构：拆分「选择图片」和「执行推理」动作，新增独立开始推理按钮。运行规则：必须成功加载模型、选中单图 / 批量图片文件夹缓存后，点击开始推理才执行检测，杜绝打开图片自动推理，避免误操作；单图、批量缓存互斥，打开单张清空批量缓存，打开批量清空单图缓存；
3. 表格显示优化：深色 UI 下表格文字改为纯黑色，解决深色底色浅色文字看不清；表头自适应拉伸，所有字段完整展示无截断；批量检测逐张处理、逐行刷新表格，处理完一张实时渲染界面，无需全部图片跑完才一次性加载，界面全程无冻结；
4. 顶部布局按需精简优化，最终固定顶部 4 个功能卡片：YOLO（实时 FPS）、Classes（总类别数）、Targets（实时缺陷数量）、Model（完整模型路径）。

阶段 6：深度 UI 定制美化，对标工业赛博参考界面

1. 整体底色修改为深蓝深色科技风，所有面板、按钮、边框增加霓虹青蓝色圆角发光边框，打造工业赛博视觉风格；
2. 顶部 4 个状态栏卡片使用横向渐变配色（青蓝、紫粉、玫紫、蓝紫），圆角卡片搭配深色加粗文字，层级区分明显；
3. 左侧设计竖向图标侧边导航栏，圆形功能图标按钮，布局对齐参考 YOLO SHOW 工业软件；
4. 界面中间为左右均等双圆角面板，分别承载原图、缺陷标注检测效果图；底部左侧垂直排布功能按钮，右侧自适应检测表格，最下方配置进度条；
5. 全部控件使用弹性 Layout 布局管理，窗口可自由缩放，所有组件自动适配拉伸，不会出现控件错位、挤压、遮挡；按钮配置 hover 变色动效，表头加粗分层，整体视觉满足工业软件专业美观要求。

阶段 7：全功能闭环验收与稳定性加固

1. 功能全链路闭环：模型加载（默认绝对路径 + 手动选权重）、单图检测、批量文件夹检测、开始推理触发机制、图片可视化标注、多字段表格记录、CSV 导出、FPS 实时刷新、批量进度可视化；
2. 程序鲁棒性优化：未加载模型、未选择图片时点击开始推理给出提示，不会触发空对象报错；坐标计算全程取绝对值，缺陷长宽、面积永远为正数；推理放到子线程运行，主线程只负责 UI 渲染，拖动、缩放窗口全程不卡顿；
3. 双推理方案兼容：原生 PyTorch GPU 推理、ONNX Runtime 轻量化推理均可使用，适配不同硬件设备；
4. Windows 可打包为独立 exe，交付工厂使用时无需配置 Python、深度学习环境。

三、全项目历史问题汇总及解决方案

（一）训练、加速阶段问题汇总

表格

问题	落地解决方案
微小工业缺陷漏检率偏高	适配缺陷尺寸重新优化锚框，新增小目标专属数据增强，上调 IOU 匹配阈值
训练后期过拟合，新样本泛化能力差	增加随机裁剪、色彩扰动，降低学习率，启用早停策略，扩充训练数据集
PyTorch 原生推理速度慢，无 GPU 工控机无法流畅运行	pt 模型导出 ONNX，依托 ONNX Runtime 加速，CPU 设备推理速度大幅提升
不同电脑 CUDA 版本不一致，环境难以复刻	使用独立 conda 环境固定全部版本；ONNX 脱离 CUDA 强绑定，跨电脑兼容性更强

（二）GUI 代码报错类问题

1. 报错name YOLO not defined：代码头部缺失from ultralytics import YOLO导入语句，补齐导入代码即可；
2. 报错No such file or directory：相对路径稳定性差，默认模型修改为绝对路径，同时开放手动选择权重入口；
3. 报错NoneType object is not callable：模型加载失败导致self.yolo_model=None，推理调用时报错；新增模型判空逻辑，加载失败禁用推理并打印日志；
4. 批量检测界面卡死阻塞：主线程循环推理阻塞 UI；改用子线程执行推理，每张图片处理完成调用界面刷新函数实时更新。

（三）交互逻辑缺陷整改

1. 选中图片自动推理，缺少人工确认环节：拆分操作流程，打开图片仅缓存路径，必须手动点击「开始推理」才执行检测；
2. 批量文件夹选择后直接自动运行：批量操作仅遍历缓存所有图片路径，不执行推理；所有推理逻辑收拢到开始推理按钮内。

（四）界面显示类问题

1. 深色主题表格浅色文字辨识度低：表格单元格强制设置黑色字体，深色底色搭配黑色文字清晰可读；
2. 表格表头字段缺失、列被截断：修改表头自适应模式为ResizeToContents，列宽度适配内容，末尾列自动拉伸铺满窗口；表头加粗区分内容行；
3. 窗口缩放后控件错位、挤压：全界面使用布局管理器管理控件，放弃固定坐标定位，所有面板弹性自适应；
4. Model 卡片仅显示文件名，无法确认加载权重：Model 卡片展示完整绝对路径，切换模型实时刷新路径文本；
5. 顶部卡片冗余：删减多余卡片，最终固定顶部四栏布局，匹配参考 UI 设计。

（五）业务计算逻辑问题

1. 缺陷 xyxy 坐标存在负数，长宽、面积出现负值：宽高计算增加abs()绝对值处理，保证尺寸、面积恒为正数；
2. 重复检测表格历史数据不会清空：新增表格内存列表，支持逐条追加，CSV 读取全部内存记录；
3. FPS、耗时计算不准：统一采用全链路计时（图片读取 + 推理 + 后处理完整耗时），FPS 基于单张总耗时实时换算。

（六）模型适配拓展问题

1. 更换其他训练模型，界面缺陷类别错乱：不再硬编码类别列表，每次加载模型自动读取model.names，顶部类别数量自动同步刷新；
2. 置信阈值修改繁琐：全局统一置信常量CONF_THRESH，一处修改全程序生效。

四、最终落地完整功能清单

1. 算法底层检测能力

1. YOLOv8 识别 6 类工业缺陷，输出缺陷类别、置信度、xyxy 像素坐标；
2. 自动计算缺陷像素宽度、高度、面积，区分 OK 良品（无缺陷）、NG 缺陷（存在缺陷）；
3. 支持 PyTorch GPU 推理、ONNX Runtime 轻量化 CPU/GPU 双方案；
4. 全局置信阈值可统一修改，适配不同质检严苛标准。

2. 桌面 GUI 软件全功能

1. 软件标题：常规 6 类缺陷检测系统，深色赛博工业 UI；左侧竖向图标侧边导航栏；
2. 顶部 4 个渐变圆角卡片：YOLO（实时 FPS）、Classes（总缺陷类别数）、Targets（实时缺陷数量）、Model（模型完整路径）；
3. 中间左右两大圆角面板：原图预览、缺陷标注检测效果图预览；
4. 左侧垂直功能按钮：打开单张图片、批量文件夹检测、选择 YOLO 模型、开始推理、导出 CSV；
5. 检测明细表格 9 列完整字段：文件名、判定结果、缺陷类别、置信度、xyxy 像素坐标、像素宽度、像素高度、像素面积、单张耗时；黑色字体，表头自适应；
6. 窗口最底部进度条可视化批量检测进度；所有控件自适应窗口拉伸，按钮 hover 带变色动效，全面板圆角霓虹边框；
7. 缓存互斥机制：单图、批量路径分开缓存，只有点击开始推理才执行检测；
8. 防护机制：无模型、无图片时点击开始推理给出提示，程序不会崩溃；
9. 一键将全量检测表格导出为 CSV 文件，支持自定义保存路径，检测数据全程内存留存。

3. 工程化落地能力

1. 独立 conda 环境，依赖清单可完整复刻；
2. 模型双模式加载：默认绝对路径 + 手动浏览选择权重，适配文件路径变动；
3. 全链路代码可复现：训练代码、测试脚本、ONNX 导出脚本、GUI 源码完整归档；
4. Windows 支持打包为独立 exe 文件，可在无 Python 环境的工控机直接运行。

五、项目收获与复盘总结

1. 技术能力收获

1. 完整掌握工业缺陷检测全闭环流程：数据集处理→模型训练调优→多端加速→桌面软件落地，熟练掌握 YOLO 系列针对小缺陷、密集缺陷的调优思路；
2. 熟练使用 PySide6 完成工业软件分层开发、QSS 深色霓虹样式美化、多线程防卡顿、交互逻辑拆分；掌握界面自适应布局、表格动态渲染、路径容错等工程化写法；
3. 掌握 ONNX 模型导出、Runtime 跨硬件加速方案，实现 GPU、CPU 设备兼容部署；
4. 积累工业软件交互设计经验：拆分资源选择与执行动作，避免程序自动运行，给人工确认空间，适配工厂产线操作习惯。

2. 现存不足与后续优化方向

1. 当前置信阈值只能改代码，后续可新增滑动条控件，可视化实时调整；
2. 可新增检测完成图片自动归档功能，按良品 / 缺陷分类保存；
3. 增加统计可视化模块：缺陷数量统计饼图、整体良品率实时统计；
4. 拓展视频流检测，适配流水线工业摄像头实时检测；
5. 增加一键清空表格、清空历史缓存按钮。

3. 项目整体落地价值

实现工业电路板缺陷质检全流程数字化，用机器视觉替代人工目检，可落地电子加工厂质检工位；整套算法方案可快速迁移到各类电子元器件表面缺陷检测场景；GUI 软件兼顾算法研发调试灵活性与产线工人简易操作，美观度、稳定性、易用性兼顾，适配研发调试与工业化量产两套使用场景。