前言在公共场所佩戴口罩已成为常态化防护措施但人工监督耗时费力且存在盲区。利用计算机视觉技术对摄像头画面进行实时检测能够有效辅助安防和防疫管理。本项目使用早期YOLOv5 2.0版本中的YOLOv5s模型实现端到端的口罩佩戴检测。与图像分类任务不同本项目需要同时解决两个核心问题1. 找到每张人脸在画面中的位置定位2. 判断该人脸属于mask戴口罩还是no-mask未戴口罩。模型最终输出若干个目标框、每个框的类别和置信度。本文作为系列开篇重点介绍项目的目标、数据集构成、文件目录结构以及完整的数据流转流程。后续文章将深入网络结构、Anchor解码、训练调参与推理部署。文章目录前言一、项目目录结构与核心文件核心文件职责说明二、数据集详解与标签格式1. 样本与标注框分布2. YOLO标签格式详解3. data.yaml 配置文件三、完整数据流转与训练推理总流程四、快速上手运行步骤五、常见问题与解决方案数据阶段六、调试建议七、总结与下篇预告一、项目目录结构与核心文件项目代码基于早期YOLOv5 2.0工程推荐使用PyCharm或VSCode打开。目录结构分为数据集存放区MaskDataSet和算法工程区yolov5_2_0。Mask_YOLO │ ├── MaskDataSet/ # 数据集根目录 │ ├── data.yaml # 数据集配置文件路径、类别数、类别名 │ ├── train/ # 训练集 │ │ ├── images/ # 训练图片105张 │ │ └── labels/ # 训练标签YOLO格式txt │ ├── valid/ # 验证集 │ │ ├── images/ # 验证图片29张 │ │ └── labels/ # 验证标签 │ └── test/ # 测试集独立复评 │ ├── images/ # 测试图片15张 │ └── labels/ # 测试标签 │ └── yolov5_2_0/ # 早期YOLOv5工程源码 ├── train.py # 训练总入口 ├── test.py # 验证与测试入口 ├── detect.py # 图片/视频推理入口 ├── camera_mask.py # 【本项目核心】摄像头实时检测入口 ├── models/ # 网络结构定义 │ ├── yolov5s.yaml # YOLOv5s网络结构、Anchor尺寸 │ └── yolo.py # 模型构建与Detect检测头逻辑 ├── utils/ # 工具函数 │ ├── datasets.py # 数据加载、Letterbox、数据增强 │ └── utils.py # IoU计算、损失函数、目标匹配、NMS ├── hyp.yaml # 超参数配置学习率、损失权重、增强参数 └── runs/ # 训练输出 └── exp17/ # 当前项目训练结果 ├── opt.yaml # 训练命令参数复现用 ├── hyp.yaml # 本次训练实际超参数 ├── results.txt # 每轮训练损失与验证指标 └── weights/ ├── best.pt # 验证集综合表现最佳权重用于最终推理 └── last.pt # 最后一轮权重用于恢复训练核心文件职责说明文件职责重要性data.yaml指定训练/验证图片路径、类别数量nc: 2、类别名称mask, no-mask数据入口必须正确配置models/yolov5s.yaml定义Backbone、Neck、Head结构及每层通道数、Anchor尺寸修改网络结构需改动此处hyp.yaml控制学习率lr00.01、动量0.937、损失权重及Mosaic等数据增强参数调优精度的关键文件train.py整合数据、模型、超参数执行训练循环、验证和模型保存训练主程序camera_mask.py调用OpenCV读取摄像头执行预处理、推理、后处理NMS和画框显示最终交付运行入口best.pt保存训练过程中验证集mAP等指标综合表现最好的模型权重最终推理必须加载此文件二、数据集详解与标签格式1. 样本与标注框分布原始数据集经过清洗和划分当前分布如下数据集图片数量Mask框数量No-mask框数量说明训练集train105张573123约4.7:1明显偏向戴口罩类别验证集valid29张14220少数类no-mask样本极少指标易波动测试集test15张915仅用于独立复评不参与训练调参合计149张806148-关键认知模型在训练时看过573道“戴口罩”的题只看过123道“未戴口罩”的题。这种类别失衡是后续项目中容易出现“漏报未戴口罩”或“误报戴口罩”的根本原因之一。2. YOLO标签格式详解每张图片对应一个同名.txt文件如0001.jpg对应0001.txt。标签文件中的每一行代表一个真实目标框格式如下class x_center y_center width height其中class整数0代表mask1代表no-mask。x_center, y_center, width, height均为归一化到[0, 1]之间的浮点数。归一化公式为以x_center为例(框的左上角x 框的右下角x) / (2 * 图片宽度)。标签示例0001.txt内容0 0.5125 0.4300 0.2100 0.3200 1 0.7600 0.5000 0.1800 0.2900这表示图片中有两个目标第一个是戴口罩的人脸位于画面中央偏左第二个是未戴口罩的人脸位于画面右侧。3.data.yaml配置文件数据集路径和类别映射全部在MaskDataSet/data.yaml中定义# data.yamltrain:MaskDataSet/train/imagesval:MaskDataSet/valid/imagestest:MaskDataSet/test/imagesnc:2# number of classesnames:[mask,no-mask]# class names调试提示YOLO读取图片依赖data.yaml中的路径。如果训练时报错FileNotFoundError优先检查此处路径是否为相对路径且与train.py所在目录的相对位置正确。三、完整数据流转与训练推理总流程下图展示了从原始数据到最终摄像头推理的完整链路清晰标出了训练阶段与推理阶段的边界。是否图片 同名YOLO标签检查类别、坐标、空标签和数据分布划分train、valid、test读取data.yaml、yolov5s.yaml、hyp.yaml加载YOLOv5s和预训练权重DataLoader读取图片并同步增强标签Backbone提取多层特征FPN PAN融合不同尺度特征P3、P4、P5三个尺度输出候选真实框与Anchor、Grid匹配计算box、obj、cls三类损失反向传播 SGD更新参数EMA平滑参数在验证集计算P、R和mAP综合表现是否更好保存best.pt继续训练并保存last.pt摄像头或图片推理Letterbox RGB CHW 归一化模型前向得到25200个候选置信度筛选 NMS坐标映射回原图画框、类别、置信度和WARNING收集漏检、误检和错分类坏例图2 项目训练与推理总流程图。上方为训练闭环数据→增强→前向→损失→反向→保存下方为推理闭环摄像头→预处理→前向→NMS→画框→坏例收集。四、快速上手运行步骤安装环境依赖建议使用Python 3.8pipinstalltorch torchvision opencv-python pandas matplotlib pyyaml tqdm检查数据集确保MaskDataSet文件夹与yolov5_2_0位于同级目录。随机打开train/labels/下的一个txt文件检查坐标是否在0~1之间。开始训练在yolov5_2_0目录下python train.py--data../MaskDataSet/data.yaml--weightsyolov5s.pt--epochs200--batch-size4--img-size640摄像头实时检测python camera_mask.py五、常见问题与解决方案数据阶段问题原因解决方法训练报错No labels founddata.yaml中路径错误或labels文件夹为空检查train/val路径是否指向images父目录确保标签与图片同名标签解析报错IndexError: list index out of range标签文件中某行缺少空格或坐标数量不为5使用文本编辑器检查txt文件确保格式为class x y w h类别数量不对应data.yaml中nc: 2但标签里出现了2或-1检查所有标签文件确保class只包含0和1验证集mAP忽高忽低验证集太小仅29张no-mask仅20框属于正常现象应结合分类别指标和具体坏例分析不只看总体mAP图像无法读取corrupted image图片文件损坏或不是标准格式如.jpg实际为.png使用cv2.imread()逐张测试修复或删除损坏图片六、调试建议建议在训练前运行以下简单脚本验证数据加载是否正确importcv2 pathMaskDataSet/train/images/0001.jpglabel_pathMaskDataSet/train/labels/0001.txtimgcv2.imread(path)print(f图片Shape:{img.shape})# 期望 (H, W, 3)withopen(label_path,r)asf:print(f标签内容:{f.read()})观察变量img是否为None标签坐标值是否在0~1范围内。七、总结与下篇预告本文作为系列的开篇梳理了YOLOv5口罩目标检测项目的基本盘我们明确了目标检测与图像分类的区别掌握了149张图片、954个标注框的数据分布特点理解了目录结构中每个关键文件的职责并且通过流程图对数据如何一步步变成检测框有了全局印象。值得记住的是本项目的训练集存在约4.7:1的类别失衡且验证集规模较小这意味着我们在后续解读mAP指标时必须保持审慎。下一篇预告我们将深入YOLOv5s的模型内部从像素、卷积、特征图开始剖析BackboneFocus/CSP/SPP、NeckFPNPAN和Detect检测头是如何将一张640×640的图片编码为25200个候选框的敬请期待。版权说明本文为原创技术文章转载请注明出处。文中代码及配置均经过实际测试可根据项目需求修改扩展。如发现疏漏或错误欢迎在评论区交流讨论。