简介：一份面向人脸检测与深度学习入门者的MTCNN完整实现，涵盖模型定义、数据准备、训练、验证与推理全流程，适合算法复现、课程设计及项目实战。压缩包共238个文件，以Python源码、PyTorch权重、图片样本与XML标注为核心，另含TensorBoard训练日志、演示视频及说明文档，整体约217MB，结构清晰便于按模块查阅。目前已有600人学习下载。代码严格按照P-Net、R-Net、O-Net三级级联组织，同时完成人脸分类、候选框回归与5点关键点定位，可直观体验候选框粗选、精炼到输出的完整流程；直接加载已训练模型即可快速验证检测效果，结合日志能观察各阶段损失下降趋势。对研究多任务级联网络的工程实现而言，是兼具完整性与可操作性的实用资料，能省去从零搭建的繁琐。
1. 为什么MTCNN三个小网络，反而比一个检测头更适合工程落地
人脸检测如果只用一个卷积网络直接输出框，模型通常要做得又深又宽才能覆盖各种尺度、姿态和遮挡，推理时计算量恒定地压在整张图上。MTCNN把人脸检测拆成三个小网络级联处理，PNet负责在图像金字塔上快速召回候选框，RNet负责过滤误检，ONet负责精修边界框并输出五点关键点，三个网络串联起来的总计算量反而比单阶段模型可控得多。这套多任务级联卷积网络很适合CPU、嵌入式设备和数据标注预处理场景，也一直是课程设计和算法复现里常被要求完整实现的经典项目。这篇笔记把从数据生成、三网结构、训练配比到部署验证的完整链路拆开讲，新手能照着跑通，熟手可以直接对照参数和坑位。
2. 级联设计选型：PNet-RNet-ONet的输入尺度、产出与取舍
2.1 为什么三网络级联比单检测头更适合小芯片
MTCNN的核心是把一次大计算拆成三次小计算，而且后两次计算量随候选框数量动态变化。图像先被缩放到多个尺度形成金字塔，PNet以全卷积方式扫过每一层，输出大量带置信度的粗框；这些粗框被裁剪成24x24送入RNet，RNet去掉明显不是人脸的区域；剩下的候选再放大到48x48交给ONet做最终判断。PNet扫完整张图是固定开销，RNet和ONet只在少量候选框上工作，所以总耗时会随图像内容自适应，而单阶段检测器不管图里有多少张脸，计算量都是一样的。
这种设计对端侧尤其友好。PNet为了扫全图，网络必须做得非常浅，12x12输入下卷积层加起来也没多少参数；RNet和ONet引入全连接层之后，特征开始走向全局整合，但只处理前一级输出的几十个候选。实测里一张1080p图片，PNet生成的候选框大多集中在几十到一百多个，真正走到ONet的往往只有几个到十几个。三级之间的计算量配比不是固定的，候选框数量越多，ONet占比越高，这也是为什么调参时先看各级候选框数量而不是只看最终精度。
2.2 三网络的输入尺度、输出分支与计算量对照
| 网络 | 输入尺寸 | 网络形态 | 输出分支 | 主要职责 |
|---|---|---|---|---|
| PNet | 12x12 | 全卷积，无全连接 | 2分类、4框偏移、10关键点 | 图像金字塔上快速召回候选框 |
| RNet | 24x24 | 卷积+全连接 | 2分类、4框偏移、10关键点 | 过滤PNet带入的大量误检 |
| ONet | 48x48 | 卷积+全连接 | 2分类、4框偏移、10关键点 | 精修边界框，输出五点关键点 |
三个网络都输出三个分支，这一点常被忽略。PNet和RNet理论上也会输出关键点坐标，但12x24这样的小输入分辨率很难稳定定位眼睛鼻子和嘴角，实际工程里关键点只信任ONet的结果。PNet因为要保持全卷积特性，输出层用1x1卷积代替全连接，这样它才能接受任意尺寸的输入图；RNet和ONet有全连接层，输入尺寸必须固定，所以前一级裁剪出来的框会被统一缩放到24或48。
2.3 三个输出分支的loss匹配：分类、框回归、关键点权重怎么设
多任务loss里三个分支的权重直接决定训练走向。常见基线是分类权重1.0、框回归权重0.5、关键点权重0.5，这个配比适合通用场景。但如果你手工调大回归权重，模型会把更多精力放在把负样本的框也修得整齐，误检框看起来反而更“真实”；调大分类权重又会压缩回归分支的梯度，框的位置会偏。我一般会先保持1.0/0.5/0.5跑通全流程，再看每级网络输出框的分布，而不是单纯盯着总loss曲线。损失函数的设计要跟数据样本类型对应起来：负样本只参与分类loss，部分样本只参与回归，正样本同时参与两者，关键点分支只在带关键点标注的样本上生效。
3. 训练数据生成流程：IOU切分、难样本挖掘与归一化约定
3.1 正样本、负样本、部分样本与关键点样本的IOU划分
训练MTCNN不能只用“是人脸”和“不是人脸”两种标签。真实场景里候选框常常只框住脸的一部分，这种框直接归为负样本太浪费，归为正样本又会让分类器混乱，所以需要第三类：部分样本。按候选框与真实框的最大IoU来切分，常用的区间是：IoU小于0.3归为负样本，0.4到0.65归为部分样本，大于0.65归为正样本。三种样本参与的任务不同，负样本只参与分类，部分样本只参与框回归，正样本参与分类和框回归。带关键点标注的样本单独作为关键点样本加入训练，它的分类标签和正样本一致，但额外激活关键点分支。
| 样本类型 | IoU区间 | 参与分类 | 参与框回归 | 参与关键点 |
|---|---|---|---|---|
| 负样本 | < 0.3 | 是 | 否 | 否 |
| 部分样本 | 0.4 ~ 0.65 | 否 | 是 | 否 |
| 正样本 | >= 0.65 | 是 | 是 | 否 |
| 关键点样本 | >= 0.65 | 是 | 是 | 是 |
训练时各类样本的比例也需要人为控制。负样本数量天然远多于正样本，如果不加限制，一个batch里负样本占比会超过90%，模型学到的只是“全部判负”。常见做法是每轮从图片里随机采样，让正样本、负样本、部分样本的比例接近一比一比二，再叠加关键点样本单独补充。采样比例这个参数直接影响训练稳定性，比学习率更值得先调。
3.2 用前级网络为后级网络生成训练数据
后级网络的训练数据必须由前级网络产出，这是整个MTCNN训练流程里最容易被跳过的关键。RNet在推理时吃到的输入是PNet给出来的粗框裁剪图，这些框的位置、尺度和边界形态跟原始标注框完全不同。如果直接用真实标注框裁剪数据训练RNet，RNet在推理时面对PNet的粗糙输出会不知所措。所以数据生成脚本的中心逻辑是：冻结PNet，让它对训练图片做一次粗检，把输出框作为候选，再和真实框计算IoU划分类型。
def build_net_training_data(pnet_model, image_list, gt_boxes_list, out_size): """用PNet的粗检结果为RNet/ONet生成训练样本，out_size取24或48""" pnet_model.eval() samples = [] for img_path, gt_boxes in zip(image_list, gt_boxes_list): img = cv2.imread(img_path) dets = pnet_detect(img, pnet_model, conf_thresh=0.6) for det in dets: # 与所有真实框算IoU，取最大值作为该候选的标签依据 iou = compute_iou(det, gt_boxes) if iou >= 0.65: label = 1 # 正样本，参与分类+回归 elif iou >= 0.40: label = -1 # 部分样本，只参与回归 else: label = 0 # 负样本，只参与分类 crop = crop_and_resize(img, det, out_size) # 回归目标用(det中心-真实中心)/det宽高，归一化到框尺度 reg_target = cal_reg_target(det, gt_boxes, iou) samples.append((crop, label, reg_target)) return samples这段脚本的关键参数有两个。conf_thresh设成0.6，表示取PNet置信度高于0.6的框作为候选；如果PNet训练还不充分，可以降到0.5，让更多框进入候选池，避免样本类型分布过于单一。部分样本的IoU下界取0.4，低于这个值就算作负样本；上界0.65以上才算正样本，这个区间窗口太窄会导致部分样本过少，窗口太宽会让分类任务变模糊。回归目标必须除以候选框的宽高，得到相对坐标偏移，而不是直接预测像素差值。
3.3 关键点样本的归一化约定
关键点坐标的归一化方式直接影响训练能不能收敛。五点关键点分别是左眼、右眼、鼻子、左嘴角、右嘴角，每个点有x和y两个坐标，一共十个输出值。归一化不能用图像宽高做分母，而是以人脸框的宽高做分母：关键点坐标先减去人脸框左上角坐标，再分别除以框的宽和高。这样做的原因是不同尺寸人脸的关键点相对位置是一致的，眼睛大约在框高的三分之一处，鼻子在中间偏下，除以框宽高之后网络学到的模式才跟图像分辨率无关。
推理阶段还原关键点时，同样要按这个约定逆操作。常见错误是把训练输出直接乘原图尺寸，导致关键点被放到远离人脸框的位置。出现这种问题时，先检查归一化和还原是不是用了同一个参考系，这类错误在代码里往往只有一行之差。
4. 从PNet到ONet：网络定义、训练循环与损失权重配置
4.1 PNet的网络结构与三个输出分支
PNet是三个网络里唯一保持全卷积形态的，它的设计目的是扫整张图像金字塔，所以不能引入全连接层。输入是12x12的彩色图，经过三层卷积加PReLU激活之后，分别用三个1x1卷积输出分类置信度、框偏移和关键点偏移。为什么用1x1卷积而不是全连接？因为全连接层一旦确定输入尺寸，网络就只能接受固定输入，而PNet推理时要处理金字塔里各种尺寸的图，全卷积结构让它可以对任意尺寸输入做滑动。
class PNet(nn.Module): def __init__(self): super().__init__() self.features = nn.Sequential( nn.Conv2d(3, 10, 3, 1), nn.PReLU(10), nn.MaxPool2d(2, 2), nn.Conv2d(10, 16, 3, 1), nn.PReLU(16), nn.Conv2d(16, 32, 3, 1), nn.PReLU(32), ) self.cls = nn.Conv2d(32, 2, 1) self.bbox = nn.Conv2d(32, 4, 1) self.landmark = nn.Conv2d(32, 10, 1) def forward(self, x): x = self.features(x) return self.cls(x), self.bbox(x), self.landmark(x)激活函数选PReLU而不是ReLU，也是有意为之。小尺寸feature map信息量有限，PReLU在负区间保留了一个可学习的斜率参数，梯度不会直接归零，这对浅层网络的参数更新更友好。前两层卷积核数量从10增加到32，保持通道数小步上升，避免在12x12这样的小输入上用大通道数造成过拟合。输出分支的通道数对应任务需求：2是前景和背景两类，4是框的中心偏移和宽高缩放参数，10是五点关键点的xy坐标。
4.2 训练循环里的OHEM实现与损失配置
训练MTCNN最怕的是负样本淹没正样本。由于负样本在数量上占绝对优势，普通交叉熵loss会被大量易分类的负样本主导，模型很快退化成“全部输出负样本”。解决思路是在线难样本挖掘，每个batch内按分类loss从高到低排序，只保留难度最高的前百分之七十的样本参与反向传播。这些样本里既包含难负样本，也包含误分类的正样本，让模型持续关注最容易被判断错的部分。
def train_one_batch(net, batch, optimizer): imgs, label_t, reg_t, lmk_t = batch cls_out, reg_out, lmk_out = net(imgs) # 分类分支用交叉熵，先不聚合，按样本粒度保留 cls_loss = F.cross_entropy(cls_out, label_t, reduction='none') k = int(cls_loss.numel() * 0.7) hard_indices = cls_loss.topk(k, dim=0)[1] cls_loss = cls_loss[hard_indices].mean() # 回归分支只对正样本和部分样本计算 mask = (label_t == 1) | (label_t == -1) reg_loss = (reg_out[mask] - reg_t[mask]).abs().mean() loss = 1.0 * cls_loss + 0.5 * reg_loss optimizer.zero_grad() loss.backward() optimizer.step()OHEM比例这里取的是0.7，是一个折中值。比例太高，比如0.9，几乎没有筛掉任何样本，负样本仍然占主导；比例太低，比如0.3，又会让大量困难正样本被丢掉，模型会变得保守。回归分支用绝对值误差而不是平方误差，MTCNN的框回归目标本质上是中心偏移和宽高缩放，绝对值误差对大偏移的惩罚比平方误差温和，训练初期不容易因为个别离谱的框导致loss震荡。权重配比里分类是1.0，回归是0.5，关键点是0.5，这个配置下三个分支的loss量级基本能保持一致。
4.3 三网络级联训练流程与超参对照
级联训练的顺序不能乱。第一步用公开人脸检测数据训练PNet，让它先具备粗检能力；第二步冻结PNet，用它的输出框生成RNet训练数据，训练RNet；第三步把PNet和RNet串联起来，用前两级的输出生成ONet训练数据。这个流程保证每一级网络的输入分布都来自真实推理链路，而不是来自标注框。三个网络的训练超参有差异，主要体现在输入尺寸和batch大小上。
| 网络 | 输入尺寸 | batch_size | 初始学习率 | OHEM比例 | 训练数据来源 |
|---|---|---|---|---|---|
| PNet | 12x12 | 128 | 1e-3 | 0.7 | 原始图像随机裁剪 |
| RNet | 24x24 | 64 | 1e-3 | 0.7 | PNet粗检输出 |
| ONet | 48x48 | 32 | 1e-3 | 0.7 | PNet+RNet串联输出 |
PNet输入小，batch可以开得大，GPU显存压力小；ONet输入48x48，加上全连接层的参数量，batch 32已经比较稳。学习率统一从1e-3起步，训练到loss曲线平缓后降到1e-4做微调。启动训练时用这类命令：
python train.py --net pnet --batch_size 128 --lr 1e-3 --ohem_ratio 0.7--net参数切换当前训练哪个网络，数据加载逻辑会自动选择对应尺寸的裁剪样本；--ohem_ratio对应上面代码里的0.7，需要调的时候直接改这个值，比改代码方便。
5. 常见问题排查：五条翻车记录和规避方案
5.1 后级网络训练数据分布与实际推理不一致
现象：RNet单独验证时精度很高，接在PNet后面整体检测率断崖式下降，大量人脸在PNet阶段就被丢弃或框位偏得太远。
原因：RNet的训练数据用的是真实标注框裁剪，而推理时RNet吃的是PNet输出的粗框，两者框的位置、尺度和边界噪声完全不同。RNet只学会了处理“干净”的框，遇到PNet的粗糙输出就失效了。
解决：训练RNet和ONet的数据必须从PNet的检测结果里生成，把PNet冻结后跑一遍训练集，收集输出框再裁剪。这一步不能省，也不能用标注框替代。我在代码里把数据生成封装成独立脚本，每次换数据集都会重新生成一遍，绝不重复使用上一轮的数据缓存。
5.2 边界框回归offset符号反了
现象：检测框中心明显偏离人脸中心，框总是整体往某个方向偏移，回归loss已经很低但框位就是不贴合。
原因：框回归的学习目标是候选框到真实框的偏移量，推理时要把这个偏移应用到候选框上。不同实现里offset的定义方向不一致，有的存的是“真实框减候选框”，有的存的是“候选框减真实框”，符号反了之后loss照样能降，因为模型学会了输出反向的偏移，但加上推理时的修正逻辑就变成越修越偏。
解决：单独写一个可视化脚本，把PNet输出的原始框和回归修正后的框同时画出来。如果原始框贴着人脸但修正后偏移，说明符号反了，把offset的加减方向反过来即可。这个检查应该在训练早期就做，不要等整个pipeline跑通再排查。
5.3 关键点还原时分母用错
现象：ONet输出的关键点画在图像左上角，或者全部挤在框的右下角，看起来像一组乱码点。
原因：训练时关键点坐标做了归一化，减框左上角后除以框宽高。推理时还原必须用同一个公式乘回去。常见错误是用原图宽高做分母归一化，训练和推理两端各自用了不同参考系，输出自然对不上。
解决：还原公式固定写成x = bx + landmark_x * box_w，y = by + landmark_y * box_h。无论模型从哪里换来的，先验证这组公式在单个样本上能正确还原，再进入批量推理流程。
5.4 分类loss正常但回归loss不降
现象：分类准确率已经到90%以上，框回归loss却一直在0.05附近波动，检测框位置始终差几个像素。
原因：训练数据里部分样本比例不足，回归分支的有效训练样本太少；或者回归目标没有归一化到框尺度，直接用了像素差值，导致loss数值巨大且梯度难收敛。
解决：打印每个batch里正样本、部分样本、负样本的数量，部分样本比例低于20%需要重新采样。回归目标统一改为相对坐标偏移，让目标值落在0到1附近。我在实践中还会把回归loss改成smooth L1，对小偏移的梯度更平滑，后期收敛更稳。
5.5 图像金字塔参数调整不当导致小脸漏检
现象：图片里远处的小脸完全检测不到，或者大脸检测框明显超出人脸范围。
原因：min_face参数控制金字塔最底层能覆盖的最小人脸尺寸，设得太大，小于这个尺寸的人脸在金字塔里缩放后不足12x12，PNet根本看不到；scale_factor控制相邻金字塔层之间的缩放间隔，取值太大则中间尺度覆盖不足，特定尺度的人脸会漏掉。
解决：先保持scale_factor=0.709不动，这个值来自面积缩放0.5开根号的近似，每一层金字塔边长约缩小为上一层根号二分之一，覆盖密度比较合理。优先调min_face，端侧追求速度可以提到40，追求recall就用20。通过打印金字塔层数和检出框数量来确认参数影响，不要凭感觉乱改缩放因子。
6. 验证与端侧部署：单图排查脚本和CPU实时参数
6.1 单图验证脚本：把框、关键点、置信度一次画出来
拿到一份MTCNN实现，第一件事不是训练，而是跑单图验证脚本。这个脚本加载三个网络的权重，对一张图做完整检测，把检测框、五点关键点、置信度全部画出来，同时打印每一级输出的候选框数量。通过数量和位置的比对，能快速定位问题出在哪个网络环节。
def verify_mtcnn(image_path, nets, save_path='verify.jpg'): img = cv2.imread(image_path) pnet, rnet, onet = nets boxes = pyramid_detect(img, pnet, rnet, onet, min_face=20, scale_factor=0.709, nms_thresh=0.7) for box in boxes: x1, y1, x2, y2, conf = box[:5] lmk = box[5:].reshape(5, 2) cv2.rectangle(img, (int(x1), int(y1)), (int(x2), int(y2)), (0, 255, 0), 2) for (lx, ly) in lmk: cv2.circle(img, (int(lx), int(ly)), 2, (0, 0, 255), -1) cv2.imwrite(save_path, img)pyramid_detect内部按顺序做了三件事：构建图像金字塔、让PNet在每层上做粗检并回归修正、把候选框送入RNet和ONet逐级过滤。第一次跑这个脚本，重点看PNet输出的候选框数量：一张图如果只有人脸却输出上百个候选框，说明PNet置信度阈值偏低；如果候选框里人脸框位置明显偏离，优先检查上一节说的回归符号。关键点画出来应当分别落在左右眼中心、鼻尖和嘴角位置，任何偏移都值得先排查归一化公式。
6.2 CPU部署的最小配置与优化顺序
MTCNN整套跑起来不需要GPU，三个网络加起来参数量很小，纯CPU上处理单帧能做到几十毫秒级别，具体看图像分辨率、候选框数量和线程数。部署时最小配置包含三份权重文件、图像金字塔构建逻辑和NMS后处理。如果只看人脸检测不需要关键点，可以把ONet换成轻量判断或者直接用RNet的输出，速度能再上一档。
优化顺序有讲究，先限流再改参数。第一步提高PNet的置信度阈值，从0.6提到0.7，候选框数量能降一半以上，后两级计算量随之减少；第二步调大min_face，跳过小脸检测；最后才考虑修改网络结构。把PNet的stride从2改成1可以提升小脸召回，但PNet要扫的像素位置翻倍，速度直接掉一半，属于性价比很低的改动。图像金字塔层数也可以通过限制最长边来控制，1080p图缩放到640以内再检测，速度提升明显且精度损失有限。
这套流程我前前后后复现过几次，每一次踩坑的位置都是数据生成和归一化这两块，网络结构反而是最不容易出错的部分。从那以后我每次拿到新的检测任务，都会强制让训练数据生成和单图验证脚本先跑通一遍，确认三级候选框数量变化符合预期，再回去调loss和超参，整个流程稳了很多。希望这份笔记能帮你在MTCNN的完整实现上少走几步弯路。
本文还有配套的精品资源，点击获取
