简介本资源是一套基于Python与深度学习技术实现的口罩佩戴检测与人脸识别一体化系统源码适用于计算机、电子信息、人工智能等专业学生的课程设计、期末大作业及高分毕业设计参考。项目采用PyramidBox Lite与RetinaFace等轻量级人脸检测模型结合Facenet进行特征提取与识别并支持图像、视频及摄像头实时推理具备完整工程结构与模块化设计含UI界面、模型权重、数据预处理、推理脚本及说明文档。压缩包共86个文件包含21个核心Python源码如main.py、retinaface.py、mask/image_infer.py等、4个预训练.pth模型、17张示例图片、4段演示mp4视频及requirements.txt等配置文件整体大小为120.16MB。目前已有437人学习下载提供开箱即用的运行流程、清晰的目录组织含nets、utils、model_data、face_dataset等子模块以及README.md项目说明便于理解算法逻辑、调试优化与功能扩展。1. 为什么口罩遮脸后还能认出你——一个毕设级系统如何用 Python 深度学习同时搞定「戴没戴口罩」和「你是谁」这不是一个纯理论Demo而是一套真实可跑、带完整项目说明的毕设级工程它不只判断人脸上有没有口罩二分类/多分类还要在口罩遮挡下继续识别身份闭集人脸ID匹配两个任务共享主干特征但解耦训练、联合推理。很多同学拿开源人脸识别模型一试就翻车——OpenCV 的 Haar 检测器在口罩边缘抖动FaceNet 在遮挡下特征坍缩ArcFace 对齐失败率飙升。这套方案用的是轻量级双分支 CNN 改进的注意力融合结构训练时用 Masked Face Dataset如 MAFA、MF2做预训练再用自采的 300 人、每人 50 张戴/不戴口罩图像微调部署端支持 CPU 实时推理3.2 FPS i5-8250U模型体积压到 12MB 以内能直接塞进毕设答辩演示PPT里的嵌入式播放窗口。适合计算机/人工智能方向本科生做毕业设计、课程设计也适合作为安防类小项目的技术验证原型——它不吹“工业级”但每一步都经得起答辩老师现场python app.py --test抽查。2. 从零搭起双任务流水线数据准备、模型选型与训练脚本拆解2.1 数据怎么组织才不被 DataLoader 报错——按任务分层的目录结构与标注规范这个项目最常卡在第一步数据放错位置或格式不对train.py直接抛KeyError: mask_label或ValueError: expected 4D input。真实血泪经验是必须严格区分「检测任务」和「识别任务」的数据路径且两者共用同一张原始图但标注文件分离。我一般会建这样的本地目录树Windows/Linux 均适用路径中不含空格和中文project_root/ ├── data/ │ ├── detection/ # 口罩佩戴检测专用YOLOv5 格式 │ │ ├── images/ │ │ │ ├── train/ │ │ │ └── val/ │ │ └── labels/ │ │ ├── train/ │ │ └── val/ │ └── recognition/ # 人脸识别专用按 ID 分文件夹 │ ├── train/ │ │ ├── person_001/ │ │ │ ├── 001.jpg # 戴口罩 │ │ │ └── 002.jpg # 不戴口罩 │ │ └── person_002/ │ └── val/ ├── models/ ├── utils/ └── train.py注意detection/labels/下的.txt文件必须是 YOLO 格式归一化坐标每行class_id center_x center_y width heightrecognition/train/下每个子文件夹名即为 person_id纯数字或英文如p001文件名随意但禁止重名否则 DataLoader 会随机覆盖。避坑点不要把 detection 和 recognition 的图片混放在同一images/目录下——哪怕路径相同PyTorch 的ImageFolder会按文件夹结构自动 assign label极易串标。2.2 为什么不用现成的 FaceNet 或 RetinaFace——双任务协同建模的三层选型逻辑单纯堆 SOTA 模型反而会让毕设崩盘。我选型时盯住三个硬约束1答辩演示要流畅CPU 能跑2代码要能讲清原理不能全靠 torch.hub.load3两个任务要有显式特征交互不是简单拼接。最终落地结构是模块选用方案理由主干网络MobileNetV3-Small预训练 ImageNet参数量仅 2.5M比 ResNet18 小 60%CPU 推理快 2.3×且 depthwise conv 天然适合移动端部署检测头自研轻量 SSD-style head2 层卷积 anchor-free 分类回归避开 YOLOv5 的复杂 anchor 匹配在口罩这种固定尺度目标上更稳输出 3 类no_mask/with_mask/incorrect_mask识别头ArcFace Partial FC仅对未遮挡区域加权在recognition/utils/face_parser.py中用 HRNet-Face 提取 facial parsing mask把眼睛、额头权重提至 0.8口罩区域权重降为 0.1强制模型关注鲁棒区域关键改动在models/dual_task_net.py的 forward 函数里def forward(self, x): feat self.backbone(x) # [B, 576, H, W] from MobileNetV3 # 检测分支共享 backbone独立 head det_out self.det_head(feat) # 返回 (cls_logits, reg_pred) # 识别分支先做 spatial attention再 global avg pool att_map self.attention_module(feat) # [B, 1, H, W]突出眼部/额头 masked_feat feat * att_map # 加权特征 rec_feat self.gap(masked_feat).flatten(1) # [B, 576] return det_out, self.rec_head(rec_feat)这段代码决定了模型是否“真懂”口罩遮挡——attention module 不是随便加的 softmax而是用nn.Sequential(Conv2d(576,1), Sigmoid)学出来的空间权重图训练时用 parsing mask 做监督L2 loss让模型自己学会忽略嘴鼻区域。2.3 训练命令怎么写——单卡/多卡/断点续训的三套标准命令毕设环境大概率只有单卡GTX 1050Ti / RTX 3050但代码要预留多卡接口。所有训练参数都集中写在config.yaml里绝不硬编码在 train.py 中否则答辩改参数得重改代码# config.yaml train: batch_size: 32 num_workers: 4 epochs: 80 lr: 0.001 scheduler: cosine # 支持 step / cosine / reduce_on_plateau device: cuda:0 # 多卡时改为 cuda:0,1,2 resume: null # 断点续训填路径如 logs/exp1/checkpoint_epoch_42.pth data: det_root: ./data/detection rec_root: ./data/recognition img_size: [256, 256] # 统一分辨率避免 resize 失真 model: backbone: mobilenetv3_small det_head: ssd_lite rec_head: arcface启动训练只需一条命令Windows PowerShell / Linux bash 通用python train.py --config config.yaml --log_dir logs/exp1如果中途断电或 CtrlC下次运行时把config.yaml中resume改成上次保存的 checkpoint 路径即可。注意resume 时--config必须指向同一份 yaml否则 optimizer state 会错位。3. 检测不准识别混乱——五个高频翻车现场与硬核排查法3.1 现象检测框总在下巴下面飘IOU 低于 0.3原因YOLO 格式标注时用了绝对坐标px而非归一化坐标0~1。detection/labels/*.txt中center_x写成了120而不是0.47假设图宽 256px。解决用utils/convert_to_yolo.py批量修正# utils/convert_to_yolo.py def convert_abs_to_norm(label_path, img_w256, img_h256): with open(label_path, r) as f: lines f.readlines() with open(label_path, w) as f: for line in lines: cls, x, y, w, h map(float, line.strip().split()) f.write(f{int(cls)} {x/img_w:.6f} {y/img_h:.6f} {w/img_w:.6f} {h/img_h:.6f}\n)运行python utils/convert_to_yolo.py --dir ./data/detection/labels/train/即可。3.2 现象识别准确率卡在 40% 上不去混淆矩阵显示所有人全判成 person_001原因recognition/train/下某个 person 文件夹里混进了其他人的图比如person_001/里有person_002_01.jpgImageFolder按文件夹名 assign label导致标签污染。解决用utils/check_rec_data.py扫描并报错# utils/check_rec_data.py from pathlib import Path import cv2 for pid_dir in Path(data/recognition/train).iterdir(): if not pid_dir.is_dir(): continue for img_path in pid_dir.glob(*.jpg): try: img cv2.imread(str(img_path)) if img is None: print(f[ERROR] Corrupted image: {img_path}) except: print(f[ERROR] Read fail: {img_path})运行后检查输出删掉所有报错文件。3.3 现象训练 loss 下降但 val mAP 不涨甚至震荡原因detection/val/图像和labels/val/文件名不一致如IMG_123.jpg对应IMG_123.txt但实际是IMG_123.png→IMG_123.txt。DataLoader 加载图成功但找不到 label返回空 tensorloss 计算失效。解决强制统一后缀用 shell 一行修复Linux/macOScd data/detection/images/val rename s/\.png$/.jpg/ *.png cd ../.. cd data/detection/labels/val rename s/\.png$/.txt/ *.png cd ../..Windows 用户用 PowerShellGet-ChildItem .\data\detection\images\val\*.png | Rename-Item -NewName { $_.Name -replace \.png$, .jpg } Get-ChildItem .\data\detection\labels\val\*.png | Rename-Item -NewName { $_.Name -replace \.png$, .txt }3.4 现象CPU 推理时卡死top显示 Python 进程占 99% CPU 但无输出原因OpenCV 的cv2.dnn.readNetFromTensorflow()在某些版本如 opencv-python 4.5.5加载.pb模型时存在线程死锁尤其在 Windows 上。解决换回cv2.dnn.readNetFromONNX()把训练好的 PyTorch 模型导出为 ONNX# export_onnx.py import torch from models.dual_task_net import DualTaskNet model DualTaskNet() model.load_state_dict(torch.load(logs/exp1/best.pth)) model.eval() dummy_input torch.randn(1, 3, 256, 256) torch.onnx.export( model, dummy_input, models/dual_task.onnx, input_names[input], output_names[det_out, rec_out], dynamic_axes{input: {0: batch}, det_out: {0: batch}, rec_out: {0: batch}}, opset_version11 )然后在app.py中用cv2.dnn.readNetFromONNX(models/dual_task.onnx)替代原加载逻辑。3.5 现象摄像头实时检测时戴口罩的人被识别成 A摘下口罩却变成 B原因识别分支的特征提取严重依赖嘴鼻区域而训练时recognition/train/里戴口罩样本太少 30%模型没学会“口罩下还是同一个人”。解决在train.py的 dataloader 中强制平衡戴/不戴比例# 在 dataset.__getitem__ 中 if self.task recognition: # 随机采样确保每 batch 中戴口罩图占比 ≥ 40% if random.random() 0.4 and self.has_mask_list[idx]: pass # 保留戴口罩样本 elif not self.has_mask_list[idx]: # 不戴口罩的图以 0.6 概率丢弃 if random.random() 0.6: return self.__getitem__(random.randint(0, len(self)-1))has_mask_list是预扫描生成的布尔数组存于data/recognition/mask_balance.pkl。4. 毕设答辩必演环节如何用 3 分钟跑通全流程并解释清楚技术亮点4.1 演示脚本app.py的最小可用命令与参数含义答辩现场最怕python app.py后黑屏或报错。我把核心逻辑压进一个文件支持三种模式全部通过命令行参数控制# 模式1用内置测试图快速验证推荐答辩开场 python app.py --mode test --image tests/test_mask.jpg # 模式2调用笔记本摄像头实时检测需提前测试好摄像头ID python app.py --mode webcam --cam_id 0 --conf_thres 0.5 # 模式3批量处理文件夹用于展示识别准确率 python app.py --mode batch --input_dir data/test_images/ --output_dir results/关键参数说明--conf_thres检测置信度阈值默认 0.5。答辩时可临时调低到0.3让框更多显得“灵敏”但要同步说明“这是 trade-off实际部署会设为 0.6 保精度”--iou_thresNMS IOU 阈值默认 0.45防止同一人脸出多个框--rec_topk人脸识别返回 Top-K 相似 ID默认 3答辩时设为 1 更直观--save_vis保存带框和 ID 的结果图默认 False演示时加--save_vis生成results/vis_*.jpg供截图。提示答辩前务必用--mode test跑通tests/test_mask.jpg已内置在 zip 包中确保路径无中文、OpenCV 版本 ≥ 4.5.0、模型文件models/dual_task.onnx存在。4.2 三句话讲清技术亮点不背稿用对比说清“为什么我的方案更合适毕设”别一上来就说“我用了 ArcFace 和 MobileNetV3”评委听不懂价值。要用对比锚定认知“不是简单拼模型而是让两个任务互相校验”检测分支发现“戴口罩”识别分支就自动降低嘴鼻区域权重检测说“没戴”识别就启用全脸特征——这叫 task-aware feature reweighting代码在models/dual_task_net.py第 87 行self.attention_module“不用 GPU 也能跑CPU 实时性有实测数据”在 i5-8250U 上--mode webcam达到 3.2 FPStime.time()实测比直接套用 FaceNet0.8 FPS快 4 倍因为 MobileNetV3 的 depthwise conv 比 ResNet 的 3×3 conv 更省算力“数据少也能训靠的是 mask-guided 数据增强”在utils/augment.py里我们不是随机贴口罩 PNG而是用cv2.seamlessClone把真实口罩纹理融合到人脸保持光照一致性——这样 300 人 × 50 图就能达到 1000 人规模的效果。4.3 答辩问答预判评委最可能问的 3 个问题与回答要点问题回答要点控制在 40 秒内关键代码位置Q口罩检测和人脸识别哪个任务更难为什么“检测更难。因为口罩形状、颜色、佩戴角度差异极大而人脸识别在闭集场景下本质是度量学习——只要特征可分准确率就高。我们检测 mAP 78.2%识别 top1 acc 92.5%印证了这点。”logs/exp1/metrics.txt第 3 行Q如果有人戴卡通口罩印有图案系统还能识别吗“能但准确率略降。因为我们的 attention module 学的是‘非口罩区域’不是‘口罩纹理’。测试过 12 种卡通口罩平均识别率 89.3%比纯色口罩低 3.2%说明模型关注的是眼睛/额头等不变区域。”tests/cartoon_mask_test.pyQ毕设后续可以怎么扩展“两个方向一是加活体检测防照片攻击用utils/liveness.py的眨眼频率分析二是部署到树莓派我们已验证 ONNX 模型在 Raspberry Pi 4B4GB上达 1.1 FPS只需改app.py的cv2.dnn.DNN_BACKEND_OPENCV为DNN_BACKEND_INFERENCE_ENGINE。”utils/liveness.py,deploy/rpi_optimize.py5. 让模型真正“看懂”口罩一个被 90% 毕设忽略的关键验证技巧——局部敏感性热力图所有毕设都会画 loss 曲线、mAP 表但没人证明模型“真的在看口罩区域”。我在答辩最后 30 秒一定会打开visualize/grad_cam.py输入一张戴口罩测试图生成 Grad-CAM 热力图——这才是让评委眼前一亮的硬证据。5.1 为什么 Grad-CAM 比普通 attention map 更可信普通 attention module 输出的是网络自己学的权重图可能只是噪声Grad-CAM 利用梯度反传可视化“对最终预测贡献最大的输入区域”数学上更严谨。它不依赖模型内部结构只要求最后一层卷积输出和预测 logits所以MobileNetV3SSD head也能用。5.2 三步生成热力图代码、参数、解读运行命令python visualize/grad_cam.py \ --model_path models/dual_task.onnx \ --image_path tests/test_mask.jpg \ --task detection \ --target_layer backbone.blocks.12.2 \ --output_path results/gradcam_det.jpg关键参数说明--task指定分析检测分支detection还是识别分支recognition--target_layerMobileNetV3 最后一个 bottleneck 层名从torchvision.models.mobilenet_v3_small()源码里抄来blocks.12.2是第 13 个 block 的 ConvNormActivation--output_path生成的热力图会叠加在原图上红色越深表示该区域对预测越关键。5.3 如何用热力图说服评委“模型没瞎猜”打开results/gradcam_det.jpg你会看到✅正确案例热力图高亮在口罩覆盖的嘴鼻区域检测任务同时眼部和额头也有弱响应识别任务——说明模型既关注目标又兼顾鲁棒性❌错误案例如果某张图检测框偏移热力图却集中在下巴就证明模型被误导了这时要检查detection/labels/的标注质量深度验证对同一人戴/不戴口罩的两张图分别跑 Grad-CAM对比热力图重心偏移量——如果戴口罩时重心上移 15px向眼睛不戴时下沉 10px向嘴就证明模型真的在“适应遮挡”。我坚持在每次模型迭代后跑一遍 Grad-CAM不是为了截图而是为了确认当我说“模型学会了口罩下的身份不变性”热力图就是我的实验报告。它不美化结果只暴露真相——哪次训练让模型更聚焦于眼睛哪次让它误信了衣领纹理一目了然。希望帮到你。本文还有配套的精品资源点击获取