简介：基于YOLOv7的口罩检测模型完整资源包，面向计算机视觉开发者、科研人员与安防集成者，用于公共场所口罩佩戴自动识别，可区分戴口罩、未戴口罩和佩戴不规范三类情况，能够部署到机场、车站、商场和园区出入口等实时监控场景。模型采用Darknet框架，引入自适应锚点、空间金字塔池化和Mish激活函数，经大规模标注人像数据训练后精度约93%，可对视频流快速推理。整个压缩包共150个文件，约669MB，核心包含训练好的权重文件、结构配置文件、Python训练/推理脚本、可视化预测图片及使用文档，便于复现训练和二次开发。资源内置Dockerfile、教程PDF和说明文档，可快速搭建环境并迁移到自己的项目。目前已有3045人学习下载，适合想完整掌握YOLOv7口罩检测流程的开发者参考。
1. yolov7做口罩检测：先想清楚检测的是“人脸状态”还是“口罩区域”
yolov7做口罩检测看起来是目标检测里的标准操作，但落地到园区闸机、门禁一体机、教室考勤这类真实场景时，很多人会在“离线指标挺漂亮，现场一跑就误报漏报”上翻车。口罩检测真正难的点不在训练本身，而在三个前置问题：标注目标到底选人脸框还是口罩框、数据集覆盖不覆盖现场视角、以及业务上要的是“提醒戴”还是“禁止未戴”。这篇文章沿着一套可复现的链路讲：数据集怎么选怎么标、yolov7训练怎么做、精度如何调优、部署时怎么压测，新手能按步骤跑通，熟手能直接对照参数和边界。
2. 口罩检测的数据集：公开集选型、自建标注与YOLO格式转换
2.1 先定任务边界：检测人脸状态，而不是检测口罩物体
很多第一次做口罩检测的人会直觉地把“口罩”当成检测目标，框住口罩区域。这个方案有个致命问题：当画面里有人但没戴口罩时，模型没有目标可以输出，你无法区分“没人”和“有人但没戴口罩”。所以实际项目中主流做法是检测“人脸区域”，把每个人的脸框出来，然后分成 with_mask 和 without_mask 两个类别，或者只检测 without_mask 这一类，让没戴口罩的人脸成为唯一目标。
这两种方案的区别在业务侧。
- 二分类（with_mask / without_mask）：适合需要统计“多少人戴了、多少人没戴”的闸机和考勤场景，也能同时给出未戴口罩的人脸位置。
- 单类（只检测 without_mask）：只输出违规者位置，后处理最简单，误报率更容易压下去，但无法区分“无人”和“全员合规”。
我一般建议客户先确认业务口径：是“有人没戴就告警”，还是“要统计全天戴口罩率”。前者用单类就能跑，后者必须做二分类。这个决定直接影响你要标多少数据、训练几轮、最后阈值怎么调，建议在动任何代码前先拍板。
2.2 公开数据集与自建数据怎么组合
口罩检测有现成公开数据集可以用，但直接用它们训出来的模型，在现场大概率达不到可用水平。常见可参考的数据集包括两类：
- RMFD（Real-World Masked Face Dataset）：真实场景下的戴口罩人脸，包含大量带口罩和不带口罩的人脸图片。它的标注以人脸框为主，适合用来做二分类人脸检测的预训练或数据补充。
- MAFA：主要面向口罩遮挡人脸，对遮挡区域有标注，但图片分辨率参差不齐，直接用来训练检测器需要清洗。
这两类数据集的共性是“人脸占比大、背景简单”，与闸机画面里的半身或全身构图差异很大。公开数据集可以当底座，但真正决定现场效果的是你从实际摄像头里抽帧补进来的数据。我的做法是：公开数据占一半，现场数据占一半，现场数据至少覆盖三个维度——不同机位高度、不同光照时段、不同口罩颜色和佩戴方式。
还要提醒一句：公共数据集的许可协议并不一致，研究用途和商用部署是两回事，落地前把授权情况确认清楚，这个环节省不掉。
2.3 VOC转YOLO：转换脚本与参数说明
公开数据集和标注工具（LabelImg 等）常见输出是 VOC 格式的 XML，而 yolov7 训练需要的是每张图对应一个同名 txt，每行格式为class cx cy w h，坐标值归一化到 0~1。下面这个转换脚本可以直接改路径使用。
import os import xml.etree.ElementTree as ET # 类别映射：按实际标注类别调整 class_map = {"with_mask": 0, "without_mask": 1} def convert_annotation(xml_path, out_path, img_w, img_h): tree = ET.parse(xml_path) root = tree.getroot() lines = [] for obj in root.iter("object"): name = obj.find("name").text if name not in class_map: continue cls_id = class_map[name] bbox = obj.find("bndbox") xmin = float(bbox.find("xmin").text) ymin = float(bbox.find("ymin").text) xmax = float(bbox.find("xmax").text) ymax = float(bbox.find("ymax").text) # 归一化并转成 YOLO 的 cx, cy, w, h 格式 cx = (xmin + xmax) / 2.0 / img_w cy = (ymin + ymax) / 2.0 / img_h w = (xmax - xmin) / img_w h = (ymax - ymin) / img_h # 越界框截断，避免训练时标签超出图像边界 cx = min(max(cx, 0.0), 1.0) cy = min(max(cy, 0.0), 1.0) w = min(max(w, 0.0), 1.0) h = min(max(h, 0.0), 1.0) lines.append(f"{cls_id} {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}") with open(out_path, "w") as f: f.write("\n".join(lines))这个脚本的关键点有四个。第一，class_map必须和后续 mask.yaml 中的names顺序保持一致，否则训练出来的类别对应关系全乱。第二，转换时越界框要做截断，因为人工标注偶尔会把框拖出图像边缘，yolov7 对超出边界的标签容忍度有限。第三，输出的小数位保留 6 位足够，不要用像%.3f那样过粗的精度，小目标框会受影响。第四，XML 里如果存在被标记为难例（difficult=1）的目标，脚本里要按业务需要决定保留还是丢弃，我通常直接丢弃，避免给训练引入不确定的标签。
转换完成后，建议随机抽 20 张图，把 txt 读出来画框与原图叠在一起人工检查一遍，确认类别和坐标没有错位。这一步能省掉后面排查训练异常的很多时间。
2.4 训练集/验证集划分的细节
划分数据时最容易犯的错是随机打乱所有图片，然后按比例切训练集和验证集。如果数据是从视频里抽帧来的，同一个人的连续帧会被同时分进训练集和验证集，导致验证集指标虚高，现场表现却远差于预期。
正确做法是按“人”或按“视频片段”分组，保证同一个人只出现在训练集或只出现在验证集。具体到目录结构，我一般这样组织：
datasets/mask/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ ├── train.txt └── val.txttrain.txt 和 val.txt 里每行写一张图片的绝对路径，yolov7 的 mask.yaml 直接引用这两个文件即可。划分时还要注意类别平衡：without_mask 这类样本在采集时通常偏少，如果训练集里两类比例超过 3:1，验证指标会失真，需要额外补充少数类的图片或做重采样。
3. 跑通yolov7训练：环境准备、mask.yaml与一次完整的训练监控
3.1 训练环境与依赖版本
yolov7 对训练环境的要求不算苛刻，但版本匹配容易把人卡住。我的建议是：Python 3.8 或 3.9，PyTorch 1.10 到 1.13，CUDA 11.x，显卡显存不低于 8G。Python 3.10 以上和 PyTorch 2.x 也能跑，但部分算子行为有变化，如果训练中途报错，先把 torch 降到 1.12 再试。
git clone https://github.com/WongKinYiu/yolov7 cd yolov7 pip install -r requirements.txtrequirements.txt里包含训练所需的依赖，但不会自动确认 torch 版本。如果你机器上已经装了别的 torch 版本，建议建一个新的 conda 环境再装，避免把其他项目的环境搞坏。装完后执行下面命令验证 GPU 可用：
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"输出结果里cuda.is_available()必须是True。我第一次在这台机器上跑的时候，pip install默认装了 CPU 版 torch，怎么跑都是 CPU 训练，速度慢得离谱，检查半天才发现是 torch 版本问题。这个坑很基础，但出现频率意外地高。
3.2 mask.yaml配置
yolov7 的数据配置通过一个 yaml 文件完成，里面指定训练集、验证集路径、类别数和类别名。这是训练启动前唯一必须手写的配置。
# data/mask.yaml train: /data/datasets/mask/train.txt val: /data/datasets/mask/val.txt nc: 2 names: 0: with_mask 1: without_mask这里的路径我用的是 train.txt 和 val.txt，而不是 images 目录，这样写的好处是路径集中管理，换机器时只改这一个文件。如果直接用 images 目录路径，yolov7 会自动去找同级的 labels 目录，要求目录结构严格匹配，稍微移动一下文件就会报标签缺失。
nc是类别数，必须和names里的键数量一致。如果前面决定只检测 without_mask 单类，这里就改成nc: 1、names只留0: without_mask。注意单类情况下，with_mask 的人脸不需要标注，但图片仍然可以保留在训练集里作为背景样本，只是不产生正样本框。
3.3 训练命令与参数详解
yolov7 的基础训练命令如下：
python train.py \ --workers 8 \ --device 0 \ --batch-size 16 \ --data data/mask.yaml \ --img 640 640 \ --cfg cfg/training/yolov7.yaml \ --weights yolov7_training.pt \ --name mask-v1 \ --hyp data/hyp.scratch.p5.yaml逐项说明参数含义。
--workers 8：数据加载线程数。太小会让 GPU 等数据，太大容易挤占系统内存。8 是 CPU 16 线程以下的安全值。--batch-size 16：单卡 10G 显存的基准值。显存紧张时优先降到 8，不建议降到 4 以下，否则 BN 统计不稳定。--img 640 640：训练输入分辨率。口罩检测任务里，人脸目标偏小，如果现场摄像头能看到 10 米外的人，建议用 768 甚至 960 输入，代价是显存占用和训练时间增加。--cfg cfg/training/yolov7.yaml：模型结构配置。小团队或单卡环境用默认的 yolov7 即可，不要一上来就上 yolov7x，训练时间长且收益有限。--weights yolov7_training.pt：官方预训练权重，可以从 release 页下载。它会显著加速收敛，口罩检测和 COCO 检测的底层特征高度共享，不建议从零训练。--hyp data/hyp.scratch.p5.yaml：超参数文件，后面调精度时主要改它。
训练启动后，如果显存不够，报错通常是 CUDA out of memory。先把 batch-size 降到 8 或 4，如果还不够，把--img从 640 降到 512。要注意降分辨率会直接削弱小目标检测能力，现场人脸本身就小的话，宁可用梯度累积也要保住分辨率。yolov7 没有内置梯度累积参数，常见做法是通过脚本循环多次 backward 模拟，或者干脆用 2 卡并行。
3.4 训练过程中的监控方法与停机时机
yolov7 训练时日志和权重都输出到runs/train/mask-v1/目录下。训练过程中最重要的监控文件是results.csv，每一行对应一个 epoch 的 loss 和指标。我通常会开一个终端实时查看：
tail -f runs/train/mask-v1/results.csv重点看三列：train/obj_loss、val/obj_loss和metrics/mAP_0.5。前两个是目标损失，趋势应该是持续下降并趋于平缓；如果 val loss 连续 20 个 epoch 不降反升，说明过拟合了，可以提前 Ctrl+C 停掉，用已经保存的 best.pt。mAP_0.5 是验收指标，但对口罩检测来说，mAP 高不等于现场好用，后面会细说。
训练完一个阶段的常见操作是接着调优而不是重新开始。如果想接着跑更多轮次，用以下命令：
python train.py --resume runs/train/mask-v1/weights/last.pt--resume会从断点继续，加载 last.pt 中保存的 epoch、优化器状态和学习率。这个功能在显存爆掉、断电、或者想延长训练时很有用，不用从头再来。
4. 口罩检测精度调优：数据增强、anchor与阈值参数的三种手段
4.1 mosaic与copy_paste：增强策略的边界
yolov7 的默认超参数里，mosaic 增强是开着的，它把 4 张图拼成一张再喂给模型，对提升小目标检测效果很有效。但口罩检测有自己的特殊性：人脸目标和口罩状态强相关，过度的随机裁剪、旋转、透视变换会把“脸部上下文”切碎，模型学到的东西反而跑偏。
我一般会在默认hyp.scratch.p5.yaml基础上做一个小覆盖文件，创建一个hyp.mask.yaml，只改几个关键项：
mosaic: 1.0 mixup: 0.0 copy_paste: 0.1 degrees: 5.0 translate: 0.1 scale: 0.5 shear: 2.0这里保留了 mosaic 但把旋转、剪切限制在很小范围。人脸检测有一个先验知识：人的头基本是正的，摄像头安装角度固定，所以训练时让模型见过太多旋转角度反而是干扰。mixup我直接关掉，口罩状态属于细粒度差异，mixup 会把两张不同状态的图混合在一起，标签变成模糊的中间态，模型学起来很痛苦。
copy_paste对带口罩目标有一定帮助，它能把一个人脸粘贴到另外的背景上，相当于扩充场景多样性。但要注意标签会跟着 paste 操作迁移，如果现场背景复杂，粘贴出来的人脸轮廓和光影明显不协调，模型会学到“人脸周围有一圈奇怪边缘”这种假特征，这时候就把copy_paste也关掉。
4.2 anchor要不要改：先统计再决定
yolov7 默认使用 COCO 数据集上聚类出来的 anchor，三组输出尺度分别对应大、中、小目标。口罩检测任务里的人脸框有两个特点：宽高比集中在 0.7 到 1.3 之间（因为人脸基本是方形的），尺寸分布则取决于摄像头安装距离。
在修改 anchor 前，先做一个统计。把训练集所有标注框的宽度和高度收集出来，做一次 k-means 聚类，看聚类中心与默认 anchor 的差异。常见结果有两种：
- 如果摄像头安装在闸机或门禁位置，人脸大小集中在 100 到 200 像素（640 输入下），默认 anchor 基本够用，不需要改。
- 如果现场是走廊远端抓拍，人脸只有 30 到 60 像素，默认的小尺度 anchor 会显得偏大，这时候可以按聚类结果替换 cfg/training/yolov7.yaml 里的 anchor 数值。
需要注意，anchor 只是训练时的初始先验，模型在训练中会逐步回归修正，所以 anchor 略偏不会造成灾难性影响。除非聚类结果和默认值差距超过一倍，否则不值得折腾。改完 anchor 一定要对比验证集的 mAP，而不是凭感觉判断，有时改了反而掉点。
4.3 conf_thres与iou_thres：模型阈值不是业务阈值
部署时 detect.py 里有两个阈值经常被混为一谈：conf_thres 控制检测框的最低置信度，iou_thres 控制 NMS 的重复框抑制力度。很多人在现场误报多时只调高 conf_thres，发现误报降了但漏报也多了，然后不知道怎么办。
我的经验是：conf_thres 和 iou_thres 要分开调，先调 iou 再调 conf。
python detect.py \ --weights runs/train/mask-v1/weights/best.pt \ --conf-thres 0.4 \ --iou-thres 0.5 \ --source test.mp4如果同一个人的脸被框了两三个框，属于 iou_thres 设置过小导致 NMS 没有充分合并，优先把 iou_thres 调到 0.5 到 0.6。如果不同目标之间出现误报，比如把口罩图案、深色衣服误判成 with_mask，才考虑把 conf_thres 从 0.25 提到 0.4。两个阈值的作用对象不同，混淆了排查方向会白白浪费时间。
从业务角度说，门禁场景通常更怕漏报（没戴口罩的人直接进去了），conf_thres 不宜设太高，0.3 左右比较合适；如果是统计报表场景，对误报容忍度更低，可以提到 0.5。这个值没有绝对标准，应该用现场视频实测，而不是在单张图片上反复试。
4.4 针对现场难样本的三种增强
口罩检测最常见的三种难样本：手捂嘴但没戴口罩、口罩佩戴不规范（露出鼻子）、低照度或逆光下黑色口罩与黑色衣服连成一片。
针对手捂嘴和露出鼻子，单靠数据增强很难解决，因为这是语义层面问题。正确做法是主动去现场采集这类“伪装行为”的样本，单独标注成 without_mask，回灌训练集。通常连续回灌两轮到三轮，模型就能学会区分。
针对低照度、黑色口罩，可以在超参数里加大 HSV 扰动中的色相和饱和度变化幅度，让模型见过更多颜色偏移的口罩。常见做法是把hsv_h和hsv_s各提高 20% 到 30%。但要控制幅度，增强过度会让画面色彩失真，训练出来的模型在现场偏色环境下反而更稳。
回灌样本时有个细节：新采集的样本不要一次性全部加入，按批次混入旧数据重训，否则模型可能遗忘旧知识。我用的是 7:3 的比例，旧数据占七成、新数据占三成，效果比较稳定。
5. 避坑与常见问题排查：yolov7口罩检测训练中的五个翻车现场
5.1 训练loss变成nan
训练刚开始没几个 epoch，train/obj_loss直接变成nan，然后所有指标跟着失效。
这种情况最常见的原因是学习率过高导致梯度爆炸，尤其是用预训练权重继续训练时，初始学习率设置不合理。另一个诱因是训练数据里有损坏的图片或异常标注，比如某张图的标注框宽度为 0。
解决方法是先检查数据：写个脚本扫描所有训练图片，确认能正常用 OpenCV 读取、尺寸不为 0；再检查所有标注 txt，过滤掉 w 或 h 小于 1 像素的框。数据没问题的话，把hyp.scratch.p5.yaml里的初始学习率lr0从 0.01 降到 0.001，同时给前 3 个 epoch 一个较小的 warmup 系数让模型先稳定。我遇到的 nan 案例里，八成因数据异常，两成因学习率，按这个顺序排查最快。
5.2 验证集mAP很高，现场一跑误检率高
训练日志里 mAP@0.5 到了 0.95 以上，模型下载到现场设备，随便跑一段视频就频繁误报，把阴影、广告牌上的人脸印刷图像当成了真实人脸。
原因通常是训练集和现场数据分布不一致。公开数据集里的照片大多是人脸特写，背景干净、光线均匀；现场摄像头是俯视角、逆光、背景杂乱，模型没见过这种构图，只能凭“长得像脸”的局部特征硬猜。
解决思路是把现场设备录制的 30 到 60 分钟视频抽帧，按每 5 秒一帧的频率筛出约 500 到 1000 张图像，人工标注后回灌训练集。同时验证方式要从“单张图片测试”改成“完整视频压测”，统计误报帧数和漏报帧数。这个分布不拉齐，调任何阈值都只是拆东墙补西墙。
5.3 手捂嘴被判成戴口罩
测试时有人用手捂住嘴，模型输出with_mask且置信度不低，业务上这是漏报，属于最不能接受的那类错误。
原因是训练集中缺少“手捂嘴”的负样本，模型没有见过“嘴部被非口罩物体遮挡”的画面，它学到的是“嘴部区域有遮挡物 => 戴口罩”这种简化逻辑。
解决方法是专门采集手捂嘴、手捏鼻子、围巾遮脸这几类“伪口罩”样本，统一标注为without_mask加入训练集。注意标注时不要偷懒，手捂嘴的画面确实容易让人犹豫，但业务口径要求严格，只要不是口罩都算 without_mask。加入 100 到 200 张这样的样本，模型的误判率会有明显下降。
5.4 同一个人头被重复框住
检测结果里同一张脸同时出现两个高度重叠的框，一个置信度 0.8，一个 0.6，看起来像模型在“抢答”。
这是 NMS 没有把重叠框合并干净。常见原因是检测头在不同尺度都输出了同一个目标的框，而 iou_thres 设置过小，导致 NMS 认为两个框属于不同目标。也可能是后处理时对agnostic参数设置不当，跨类别没有做抑制。
先检查 iou_thres，这是最可能的问题。把它从默认 0.45 调到 0.5 或 0.55，重复框通常会消失。如果还在，检查是否在多个类别之间做 NMS，二分类情况下两个类别的人脸框也会互相重叠，需要打开类别无关的 NMS 逻辑。改完后用同一段视频对比，看重复框数量是否降为 0。
5.5 GPU显存不足但占用率低
训练时nvidia-smi显示显存几乎占满，但 GPU-Util（利用率）只有 20% 到 30%，训练一个 epoch 非常慢。
这是数据加载瓶颈，GPU 在等 CPU 喂数据。常见原因是 workers 数过小，或者没开pin_memory，导致数据从内存拷贝到显存的过程成为瓶颈。
解决方案是在训练命令里增加两个参数：
python train.py \ --workers 16 \ --batch-size 16 \ --data data/mask.yaml \ --img 640 640 \ --cfg cfg/training/yolov7.yaml \ --weights yolov7_training.pt \ --name mask-v2 \ --cache-images--workers 16让数据加载线程数匹配 CPU 核心数，--cache-images把训练集图片预加载进内存，省去每个 epoch 重复读磁盘的时间。如果数据集特别大，内存不够用，至少把 val 集加上缓存。这个组合通常能把 GPU 利用率拉到 80% 以上。
6. 部署与进阶：ONNX/TensorRT加速、视频级误检率压测和一个参数管理习惯
6.1 导出ONNX与TensorRT的常见参数
训练完 best.pt 后，部署的第一步是转 ONNX。yolov7 自带 export.py，常用命令如下：
python export.py \ --weights runs/train/mask-v1/weights/best.pt \ --grid --end2end --simplify \ --img-size 640 640 \ --conf-thres 0.25 --iou-thres 0.45 \ --topk-all 100 --max-wh 640--end2end会把 NMS 一起导出到模型里，部署时省掉自己写后处理的步骤；--simplify用 onnx-simplifier 清理冗余节点。转完后用onnxruntime跑一遍测试图，确认输出格式和预期一致。
如果设备是 NVIDIA 平台，接着用 TensorRT 加速。常见做法是用 trtexec 工具生成 engine：
trtexec --onnx=mask.onnx --saveEngine=mask.engine --fp16fp16 精度对口罩检测这类任务损失很小，速度能快一倍。INT8 需要额外的校准数据，一般不用在口罩检测上，除非设备性能确实吃紧。
6.2 用完整视频做误检率压测
模型部署前的验收，一定要用完整视频而不是单张图片。单张图片只能证明“模型认识这张图”，视频压测才能暴露出误报率、漏报率和帧率稳定性。统计脚本的核心逻辑如下：
import cv2 import torch model = torch.hub.load('WongKinYiu/yolov7', 'custom', 'runs/train/mask-v1/weights/best.pt', force_reload=True) cap = cv2.VideoCapture('field_video.mp4') total = fp = fn = 0 while cap.isOpened(): ret, frame = cap.read() if not ret: break total += 1 # 模型推理 results = model(frame) dets = results.pred[0] # 按业务规则统计：假设真值中第 10~20 秒无人， # 如果模型在这段时间持续输出 without_mask，记为误报。 # 具体统计口径需要结合标注的真值文件和现场时段划分。 for det in dets: cls_id = int(det[5]) conf = float(det[4]) if cls_id == 1 and conf > 0.4: # 结合真值判断该帧是否真的存在未戴口罩的人 pass cap.release()压测时至少选三段不同时段的视频：白天强光、傍晚逆光、室内灯光。每段统计两个数：误报帧占比和漏报帧占比。这两个数比 mAP 更能反映现场可用性，mAP 是离线指标，这两个才是业务指标。
6.3 每次训练记录hyp与数据版本
最后一个习惯，也是我自己吃过亏之后养成的：每次训练启动前，把本次用的数据版本、hyp.yaml 内容、训练命令、当时选择的阈值，全部记录成一个 txt 放在 runs/train/mask-v1/ 目录下。
原因很简单，模型迭代到第三轮、第五轮之后，很容易忘记某个版本是用什么数据、哪份超参数训出来的。现场效果变好或变坏时，没有这份记录，你根本没法回答“到底改了什么导致变化”。我现在每次训练都先执行一条复制命令，把 hyp 文件和 mask.yaml 备份进训练输出目录，然后再启动训练。翻车不可怕，怕的是不知道上次是怎么跑通的。希望这些经验能帮到你，少走一些我走过的弯路。
本文还有配套的精品资源，点击获取
