云计算百科
云计算领域专业知识百科平台

从零拆解一个 YOLOv8 安全帽检测系统:模型训练 + PyQt5 桌面端的完整工程结构


 

做安全帽检测的练手项目很多,但大多数只给一个 train.py 和一个 detect.py,真正把它做成「能点、能存、能看」的桌面软件的资料并不多。这篇文章按工程真实的文件顺序往下拆:先讲清楚这个任务到底难在哪、方案为什么这么分层,再把 YOLOv8 的网络结构与损失讲透,然后是数据集组织、训练超参、训练日志里那条曲线到底说明了什么,接着逐段读核心代码,最后给出部署步骤、常见报错排查表和一份老实的效果分析。读完你应该能独立复现这套流程,也能判断别人博客里那些「准确率 98%」到底靠不靠谱。


一、项目背景

施工现场的安全帽佩戴检查,本质是一个双类别检测问题:既要找到「人」,也要判断「人头上有没有安全帽」。注意这里不是分类任务——分类只能回答「这张图里有没有人没戴帽子」,一旦画面里有五个人、三个戴了、两个没戴,分类就彻底失效。检测才能给出「哪一个人没戴、在画面哪个位置」,这也是后续要输出坐标、要联动报警、要给巡检留证据的前提。

这个项目把它落成一套桌面工具:

  • 输入:单张图片、图片文件夹、视频文件、USB 摄像头
  • 输出:带框的结果图/结果视频、逐目标的类别/置信度/坐标表格
  • 交互:下拉框选中某个目标后,右侧面板回填它的具体坐标与置信度

界面标题就是「基于Yolov8安全帽检测与识别系统」,检测类别只有两类:

类别 iddata.yaml界面显示
0 hat 安全帽
1 person 人

从业务角度看,这两个类别其实是配套关系:只检测「人」,你不知道他戴没戴;只检测「安全帽」,画面里没人时你无法判断是「没人」还是「有人没戴」。所以正确用法是把 person 框和 hat 框做空间比对——如果某个 person 框的头部区域内不存在 hat 框,就判定为未佩戴。这个比对逻辑工程里没有实现(属于功能缺口),但它恰恰是这类系统最有价值的延伸方向,后面「可优化方向」里会展开。

坑点提醒 1:Config.py 里又把 0 类写成 helmet,和 data.yaml 的 hat 不一致。界面显示统一用 CH_names = ['安全帽', '人'],所以不影响使用,但你重新训练后一定要把三处(data.yaml 的 names、Config.names、Config.CH_names)对齐,否则 yaml 里改类名、界面还在按旧索引取中文名,就会出现「检测出 person 却显示成安全帽」的经典错位。


二、整体技术方案

整个工程可以分成三层,职责非常清晰:

层文件职责
模型层 train.py、yolov8n.pt、models/best.pt 训练与权重管理,推理统一走 Ultralytics 的 YOLO.predict
推理/工具层 MainProgram.py、detect_tools.py 图片/视频/摄像头统一调度,画框、中文渲染、坐标转换、视频写出
界面层 UIProgram/UiMain.py、style.css、QssLoader.py Qt Designer 生成的界面 + QSS 皮肤 + 信号槽绑定

