简介：MTCNN（多任务级联卷积神经网络）是人脸检测中的经典算法，由P-Net、R-Net、O-Net三级网络逐级精化完成候选框筛选与关键点定位。这份代码实现覆盖网络结构定义、候选框生成、关键点回归、训练与测试等完整环节，适合深度学习、目标检测方向的开发者复现实验、完成课程设计或进行算法调优。压缩包共包含238个文件，大小约216.98MB，其中以Python脚本、jpg/png图像、pt模型权重为主，还附有tfevents训练日志、xml标注、pyc编译文件及readme说明；多级目录清晰区分不同阶段和训练产物，便于逐文件对照学习。目前已有600人学习下载。通过这份资料，可以快速搭建MTCNN训练与推理环境，理解多任务级联与难样本挖掘等细节，并借助已提供的权重和样本图像进行效果验证，对学术研究与工程落地均有参考价值。
1. 项目解剖：MTCNN三网级联在目标检测里的位置
拿一份MTCNN源码做二次开发，是我接触深度学习、目标检测、卷积神经网络这几条技术线之后做得最值的一件小事。很多人以为MTCNN只是“人脸检测老古董”，但把它拆开之后你会发现，P-Net、R-Net、O-Net这三个小网络组成的级联结构，恰恰是卷积神经网络做小目标检测时最实用的一套脚手架。它既能在一张满是噪点的照片里靠多尺度金字塔捞回远处的小脸，又能在只有CPU的机器上跑出每秒十几帧的速度；对新手来说，它从数据准备到训练推理的链路短，对熟手来说，它改造成通用检测器的潜力比想象中大。这篇笔记就按我拆这份项目源码的实际顺序来讲。
2. 整体架构与代码布局：P-Net、R-Net、O-Net是如何分工的
2.1 为什么是三个小网络级联，而不是一个深网
MTCNN的核心思想是“粗筛、细筛、精修”。P-Net是一个全卷积网络，输入分辨率只有12×12，作用是滑窗扫描图像金字塔，产出大量候选框；R-Net把P-Net的候选框统一缩放到24×24，再做一次分类和回归，把明显不是脸的框去掉；O-Net拿到48×48的输入，输出最终的边界框和5个关键点坐标。这种设计让计算量大的精修只发生在少量候选框上，而不是一开始就对全图做高分辨率卷积。
从代码结构看，三个网络定义在modcls.py这类文件里，它们共享同一套卷积、PReLU激活、池化组合，差别只在深度和最后的分支。以P-Net为例，它的定义相当紧凑：
class PNet(nn.Module): def __init__(self): super().__init__() self.features = nn.Sequential( nn.Conv2d(3, 10, kernel_size=3, padding=1), nn.PReLU(), nn.MaxPool2d(2, 2), nn.Conv2d(10, 16, kernel_size=3, padding=1), nn.PReLU(), nn.Conv2d(16, 32, kernel_size=3, padding=1), nn.PReLU(), ) self.cls = nn.Conv2d(32, 1, kernel_size=1) self.box = nn.Conv2d(32, 4, kernel_size=1) self.landmark = nn.Conv2d(32, 10, kernel_size=1) def forward(self, x): x = self.features(x) cls = torch.sigmoid(self.cls(x)) box = self.box(x) landmark = self.landmark(x) return cls, box, landmark这段代码里有几个值得注意的点：cls分支输出单通道，用sigmoid压到0到1之间，表示“这块区域是人脸”的概率；box分支输出4个值，分别对应当前锚点框的左上角x、y、右下角x、y的偏移量；landmark分支输出10个值，是5个关键点（左眼、右眼、鼻子、左嘴角、右嘴角）的归一化坐标。共享卷积层让三个任务共用底层特征，这也是MTCNN能在一个网络里同时完成检测和对齐的关键。
实际训练时R-Net和O-Net的网络体量逐级增大，但这三兄弟的输入尺寸是写死的12、24、48。如果你第一次拿到这份源码，建议先把pnet.py、rnet.py、onet.py三个模型的输入输出维度打印一遍，因为后续所有roi变换、坐标还原都依赖这三个尺寸。
2.2 目录结构与运行入口
这份项目的目录安排属于典型的训练/推理分离结构，我只做了一点整理，原样跑通的关键路径大致如下：
mtcnn/ ├── config.py # 全局参数：金字塔、阈值、路径 ├── models/ │ ├── pnet.py │ ├── rnet.py │ └── onet.py ├── train/ │ ├── data_utils.py # 样本生成、IoU标签分配 │ ├── train_pnet.py │ ├── train_rnet.py │ └── train_onet.py ├── detect/ │ └── detector.py # 推理入口 └── utils/ ├── nms.py # 非极大值抑制 ├── pyramid.py # 图像金字塔 └── image_tools.py # 裁剪、缩放的辅助函数训练和检测是两条独立链路。train_pnet.py先启动，生成P-Net难例并保存预测结果；train_rnet.py依赖P-Net产出的候选框；train_onet.py又依赖R-Net。detect/detector.py则是把三个网络串成一条推理流水线，你只需要传一张图片和一个config配置对象。
config.py里的参数基本上是MTCNN能用好的“玄学”所在，拿到代码后先看这几个：
| 参数 | 默认值 | 说明 |
|---|---|---|
| min_face_size | 20 | 金字塔终止条件，小于这个尺寸不再缩放 |
| scale_factor | 0.709 | 每次金字塔缩放比例，值越小能搜到的脸越小 |
| thresholds | [0.6, 0.7, 0.7] | P-Net、R-Net、O-Net的置信度阈值 |
| nms_threshold | 0.7 | NMS的IoU重叠抑制阈值 |
| batch_size | 128 | 每个阶段训练的batch大小 |
我第一次跑的时候就吃过阈值的亏：P-Net阈值设太高，小脸候选框直接全被滤掉，后面的R-Net再厉害也救不回来。正确的做法是先保存P-Net的全部候选框，可视化看看分布，再决定阈值。detect/detector.py内部会按金字塔从小到大逐层处理，每层输出经过NMS后交给下一级网络，这个流程走到最后基本就是稳定的检测结果。
3. 核心模块拆解：从图像金字塔到5点关键坐标的完整链路
3.1 图像金字塔：让大脸小脸都逃不掉
图像金字塔是MTCNN解决尺度问题的第一道工序。它的做法很简单：把原图按scale_factor逐级缩小，形成一叠分辨率递减的图，让同一个P-Net的12×12滑窗在不同尺度的图上对应不同大小的脸。这一步直接决定你能检测到的最小人脸尺寸。
import numpy as np def build_pyramid(img, min_face_size=20, scale_factor=0.709): h, w = img.shape[:2] scales = [] current_scale = 1.0 min_side = min(h, w) while min_side * current_scale >= min_face_size: scales.append(current_scale) current_scale *= scale_factor return scales这段代码的逻辑很直白：从原始尺度开始，每次乘0.709，直到最短边缩到min_face_size以下。0.709这个数字来自论文，经验上是比较稳的频率，因为它在检测召回率和推理速度之间平衡得不错。min_face_size的含义是“你期望检测到的最小人脸边长”，如果你要抓远处的小脸，可以把它调到12，但代价是金字塔层数变多，P-Net要处理更多尺度的图。
准备推理时，我一般会对长边超过1600像素的大图先做一次降采样，不然金字塔十几层全部跑一遍，P-Net的卷积输出会非常大。detect/detector.py里常见的做法是先用一个resize函数限制最长边，再进入金字塔循环。这一步虽然不改变算法逻辑，但能避免后面的NMS阶段把内存撑爆。
3.2 NMS与边界框校准：把候选框变干净
P-Net在金字塔每一层会输出大量的框，这些框彼此重叠、坐标还停留在缩放后的尺度上，不能直接用。NMS的作用就是把重叠度高的框合并，留下每个区域内置信度最高的那个。下面是常见的NMS实现：
def nms(boxes, scores, threshold=0.7): x1 = boxes[:, 0] y1 = boxes[:, 1] x2 = boxes[:, 2] y2 = boxes[:, 3] areas = (x2 - x1 + 1) * (y2 - y1 + 1) order = scores.argsort()[::-1] keep = [] while order.size > 0: i = order[0] keep.append(i) xx1 = np.maximum(x1[i], x1[order[1:]]) yy1 = np.maximum(y1[i], y1[order[1:]]) xx2 = np.minimum(x2[i], x2[order[1:]]) yy2 = np.minimum(y2[i], y2[order[1:]]) inter = np.maximum(0.0, xx2 - xx1 + 1) * np.maximum(0.0, yy2 - yy1 + 1) iou = inter / (areas[i] + areas[order[1:]] - inter) order = order[np.where(iou <= threshold)[0] + 1] return keepscores.argsort()[::-1]把候选框按置信度从高到低排序，每次取最高分框，然后计算它和其他框的IoU，把高于threshold的框全部抑制掉。threshold一般在0.6到0.7之间，太低会让相邻的框被误删，太高又会留下大量重复框，导致R-Net的输入数量膨胀。
P-Net输出的box分支是偏移量，不是绝对坐标。还原的时候要把偏移量乘上当前金字塔尺度的边长，再加上滑窗锚点的起始坐标。这个坐标还原最容易被忽略：如果直接在缩放后的图上计算框坐标再除以scale，会和真实位置差一截。正确顺序是先还原到缩放图坐标，再统一除以scale映射回原图。
3.3 关键点对齐：5点输出的意义
O-Net的landmark分支输出10个值，对应5个关键点的归一化坐标。很多人以为关键点只是“把人脸框出来”的花活，但它在人脸对齐、活体检测、人脸比对里都是前置条件。裁剪人脸区域时，要按O-Net输出的关键点做仿射变换，把眼睛拉平、嘴巴摆正。
def align_face(img, landmark, output_size=(112, 112)): left_eye = landmark[0] right_eye = landmark[1] nose = landmark[2] left_mouth = landmark[3] right_mouth = landmark[4] # 以两眼中心为基准计算旋转角度 dy = right_eye[1] - left_eye[1] dx = right_eye[0] - left_eye[0] angle = np.degrees(np.arctan2(dy, dx)) center = ((left_eye[0] + right_eye[0]) / 2, (left_eye[1] + right_eye[1]) / 2) matrix = cv2.getRotationMatrix2D(center, angle, scale=1) aligned = cv2.warpAffine(img, matrix, (img.shape[1], img.shape[0])) return aligned这段代码的关键参数是5个点里前两个：左眼和右眼。两眼连线与水平线的夹角就是人脸倾斜角，把图像旋转这个角度之后，人脸就摆正了。注意landmark本身是归一化坐标，范围在0到1之间，还原成像素坐标时要乘以对应候选框的宽度和高度。这一步如果忘了乘，轻则关键点偏移，重则仿射变换后裁出来的脸完全是歪的。
4. 训练实战与避坑手册：从数据准备到模型收敛
4.1 数据准备：正样本、负样本、部分样本怎么划分
MTCNN训练数据不像分类任务那样只需要标签，它需要全部三个分支的监督信号。数据准备的核心是IoU标签分配：把裁剪出来的候选框和标注的真实人脸框计算IoU，按区间分成正样本、部分样本、负样本三类。
def assign_label(iou): if iou >= 0.65: # 正样本：分类和回归都参与训练 return 1 elif iou >= 0.3: # 部分样本：只参与回归，不参与分类 return -1 else: # 负样本：只参与分类，让网络学会拒绝背景 return 0这个分配规则决定了整个训练质量。正样本太少，网络会把背景误判成人脸；负样本太少，网络会变得极其保守，真脸也漏检。常见做法是控制正负样本比例在1比3左右，部分样本比例也要适当。我在准备样本时会在一个batch里统计三类样本的数量，如果负样本超过正样本3倍，就随机丢一部分负样本。这份缺点也是最容易让人翻车的地方之一。
4.2 三阶段训练与多任务损失函数
MTCNN的训练不是一次跑完，而是严格按照P-Net、R-Net、O-Net的依赖关系分三阶段推进。P-Net先用公开的人脸检测数据集训练；P-Net收敛后，拿它去跑一遍训练集，把P-Net认为“可能是脸”的区域裁剪出来，作为R-Net的输入；R-Net训练好后，再让它跑一遍，产出O-Net的输入。每个阶段都要重新生成样本，而不是复用之前的裁剪结果。
损失函数由三部分组成：分类任务用交叉熵，边界框回归和关键点回归用欧氏距离（均方误差）。代码实现里通常写成下面这种多任务形式：
def mtcnn_loss(cls_prob, label, bbox_pred, bbox_target, landmark_pred, landmark_target): cls_loss = F.binary_cross_entropy(cls_prob, label) box_mask = torch.abs(label[None, :]) - 1 box_mask = (box_mask >= 0).float() box_loss = F.mse_loss(bbox_pred, bbox_target) * box_mask landmark_loss = F.mse_loss(landmark_pred, landmark_target) * box_mask return cls_loss + 0.5 * box_loss + 0.5 * landmark_loss注意box_mask的写法：只让正样本和部分样本参与回归训练，负样本的回归loss必须置零；landmark分支同理。很多初学者的代码把负样本也拿去做回归，结果网络被背景区域的随机偏移量带偏，收敛之后框的位置总是忽大忽小。正样本在总样本里占比本来就低，如果链接不好，一眼看过去训练loss下降得很漂亮，实际框全是歪的。
4.3 避坑记录：我踩过的5个坑
先说结论：MTCNN这套代码跑通不难，难的是把训练调到稳定收敛。我在复现和改造过程中踩过不少坑，下面是记录最深的5条。
第一条是P-Net分类分支不收敛。现象是训练loss降得很快，但验证准确率卡在0.75左右上不去。原因是正负样本比例没控住，每个batch里负样本占了九成，网络学到“全部输出0”就能拿到最小loss。解决方法是强制正负样本比例不超过1比3，并且每个batch都做一次随机重采样。从那以后我每轮训练前都会先打印batch内标签分布。
第二条是小脸检测不到。现象是测试集里人脸小于40像素时几乎全部漏检。原因是config里min_face_size设成了40，金字塔在缩放到第3层就停了，更小的脸根本没有机会被P-Net看到。解决方法是把min_face_size降到12到20，同时把scale_factor调成0.6到0.7，让金字塔层数足够覆盖小目标。
第三条是R-Net输入图片resize后边界信息失真。现象是R-Net阶段误杀率奇高，本来P-Net输出的候选框有九成召回，经过R-Net后掉到六成。原因是resize时用了最近邻插值，12×12放大到24×24的边缘锯齿被R-Net当成了纹理特征。解决方法是统一用线性插值resize，并且在输入网络前做一次归一化到0到1之间。
第四条是推理时内存暴涨。现象是单张图片没问题，连续跑几十张后进程被杀死。原因是P-Net在全图金字塔上输出的feature map没有及时释放，加上NMS阶段候选框全部保留。解决方法是限制P-Net单层输出的候选框数量，按置信度排序后只保留前5000个，再进R-Net。
第五条是O-Net关键点和框错位。现象是框位置是准的，但5个关键点整体偏到框的右上角。原因是landmark坐标在生成训练样本时用的是局部坐标，而推理时没有变回全局坐标就直接用了。解决方法是把landmark输出乘以候选框宽高，再加上框的左上角坐标，得到原图坐标。从那以后我每次改数据预处理都会多写一个“坐标还原”的单元测试。
5. 二次开发：如何把它改造成你的专属检测器
5.1 改造思路：从人脸到任意目标的迁移
把MTCNN改造成自定义目标检测器，并不需要动三个网络的级联骨架。你需要改的是数据生成逻辑和输出语义。如果你要检测的不是人脸而是车辆，训练阶段只需要把标注换成车辆框，重新生成正负样本，P-Net的分类分支仍然输出单通道置信度，box分支仍然输出4个偏移量。唯一要处理的是输出维度：人脸有5个关键点，而车辆可能不需要关键点，此时直接把landmark分支的loss权重调成0，或者将landmark输出通道改成2×K，K为自定义关键点数。
我一般会先把模型的landmark分支暂时砍掉，只保留cls和box两个输出，这样改造的代码面最小。跑通一个基础版本之后，再根据业务需要决定是否加回关键点。如果目标本身有固定结构，比如车牌的四角、工业零件的定位孔，保留关键点分支会比单纯画框有用得多。
5.2 一个实用技巧：导出ONNX后接外部NMS
训练完的MTCNN模型在实际部署时，经常要脱离PyTorch环境跑。这里有一个可以让你少踩坑的技巧：把三个网络分别导出成ONNX，在外部统一做NMS。这样既保留了MTCNN的检测效果，又避免在C++环境里手写一套坐标还原逻辑。
import torch from models.onet import ONet model = ONet() model.load_state_dict(torch.load('weights/onet.pt', map_location='cpu')) model.eval() dummy_input = torch.randn(1, 3, 48, 48) torch.onnx.export(model, dummy_input, 'onet.onnx', input_names=['input'], output_names=['cls', 'box', 'landmark'], opset_version=11)导出时有两个参数要特别注意：opset_version不要设太低，否则PReLU这种激活函数可能导出失败；input_names和output_names一定要写清楚，因为后续接C++或Java推理时，要按这些名字从推理引擎里取张量。外部NMS的好处是你可以灵活调整阈值，甚至对P-Net和O-Net分别用不同阈值，这一点在Python那套脚本里调起来很笨重，放到部署代码里反而简单。
我自己的教训是：第一次导出R-Net时忘了设置dynamic_axes，结果模型只能接受固定24×24输入，倒是没报错，但后面想融合多尺度输入时完全动不了。从那以后我每次做ONNX导出都会先确认输入输出张量的名字，再检查一次输入尺寸是否和模型定义一致。这套MTCNN代码真正帮我建立了一个习惯：项目到手先梳理数据流走向，而不是急着跑demo。希望这篇拆解能给你省下一些排查时间。
本文还有配套的精品资源，点击获取
