YOLOv4人脸口罩识别实战：从环境搭建到PyTorch训练避坑全解析

简介基于YOLOv4与PyTorch实现的人脸口罩识别项目是一套完整可运行的Python工程面向计算机视觉、人工智能等专业的在校学生、教师及开发者可支撑毕业设计、课程设计、课题演示或目标检测算法进阶练习。压缩包共367个文件容量约9.31MB其中20个Python文件构成核心代码覆盖模型构建、训练与推理检测全流程322个XML文件为标注数据便于理解目标框标签结构另有多个AVI测试视频可直观查看检测效果并附带字体文件、配置文件和README说明文档压缩包内目录模块清晰下载后对照文档可快速复现口罩佩戴识别。代码经作者反复调试稳定运行原作者称答辩评审平均分达到96分学习参考价值较高适合作业、毕设或项目初期的快速原型。目前已有53人浏览学习除常规口罩识别外还可在此基础上调整数据与类别参数扩展至人脸检测、通用目标检测等实验。1. YOLOv4人脸口罩识别源码一份能跑的毕设工程先看它值不值得下人脸口罩识别这套源码搜索热度一直不低原因很实在门禁、考勤、食堂闸机都在用毕设和课设也常拿它当题目。这份基于YOLOv4和PyTorch的资源把训练、推理、测试视频都打包齐了——YOLOv4负责从图片或视频里框出人脸并判断是否戴口罩PyTorch负责训练和推理的框架支持。拿到资源后第一步不是改代码而是先把整个流程完整跑通再评估要不要换自己的数据集。它适合三类人计算机相关专业做毕设的学生、想快速验证YOLO系列检测效果的在职人员、以及刚接触目标检测想找个能落地参考工程的小白。下面把文件结构、环境搭建、训练参数和踩过的坑一次讲清。2. 项目文件解剖从README到测试视频源码包里每样东西的用途2.1 核心代码与辅助产物先分清哪些该动、哪些别管拿到压缩包后第一步不是急着双击py文件而是先做一次文件分拣。这份资源的根目录下除了yolov4-pytorch-master工程目录还散着几个看起来像项目文件的视频和图片什么时候该用哪个、哪个是编辑器生成的垃圾文件分不清楚的话后面操作容易走弯路。文件/目录类型实际作用yolov4-pytorch-master/核心源码模型定义、训练脚本、推理脚本、config配置全部在这里output202212031535.avi测试视频训练完成后对视频的检测输出验收用output202212031534.avi、output202212041735.avi测试视频与上一个同属视频推理结果mask.jpg输入样例单张戴口罩人脸图片跑demo的输入result.jpg输出样例推理后的标注结果图video_tmp.jpg中间产物视频抽帧后留下的临时帧README.md说明文档项目说明、运行方式、依赖清单.gitignore版本控制上传仓库时忽略的目录清单运行无关VSWorkspaceState.json、*.imlIDE状态文件编辑器自动生成与项目运行无关看列表就能得到两个结论。第一真正需要改动的代码全在yolov4-pytorch-master目录内README.md是唯一需要通读的文档第二mask.jpg和result.jpg是一对输入输出样例三个avi是视频级别的推理结果video_tmp.jpg是抽帧留下的临时产物直接忽略。VSWorkspaceState.json和.iml这两个是Visual Studio与IntelliJ系IDE自动生成的工作区描述文件删了都不影响运行。这套检测逻辑建立在YOLOv4的骨干网络CSPDarknet53上配合SPP和PANet做多尺度特征融合。口罩目标在画面上通常只占人脸区域的一部分属于典型的中小目标YOLOv4对中小目标的检测能力比之前的YOLOv3强不少这正是它在这个场景下的选型理由。后面改模型或换数据时骨干网络不需要动要动的是anchors、类别数和输入尺寸这几个参数。2.2 README先读启动入口、依赖清单与模型说明怎么找YOLOv4和PyTorch环境搭建不是看网上一堆教程就能合上的依赖版本一个对不上训练时就会报错。README是这份资源里唯一值得信任的启动入口它帮你省掉从报错栈里猜配置的环节。我读README一般按顺序找三段内容。第一段是Requirements它告诉你要装哪些包、锁哪些版本这一段决定你后面能不能顺利import torch第二段是Weights说明预训练权重放在哪个目录、文件名叫什么、加载方式是直接load还是需要先转换第三段是Usage通常会给demo.py和train.py的调用示例命令格式以它为准因为不同作者写的YOLOv4 PyTorch版本入口脚本命名和参数风格差别不小。一个容易踩的细节是README里如果写了下载预训练权重放到weights目录那这个权重一般不会和源码一起打包需要自己去下载或者从训练过的日志里恢复。你拿到这份资源时如果权重文件确实缺失先确认是不是漏看了README里的Weights段而不是代码本身有问题。2.3 测试视频与结果图验证项目可用性的最低成本路径最高效的验证路径是先看产物再碰代码。用播放器打开三个avi中的一个确认画面里检测框能不能稳定落在人脸区域置信度数值是否会随遮挡抖动然后再打开result.jpg和mask.jpg对比看看单张图片的检测框位置、类别标签和置信度画得对不对。这两个检查都通过了说明这份资源的上传者是完整跑过一遍的环境问题大概率出在你自己机器上而不是源码本身。如果result.jpg里的检测框画得歪歪扭扭或者视频是纯黑帧那就先怀疑下载的文件是否完整解压是不是中途报错别一上来就改代码。我一般还会顺手看一眼视频的分辨率和帧率和config里设置的输入尺寸做对比这会直接影响后面复现时的显存占用和推理速度。3. PyTorch环境搭建Python 3.8、CUDA 10.2与PyTorch 1.8的稳妥组合3.1 环境版本怎么选Anaconda隔离环境是最省心的方案这套代码翻车率最高的位置就是环境。新手拿来就在系统Python里直接pip install结果import torch那一步就开始报错老手也容易在CUDA和PyTorch版本搭配上反复横跳。我的建议是直接用Anaconda建独立环境不碰系统Python这样不管系统里装了什么都不会互相污染。conda create -n yolo_mask python3.8 conda activate yolo_mask conda install pytorch1.8.1 torchvision0.9.0 cudatoolkit10.2 -c pytorch上面三行命令各说明一下。conda create -n yolo_mask python3.8是创建一个名为yolo_mask的隔离环境Python选3.8是因为一批老YOLOv4代码在3.9以上会出现torchvision API兼容问题没必要冒这个险conda activate yolo_mask切换进环境最后一行安装PyTorch 1.8.1、配套的torchvision 0.9.0和CUDA 10.2的runtimecudatoolkit这三个版本是经过验证的组合能覆盖绝大多数YOLOv4 PyTorch实现的依赖要求。这里有个容易误会的点conda里装的cudatoolkit并不等于你要在操作系统层面单独装CUDA。cudatoolkit只是把PyTorch运行CUDA算子所需的库带进了conda环境系统显卡驱动版本不低于10.2就能跑。换句话说你不需要去NVIDIA官网下载几个G的CUDA Toolkit只需要保证显卡驱动是新一点的。装完做一次快速检查确认当前环境里PyTorch真的能用GPUpython -c import torch; print(torch.__version__, torch.cuda.is_available())输出类似1.8.1 True才算正常。常见翻车是输出1.8.1 False说明你装成了CPU版回去检查conda install命令里是不是少了-c pytorch参数或者把cudatoolkit误写成了cpuonly。这一步检查不做后面训练直接卡在模型搬显存那一步。3.2 依赖库安装opencv、numpy这些基础包别漏PyTorch装好之后还需要把项目运行所需的其他Python库补齐。YOLOv4这类项目最常用的依赖是这几样pip install opencv-python numpy matplotlib tqdm tensorboard逐个说用途。opencv-python负责图片和视频帧的读取、缩放、画检测框是整个推理链路的地基numpy负责数组和坐标运算matplotlib用来可视化预测结果tqdm显示训练进度条方便你盯着loss看tensorboard是训练日志可视化工具loss曲线和mAP变化都在它里面看。如果项目根目录下有requirements.txt也可以直接执行pip install -r requirements.txt一次装齐。装完之后再从opencv角度验证一次python -c import cv2; print(cv2.version)能输出类似4.5.1的版本号就行。opencv版本太老或太新都可能出现VideoCapture读取avi异常的现象如果后面视频推理翻车优先看这里。3.3 跑通第一次推理单张图片和视频的参数怎么传环境起来后先拿mask.jpg做单张图片推理验证。不同YOLOv4 PyTorch实现的入口脚本命名不一样有的叫demo.py有的叫detect.py以README为准但参数结构通常长这样python demo.py \ --model_def config/yolov4.cfg \ --weights weights/yolov4.weights \ --input mask.jpg \ --output result_yolo.jpg参数说明--model_def指向模型结构配置文件里面定义了网络层结构、anchors和类别数--weights指向预训练权重文件如果这个路径不存在程序会直接报FileNotFoundError那就是权重没下载或放错目录--input是输入图片路径--output是保存结果图的路径。第一次跑的时候如果报错说缺少某个模块回到3.2节把依赖装齐再重跑。单张图成功之后把视频推理也验证一遍这一步顺带检查OpenCV的VideoWriter编码器是否正常python demo.py \ --model_def config/yolov4.cfg \ --weights weights/yolov4.weights \ --input output202212031535.avi \ --output my_output.avi输出文件my_output.avi如果打不开多半是编码器问题把输出后缀改成.mp4或者换一个fourcc编码就行。跑视频的时候留意一下处理速度如果一秒钟只能处理两三帧说明机器在做纯CPU推理或模型输入尺寸开太大后续换GPU或降分辨率。4. 训练自己的口罩检测模型VOC数据组织、参数修改与训练流程4.1 数据准备labelImg标注与VOC目录结构只跑demo不动数据的话你验证的永远是别人的模型。要训练自己的口罩识别模型第一步是准备数据集。常见做法是用labelImg工具标注格式选PASCAL VOC这样后面转YOLO格式的txt也方便。标签只留一类还是两类取决于需求只关心戴没戴口罩就一类要同时区分戴和不戴就得两类类别名对应不同的class_id。标注完的目录结构按VOC规范组织VOCdevkit/ └── VOC2007/ ├── JPEGImages/ # 原始图片 ├── Annotations/ # labelImg生成的XML标注 ├── ImageSets/ │ └── Main/ # train.txt / val.txt └── labels/ # YOLO格式txt脚本生成JPEGImages放原图Annotations放xml标注ImageSets/Main下的train.txt和val.txt存放图片文件名列表不带扩展名每行一个labels目录由脚本从xml转换而来每行一个目标格式是class_id x_center y_center w h坐标归一化到0到1。YOLO训练直接读labels和JPEGImagesImageSets只是用来划分训练集和验证集。新手常犯的错是把xml直接当训练输入。YOLOv4系的训练代码读的是txt格式xml只是中间标注漏掉转换脚本这一步训练时就会报找不到标签文件的错。数据量方面口罩识别这个任务比通用物体检测简单一个类别的数据有500到1000张图就够出效果前提是场景多样性要够——室内、室外、侧脸、遮挡、口罩颜色差异都要有。4.2 训练参数修改类别数、batch_size、学习率这几项必须动数据放好后打开config目录下的yolov4_config.py重点改这几个参数# config/yolov4_config.py NUM_CLASSES 1 # 口罩识别只分戴了口罩一类 CLASS_NAMES (face_with_mask,) BATCH_SIZE 8 # 6G显存以内建议降到4 LEARNING_RATE 1e-3 EPOCHS 100NUM_CLASSES和CLASS_NAMES必须和你的标注对齐。类别数量不一致加载预训练权重时会报维度不匹配的错因为最后一层卷积的卷积核个数是根据类别数算的。BATCH_SIZE取决于显卡显存6G显存用8比较稳4G就降到2或4不然训练刚开始就CUDA out of memory。LEARNING_RATE我一般先用1e-3前10个epoch看loss变化再决定要不要调到5e-4。还有个容易忘的地方是anchors。YOLOv4的默认anchors是针对COCO数据集算出来的COCO里大目标多。如果你收集的口罩图是门禁摄像头视角人脸小、占比低那默认anchors会明显带偏回归分支。这种情况要跑项目自带的k-means聚类脚本基于你标注的框重新算一组anchors再填回配置里。不做这一步训练出来的模型在真实场景下召回率会肉眼可见地掉。4.3 启动训练与日志观察loss怎么掉才算正常训练命令在README里一般有模板常见写法是这样python train.py \ --model_def config/yolov4.cfg \ --data_config config/custom.data \ --pretrained weights/yolov4.weights--model_def指向网络结构文件--data_config指向数据配置文件里面写了训练集路径、验证集路径、类别数--pretrained是预训练权重路径。用预训练权重做迁移学习能大幅缩短训练时间从零训练100个epoch未必能收敛用COCO预训练权重微调的话30到50个epoch通常就能出不错的效果。看训练日志时重点盯每轮的loss和mAP。loss在前10个epoch处于5到20之间波动很正常别被吓到如果loss一直在几十上下不降先查anchors有没有对准数据再查学习率是不是偏大如果loss突然变成nan把LEARNING_RATE降一个数量级再继续。训练结束后验证集上的mAP能到0.85以上这个模型就可以拿去做实际场景测试了。5. 避坑与常见问题排查换机器、换数据、换环境后翻车的5个案例5.1 现象训练一开始就报CUDA out of memory训练脚本跑起来第一轮epoch还没结束就抛RuntimeError: CUDA out of memory。这种情况在大模型小显存组合里非常常见。原因基本是三个batch_size开太大、模型输入尺寸设太高、或者显卡同时被其他程序占用。YOLOv4默认输入尺寸是608显存占用比416高出一大截。解决先把BATCH_SIZE减半8降到44降到2再把config里的输入尺寸从608降到416。两步都不够的话在训练循环开头加一句torch.cuda.empty_cache()强制清理缓存。import torch torch.cuda.empty_cache()这句代码清理的是PyTorch缓存的显存块不影响已经在用的数据。它是急救手段不能从根本上解决显存不足长期方案还是调低batch_size和输入尺寸。5.2 现象loss一路不降甚至来回振荡训练跑了几十个epochloss始终在某个区间晃或者不降反升。最常见的原因是anchors和你的数据集没对齐默认anchors是从COCO来的目标框尺寸分布和你的口罩数据差异大回归分支怎么学都学不准。解决跑项目自带的k-means聚类脚本重算anchors同时把LEARNING_RATE降到5e-4。如果数据里大量图片内容是同一段视频抽帧几乎每张都长得差不多模型会在重复样本上反复打转清洗掉相似度过高的帧loss才可能正常下降。5.3 现象单张图检测正常视频推理时漏检率突然升高用mask.jpg测单张图效果还不错一跑视频就频繁漏检检测框时有时无。原因通常是两个视频帧里有运动模糊目标外观和静态图差异大或者推理脚本里置信度阈值设得偏高模糊帧的置信度达不到阈值被滤掉了。解决把置信度阈值从0.5降到0.25到0.3。代价是误检会多几个框但对视频监测场景来说漏检比误检更致命。如果视频分辨率高、目标小还应该把输入尺寸调回608并用跳帧策略保证推理速度而不是盲目压缩输入。5.4 现象cv2.VideoCapture读取带中文路径的视频直接报错代码是Windows下跑的视频放在D盘的某个中文目录里cv2.VideoCapture返回的布尔值直接是False一帧都读不出来。原因是OpenCV的旧版VideoCapture在Windows上对中文编码路径处理不好这是老问题。解决最快的方法是路径全改英文文件夹名和文件名都避开中文。如果路径不能改就绕过VideoCapture用imageio库读视频它走的是另一套底层实现对中文路径支持要好很多。5.5 现象加载预训练权重时报unexpected key in state_dict加载weights下的预训练权重时报错提示state_dict里有某些key匹配不上。原因常见于两种一是你改了NUM_CLASSES分类层卷积核数量变了预训练权重里对应的层自然对不上二是PyTorch版本差异导致的序列化格式不兼容。解决检查NUM_CLASSES是否和权重训练时一致在加载代码里给load_state_dict加上strictFalse参数跳过不匹配的层。加载完之后再用验证集跑一次推理确认模型不是全输出垃圾。6. 进阶验证用mAP量化模型效果把检测结果输出成结构化数据6.1 mAP评估不看单张效果看整个验证集的平均精度训练完只看几张图的输出就下结论这是最容易自欺欺人的做法。我一般会跑一遍验证集上的mAP评估用数据说话。YOLOv4 PyTorch版本里通常自带eval.py脚本命令和训练类似python eval.py \ --model_def config/yolov4.cfg \ --weights weights/best.pt \ --data_config config/custom.data跑完之后关注三个指标mAP0.5、Precision、Recall。口罩场景下mAP0.5能到0.85以上基本可用Precision最好在0.9以上Recall至少0.8不然漏检太多。指标含义口罩场景可接受基线mAP0.5IoU阈值0.5下的均值平均精度≥0.85Precision预测框里真正框对的占比≥0.9Recall真实目标里被召回的比例≥0.8如果mAP只有0.6先别急着怀疑模型结构去看数据集是不是有错标框、类别漏标严重、或者图片尺寸和训练时不一致。多数低mAP问题出在数据标注而不是网络本身。6.2 检测结果结构化输出把坐标和置信度写成CSV不少场景需要把检测结果交给下游业务比如统计某个时段未戴口罩的人数、联动闸机报警。这时候把检测框坐标和置信度写进CSV是常用做法代码很简单import csv import cv2 import torch img cv2.imread(mask.jpg) results detector.detect_frame(img) # 返回 [x1, y1, x2, y2, conf, class_id] with open(mask_result.csv, w, newline, encodingutf-8) as f: writer csv.writer(f) writer.writerow([x1, y1, x2, y2, confidence, class_name]) for x1, y1, x2, y2, conf, cls in results: writer.writerow([x1, y1, x2, y2, round(conf, 4), cls]) print(saved mask_result.csv)这段代码的核心是detect_frame的返回结构。x1、y1是检测框左上角坐标x2、y2是右下角坐标单位是像素confidence保留四位小数后续做阈值过滤直接读这一列就可以。CSV格式的好处是不依赖Python环境Excel、数据库、报表工具都能直接读。这套口罩识别项目我前前后后在不同机器上跑过三遍第一次因为环境版本不对卡了两天后面两次各花了不到一下午。从那以后我每次拿到一套YOLO系源码都会强制走一遍先看README、建独立环境、跑demo、用验证集评mAP这个流程这个顺序能省掉大多数翻车。希望帮到你。本文还有配套的精品资源点击获取