几个关键设计选择,都是踩过坑之后才会这么写的:

  • 模型只加载一次:initMain() 里 YOLO(Config.model_path, task='detect') 之后,立刻用 np.zeros((48,48,3)) 跑一次空推理做预热。第一次推理要建图、加载 cuDNN kernel,界面会「假死」两三秒;把这份代价提前到启动阶段,用户点检测时才是即时响应。这个技巧在任何「模型 + GUI」组合里都值得抄。
  • 设备自适应:self.device = 0 if torch.cuda.is_available() else 'cpu',没有 GPU 也能跑,只是慢。注意:这行赋值在工程里只写进了实例属性,model.predict 并没有显式传 device,所以实际设备由 Ultralytics 内部自动判断决定——想强制指定设备,得在推理时显式传 device=self.device。这算一处「写了但没接上」的半成品代码。
  • 配置与代码分离:模型路径、保存目录、中英文类名全在 Config.py,换模型不用改主程序。
  • 中文绘制:OpenCV 的 cv2.putText 只支持 ASCII,画中文会变成一排问号。工程里用 ImageFont.truetype("Font/platech.ttf", 25, 0) 配合 PIL 渲染中文标签,再把 PIL 图转回 numpy 数组,字体文件随项目附带。
  • 先看一张这个工程的真实输出,后面所有的代码都是为了复现这张图:

    图 9 单图检测效果 1

    以上为工程 save_data 目录中保存的实际检测结果(由 MainProgram.py 的图片检测流程输出,带类别与置信度标签)。


    三、算法原理:YOLOv8 是怎么把"找框"和"分类"一次做完的

    很多人会用 model.train(),但说不清 backbone 里到底发生了什么。这一节把与本项目直接相关的部分讲清楚,不涉及论文里那些与本任务无关的消融细节。

    3.1 整体结构:Backbone + Neck + Head

    YOLOv8 是典型的单阶段(one-stage)、Anchor-Free 检测器,一次前向就同时输出「框的位置」和「框的类别」,不像 Faster R-CNN 那样先出候选区域再逐个分类,所以延迟低、适合视频与摄像头这种连续推理场景。

    • Backbone(主干):由若干 Conv 与 C2f 模块堆叠,再加一个 SPPF。C2f 是 YOLOv8 相对 YOLOv5 的主要改动之一:它在跨层连接上做了更充分的分支与拼接,让梯度流动更顺、特征复用更充分;SPPF 用串联的多个最大池化等效扩大感受野,代价远低于大核卷积。这两个模块共同决定了「特征提得准不准」。
    • Neck(颈部):PAN-FPN 结构,自顶向下传语义、自底向上传定位细节。对安全帽这种「小目标 + 密集遮挡」的场景,Neck 里的高分辨率支路尤其关键——安全帽在远景图里可能只有 20×15 像素,全靠 P3 这类浅层高分辨率特征图才抓得住。
    • Head(头部):解耦头(decoupled head),分类分支和回归分支分成两条独立的小卷积通路,各自学各自的,避免「分类与定位目标不一致」的相互干扰。输出是 anchor-free 的,直接回归到网格中心到框边的距离,再用 DFL(Distribution Focal Loss) 把距离建模成一个离散分布取期望,这样边界回归更平滑,对小目标的亚像素级偏差更友好。

    3.2 损失函数:三个部分各管一件事

    训练时总损失由三项加权构成,results.csv 里也正好对应三列,读日志时必须分清楚:

    损失项日志列名管什么异常表现
    框回归损失 train/box_loss、val/box_loss 预测框与真值框的位置偏差(CIoU 一类) 一直高 → 定位学不动,检查标注框是否错位/归一化错误
    分类损失 train/cls_loss、val/cls_loss 类别判对没有(BCE) 高且不降 → 类名映射错、类别不平衡
    分布焦点损失 train/dfl_loss、val/dfl_loss 边界距离分布的精细程度 高 → 小目标多、边界模糊

    理解这三项的意义在于:当你的 mAP 卡住不动时,先看是哪一项在拖后腿,而不是盲目加轮数。本项目的日志里 train/box_loss 从 1.5328 一路降到 1.255,而 val/box_loss 在 1.38~1.47 之间反复横跳,这个「训练降、验证不降」的剪刀差就是典型的轻微过拟合信号,后面第六节会用真实数字展开。

    3.3 推理后处理:置信度阈值 + NMS

    模型原始输出是成千上万个候选框,真正变成我们能看到的几个框,靠两步:

  • 置信度过滤:低于阈值(Ultralytics 默认 conf=0.25)的框直接丢弃。工程里没有把 conf 暴露到界面上,用的是库默认值——这也是个可优化点,工业场景通常会把 conf 提到 0.4~0.5 以减少误报。
  • NMS(非极大值抑制):同一目标被重复预测出多个框时,按置信度排序后抑制重叠度(IoU)超过阈值的低分框。人群密集场景里 NMS 阈值调太高会「一个框吞掉两个人」,调太低会「同一个人出三个框」,这是调参时最需要肉眼验证的一步。
  • 另外,输入图会先经过 letterbox 缩放到 imgsz=640(保持长宽比、灰边填充),推理完再把框坐标反向映射回原图尺寸。这一层在工程里由 results.plot() 自动完成,不需要手写,但你要知道框坐标为什么和原图尺寸对得上。


    四、数据集构建与标注细节

    数据集放在 datasets/helmetData,标准 YOLO 结构(图片与同名 txt 标签分目录):

    datasets/helmetData/
    ├── data.yaml
    ├── train/{images, labels}
    ├── valid/{images, labels}
    └── test/{images, labels}

    实际规模(逐文件统计):

    划分图片数标签数
    train 6026 6017
    valid 763 762
    test 792 792
    合计 7581 7571

    train/valid 里有少量「有图无标签」的样本(train 差 9、valid 差 1),这通常是负样本(画面里既没帽子也没人),YOLO 允许这种空标签文件缺失或为空,属于正常现象,不要手贱去补。

    data.yaml 原文:

    train: F:\\Mlwork\\YOLOv8hat-helmet\\datasets\\helmetData\\train
    val: F:\\Mlwork\\YOLOv8hat-helmet\\datasets\\helmetData\\valid
    test: F:\\Mlwork\\YOLOv8hat-helmet\\datasets\\helmetData\\test
    nc: 2
    names: ['hat', 'person']

    两个必须注意的点:

    • 绝对路径:这是原作者本机路径,你搬到自己机器上必须改,否则一启动训练就报 Dataset not found。建议改成相对 path + train/val 组合,可移植性更好。
    • 文档滞后:项目里的 程序运行说明文档.txt 在「模型训练」章节还写着另一个项目 FireSmokeData 的示例路径,那是作者复制模板时漏改的。以 data.yaml 为准。

    4.1 标注格式与坐标换算

    YOLO 的标签是「一行一个目标」,格式为 class cx cy w h,后四个都是相对图像宽高的归一化值(0~1)。这种写法的好处是标签与分辨率无关,图片随便缩放都不用重标;坏处是人眼不可读,画图验证时必须换算。

    工程在 detect_tools.py 里就内置了这一对互逆函数,是排查标注问题最实用的工具:

    def yolo_to_location(w, h, yolo_data):
    # yolo文件转两点坐标,注意画图坐标要转换成int格式
    x_, y_, w_, h_ = yolo_data
    x1 = int(w * x_ – 0.5 * w * w_)
    x2 = int(w * x_ + 0.5 * w * w_)
    y1 = int(h * y_ – 0.5 * h * h_)
    y2 = int(h * y_ + 0.5 * h * h_)
    return [x1, y1, x2, y2]

    def location_to_yolo(w, h, locations):
    x1, y1, x2, y2 = locations
    x_ = float('%.5f' % ((x1 + x2) / 2 / w))
    y_ = float('%.5f' % ((y1 + y2) / 2 / h))
    w_ = float('%.5f' % ((x2 – x1) / w))
    h_ = float('%.5f' % ((y2 – y1) / h))
    return [x_, y_, w_, h_]

    配套的 draw_yolo_data(img_path, yolo_file_path) 会把某张图的 txt 标注画成红框并 imshow,标注错位、漏标、类标反了这三类问题,用它跑一遍 20 张就能发现。

    坑点提醒 2:location_to_yolo 保留 5 位小数是够用的(1/100000 的图像宽度,远小于视觉可辨差异),但千万别自己改成 2 位——归一化值 0.37 与 0.375 差的是整张图 0.5% 的宽度,密集小目标场景会直接把框推到隔壁目标身上。

    4.2 数据分布与增强策略

    训练前必看的一张图是 Ultralytics 自动生成的数据集统计图,它把标注框的尺寸分布、中心点分布、长宽比分布画在一起,能一次性暴露「小目标占比多少」「框都挤在画面中间」这类问题:

    图 2 数据集标注分布统计

    从这张图可以直接读出两件事:一是标注框尺寸分布较宽(说明数据里既有近景大目标也有远景小目标),二是中心点分布集中在画面中部(符合工地上「人站在画面中」的拍摄习惯)。这类分布如果严重偏离训练场景,就该补数据而不是调超参。

    YOLOv8 默认开启的训练增强里,对本项目影响最大的是 Mosaic:把 4 张图随机缩放、裁剪、拼接成一张,相当于在不增加显存的前提下把 batch 内样本数翻了 4 倍,还顺带造出大量「小目标 + 新背景组合」。工程 args.yaml 里 mosaic=1.0(始终开启)、close_mosaic=10(最后 10 轮关闭)。最后 10 轮关掉 Mosaic 是必要的——Mosaic 造出来的拼接图与真实场景分布不一致,关掉它让模型在真实分布上收尾,指标通常会有一次明显抬升。

    图 3 Mosaic 数据增强后的训练批次样本

    上图是训练批次第 0 批的真实样本,可以看到四图拼接的边界、灰边填充,以及部分目标被裁掉只剩半个框——这些都是 Mosaic 的正常产物,不是标注错误。


    五、训练超参与训练环境

    训练脚本非常短,但每一行参数都值得逐项说:

    #coding:utf-8
    from ultralytics import YOLO

    model = YOLO("yolov8n.pt") # 加载预训练模型

    if __name__ == '__main__':
    results = model.train(data='datasets/helmetData/data.yaml',
    epochs=150, batch=4, patience=300)
    # 将模型转为onnx格式
    # success = model.export(format='onnx')

    • yolov8n.pt:n 是最小的 YOLOv8,参数量小、推理快,适合桌面端 + 实时视频这种对延迟敏感的场景。工程内没有记录具体参数量与 FLOPs(待补充)。
    • epochs=150、batch=4:batch 只有 4,说明训练机器显存很紧张(4GB 级别的卡)。显存够的话建议 16~32,训练更稳。
    • patience=300:早停耐心值设得比总轮数还大,等于早停实际永远不会触发,一定会跑满 150 轮。如果你希望早停生效,patience 要明显小于 epochs。
    • if __name__ == '__main__'::Windows 上 DataLoader 多进程必须加这一句,否则容易报 freeze_support 相关错误。

    更完整的超参不在 train.py 里,而在训练输出目录自动留存的 args.yaml。工程里保留了三轮训练的痕迹,results.csv 实际存在于 train2、train4、train5。把两份 args.yaml 摊开对比,能看出作者两次训练的思路变化:

    超参train2train4说明
    model yolov8n.pt yolov8n.pt n 尺度不变
    data datasets/helmetData/data.yaml 同左 同一份数据
    epochs 200 150 把轮数砍下来了
    batch 32 4 显存受限后的妥协
    patience 50 300 train2 是真的会早停,train4 等于关掉早停
    workers 32 8 进程数同步下调
    imgsz 640 640 默认分辨率
    optimizer auto auto 由框架自动选(SGD/AdamW 择一并调 lr)
    lr0 0.01 0.01 初始学习率
    warmup_epochs 3.0 3.0 前三轮预热,防早期梯度爆炸
    close_mosaic 10 10 末 10 轮关 Mosaic
    mosaic / fliplr 1.0 / 0.5 1.0 / 0.5 拼接 + 水平翻转
    degrees / translate / scale 0.0 / 0.1 / 0.5 0.0 / 0.1 / 0.5 不旋转,平移 10%,缩放 50%
    mixup 0.0 0.0 未启用
    device null null 自动选择
    cache false false 未缓存到内存

    一个很容易被忽略的细节:train.py 里的参数和 train4 完全一致,而 train2 的 epochs=200 / batch=32 / patience=50 显然来自另一次手动传入。所以你在博客或论文里写「本系统训练参数为 epochs=150, batch=4」时,说的其实只是 train.py 当前版本 + train4 那一次;train2 那次是用更大的 batch 跑的,两者不能混着引用。

    训练环境方面,工程没有留存环境快照或 nvidia-smi 输出,因此显卡型号、CUDA 版本、单轮耗时、总训练时长均(待补充)。从 batch=4 与 workers=8 这组偏保守的配置反推,训练机器显存大概率在 4~6 GB 区间,但这只是推断,不能当结论写进文档。

    坑点提醒 3:requirements.txt 里列了 31 项依赖,但 pillow 没有写进去,而主程序在处理检测结果时会用到 PIL;同时 torch==1.9.0 与 ultralytics==8.0.199 这个组合偏老,新装环境时建议直接装新版本 torch,别按 requirements 硬装——旧版 torch 在新驱动上经常报 sm_xx is not compatible。装完先跑一句 from ultralytics import YOLO 验证,比训练到一半才崩要省时间。


    六、训练过程与指标分析

    先把三次训练的真实记录摆出来(全部取自 runs/detect/*/results.csv 的末行与最佳行):

    训练目录参数记录轮次最佳轮次PRmAP@0.5mAP@0.5-0.95
    train2 epochs=200, batch=32 到第 177 轮 第 162 轮 0.90749 0.87476 0.93273 0.60291
    train4 epochs=150, batch=4 跑满 150 轮 第 82 轮 0.91713 0.85287 0.92972 0.60259
    train5 epochs=150, batch=4 第 3 轮中断 第 2 轮 0.83633 0.73238 0.80050 0.47195

    这张表是训练日志的原始记录,统一标注为「对应轮次训练日志记录值」。models/best.pt 到底来自哪一轮、在验证集上的真实精度是多少,工程里没有标注,属于信息缺口。要在论文或博客里写准确率,正确做法是拿 models/best.pt 重新跑一次 model.val() 取值,而不是从 csv 里挑一个最好看的数字。

    下面这条曲线是 train2 全程 177 轮的可视化,三行分别是 box/cls/dfl 损失,两列是训练集与验证集:

    图 1 YOLOv8 安全帽检测训练曲线(train2,共 177 轮)

    光看图看不出精确数值,所以把关键轮次从 csv 里抽出来对齐看:

    轮次mAP@0.5PrecisionRecalltrain/box_lossval/box_loss
    1 0.66489 — — — —
    10 0.85001 0.87199 0.79009 1.5328 1.4758
    25 0.89816 0.89599 0.83095 1.4514 1.4230
    50 0.91088 0.89627 0.83393 1.4087 1.3982
    75 0.92608 0.90903 0.85711 1.3861 1.3842
    100 0.92994 0.89605 0.87355 1.3426 1.3852
    125 0.93129 0.89625 0.87581 1.3147 1.3834
    150 0.93066 0.89981 0.87864 1.2883 1.3908
    175 0.93214 0.90906 0.87593 1.2550 1.3935

    从这张表能读出四个结论,都是数字直接支撑的:

  • 收敛极快:第 1 轮 mAP@0.5 就有 0.66489,第 10 轮 0.85001,第 25 轮已经 0.89816。这主要归功于 yolov8n.pt 的预训练权重——它已经在 COCO 上学会了「什么是人形」「什么是圆形物体」这类通用特征,微调只需要适配本任务的类目与场景。这也是为什么这类项目「不用几轮就能出效果」,但不代表可以少跑,后期那一两个点的提升才是从「能用」到「好用」的差别。
  • 50 轮后进入平台期:第 50 轮 0.91088,第 75 轮 0.92608,第 125 轮 0.93129,第 175 轮 0.93214。后 100 轮的累计提升不到 2 个百分点,说明数据本身的信息量已经被挖得差不多,再加轮数收益极低。若想把 mAP 提到 0.95 以上,靠训练时间没用,得靠补数据(更多夜间、逆光、密集人群样本)。
  • 训练损失与验证损失出现剪刀差:train/box_loss 从 1.5328 单调降到 1.2550(降 18%),而 val/box_loss 只在 1.3842~1.4758 之间波动、整体几乎不降。这是模型开始记忆训练集细节、泛化能力停止增长的典型信号。日志里 train2 在第 162 轮达到最佳 mAP@0.5=0.93273 后,第 177 轮反而略降到 0.93189,属于正常的末端抖动,不值得为它调参。
  • Precision 始终高于 Recall:末轮 P=0.9078 / R=0.87638,差约 3 个百分点。说明模型的性格是「宁可少报,不乱报」,漏检略多于误检。安全帽检测场景下这个倾向是偏安全的(误报一次要人工复核,漏检一次可能出人命),反过来说如果想更严格,应该降低推理 conf 阈值来换 Recall。
  • 验证集的真值与模型预测放在一起对比,能直观看出漏检与误检发生在什么位置:

    图 4 验证集标注真值

    图 5 同一批验证图的模型预测结果

    对比这两张图(同一批验证图、左真值右预测),可以看到小目标和遮挡目标的差异最明显——这也是 recall 上不去的主要原因。

    混淆矩阵给出了更细的粒度:不只是「对了几成」,而是「错成了什么」:

    图 6 混淆矩阵

    两类别场景的混淆矩阵只有 3×3(hat / person / background),读法很简单:对角线是判对的,右上三角是「把 hat 判成 person」这类类别互换错误,最后一列是「真实存在但没检出来」,最后一行是「凭空多检出来的框」。安全帽与人的混判在理论上不该出现(两者尺寸、位置差异巨大),如果这两格数值偏高,第一嫌疑就是类名映射错位——也就是第一节那个 hat vs helmet 的坑。

    PR 曲线展示的是不同置信度阈值下 Precision 与 Recall 的权衡,曲线下面积(AUC)就是 AP;F1 曲线则是把两者合成一个指标,峰值点对应「综合最优的置信度阈值」:

    图 7 PR 曲线

    图 8 F1 值随置信度阈值变化

    这两张图的实际用法:F1 曲线的峰值横坐标,就是这套模型在部署时最该设置的 conf 值。工程里用的是库默认 0.25,如果你希望现场误报更少,就往峰值右侧挪;希望不漏人,就往左挪。这是把「指标」翻译成「产品决策」的关键一步,比在博客里写一句「mAP 0.93」有用得多。


    七、核心代码逐段解读

    7.1 启动与初始化:把贵的东西放在最前面

    class MainWindow(QMainWindow):
    def __init__(self):
    super().__init__()
    self.ui = Ui_MainWindow()
    self.ui.setupUi(self)
    self.initMain()
    self.signalconnect()

    __init__ 只做三件事:搭界面、初始化资源、绑信号。顺序不能换——initMain() 里要操作 self.ui 的表格控件,必须等 setupUi 之后。

    def initMain(self):
    self.show_width = 770
    self.show_height = 480
    self.org_path = None
    self.is_camera_open = False
    self.cap = None
    self.device = 0 if torch.cuda.is_available() else 'cpu'

    self.model = YOLO(Config.model_path, task='detect')
    self.model(np.zeros((48, 48, 3))) # 预先加载推理模型
    self.fontC = ImageFont.truetype("Font/platech.ttf", 25, 0)

    self.ui.tableWidget.verticalHeader().setSectionResizeMode(QHeaderView.Fixed)
    self.ui.tableWidget.verticalHeader().setDefaultSectionSize(40)
    self.ui.tableWidget.setColumnWidth(0, 80)
    self.ui.tableWidget.setColumnWidth(1, 200)
    self.ui.tableWidget.setColumnWidth(2, 150)
    self.ui.tableWidget.setColumnWidth(3, 90)
    self.ui.tableWidget.setColumnWidth(4, 230)
    self.ui.tableWidget.setSelectionBehavior(QAbstractItemView.SelectRows)
    self.ui.tableWidget.verticalHeader().setVisible(False)
    self.ui.tableWidget.setAlternatingRowColors(True)

    • self.model(np.zeros((48,48,3))) 就是前面说的空图预热。注意这行不是「多余的推理」——它触发了 Ultralytics 内部的模型 fuse、设备搬运与首次前向,省掉的就是用户第一次点按钮时那两三秒。
    • ImageFont.truetype("Font/platech.ttf", 25, 0) 用相对路径读字体,所以必须在项目根目录启动程序,否则 drawRectBox 会抛 OSError: cannot open resource。这是新手最常见的启动失败原因之一。
    • 表格那七行是把 Qt 表格「调成人能看的样子」的标准配方:行高 40 不挤、隐藏左侧行号栏、整行选中而不是单格选中、奇偶行交替配色便于横向读。后五项(列宽)与业务字段一一对应,改动列顺序时必须同步改这里。

    7.2 信号绑定:一处集中,便于维护

    def signalconnect(self):
    self.ui.PicBtn.clicked.connect(self.open_img) # 单图
    self.ui.FilesBtn.clicked.connect(self.detact_batch_imgs) # 文件夹批量
    self.ui.VideoBtn.clicked.connect(self.vedio_show) # 视频
    self.ui.CapBtn.clicked.connect(self.camera_show) # 摄像头(开关式)
    self.ui.SaveBtn.clicked.connect(self.save_detect_video) # 保存结果
    self.ui.ExitBtn.clicked.connect(QCoreApplication.quit) # 退出
    self.ui.comboBox.activated.connect(self.combox_change) # 目标下拉选择

    把所有 connect 集中在一个方法里,好处是「界面有哪些能力」可以一眼看完,不用在几千行里翻。这也是 Qt 项目的推荐写法。

    7.3 单图推理:从路径到像素,再到表格

    def open_img(self):
    if self.cap:
    self.video_stop()
    self.is_camera_open = False
    self.ui.CaplineEdit.setText('摄像头未开启')

    file_path, _ = QFileDialog.getOpenFileName(None, '打开图片', './',
    "Image files (*.jpg *.jepg *.png)")
    if file_path:
    self.ui.comboBox.setDisabled(False)
    self.org_path = file_path
    self.org_img = tools.img_cvread(self.org_path)

    t1 = time.time()
    self.results = self.model(self.org_path)[0]
    t2 = time.time()
    self.ui.time_lb.setText('{:.3f} s'.format(t2 – t1))

    location_list = self.results.boxes.xyxy.tolist()
    self.location_list = [list(map(int, e)) for e in location_list]
    cls_list = self.results.boxes.cls.tolist()
    self.cls_list = [int(i) for i in cls_list]
    conf_list = self.results.boxes.conf.tolist()
    self.conf_list = ['%.2f %%' % (each * 100) for each in self.conf_list]

    now_img = self.results.plot()
    self.draw_img = now_img
    self.img_width, self.img_height = self.get_resize_size(now_img)
    resize_cvimg = cv2.resize(now_img, (self.img_width, self.img_height))
    pix_img = tools.cvimg_to_qpiximg(resize_cvimg)
    self.ui.label_show.setPixmap(pix_img)
    self.ui.label_show.setAlignment(Qt.AlignCenter)
    self.ui.PiclineEdit.setText(self.org_path)
    self.tabel_info_show(self.location_list, self.cls_list,
    self.conf_list, path=self.org_path)

    这段是全工程信息密度最高的地方,值得逐句拆:

    • 先刹车再开新任务:进入方法第一件事是判断摄像头是否开着,开着就先 video_stop()。否则摄像头线程继续往同一个 label_show 刷帧,你刚显示的检测图会在几十毫秒后被摄像头画面覆盖,表现为「点了检测但图闪一下就没了」。
    • 计时只包住推理:t1 放在模型调用前、t2 紧跟在后面,所以界面上的「用时」是纯推理耗时,不含读盘、画框、缩放、刷新 QT 控件。这个口径要说清楚,否则别人拿它当端到端延迟会误判。
    • 三类结果分开取:坐标 boxes.xyxy(左上+右下,绝对值像素)、类别 boxes.cls(float,要转 int 当索引)、置信度 boxes.conf(0~1,乘 100 再格式化成百分比)。三者是按同一顺序排列的,索引对齐,所以后面 draw_rect_and_tabel 才能按下标把「框、类、分」拼成一行。
    • results.plot() 是省事但不灵活的选择:它直接把框、标签画好返回 BGR 图,代价是你没法自定义颜色、字体大小、标签位置。想完全控制样式就自己用 detect_tools.drawRectBox 逐框画——工程里两套都留了,draw_rect_and_tabel 走的是自定义路径。
    • 显示前必须缩放:get_resize_size() 按 770×480 的显示区做等比缩放,返回缩放后的宽高,再 cv2.resize + 转 QPixmap。不缩放直接 setPixmap,大图会把整个布局撑变形。
    • img_cvread 而不是 cv2.imread:前者用 np.fromfile + cv2.imdecode,绕开 OpenCV 对中文路径的编码问题。凡是界面允许用户自己选文件的项目,这一步都不能省。

    7.4 视频与摄像头:用 QTimer 代替 while

    def vedio_show(self):
    if self.is_camera_open:
    self.is_camera_open = False
    self.ui.CaplineEdit.setText('摄像头未开启')
    video_path = self.get_video_path()
    if not video_path:
    return None
    self.cap = cv2.VideoCapture(video_path)
    self.video_start()
    self.ui.comboBox.setDisabled(True)

    def camera_show(self):
    self.is_camera_open = not self.is_camera_open
    if self.is_camera_open:
    self.ui.CaplineEdit.setText('摄像头开启')
    self.cap = cv2.VideoCapture(0)
    self.video_start()
    self.ui.comboBox.setDisabled(True)
    else:
    self.ui.CaplineEdit.setText('摄像头未开启')
    if self.cap:
    self.cap.release()
    cv2.destroyAllWindows()
    self.ui.label_show.clear()

    video_start() 里起的是 QTimer,每次超时读一帧、推理一帧、刷一次界面。这是 PyQt 做实时画面的标准套路:绝不能在主线程写 while cap.isOpened(),那个循环会把 Qt 事件循环饿死,窗口直接「未响应」。摄像头按钮做成开关式(is_camera_open = not is_camera_open),且打开前先停掉正在播的视频,避免两个来源抢同一个画面控件。

    7.5 保存视频:为什么要开线程二次推理

    def save_detect_video(self):
    if self.cap is None and not self.org_path:
    QMessageBox.about(self, '提示', '当前没有可保存信息,请先打开图片或视频!')
    return
    if self.is_camera_open:
    QMessageBox.about(self, '提示', '摄像头视频无法保存!')
    return

    if self.cap:
    res = QMessageBox.question(self, '提示',
    '保存视频检测结果可能需要较长时间,请确认是否继续保存?',
    QMessageBox.Yes | QMessageBox.No)
    if res == QMessageBox.Yes:
    self.video_stop()
    com_text = self.ui.comboBox.currentText()
    self.btn2Thread_object = btn2Thread(self.org_path, self.model, com_text)
    self.btn2Thread_object.start()
    self.btn2Thread_object.update_ui_signal.connect(self.update_process_bar)

    btn2Thread 是一个 QThread 子类,run() 里重新 cv2.VideoCapture 打开源视频,逐帧 model(frame)[0] → results.plot() → out.write(frame),每帧 emit(cur_num, total) 更新进度条。写文件用 fourcc = cv2.VideoWriter_fourcc(*'XVID'),文件名规则是 原名_detect_result.avi。

    这个设计有一个必须承认的代价:保存一次视频 = 推理两遍。第一遍是播放时的实时预览,第二遍是保存时的重跑。为什么不用「播放时顺手存帧」?因为播放用的是 QTimer(1ms),实际刷新率受推理速度制约,掉帧是常态,顺手存出来的视频会卡顿、时长短于原视频。重跑一遍虽然慢,但能保证帧率与源视频一致、帧数完整。这是「正确性优先于速度」的取舍,也是本工程最值得学的一处工程判断。

    7.6 工具层:三个必须自己写的函数

    • drawRectBox(image, rect, addText, fontC, color):先 cv2.rectangle 画框,再在框上方画一个实心背景条(thickness=-1)当标签底色,最后 Image.fromarray → ImageDraw.text → np.array 转回,实现中文标签。背景条宽度硬编码 rect[0] + 60,标签长于 4 个汉字就会溢出,属于已知小瑕疵。
    • cvimg_to_qpiximg(cvimg):cv2.cvtColor(BGR2RGB) → 构造 QImage(注意 step 参数要传 width * depth,否则图像会斜切)→ QPixmap。这个函数是 OpenCV 与 Qt 之间的唯一桥,BGR/RGB 顺序错了就是蓝脸红人。
    • insert_rows(path, lines, header):把检测结果追加写进 csv,文件不存在时先写表头,每行自动加自增序号。这是「检测留痕」能力的实现,比只存图片更有价值——半年后要查某天检出了多少未戴帽,靠的就是这个 csv。

    八、系统功能与界面实现

    界面上半区是「文件导入」和「检测结果」两块,下半区是「检测结果与位置信息」表格 + 右侧信息面板(目标位置 / 目标数目 / 目标选择 / 用时 / 置信度),右下角「保存」「退出」。

    功能对应关系:

    功能方法实现要点
    单图检测 open_img() 推理前后取 time.time() 差值,格式化 '{:.3f} s' 显示在「用时」
    文件夹批量 detact_batch_imgs() 遍历目录逐张推理,结果命名为 xxx_detect_result.jpg
    视频检测 vedio_show() cv2.VideoCapture + QTimer 逐帧读取,替代 while 循环,避免阻塞 UI
    摄像头 camera_show() 开关式设计:打开时若已有视频在播先 video_stop(),再 cv2.VideoCapture(0)
    结果表格 tabel_info_show() 五列:序号 / 文件路径 / 类别 / 置信度 / 坐标位置,自动滚到最后一行
    目标明细 combox_change() 下拉框默认「全部」,选中某一目标后回填 xmin/ymin/xmax/ymax、类别、置信度
    结果保存 save_detect_video() 图片直接 cv2.imwrite 到 save_data;视频交给 btn2Thread 线程重跑一遍并写 xxx_detect_result.avi(XVID 编码),同时弹出 ProgressBar 可取消

    combox_change() 这个交互值得单独说:它把「表格里的一行」变成「画面上某一个框」,实现方式是按下标从 self.location_list / self.cls_list / self.conf_list 里同步取值。三个列表必须严格同长同序,一旦有一处过滤掉了背景框而另一处没过滤,就会出现「下拉框选第 3 个,画面上框的是第 4 个」的错位。这也是为什么 results.plot() 和自定义绘图两条路径不能混用——它们的框集合不一样。


    九、系统部署与运行步骤

    工程提供了一键安装脚本,环境配置就三步:

    # 1) 建 Python 3.9 环境
    conda create -n py39 python=3.9
    conda activate py39

    # 2) 进入项目根目录后安装依赖(二选一)
    python installPackages.py
    # 或
    pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

    # 3) 启动(必须在项目根目录,否则找不到 Font/ 与 models/)
    python MainProgram.py

    关键依赖版本(requirements.txt 共 31 项,节选):

    依赖版本
    ultralytics 8.0.199
    torch 1.9.0
    opencv-python 4.8.1.78
    PyQt5 5.15.2
    pyqt5-tools 5.15.2.3.1
    matplotlib 3.8.0
    numpy 1.26.1

    完整的迁移清单(换一台机器照这个顺序做,基本不会卡):

  • 改 datasets/helmetData/data.yaml 的三个路径为你本机路径。
  • 确认 models/best.pt 存在(约 5.95 MB),不存在就去 runs/detect/train*/weights/ 里取。
  • 确认 Font/platech.ttf 存在。
  • 确认 UIProgram/style.css 与 ui_imgs/ 资源完整,否则界面会变成无样式的灰白控件堆。
  • 装依赖 → 根目录启动 python MainProgram.py。
  • 用 TestFiles/test.jpg 走一次全流程,确认能出框、能存图、表格有数据。

  • 十、常见报错与排查

    部署阶段最容易卡住的几个点(都是这个工程里真实存在的):

  • Dataset not found:data.yaml 还是作者本机的 F:\\Mlwork\\… 路径。改路径,或者改用 path + 相对路径写法。
  • 路径不要有中文:程序运行说明文档.txt 开头就写了这一条。OpenCV 的 imread/imwrite 对中文路径不友好,项目里因此封装了 tools.img_cvread 用 np.fromfile + cv2.imdecode 绕开;但你自己写的脚本里如果直接 cv2.imread 就会静默返回 None,接着在 cv2.resize 处炸出 Assertion failed !ssize.empty()——这个报错的第一嫌疑永远是「路径含中文」或「文件根本不存在」。
  • ModuleNotFoundError: No module named 'PIL':requirements.txt 没有列 pillow,但主程序 from PIL import ImageFont,补 pip install pillow 即可。
  • torch.cuda.is_available() 一直是 False:清单里是 torch==1.9.0(CPU 版),想用 GPU 必须换成对应 CUDA 的发行包,否则视频推理只有个位数 FPS。
  • OSError: cannot open resource:Font/platech.ttf 找不到,通常是没在项目根目录启动。
  • 摄像头打不开(cap.isOpened() 为 False):被微信/钉钉/腾讯会议占用,关掉它们再试;笔记本上还要检查系统隐私设置里「摄像头访问」是否允许。
  • 摄像头检测结果不能保存:代码里对摄像头画面做了显式拦截并提示「摄像头视频无法保存」,这是设计约束,不是 bug。
  • 保存视频耗时较长:因为它是用独立线程把视频重新推理一遍再写文件,不是简单录屏。这样做的代价是两倍推理时间,收益是结果帧完整、不会被 UI 刷新丢帧。
  • 界面能出框但标签是方块:中文字体没加载成功,检查 platech.ttf 路径,或改用 cv2AddChineseText 里的 simsun.ttc。
  • 坑点提醒 4:models/best.pt 与 runs/detect/train2、train4、train5/weights/best.pt 的字节数完全一致(均为 6240025 字节)。这说明 models/ 下那份是复制而来的副本,但从文件本身看不出是哪一次训练的产物。三次训练的最佳 mAP@0.5 分别是 0.93273 / 0.92972 / 0.80050,差别不小,写论文时必须先跑一次 model.val() 反查,不能默认 models/best.pt 就是最好的那次。


    十一、检测效果展示与分析

    单目标场景下,模型对「人 + 头顶安全帽」的组合框得很紧,标签与置信度也清晰:

    图 10 单图检测效果 2

    多人场景才是真实考验。下图同一画面里出现多个工人,模型的取舍很能说明问题:

    图 11 多人场景检测效果

    从这三张实际输出可以归纳出几条规律(都是肉眼可核对的,不含推断性的精度声明):

    • 近景大目标几乎不漏:占画面 1/4 以上的人与帽,框都稳定,置信度也高。
    • 远景小目标是主要短板:站在画面深处的人,帽子的像素面积小,偶尔只框到人不框到帽,或者帽子框偏小。这与 mAP@0.5-0.95 只有 0.60 左右是同一个问题的两种表现——阈值 0.5 时算对,框得不够紧就掉到 0.5 以下。
    • 密集遮挡会合并框:人挤人时 NMS 更容易把相邻两个人抑制成一个框,这是后处理参数问题,不是模型没学到。
    • 逆光与夜间未覆盖:工程自带测试图都是白天场景,夜间/逆光效果无法从现有材料判断(待补充实测)。

    一个必须强调的认知:这些截图是「挑选过的成功案例」,不能反推整体精度。要给出可信的效果分析,得在验证集 763 张上统计漏检/误检分布,而工程里没有留存这类统计。这也是第八节「要点总结」里反复说的那句——日志指标 ≠ 模型指标 ≠ 真实场景表现,三者要分开引用。


    十二、可优化方向

    按「投入产出比」从高到低排,给后续接手的人一份施工图:

  • 补齐「未戴安全帽」判定逻辑(业务价值最高)。现在系统只能告诉你「这里有人、这里有一顶帽子」,不能直接输出「这个人没戴」。做法:对每个 person 框取上部 1/3 作为头部区域,判断该区域内是否存在 hat 框且 IoU 达标,不达标即判未戴;界面上用红色框单独标出。这一步不需要重训模型,纯后处理就能把系统从「检测玩具」变成「安全工具」。
  • 把 conf 与 imgsz 暴露到界面。conf 决定误报/漏报的取舍(参考 F1 曲线峰值),imgsz 提到 800 能明显改善小目标;两者做成配置项放进 settings 或 Config.py,现场人员自己就能调。
  • 补夜间与逆光数据。这是 mAP 卡在 0.93 上不去的根本原因,比调学习率有用一百倍。
  • 加跟踪(ByteTrack/BoT-SORT)。视频里逐帧独立检测会出现框闪烁、ID 跳变;接上跟踪后可以稳定统计「某区域累计多少人未戴」,这是真正的管理指标。
  • 权重与指标口径统一。跑一次 model.val() 拿到 models/best.pt 的真实指标并写进 README,把「日志末轮值」与「交付模型值」分开列,交付文档的可信度会完全不同。
  • 模型轻量化导出。train.py 里已经注释掉 model.export(format='onnx'),打开它导 ONNX,再用 onnxruntime 推理,CPU 上通常能拿到比 PyTorch 明显更低的延迟(具体加速比需实测,工程内无记录,待补充)。

  • 十三、目录结构

    YOLOv8hat-helmet/
    ├── MainProgram.py # 主程序:界面逻辑 + 检测调度 + 结果保存
    ├── Config.py # 模型路径 / 保存目录 / 中英文类名
    ├── train.py # YOLOv8n 训练脚本
    ├── detect_tools.py # 画框、中文渲染、坐标转换、视频写出
    ├── installPackages.py # 一键装依赖
    ├── requirements.txt # 31 项依赖
    ├── datasets/helmetData/ # 数据集(train/valid/test + data.yaml)
    ├── models/best.pt # 系统默认权重(约 5.95 MB)
    ├── UIProgram/ # 界面代码、QSS、图标资源
    ├── Font/platech.ttf # 中文绘制字体
    ├── TestFiles/ # 测试图片与测试视频
    ├── save_data/ # 检测结果输出目录
    └── runs/detect/ # 训练输出(train2 / train4 / train5 保留有 results.csv 与 args.yaml)


    十四、要点总结

  • 类别名必须三处对齐:data.yaml 的 names、Config.names、Config.CH_names,顺序错了界面就会张冠李戴。
  • 数据 yaml 用绝对路径是最大的迁移障碍,建议改成 path + 相对路径的写法。
  • 批量小、patience 大是这套训练参数的显著特征:batch=4 说明显存受限,patience=300 > epochs=150 说明早停形同虚设;而 train2 那次是 batch=32 / patience=50,别把两次的配置混着引用。
  • 收敛快的功劳大半在预训练权重:第 1 轮 mAP@0.5 就 0.66489,第 25 轮已 0.89816,后 150 轮只提升约 3 个百分点。想再往上必须靠数据,不是靠轮数。
  • 看三项损失分工:box 管定位、cls 管分类、dfl 管边界精度,训练降而验证不降就是过拟合的开始。
  • 日志指标 ≠ 模型指标。runs/*/results.csv 只是训练记录,models/best.pt 的真实精度必须自己 model.val() 跑一遍,别直接抄 csv。
  • 视频检测用 QTimer 而不是 while 循环,是 PyQt 做实时画面刷新的标准套路;保存视频再开 QThread 二次推理,才能兼顾界面流畅和写盘完整。
  • 中文显示靠字体文件:cv2.putText 只支持 ASCII,用 PIL + platech.ttf 渲染再转回 OpenCV 图像,是这类中文界面工程的通用解法。
  • 工程里确实缺的东西要照实说:显卡型号、CUDA 版本、单轮耗时、models/best.pt 的独立评测精度、夜间场景实测,全部(待补充)。诚实标注比编一个漂亮数字有价值得多。
  • 赞(0)
    未经允许不得转载:网硕互联帮助中心 » 从零拆解一个 YOLOv8 安全帽检测系统:模型训练 + PyQt5 桌面端的完整工程结构
    分享到: 更多 (0)

    评论 抢沙发

    评论前必须登录!