简介一份基于YOLOv5的口罩佩戴检测完整项目主要面向计算机相关专业正在做毕业设计的学生以及需要项目实战练习的学习者也可直接用于课程设计或期末大作业。压缩包共149个文件大小约139.76MB内含40个Python源码、44个YAML标注/配置文件、训练好的.pt模型权重、Shell训练脚本、Dockerfile、Jupyter教程、说明文档及示例图片覆盖数据准备、模型训练、推理测试全流程。目前已有238人学习下载。项目自带训练好的模型与标注好的数据集经过严格调试可直接运行提供tutorial.ipynb便于逐步操作复现Dockerfile可快速搭建统一环境适合作为毕设演示、二次开发或算法对比实验的基座。代码结构清晰按功能划分模块标注数据可进一步扩充类别便于读者深入理解YOLOv5的迁移学习与目标检测实践。1. 先拆开这个zipYOLOv5口罩检测项目包的四份家底打开这个压缩包你会看到四类东西标注好的数据、整理好的数据集、可运行的YOLOv5源码、训练好的模型权重。之所以用压缩包一次给全是因为口罩佩戴检测这个场景的落地痛点不在算法本身而在数据准备和训练环境的衔接——模型大家都跑得通合不合格看的是标注质量和复训参数。这篇笔记就顺着这个包的文件结构讲清楚从环境配置、标签解析、迁移学习到部署验证整条链路怎么做。适合三类人用YOLOv5做目标检测毕设的学生、要做安防或门禁原型的工程师以及想把手头标注数据快速复训成自定义模型的开发者。下文所有路径都以包内目录为准运行命令默认在项目根目录执行。2. 把YOLOv5环境配起来从零到跑通 detect.py 的最小命令2.1 环境隔离与依赖安装conda 和 requirements.txt 的搭配常见做法是先建一个独立的 conda 环境再把 requirements.txt 装进去。mask检测这个项目用到的依赖和通用 YOLOv5 一致核心是 torch、opencv-python、matplotlib、pyyaml 这几个。先建环境conda create -n maskdet python3.8 conda activate maskdet cd yolov5-mask # 进入项目代码目录 pip install -r requirements.txtrequirements.txt 里锁定了 torch 的版本范围直接装一般没问题。如果在本机装过其他深度学习项目建议先确认 torch 版本避免和本地 CUDA 不匹配——很多翻车都发生在这一步检测的时候模型能加载推理却全程跑 CPU速度慢到没法用。没有 GPU 的机器也能跑把后面命令里的 device 参数改成 cpu 就行只是单张图的推理时间会长不少。依赖装完先别急着跑训练用一条最简单的推理命令验证环境是否真的通了能输出结果图说明环境没问题后面数据、训练的问题才能单独排查。参数说明conda create 指定 python3.8 是因为 YOLOv5 官方对 3.73.9 支持最好pip install 不指定镜像源时第一次下载 torch 可能比较慢可以用 -i 指定国内 PyPI 镜像提速注意这只是加速包下载和模型权重文件是两回事Pytorch 权重还是要从包内或官方 release 里拿。2.2 第一次推理用训练好的模型权重跑一张测试图环境装好后直接用包里给好的权重做推理这是最快确认模型是否有用的方式python detect.py --weights runs/train/exp/weights/best.pt --source data/images/mask_test.jpg --conf-thres 0.5默认跑完图片会输出到 runs/detect/exp 目录打开就能看到画了检测框和置信度的结果图。这里有两个超参数值得先明白conf-thres 是置信度阈值低于 0.5 的框会被丢弃iou-thres 是 NMS非极大值抑制的 IoU 阈值控制两个重叠框是否合并。做口罩检测时 conf-thres 不建议设到 0.7 以上因为小脸、侧脸、口罩遮半边的样本置信度天然不高阈值太高会漏检。detect.py 还会自动读取 data.yaml 里的类别名在框的左上角标出 mask 或 nomask。如果跑出来的图标签乱掉先看 data.yaml 里 names 的顺序是否和标注文件里的 class id 一一对应这是最容易被忽略的问题。后面数据章节会专门讲这个对应关系。参数说明--weights 指定训练好的权重文件优先用 best.pt 而不是 last.ptbest 是按验证集指标保存的最优模型--source 可以接图片路径、文件夹路径、摄像头编号或视频文件路径做实时演示时可以传 0 调用本地摄像头。2.3 项目目录结构哪块是代码、哪块是数据包的根目录一般长这样yolov5 官方代码为主体data 下放图片和标签weights 或 runs 下放训练产物。代码和数据分开的好处是训练时改配置不影响源码换数据集时也只用动 data 目录和 yaml 配置。常见目录结构如下不依赖具体版本号data/images按 train、val 分好类的图片data/labels对应图片同文件名的 txt 标注data/mask.yaml数据集配置声明类别和路径runs/train训练输出的权重和日志runs/detect推理输出结果图models模型结构定义训练时选用的 yaml 在这里我个人习惯在拿到包后先跑一遍find或tree命令把目录结构打印出来对照文档确认每个路径的存在性。这样后面训模型时data yaml 里的路径写错了能一眼看出来——路径问题占训练报错的很大一部分。3. 数据集与标注mask 和 nomask 两类样本的后台结构3.1 数据集目录与训练配置yaml 怎么告诉 YOLOv5 数据在哪YOLOv5 的数据集不看后缀只看 yaml 配置。一个口罩检测的 mask.yaml 大致是下面这样train: data/images/train val: data/images/val nc: 2 names: [mask, nomask]先解释三个关键点的含义。train 和 val 指向的是存放图片的目录路径YOLOv5 会在对应目录的同级 labels 目录下自动找同名 txt所以 labels 目录不需要在 yaml 里显式声明nc 是类别数量等于 2对应 mask 和 nomasknames 里第一个名字对应标注 class id 0第二个对应 1顺序不能随意调否则推理时标签名会错位。如果要自己组织数据集常见规范是 images/train、images/val、labels/train、labels/val 这四个目录并排图片和标签同名不同后缀。目录名千万别写成 image 或 lablesYOLOv5 对这两个固定目录名有硬编码逻辑写错了找不到标签文件训练出来的模型会变成什么也学不到的瞎猜模型。还有一个细节需要特别提醒yaml 里的路径是相对于项目根目录的不要在路径前加斜杠写成绝对路径也不要加../跳到项目外。换机器跑的时候只需要改这个 yaml 的路径和 weights 路径其他文件不用动。3.2 标注格式与数据产生归一化的 class x y w h 到底怎么写YOLO 格式的标注文件是 txt每行表示一个目标格式如下0 0.5 0.4 0.3 0.25 1 0.7 0.6 0.2 0.3每个数字的含义是类别编号、目标的中心点 x 坐标、中心点 y 坐标、目标宽度 w、目标高度 h其中 x y w h 全部相对原图尺寸做了归一化。比如第一行的 0.5 0.4 意味着 mask 目标的中心在图片宽度的 50%、高度的 40% 处宽度占图片宽度的 30%、高度占 25%。注意是中心点坐标不是左上角坐标用 labelimg 标注时它显示的是左上角右下角导出成 YOLO 时会自动换算但如果自己写脚本处理数据这个换算关系很容易搞错。如果你手头拿到的是 VOC 格式的 XML 标注想转成 YOLO 的 txt常见做法是写一个 Python 转换脚本核心逻辑如下import xml.etree.ElementTree as ET def voc_to_yolo(xml_path, out_txt, class_list): root ET.parse(xml_path).getroot() img_w int(root.find(size/width).text) img_h int(root.find(size/height).text) lines [] for obj in root.findall(object): cls obj.find(name).text if cls not in class_list: continue class_id class_list.index(cls) box obj.find(bndbox) x1 float(box.find(xmin).text) y1 float(box.find(ymin).text) x2 float(box.find(xmax).text) y2 float(box.find(ymax).text) x_center (x1 x2) / 2.0 / img_w y_center (y1 y2) / 2.0 / img_h w (x2 - x1) / img_w h (y2 - y1) / img_h lines.append(f{class_id} {x_center:.6f} {y_center:.6f} {w:.6f} {h:.6f}) with open(out_txt, w) as f: f.write(\n.join(lines)) class_list [mask, nomask] voc_to_yolo(data/annotations/00001.xml, data/labels/00001.txt, class_list)代码逻辑说明先读 XML 里的图片宽高再把每个目标的 xmin/ymin/xmax/ymax 从左上角右下角表示换算成中心点加宽高的表示。这里最容易出的问题有两个一个是忘了除以图片宽高做归一化直接存像素值导致训练时目标框全部超出 0~1 区间loss 永远不收敛另一个是 class_list 的顺序和 mask.yaml 的 names 顺序不一致比如 XML 里是 with_mask而 names 里写的是 mask转换脚本会静默跳过这些目标最终标签文件比图片数量少很多训练集被悄悄削弱。实际标注时大家一般用 labelimg 可视化标注它支持框选后按数字键标类别导出的就是 YOLO 格式 txt。注意 labelimg 没有撤销热键标错只能删掉重框这个稍显磨人但够用。想要更省事的话可以用 labelstudio 这类工具做在线标注它的好处是多人在线协作和自动标注预标记但配置成本比本地工具高。数据标注这个环节在整个项目里最耗时包里的标注数据可以直接复用省掉了最枯燥的一步。3.3 训练集划分与样本均衡多少图片够用、两类样本怎么配模型好不好数据占比影响很大。口罩检测是个二分类目标检测任务我的经验是每个类别至少要有 300 到 500 个实例目标图片总数在 800 到 1500 张之间比较稳。如果包里数据偏少宁可先跑一个过拟合实验确认代码链路正确再着手扩数据不要直接堆 epoch 数期待奇迹。训练集和验证集划分比例一般是 8:2 或 9:1。划分时注意两个容易翻车的点一是同一个场景的连续帧图片要一起划到同一侧否则训练集和验证集出现重叠验证指标虚高二是 mask 和 nomask 两类目标的数量差距不要太大如果 nomask 样本明显偏多模型倾向于把所有脸都判成没戴口罩表现为精度可以但召回很低。常见处理办法是给样本少的一类做数据增强或是在训练时调整类别权重。划分脚本可以用一行 shuffle 命令加文件移动实现注意保持图片和标签文件同名同步移动只移图片不移标签是新手最常见的低级错误。4. 迁移学习与参数选择用自带权重复训出自己的模型4.1 训练命令和权重初始化为什么从 best.pt 开始而不是从零训拿到一个带训练好模型权的包直接训练是典型操作。命令如下python train.py --data data/mask.yaml --weights yolov5s.pt --epochs 100 --batch-size 16 --img 640这条命令的含义是用 yolov5s.pt 做预训练权重初始化在 mask.yaml 配置的数据上迭代 100 轮每批 16 张图输入分辨率 640×640。如果机器显存不足可以把 batch-size 降到 8 或 4img 降到 416效果会略有下降但模型能跑起来。迁移学习是这个项目包最有价值的地方。YOLOv5 官方在 COCO 上训练的权重已经学到区分形状、边缘、纹理的通用能力口罩检测和 COCO 的类别差异大但从预训练开始微调收敛速度仍然远快于随机初始化。数据量只有几百张时随机初始化训练 100 轮很可能不收敛而迁移学习 30 轮就能看到可用效果。选择 weights 时CPU 机器建议用 yolov5s.pt参数量小推理快显存充足且想要更高精度可以换成 yolov5m.pt代价是训练时间几乎翻倍。训练过程中注意看两个输出一个是每个 epoch 结束打印的 mAP0.5 和 Precision/Recall 指标另一个是 runs/train/exp 里的曲线图。mAP0.5 在 0.8 以上说明模型基本可用0.9 以上是优秀的口罩检测水平。4.2 三个必调参数lr、batch-size 和 img 之间的关系YOLOv5 超参数里最影响口罩检测效果的是这三个batch-size、img-size、初始学习率 lr0。batch-size 决定每个 step 看到的图片数量显存允许范围内尽量大它既影响梯度稳定性也影响一批数据里正负样本的比例img-size 决定输入分辨率口罩是小目标物体分辨率太低框会偏大偏糊分辨率太高又吃显存lr0 默认 0.01在迁移学习场景下可以做适当调整。python train.py --data data/mask.yaml --weights yolov5s.pt --epochs 100 --batch-size 8 --img 640 --hyp data/hyps/hyp.scratch-low.yamlhyp 参数文件的含义是训练策略总配置里面包含 lr0、lrf、momentum、weight_decay、数据增强系数等十几项参数。对口罩检测来说迁移学习场景下 lr0 设为 0.005 比较稳官方默认 0.01 在新的小数据集上容易出现训练初期 loss 跳变。改动时只改 lr0 一项其他增强参数先不动。这批超参数跟模型结构里的参数不是一回事调的是训练过程的行为新手最容易把它们混为一谈结果到处乱改模型越训越差。img-size 和 batch-size 的组合有一个硬关系两者同时增大时显存开销接近线性增长。显存 6G 的卡跑 640 分辨率建议 batch-size 不超过 8如果坚持用 16要么降到 416 分辨率要么开梯度累积--accumulate 参数来模拟大批次效果。梯度累积的本质是把多个小 batch 的梯度叠加后再更新权重能缓解显存压力但会拖慢训练速度迭代次数少的数据集上不明显。4.3 低显存运行模型小卡也能练完 100 轮很多用户的显卡是 4G、6G 的入门卡跑 YOLOv5s 训练确实勉强。我的建议是组合拳分辨率降到 416batch-size 取 4workers 取 0关闭 mosaic 增强用 --no-mosaic。这套配置可以让低显存环境跑通 416 分辨率的训练实测单轮速度慢但稳定不崩。python train.py --data data/mask.yaml --weights yolov5s.pt --epochs 100 --batch-size 4 --img 416 --workers 0 --no-mosaic参数说明workers 是数据加载的并行进程数Linux 下取 4 或 8 提速Windows 下经常因多进程问题卡死取 0 最保险--no-mosaic 关闭马赛克增强这是一个省显存且降低复杂度的措施缺点是模型对遮挡和小目标鲁棒性变差数据量充足时建议不要长期关闭--device 0 指定用第一张 GPU不写也是默认行为。另外有个容易被忽略的点训练时显存占用是动态的前几个 epoch 因为图片没有被 cache占用较小跑一段时间后如果开了 cache 特性显存占用会上涨。如果中途 OOM不代表配置不行先关掉 cache 相关参数再试。实际经验里低显存机器把 cache 关掉、workers 调 0、mosaic 关闭后5G 显存卡训练 640 分辨率 batch-size 4 是可以完成的只是时间会长一些胜在稳定。5. 避坑与排查口罩检测项目里最容易翻车的 5 个点5.1 训练 loss 不降先怀疑标签文件别急着调模型现象训练跑了几十个 epochloss 基本不动验证集 mAP 停在 0.1 以下。原因排查了一圈最常见的是标签文件里类别 id 越界比如类别总数是 2标注里却出现了 id 2或者标签文件为空。解决脚本批量扫描所有 txt统计每行的 class id 最大值同时检查是否有 0 字节的空标签文件。给一个快速检查命令# 统计 labels 目录里所有 txt 的首列取值分布 awk {print $1} data/labels/train/*.txt | sort | uniq -c如果出现大于等于 nc 的数字回标注工具改正如果空文件很多重新导出标注。其实训练日志里 Epoch 那行如果 box loss 和 val loss 同时震荡不降先跑这个命令比改学习率靠玄学调试靠谱得多。5.2 推理框错位归一化坐标和像素坐标混用现象训练正常验证指标不错但 detect.py 推理出来的框位置偏了或者框的大小完全不对。原因标注文件里的 x y w h 是 0~1 的归一化值YOLOv5 内部会按输入尺寸换算回像素如果数据准备阶段误用了 VOC 的像素坐标直接存成 txt那训练时模型学到的目标位置全是错的。解决检查任意一个 txt 文件看数值是否都在 0~1 之间超出就回到标注转换脚本把除以宽高那一步补上。口罩这类小目标对位置精度敏感坐标错位即使训练指标好看实际推理也会漏检或框到背景上。5.3 精度上不去验证集与训练集重叠现象训练集 loss 很低验证集 mAP 卡在 0.6 上不去怀疑是数据量不够。原因数据划分时没有按来源分组同一个视频连续帧被随机分到了 train 和 val导致验证时看到的图片是训练时见过的真实泛化能力被高估一旦换新场景就翻车。解决先按图片文件名前缀做分组再对组做随机划分。比如 camera_A_0001.jpg 到 camera_A_0100.jpg 是一组整组划入 train 或 val不要在组内切散。5.4 显存 OOMbatch-size 和分辨率是一对共犯现象训练跑到一半报 CUDA out of memory程序退出。原因GPU 显存被中间特征图占满尤以 mosaic 增强和 cache 开启时明显。解决先关 cache 和 mosaic把 batch-size 降一半若还 OOM 就把 img 从 640 降到 416。注意不要为了省显存把 img 降得太低低于 320 时口罩目标通常只剩十几个像素几乎不可检测这会影响后续模型质量。5.5 导出模型效果和 PyTorch 不一致关注 opset 版本现象用 best.pt 推理效果不错导出 ONNX 后部署到其他框架同一张图结果差异很大甚至不出框。原因导出时的 opset 版本和部署侧算子支持不一致或者模型里含某些动态尺寸操作部署时输入尺寸没有保持训练时的 640×640 导致 letterbox 处理不一致。解决导出命令显式指定 opsetpython export.py --weights runs/train/exp/weights/best.pt --include onnx --opset 12导出后先用 onnxruntime 加载同一个模型和同一张图对比输出框坐标和置信度差异在可接受范围再交给部署端。这一步是为数不多能够提前发现部署坑的后悔药值得在项目初期就走一遍。6. 再用 val.py 量化模型决定要不要微调做口罩检测做到能跑、能出框只算完成了前半段。后半段是怎么知道这个模型到底行不行、够不够上线。val.py 是验证模型在测试集上真实水平的工具和 detect.py 的定性看效果不是一个层次python val.py --data data/mask.yaml --weights runs/train/exp/weights/best.pt --img 640 --conf-thres 0.001conf-thres 在验证时设得非常低是为了完整计算 PR 曲线让 mAP 指标覆盖低置信度区间真实反映模型的召回能力。验证脚本输出一张 result.png里面有 P、R、mAP0.5、mAP0.5:0.95 四组曲线。口罩检测场景下我一般以 mAP0.5 为准0.85 以上可以用于演示和原型0.90 以上才有底气做门禁或者闸机集成。如果验证分数不理想回到数据上补样本不要盲目调超参数靠玄学调参补几十张最难的正脸侧面图往往比折腾学习率更有效。验证通过后部署方向也要想清楚。要做成桌面演示用 PyTorch 权重直接跑即可要做网络服务或嵌入设备导出 ONNX 再配合 onnxruntime 或 TensorRT 推理比直接调 Python 稳定得多。导出命令里的 opset 版本和静态尺寸这两项建议固定部署侧代码里写死输入为 640×640避免动态尺寸带来额外复杂度。最后分享一个我的习惯模型训练完成后不急着部署先把 val.py 的输出文件保留在 runs 目录里连同 best.pt 和 data.yaml 一起打包归档。三个月后回看项目时你能记得的不只是模型跑通了还有当时的精度水平、验证参数和数据集范围。这套流程里我最大的教训是先量化、再优化——用指标代替感觉能少走很多弯路。希望这份笔记能帮你在口罩检测和后续自定义目标检测项目里把时间花在数据质量和部署验证上而不是反复踩别人踩过的坑。希望帮到你。本文还有配套的精品资源点击获取