YOLOv5 口罩目标检测实战（一）：项目整体介绍与数据准备
前言
在公共场所佩戴口罩已成为常态化防护措施，但人工监督耗时费力且存在盲区。利用计算机视觉技术对摄像头画面进行实时检测，能够有效辅助安防和防疫管理。
本项目使用早期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 | 控制学习率（lr0=0.01）、动量（0.937）、损失权重及Mosaic等数据增强参数 | 调优精度的关键文件 |
train.py | 整合数据、模型、超参数，执行训练循环、验证和模型保存 | 训练主程序 |
camera_mask.py | 调用OpenCV读取摄像头，执行预处理、推理、后处理（NMS）和画框显示 | 最终交付运行入口 |
best.pt | 保存训练过程中验证集mAP等指标综合表现最好的模型权重 | 最终推理必须加载此文件 |
二、数据集详解与标签格式
1. 样本与标注框分布
原始数据集经过清洗和划分，当前分布如下：
| 数据集 | 图片数量 | Mask框数量 | No-mask框数量 | 说明 |
|---|---|---|---|---|
| 训练集（train） | 105张 | 573 | 123 | 约4.7:1，明显偏向戴口罩类别 |
| 验证集（valid） | 29张 | 142 | 20 | 少数类（no-mask）样本极少，指标易波动 |
| 测试集（test） | 15张 | 91 | 5 | 仅用于独立复评，不参与训练调参 |
| 合计 | 149张 | 806 | 148 | - |
关键认知：模型在训练时看过573道“戴口罩”的题，只看过123道“未戴口罩”的题。这种类别失衡是后续项目中容易出现“漏报未戴口罩”或“误报戴口罩”的根本原因之一。
2. YOLO标签格式详解
每张图片对应一个同名.txt文件（如0001.jpg对应0001.txt）。标签文件中的每一行代表一个真实目标框，格式如下：
class x_center y_center width height其中：
- class：整数，
0代表mask，1代表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所在目录的相对位置正确。
三、完整数据流转与训练推理总流程
下图展示了从原始数据到最终摄像头推理的完整链路，清晰标出了训练阶段与推理阶段的边界。
图2 项目训练与推理总流程图。上方为训练闭环（数据→增强→前向→损失→反向→保存），下方为推理闭环（摄像头→预处理→前向→NMS→画框→坏例收集）。
四、快速上手运行步骤
安装环境依赖（建议使用Python 3.8）：
pipinstalltorch 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 found | data.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 path="MaskDataSet/train/images/0001.jpg"label_path="MaskDataSet/train/labels/0001.txt"img=cv2.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的模型内部，从像素、卷积、特征图开始，剖析Backbone（Focus/CSP/SPP）、Neck（FPN+PAN）和Detect检测头是如何将一张640×640的图片编码为25200个候选框的，敬请期待。
版权说明
本文为原创技术文章，转载请注明出处。
文中代码及配置均经过实际测试，可根据项目需求修改扩展。
如发现疏漏或错误，欢迎在评论区交流讨论。