简介这是一份基于 Faster RCNN 的人脸口罩识别系统工程包主要面向计算机、人工智能、自动化、电子信息等专业的在校生与开发者适用于课程设计、毕业设计或项目初期演示。项目将数据、模型、训练与部署整合在一起dataset 目录按“姓名”存放训练图片trainer.py 负责训练人脸数据集recognizer.py 用 Streamlit 完成口罩场景下的人脸识别另附效果截图与 Markdown 运行说明便于理解流程和复现。压缩包共 5 个文件以 Python 脚本为主含 2 张界面示意图与 1 份说明文档整体约 881KB结构简洁但覆盖完整。代码已经测试通过适合以此为基础修改出更多功能已有 205 人学习浏览可作为人脸识别课设、毕设和口罩检测任务的参考项目。1. 人脸口罩识别选 Faster RCNN课程设计的标准答案与隐藏成本很多课程设计题面写着“基于 Faster RCNN 的人脸口罩识别”交付物约定是 python 源码、运行说明、数据集和训练好的模型看起来是一项“包通过”的工程。但真要把这套东西从压缩包变成能答辩的演示你很快会发现难点不在算法而在版本对齐torchvision 的 Faster RCNN 接口、CUDA 与 PyTorch 的匹配、预训练权重文件的完整性任何一环出错模型就成了黑匣子。这篇文章按“原理 → 数据 → 跑通 → 训练 → 踩坑 → 验证”的顺序把一条能在两三天内走完的路径写清楚适合正在做课程设计、毕业设计或者第一次用 PyTorch 跑目标检测的新手。2. 把 Faster RCNN 拆开Anchor 机制、两阶段检测与口罩样本从哪来2.1 为什么是两阶段候选区域先粗筛再做精修Faster RCNN 和 YOLO 系列最大的区别在于“两阶段”这个设计。第一阶段是 RPNRegion Proposal Network它在一张图上铺大量预设好的 Anchor用卷积特征快速判断哪些位置“可能有目标”并粗略修正框的位置第二阶段才是真正的分类和回归把 RPN 选出来的候选框送到 RoIHead 里细分成“戴口罩/没戴口罩/背景”同时把框再精修一次。这种串行结构在 GPU 上比 YOLO 慢不少但好处是候选框质量高小目标和遮挡场景更稳。口罩检测恰恰是目标小、遮挡多的场景人脸在画面里可能只占几百个像素口罩又贴着人脸下半部分纯单阶段网络容易把口罩和肤色混在一起。因此课程设计选 Faster RCNN天然比 YOLO 更稳妥。从工程角度看torchvision 的fasterrcnn_resnet50_fpn已经帮你实现了完整的两阶段结构不用自己写 RPN 和 RoIHead。常见做法是只用预训练权重在口罩数据集上微调finetune而不是从零训练。预训练权重在 COCO 上见过大量“人”和“脸”的语义ResNet50 FPN 的底层特征已经能响应皮肤的纹理和器官轮廓微调时只需要让上层学会区分“口罩遮挡”和“无遮挡”。这也是为什么小数据集几千张也能训出可展示的效果。2.2 Anchor 尺度怎么影响口罩检测一张参数表说清楚Anchor 是 Faster RCNN 里“先验框”的统称。RPN 在每张特征图上预设几组不同面积和长宽比的框默认配置是面积为 32²、64²、128²、256²、512² 五种比例取 0.5、1.0、2.0共 15 个。口罩在画面里通常比人脸小一号如果整张图被网络缩放到 800 像素边长一张标准人脸约占 100×150 像素口罩大约占 60×20 像素。你会发现默认的最小 anchor 面积是 32²1024 像素对有 1200 像素的口罩区域来说够用但对门口监控里 25×8 像素的远距离口罩默认配置直接失效。课设项目里如果出现“近处能检测远处漏检”多半是 anchor 面积和输入尺寸不匹配。参数项默认值口罩场景建议说明anchor_sizes(32, 64, 128, 256, 512)(16, 32, 64, 128, 256)缩小最小面积提升小口罩召回aspect_ratios(0.5, 1.0, 2.0)(0.5, 1.0, 2.0)口罩横向比例多可加 3.0rpn_pre_nms_top_n_train120006000训练时 NMS 前的候选框数量rpn_post_nms_top_n_train20001000NMS 后保留的框课设内存紧张可调低box_score_thresh0.050.5推理时过滤低置信度框实际调参时别一上来就乱动 anchor。先把输入图片的min_size从默认 800 改到 1000口罩在放大的图上像素变多比单纯改 anchor 面积更直接。如果需要同时兼顾远处小口罩再把anchor_sizes的最小值降到 16。2.3 数据集从哪来公开资源与 labelImg 手工标注的取舍课程设计最容易被卡住的是数据集。公开渠道能找到不少带标注的口罩数据集常见的是 VOC 格式的 XML 标注类别名通常是mask和no_mask或者face_mask和face_no_mask。拿到包后先看两件事第一图片尺寸是不是同一量级有的数据集混入 4K 大图和 480p 小图训练时容易崩第二类别分布是否均衡很多数据集mask样本是no_mask的三四倍不处理的话模型会偏向多数类。也有人拿 CCPD、CrowdHuman 这类热门数据集来问“能不能直接用于口罩识别”那分别是车牌和行人数据集类别对不上转标注的成本比重新标注还高。我的建议是如果时间紧张优先用现成的公开口罩数据集但只取其中 2000 到 3000 张做训练没必要全量吃进去Faster RCNN 在小数据集上的微调效果已经够答辩展示。如果你想自己标注工具用 labelImg输出 PASCAL VOC 格式标注时把“口罩区域”框得稍微比口罩大一圈留出边缘上下文对检测头更友好。一定不要把图像上下翻转的镜面反转当成增强手段口罩翻转后其实没意义水平翻转才是适合口罩任务的正向增强。3. 在 PyTorch 下跑通最小推理环境、权重与第一条检测框3.1 环境版本对照一段能用的配置比高版本更重要拿到源码包后第一步不是读代码而是锁环境。Faster RCNN 的 torchvision 实现从 0.10 到 0.17 改过不少默认行为anchor_sizes入参从 list 改成了 tuplepretrained参数改成了weights如果代码是基于旧版写的用新版 torchvision 直接报TypeError或AttributeError。课设项目里最常见的翻车就是“PPT 里写着 PyTorch 1.13实际机器装的是 2.x模型加载不出来”。我一般会建议直接按源码包里requirements.txt的版本装没有 spec 文件再看代码里 import 了哪些模块。这里给一套经过验证的稳定组合适用于大多数课程设计源码组件推荐版本说明Python3.8.10太高版本的 Python 与旧版 torch 不兼容PyTorch1.10.0稳定、教程多、算子齐全torchvision0.11.0与 PyTorch 1.10 配套含 Faster RCNN 实现CUDA11.3小于等于 PyTorch 1.10 的官方支持上限OpenCV4.5.5图像读取和画框用确认 GPU 可用性时直接用python -c import torch; print(torch.__version__, torch.cuda.is_available())输出应为1.10.0 True。如果is_available()是 False八成是 CUDA 驱动版本低于 11.3或者在安装 pytorch 时选了 cpu 版本。课设环境不建议折腾 CUDA 手动编译卸载重装带 cu113 后缀的版本最省时间。没有 GPU 的机器也可以跑 CPU 版推理单张图约 2 到 4 秒训练就别指望了。3.2 目录结构先看清楚模型权重文件别放错位置一个规范的 Faster RCNN 课设工程目录组织大致是project_root/ ├── checkpoints/ # 训练好的模型权重 .pth 文件 ├── datasets/ # 图片 标注 │ ├── images/ │ ├── annotations/ │ └── train.txt ├── models/ # 如果作者没有直接用 torchvision会放自定义网络 ├── utils/ # 数据加载、可视化工具函数 ├── train.py # 训练入口 ├── test.py # 单图测试入口 ├── predict.py # 推理脚本 └── requirements.txt拿到包后先打开test.py或predict.py找到模型加载语句。很多课设代码会直接在文件里写model.load_state_dict(torch.load(checkpoints/model.pth))这里的相对路径以当前工作目录为基准如果你在项目根目录以外执行命令就会报FileNotFoundError。正确做法是在项目根目录打开终端运行或者在代码里改成基于__file__的绝对路径这是运行说明里最容易遗漏的细节。3.3 单图推理替换图片路径后的第一个可见结果先不碰训练把推理跑通是建立信心的关键。课设源码里的predict.py如果不可用可以直接基于 torchvision 写一个最小的推理脚本import torch import cv2 from torchvision.models.detection import fasterrcnn_resnet50_fpn # 加载模型结构 device torch.device(cuda if torch.cuda.is_available() else cpu) model fasterrcnn_resnet50_fpn(pretrainedFalse, num_classes2) # 1类口罩 1类背景 model.load_state_dict(torch.load(checkpoints/model.pth, map_locationdevice)) model.to(device) model.eval() # 读取图片并做归一化 img cv2.imread(datasets/images/sample01.jpg) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img_tensor torch.from_numpy(img).permute(2, 0, 1).float() / 255.0 img_tensor img_tensor.unsqueeze(0).to(device) # 推理 with torch.no_grad(): predictions model(img_tensor)[0] # 过滤低置信度结果 boxes predictions[boxes].cpu().numpy() scores predictions[scores].cpu().numpy() for box, score in zip(boxes, scores): if score 0.5: x1, y1, x2, y2 box.astype(int) cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(img, fmask {score:.2f}, (x1, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2) cv2.imwrite(result.jpg, cv2.cvtColor(img, cv2.COLOR_RGB2BGR))逻辑说明第 3 行加载的是 torchvision 内置的 Faster RCNN 网络结构num_classes2表示模型输出 1 个目标类别加上 1 个背景类如果你手里的数据集类别是mask和no_mask两类目标这个值应该是3。第 11 行从.pth文件恢复权重map_locationcpu保证没有 GPU 的机器也能加载 GPU 训练出的权重。第 16 行把 HWC 格式的图片转成 CHW并归一化到 0~1 区间这是 torchvision 预训练模型的统一输入格式漏掉归一化是推理结果全乱的经典原因。第 23 行遍历预测结果score 0.5保留高置信度框实际课设演示时可以降到 0.3以展示更多检测框。4. 训练属于自己的口罩模型从标注转换到调参4.1 标注格式统一VOC XML 转成 torchvision 的 targets dicttorchvision 的 Faster RCNN 训练接口不接受 PASCAL VOC 的 XML它需要的是一个targets字典列表。每个 targets 包含三样东西boxes是 N×4 的 FloatTensor存归一化后的绝对像素坐标labels是 N 的 Int64Tensor从 1 开始计数0 是背景image_id是图片索引。这个转换是课设源码里最常见的自定义点可以手写一个 Dataset 类import os import torch import cv2 import xml.etree.ElementTree as ET from torch.utils.data import Dataset class MaskDataset(Dataset): def __init__(self, img_dir, xml_dir, image_ids): # image_ids 是训练文件名列表 self.img_dir img_dir self.xml_dir xml_dir self.image_ids image_ids self.class_map {mask: 1, no_mask: 2} # 类别名转数字 def __len__(self): return len(self.image_ids) def __getitem__(self, idx): img_id self.image_ids[idx] # 读图片 img cv2.imread(os.path.join(self.img_dir, img_id .jpg)) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) h, w img.shape[:2] # 解析 xml 标注 tree ET.parse(os.path.join(self.xml_dir, img_id .xml)) boxes, labels [], [] for obj in tree.findall(object): name obj.find(name).text # 有的数据集标注不带 bndbox可能只有 polygon需单独处理 box obj.find(bndbox) x1 float(box.find(xmin).text) y1 float(box.find(ymin).text) x2 float(box.find(xmax).text) y2 float(box.find(ymax).text) boxes.append([x1, y1, x2, y2]) labels.append(self.class_map[name]) # 空标注图片直接跳过不放进训练 if len(boxes) 0: boxes torch.zeros((0, 4), dtypetorch.float32) labels torch.zeros((0,), dtypetorch.int64) else: boxes torch.as_tensor(boxes, dtypetorch.float32) labels torch.as_tensor(labels, dtypetorch.int64) target {boxes: boxes, labels: labels, image_id: torch.tensor([idx])} return img, target逻辑说明第 10 行定义了类别映射字典实际数据集里如果只有with_mask和without_mask两个类别就映射成 1 和 2。第 21 行读 XML 时需要注意坐标VOC 格式有些是整数有些是浮点统一转 float 处理不会出错。第 30 到 34 行的空标注处理很重要公开数据集里存在少量图片没有任何目标直接返回[0, 0, 0, 0]的伪框会让损失计算报错所以保持 0 长度张量即可。4.2 数据增强与归一化水平翻转和 Normalize 就够了训练 Faster RCNN 时数据增强太多反而不好收敛。课设阶段我一般用两个手段RandomHorizontalFlip和ColorJitter。水平翻转不改变口罩的语义方向也没有翻转文字这类干扰颜色抖动能模拟光线变化让模型不依赖肤色亮度。注意不要用随机裁剪RPN 的 anchor 本身就处理了尺度问题裁剪会破坏样本分布。torchvision 内置的检测模型期望输入张量是归一化到[0, 1]的使用标准化时用 COCO 预训练统计量from torchvision import transforms as T class Compose: def __init__(self, transforms): self.transforms transforms def __call__(self, img, targetNone): for t in self.transforms: img, target t(img, target) return img, target train_transform Compose([ T.ToTensor(), # HWC uint8 - CHW float且除以255 T.RandomHorizontalFlip(0.5), T.Normalize(mean[0.485, 0.456, 0.406], std[0.229, 0.224, 0.225]) ])逻辑说明ToTensor是归一化最容易漏掉的一步它把 OpenCV 读取的uint8数组转成float32并把像素值压缩到 0~1。Normalize用的是 ImageNet 统计量因为 torchvision 预训练权重是在 ImageNet 分类任务上预训练的沿用这套统计量能保证特征分布一致。推理时如果没做Normalize特征分布会偏移这就是为什么很多人的模型训练时 loss 正常、推理时全输出 0.99 置信度的伪框。4.3 训练启动与关键参数batch size、学习率与冻结层训练脚本里最重要的三个参数是lr、batch_size和epochs。课程设计的 GPU 一般是 GTX 1650 或 3060 Laptop显存 4G 到 6Gbatch_size4、image min_size800是临界值。学习率从0.005开始用 SGD 加momentum0.9、weight_decay0.0005每 3 个 epoch 衰减一次。这个配置来自 torchvision 官方检测脚本的经验实测在小数据集上 10 个 epoch 内就能看到框的位置基本正确。import torchvision from torch.optim import SGD from torch.utils.data import DataLoader model torchvision.models.detection.fasterrcnn_resnet50_fpn( pretrainedTrue, num_classes3 ).to(device) # 冻结 backbone 底层只训练高层的 FPN 和 RPN params [p for p in model.parameters() if p.requires_grad] optimizer SGD(params, lr0.005, momentum0.9, weight_decay0.0005) lr_scheduler torch.optim.lr_scheduler.StepLR(optimizer, step_size3, gamma0.1) def collate_fn(batch): return tuple(zip(*batch)) train_loader DataLoader(train_dataset, batch_size4, shuffleTrue, num_workers0, collate_fncollate_fn) for epoch in range(10): model.train() total_loss 0.0 for images, targets in train_loader: images [img.to(device) for img in images] targets [{k: v.to(device) for k, v in t.items()} for t in targets] loss_dict model(images, targets) loss sum(loss for loss in loss_dict.values()) optimizer.zero_grad() loss.backward() optimizer.step() total_loss loss.item() lr_scheduler.step() print(fEpoch {epoch1}/{10}, loss: {total_loss/len(train_loader):.4f})逻辑说明第 8 行pretrainedTrue会自动去下载 COCO 预训练权重如果你机器不能从官方源下载需要手动把.pth文件放到缓存目录这是源码包容易缺失的一环。第 17 行的collate_fn是检测任务的标准写法因为一张图的目标数量不定不能用默认的 stack 方式批量拼接。第 27 行model(images, targets)在训练模式返回的是损失字典不是预测结果这点与推理时完全不同。第 31 行统计的是 5 个损失项之和loss_classifier分类损失、loss_box_reg候选框回归损失、loss_objectnessRPN 目标性损失、loss_rpn_box_regRPN 框回归损失如果某个分量持续不降要单独打印出来排查。停止训练的标准不是 loss 降到最低而是验证集上的框不再明显偏移。课设场景里训练 10 个 epoch 足够再多就有过拟合风险表现为训练 loss 很低但验证集检测错乱。5. 常见问题与避坑训不收敛、漏检小口罩、显存爆掉的排查思路5.1 模型输出大量整图伪框置信度接近 1现象是推理时每个边框都覆盖图片的大半部分置信度还高达 0.98看起来“检测”到了所有位置。绝大多数情况是输入张量的数值范围不对训练时用ToTensor把像素除以 255 得到 0~1推理时如果直接用torch.from_numpy(img).permute(2,0,1).float()像素值还是 0~255模型看到的是被放大了 255 倍强度的异常输入。解决方法是推理前给张量手动除以 255同时补上Normalize的参数让推理和训练走完全相同的预处理管线。5.2 训练 loss 在 0.7 附近不降检测框总是画偏0.7 是一个很典型的“停滞值”通常意味着类别严重不均衡。Faster RCNN 的默认损失里分类部分用的是交叉熵如果no_mask样本是mask样本的三倍模型只需把所有框都归为多数类就能拿到很低的 lossRPN 部分学习不到有意义的框偏移。另一个常见原因是 anchor 与目标尺度差距过大如果图片里人脸只有 40×40 像素默认最小 anchor 是 32×32长宽比 2:1 的口罩恰好落在 anchor 的比例盲区。解决方法是先做数据均衡用WeightedRandomSampler对少样本类别过采样再缩小anchor_sizes或增大输入min_size。5.3 训练中途显存溢出 OutOfMemory在 4G 显存上跑batch_size4、min_size800的 FPN 很容易爆显存。现象不是一开始就爆而是前几个 batch 正常第 20 个 batch 突然报CUDA out of memory。原因在于检测任务的显存占用随目标数量动态变化目标多的图在 RPN 阶段产生的候选框更多占用瞬时飙升。解决思路有三种把batch_size降到 2把输入min_size从 800 降到 640在torch.cuda.amp的GradScaler下用混合精度训练。课设优先选前两种混合精度会引入少量数值误差对新手不友好。另外建议在训练循环里加一句torch.cuda.empty_cache()释放上一 batch 的缓存碎片实测能缓解一部分峰值压力。5.4 预训练权重加载时报错size mismatchsize mismatch for roi_heads.box_predictor.cls_score...是改类别数时最经典的报错。原因是你在代码里设置了num_classes3但加载的 COCO 预训练权重最后一个分类层是 81 维80 个类别加背景无法对位。除非你想用 COCO 模型的 80 类检测结果做迁移否则加载预训练权重时要么用strictFalse忽略不匹配的层要么按顺序先加载backs特征层再随机初始化分类头。正确做法是state_dict torch.load(fasterrcnn_resnet50_fpn_coco.pth) model.load_state_dict(state_dict, strictFalse)strictFalse会让能匹配的层加载权重分类层保留随机初始值。注意这样做的代价是前面几轮训练分类头时梯度会比较大学习率要调低 5 倍否则容易震荡。5.5 同一份权重不同机器跑出不同结果这是新手最容易当成“玄学”的问题其实原因很明确eval()模式没设置。PyTorch 的 BatchNorm 层在训练和推理时行为不同训练时用当前 batch 的均值和方差推理时用累计的全局统计量。如果保存模型前的最后一个操作是model.train()状态那么你保存的 BN 层统计量已经乱掉了。正确做法是训练结束后先model.eval()再做一次torch.save。加载一方也要注意在model.load_state_dict之后显式调用model.eval()不要依赖模型的默认状态。6. 验证与进阶mAP 怎么算、Faster RCNN 如何换 Backbone训练完成的标记不是 loss 曲线而是验证集上出现稳定的高质量检测框。课程设计答辩时老师最常问“你的模型效果怎么衡量”。如果源码包里没写评估逻辑可以自己实现一套最简单的 mAP0.5 计算对验证集的每个预测框按置信度降序排列逐个计算它与真值框的 IoU阈值取 0.5IoU 大于阈值且类别一致视为 True Positive。用这个每次迭代时打印比只看 loss 更有说服力。COCO 官方的 eval 接口更全面但依赖pycocotools课设时间紧不建议引入额外依赖。进阶方向有两个。一个是把 Backbone 从 ResNet50 换成 ResNet101 或 MobileNetV3torchvision 对 Faster RCNN 提供了backbone参数入口但课程设计代码大多是封装的最省事的替换方式是保留 FPN 结构单独把backbone换成 torchvision 里resnet101的layer4输出通道为 2048 的特征层再改out_channels。另一个方向是导出 ONNX 模型用 OpenVINO 或者 ONNXRuntime 做加速部署这样可以把模型从 Python 脚本里解放出来接到 Flask 或桌面端的演示上。导出 ONNX 时注意要固定输入尺寸动态 shape 在 ONNX 里兼容性差。我现在拿到新工程量体时有个固定习惯先看checkpoints目录里有没有权重文件再跑一次推理脚本最后才看训练代码。这个顺序能帮你快速区分“环境问题”和“算法问题”比从头读代码高效得多。调参时不要一次改三个以上参数否则模型效果变差你根本不知道是哪个改动引起的。训练集和验证集完全分开是基本纪律朋友圈照片、网上随便下的口罩图都塞进训练集答辩时验证集没漏检但只要换一张现场图片就露馅。希望这篇笔记能帮你把 Faster RCNN 口罩识别的课设做得扎实少熬几个调参的夜。本文还有配套的精品资源点击获取