Ultra-Light-Fast-Generic-Face-Detector-1MB:1MB 级轻量人脸检测模型的原理、训练与多端部署实战指南
Ultra-Light-Fast-Generic-Face-Detector-1MB:1MB 级轻量人脸检测模型的原理、训练与多端部署实战指南
本文围绕开源仓库 Ultra-Light-Fast-Generic-Face-Detector-1MB(以下简称 UltraFace-1MB)展开,系统讲解这款专为边缘计算设备设计的轻量人脸检测模型的核心特性、网络结构、WIDER FACE 数据集准备、PyTorch 训练流程,以及 ONNX / NCNN / MNN / Caffe / OpenCV DNN / TFLite 等多种推理部署路径。读完本文,你将掌握从数据清洗、VOC 标注生成、模型训练到多端推理的完整闭环,并能依据实际场景合理选择 320/640 等输入分辨率来权衡速度与精度。
一、项目概览与核心特性
UltraFace-1MB 是面向边缘计算设备(如树莓派、手机、嵌入式 AI 芯片)设计的轻量人脸检测模型,核心指标如下(数据来自 README.md):
- 模型体积小:默认 FP32 精度(
.pth)文件大小为 1.04~1.1MB;经推理框架 int8 量化后约 300KB。 - 计算量低:在 320x240 输入分辨率下约为 90~109 MFlops。
- 双版本可选:
version-slim:主干网络精简,推理速度略快;version-RFB:引入改进后的 RFB(Receptive Field Block)模块,精度更高。
- 多分辨率预训练模型:提供 320x240 与 640x480 两种输入分辨率下基于 WIDER FACE 训练的预训练模型,便于适配不同应用场景。
- 格式迁移友好:支持导出 ONNX,便于跨框架迁移与推理。
- 推理代码齐全:提供 NCNN C++、MNN C++ 与 Python、Caffe / OpenCV DNN、TFLite 等多套推理实现。
仓库根目录下预训练模型位于 models/pretrained,ONNX 模型位于 models/onnx,MNN 量化模型位于 MNN/model,Caffe 模型位于 caffe/model,TFLite 模型位于 tflite/pretrained,口罩人脸变体(masked face)模型位于 masked_face/pretrained。
已验证的运行环境
README.md 中给出的测试通过环境为:
- Ubuntu 16.04、Ubuntu 18.04、Windows 10(用于推理);
- Python 3.6;
- PyTorch 1.2;
- CUDA 10.0 + cuDNN 7.6。
二、网络结构源码解析
UltraFace-1MB 采用 SSD(Single Shot MultiBox Detector)风格的检测框架:轻量骨干网络提取多尺度特征,SSD 检测头在多个特征层上输出分类得分与边界框回归量。仓库中训练与推理使用的完整结构见 vision/ssd/mb_tiny_fd.py 与 vision/ssd/mb_tiny_RFB_fd.py。
1. Mb_Tiny 轻量骨干网络
version-slim 使用 vision/nn/mb_tiny.py 中定义的 Mb_Tiny 骨干。其特点:
- 基础通道数
base_channel = 8 * 2 = 16; - 采用
conv_bn(3x3 卷积 + BatchNorm + ReLU)与conv_dw(depthwise 3x3 卷积 + pointwise 1x1 卷积)交替堆叠,这正是 MobileNet 风格的深度可分离卷积结构; - 通过 stride=2 的下采样逐级缩小特征图:160x120 → 80x60 → 40x30 → 20x15 → 10x8,最终特征图尺寸由输入分辨率决定。
从代码结构可以推断,深度可分离卷积显著减少了参数量与计算量,这是整个模型能控制在 1MB 量级的关键原因之一。
2. BasicRFB 感受野增强模块
version-RFB 在骨干的 40x30 特征层位置(source_layer_indexes 中第 8 层之前)插入了 vision/nn/mb_tiny_RFB.py 定义的 BasicRFB 模块。该模块参考 RFBNet 设计,核心思路是:
- 使用三条并行的卷积分支,分别采用膨胀率(dilation)为
vision+1、vision+2、vision+4的空洞卷积,在不增加参数量与计算量的前提下扩大感受野; - 三个分支的输出拼接后经 1x1 卷积线性组合,再与 shortcut 残差相加并乘以
scale系数(此处scale=1.0),最后接 ReLU 激活。
这种结构可有效捕捉多尺度上下文信息,从而提升中小人脸的召回能力,代价是推理速度略慢——这正是 RFB 版本精度更高、slim 版本速度更快的结构性原因。
3. SSD 检测头与先验框配置
在 vision/ssd/mb_tiny_fd.py 中,两个版本均从骨干的 source_layer_indexes = [8, 11, 13] 三个特征层取特征,再接一层 extras 下采样模块,最终在 4 个特征层上分别挂载分类头与回归头。回归头输出通道为 anchors × 4,分类头输出通道为 anchors × num_classes,其中不同层对应的 anchor 个数(3、2、2、3)由 vision/ssd/config/fd_config.py 的 min_boxes = [[10, 16, 24], [32, 48], [64, 96], [128, 192, 256]] 决定。
检测相关的超参数集中定义在 vision/ssd/config/fd_config.py:
| 参数 | 值 | 作用 |
|---|---|---|
image_mean |
[127, 127, 127] |
推理与训练时的像素均值(减均值归一化) |
image_std |
128.0 |
归一化标准差 |
iou_threshold |
0.3 |
NMS 与先验框匹配的 IoU 阈值 |
center_variance |
0.1 |
中心点回归方差 |
size_variance |
0.2 |
尺寸回归方差 |
image_size |
[320, 240] |
默认输入尺寸(宽 x 高) |
define_img_size(size) 支持 128 / 160 / 320 / 480 / 640 / 1280 六档输入尺寸,会同步更新 image_size、feature_map_w_h_list 并调用 generate_priors 生成对应分辨率下的先验框,保证「训练/推理分辨率」与「先验框集合」一致——这是后续章节反复强调输入分辨率匹配原则的底层实现基础。
三、精度、速度与模型体积对比
以下数据均来自 README.md 作者自测结果,评测设置说明:RetinaFace-Mobilenet-0.25 采用按最大边长等比缩放(人脸不变形),其余网络采用固定尺寸 resize;WIDER FACE val 集最优单尺度(1600)结果为 0.887(Easy)/ 0.87(Medium)/ 0.791(Hard)。
1. WIDER FACE val 精度(320x240 或按最大边长 320 缩放)
| 模型 | Easy Set | Medium Set | Hard Set |
|---|---|---|---|
| libfacedetection v1(caffe) | 0.65 | 0.5 | 0.233 |
| libfacedetection v2(caffe) | 0.714 | 0.585 | 0.306 |
| Retinaface-Mobilenet-0.25 (Mxnet) | 0.745 | 0.553 | 0.232 |
| version-slim | 0.77 | 0.671 | 0.395 |
| version-RFB | 0.787 | 0.698 | 0.438 |
2. WIDER FACE val 精度(VGA 640x480 或按最大边长 640 缩放)
| 模型 | Easy Set | Medium Set | Hard Set |
|---|---|---|---|
| libfacedetection v1(caffe) | 0.741 | 0.683 | 0.421 |
| libfacedetection v2(caffe) | 0.773 | 0.718 | 0.485 |
| Retinaface-Mobilenet-0.25 (Mxnet) | 0.879 | 0.807 | 0.481 |
| version-slim | 0.853 | 0.819 | 0.539 |
| version-RFB | 0.855 | 0.822 | 0.579 |
从两张表可以看出:在中小分辨率测试集上,RFB 版本在 Medium / Hard 子集上表现最好;640 分辨率下各模型精度普遍优于 320 分辨率,验证了「提高输入分辨率提升小脸召回」的趋势。
3. 终端设备推理速度
树莓派 4B MNN 推理耗时(ms,ARM/A72x4/1.5GHz,输入 320x240,int8 量化):
| 模型 | 1 核 | 2 核 | 3 核 | 4 核 |
|---|---|---|---|---|
| libfacedetection v1 | 28 | 16 | 12 | 9.7 |
| 官方 Retinaface-Mobilenet-0.25 (Mxnet) | 46 | 25 | 18.5 | 15 |
| version-slim | 29 | 16 | 12 | 9.5 |
| version-RFB | 35 | 19.6 | 14.8 | 11 |
iPhone 6s Plus MNN(版本 Tag:0.2.1.5)推理耗时(输入 320x240,数据来自 MNN 官方):
| 模型 | 耗时(ms) |
|---|---|
| slim-320 | 6.33 |
| RFB-320 | 7.8 |
Kendryte K210 NNCase 推理耗时(RISC-V/400MHz,输入 320x240,int8 量化,数据来自 NNCase): slim-320 为 65.6ms,RFB-320 为 164.8ms。
4. 模型体积对比
| 模型 | 模型文件大小(MB) |
|---|---|
| libfacedetection v1(caffe) | 2.58 |
| libfacedetection v2(caffe) | 3.34 |
| 官方 Retinaface-Mobilenet-0.25 (Mxnet) | 1.68 |
| version-slim | 1.04 |
| version-RFB | 1.11 |
四、从 WIDER FACE 生成 VOC 格式训练数据集
训练集来源于 WIDER FACE 数据集 + Retinaface 提供的清洗后标签(清洗数据在仓库 data/retinaface_labels 中按 train/test/val 划分)。完整流程如下:
步骤 1:下载数据
将下载的数据解压放入 ./data 目录,二选一:
- 过滤掉 10px×10px 小人脸后的干净 widerface 数据包(百度云盘提取码:
cbiu/ Google Drive);若使用该数据包,可直接跳过步骤 2; - 未过滤小人脸的完整 widerface 数据压缩包(百度云盘提取码:
ievk/ Google Drive)。
步骤 2:过滤小人脸并生成 VOC 标注
由于 WIDER FACE 中存在大量极小且模糊的人脸,不利于高效模型的收敛,训练前需要过滤,默认过滤 10 像素×10 像素以下的人脸。运行仓库根目录下的转换脚本:
python3 ./data/wider_face_2_voc_add_landmark.py
从 data/wider_face_2_voc_add_landmark.py 的源码可以看到关键逻辑:
minsize2select = 10定义了最小人脸尺寸阈值,宽高任一小于该值的框会被丢弃;- 脚本读取 data/retinaface_labels 下的
label.txt(格式:x, y, width, height 及可选 5 点关键点),将满足条件的框写入 VOC XML 标注,并将 train 集的人脸关键点(5 点 landmark + visible + blur 属性)写入<lm>节点; - 同时支持
convert2yoloformat = True时输出 YOLO 格式的归一化 txt 标签(当前默认False); - 程序结束后会把
ImageSets/Main/train.txt重命名为trainval.txt、val.txt重命名为test.txt,从而形成标准的 VOC trainval/test 划分。
运行完成后,./data 目录下会生成 wider_face_add_lm_10_10 文件夹,其内容与数据包(1)解压后相同。完整目录结构如下:
data/
├── retinaface_labels/
│ ├── test/
│ ├── train/
│ └── val/
├── wider_face/
│ ├── WIDER_test/
│ ├── WIDER_train/
│ └── WIDER_val/
├── wider_face_add_lm_10_10/
│ ├── Annotations/
│ ├── ImageSets/
│ └── JPEGImages/
└── wider_face_2_voc_add_landmark.py
步骤 3:训练集就绪
至此 VOC 格式训练集准备完毕。项目根目录提供了两个训练脚本:train-version-slim.sh(训练 slim 版本)与 train-version-RFB.sh(训练 RFB 版本),默认参数已设置好,如需微调请参考 train.py 中各训练参数的说明。
五、PyTorch 模型训练
1. 训练脚本
运行:
sh train-version-slim.sh # 或 sh train-version-RFB.sh
以 train-version-slim.sh 为例,脚本内容核心部分为:
python3 -u train.py \
--datasets ./data/wider_face_add_lm_10_10 \
--validation_dataset ./data/wider_face_add_lm_10_10 \
--net slim \
--num_epochs 200 \
--milestones "95,150" \
--lr 1e-2 \
--batch_size 24 \
--input_size 320 \
--checkpoint_folder ./models/train-version-slim \
--num_workers 4 \
--log_dir ./models/train-version-slim/logs \
--cuda_index 0 \
2>&1 | tee "$log"
train-version-RFB.sh 与前者差异仅在 --net RFB、--checkpoint_folder ./models/train-version-RFB 以及 --num_workers 0。
2. 训练入口与超参数详解
训练主入口为 train.py,其命令行参数(部分)及默认值如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
--net |
RFB |
网络结构,可选 RFB(精度高)或 slim(速度快) |
--datasets |
无 | 训练数据集目录路径,支持多个(nargs='+') |
--validation_dataset |
无 | 验证数据集目录路径 |
--input_size |
320 |
网络输入尺寸,可选 128/160/320/480/640/1280 |
--num_epochs |
200 |
训练轮数 |
--batch_size |
24 |
批大小 |
--lr |
1e-2 |
初始学习率 |
--momentum |
0.9 |
SGD 动量 |
--weight_decay |
5e-4 |
权重衰减 |
--milestones |
"80,100" |
MultiStepLR 学习率衰减节点(脚本中为 "95,150") |
--scheduler |
multi-step |
学习率调度器,可选 multi-step / cosine / poly |
--t_max |
120 |
Cosine 调度器的 T_max |
--optimizer_type |
SGD |
优化器,可选 SGD / Adam |
--overlap_threshold |
0.35 |
先验框与 GT 匹配的 IoU 阈值 |
--freeze_base_net |
False |
冻结骨干网络只训练头部 |
--freeze_net |
False |
冻结除预测头外的所有层 |
--base_net / --pretrained_ssd / --resume |
无 | 加载预训练骨干 / 预训练 SSD / 断点续训 |
--use_cuda |
True |
是否使用 CUDA |
--cuda_index |
0 |
GPU 索引,多卡可用 0,1,2,3 |
--num_workers |
4 |
DataLoader 工作进程数 |
--debug_steps |
100 |
训练日志输出频率 |
--validation_epochs |
5 |
每 N 个 epoch 验证并保存一次模型 |
--checkpoint_folder |
models/ |
模型保存目录 |
从 train.py 的源码实现可以确认几点关键逻辑:
- 必须先调用
define_img_size():train.py在import fd_config之前调用define_img_size(input_img_size)更新先验框集合,保证训练分辨率与先验框一致(见 train.py); - 训练流水线:
TrainAugmentation在 vision/ssd/data_preprocessing.py 中依次执行色彩扰动(PhotometricDistort)、随机裁剪(RandomSampleCrop_v2)、随机镜像(RandomMirror)、坐标归一化(ToPercentCoords)、缩放到目标尺寸(Resize)、减均值除标准差,最后转 Tensor; - 损失函数:
MultiboxLoss(见 vision/nn/multibox_loss.py)采用 SSD 的定位损失 + 置信度损失,neg_pos_ratio=3做困难样本挖掘,MatchPrior负责先验框与 GT 的匹配; - 模型保存:每
validation_epochs轮或最后一轮以{net}-Epoch-{epoch}-Loss-{val_loss}.pth命名保存 checkpoint,同时把类别名写入voc-model-labels.txt(仓库根目录已提供 models/voc-model-labels.txt,内容为background与face两个类别)。
3. 训练效果展示
以下为 640x480 输入分辨率下的检测效果示例(图片来自 readme_imgs):
六、模型推理与多端部署
1. PyTorch 批量图片检测
仓库根目录的 detect_imgs.py 可对文件夹内图片批量检测,参数如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
--net_type |
RFB |
RFB(精度高)或 slim(速度快) |
--input_size |
640 |
输入尺寸,可选 128/160/320/480/640/1280 |
--threshold |
0.6 |
置信度阈值 |
--candidate_size |
1500 |
NMS 候选框数量 |
--path |
imgs |
待检测图片目录 |
--test_device |
cuda:0 |
推理设备,cuda:0 或 cpu |
python3 detect_imgs.py --net_type RFB --input_size 640 --threshold 0.6 --path imgs
推理管线内部由 vision/ssd/predictor.py 的 Predictor.predict 完成:先经 PredictionTransform 缩放并归一化,前向得到 scores 与 boxes,再按类别阈值过滤、执行 NMS(实现见 vision/utils/box_utils.py 中的 nms / hard_nms / soft_nms),最后把归一化坐标乘回原图宽高。
2. ONNX 导出与推理
模型支持一键导出 ONNX。修改 convert_to_onnx.py 中的 input_img_size(默认 320)与 net_type(默认 RFB)后运行:
python3 convert_to_onnx.py
该脚本使用 torch.randn(1, 3, 240, 320) 作为 dummy input,导出到 models/onnx,输入节点名为 input,输出节点名为 scores、boxes。仓库已提供包含后处理的完整模型、经简化工具处理后的 _simplified 模型以及去掉后处理的 _without_postprocessing 模型。
ONNX 推理示例见 detect_imgs_onnx.py,它同时演示了 caffe2 backend 与 onnxruntime 两种运行方式:预处理(BGR→RGB、resize 到 320x240、减 [127,127,127]、除 128、CHW 转置)与 PyTorch 推理保持完全一致,其后处理(解码 + hard_nms)复用 vision/utils/box_utils_numpy.py 的 NumPy 实现。视频/摄像头实时检测参考 run_video_face_detect.py 与 run_video_face_detect_onnx.py。
3. NCNN C++ 推理
NCNN 部署代码位于 ncnn,模型文件(.param + .bin)位于 ncnn/data。核心实现 ncnn/src/UltraFace.cpp 展示了完整的端侧推理流程:
- 按输入尺寸与
strides(8/16/32/64)在构造函数中动态生成 prior anchors(与 PyTorch 端generate_priors逻辑一致); detect中先resize_bilinear到输入尺寸,再substract_mean_normalize完成减均值归一化;- 通过
Extractor输入input、取出scores与boxes输出; generateBBox使用center_variance * box + prior解码中心点、exp(size_variance * box) * prior解码宽高;nms提供hard_nms与blending_nms两种模式,iou_threshold与 score 阈值均由构造参数控制。
构建与运行方式参考 ncnn/CMakeLists.txt 与 ncnn/README.md。
4. MNN C++ 与 Python 推理
MNN 部署代码位于 MNN:
- C++ 推理:核心实现 MNN/src/UltraFace.cpp 使用
MNN::Interpreter::createFromFile加载.mnn模型,通过ScheduleConfig设置线程数与低精度后端,ImageProcess完成 BGR→RGB 转换与减均值归一化;推理代码与参考实现见 MNN/src/main.cpp,头文件 MNN/src/UltraFace.hpp; - Python 推理:MNN/python/ultraface_py_mnn.py 支持以下命令行参数:
python3 ultraface_py_mnn.py \
--model_path ../model/version-RFB/RFB-320.mnn \
--input_size 320,240 \
--threshold 0.7 \
--imgs_path ../imgs \
--results_path results
其内部使用 MNN.Interpreter 创建会话、MNN.Tensor 构造 NCHW 输入,输出经 vision/utils/box_utils_numpy.py 解码后再做 NMS,并将归一化坐标映射回原图。
- 量化模型:FP32 / INT8 量化后的模型见 MNN/model/version-RFB 与 MNN/model/version-slim。其中
RFB-320.mnn/slim-320.mnn即为上节速度测试所用的模型。
5. Caffe、OpenCV DNN 与 TFLite
- Caffe:转换后的模型见 caffe/model(RFB-320 与 Slim-320 的
.caffemodel/.prototxt),转换代码为 caffe/onnx2caffe(ONNX 转 Caffe 的算子实现),Python 推理示例见 caffe/ultra_face_caffe_inference.py,OpenCV DNN 推理示例见 caffe/ultra_face_opencvdnn_inference.py 及 opencv_dnn/cv_dnn_ultraface.cpp; - TFLite:去后处理(
without_postprocessing)的 TFLite 模型见 tflite/pretrained,检测类封装在 tflite/TFLiteFaceDetector.py,推理测试见 tflite/inference_test.py。
七、输入分辨率选型建议
README.md 的 PS 部分针对不同生产场景给出了明确选型建议,核心原则是「输入分辨率与训练分辨率尽量保持一致,上下浮动不宜过大」:
- 场景 A(中近距离、人脸大、人脸数少):建议使用
input_size: 320(320x240)分辨率训练,推理时采用 320x240、160x120 或 128x96 的输入,例如使用预训练模型 models/pretrained/version-slim-320.pth 或 models/pretrained/version-RFB-320.pth; - 场景 B(中远距离、人脸中小、人脸数多),推荐两种方案:
- 最优:
input_size: 640(640x480)分辨率训练,推理采用同等或更大输入,如 models/pretrained/version-slim-640.pth 或 models/pretrained/version-RFB-640.pth,误报更低; - 次优:320 分辨率训练、480x360 或 640x480 输入推理,对小人脸更敏感,但误报会增加。
- 最优:
其余工程经验:
- 各场景的最佳效果需要调整输入分辨率,在速度与精度之间取得平衡;
- 输入分辨率过大:增强小人脸召回率,但会提高大、近距离人脸的误报率,且推理延迟成倍增加;
- 输入分辨率过小:明显加快推理速度,但大幅降低小人脸召回率。
八、评测、生态与延伸
1. WIDER FACE 官方评测
仓库提供 widerface_evaluate 评测代码,包含 widerface_evaluate/evaluation_on_widerface.py、widerface_evaluate/evaluation.py 及 Easy/Medium/Hard 三档 ground truth(widerface_evaluate/ground_truth),可复现本文第三节的精度指标。
2. 已完成功能与第三方生态
- 已完成:Widerface 测试代码、NCNN C++ 推理、MNN C++ / Python 推理、Caffe 模型与 onnx2caffe 转换、Caffe / OpenCV DNN 推理;
- 第三方相关工程:NNCase C++ 推理、UltraFaceDotNet(C#)、faceDetect-ios、Android-FaceDetection-UltraNet-MNN、Ultra-Tensorflow-Model-Converter、UltraFace TNN C++ Demo 等;
- 仓库同时提供了口罩人脸检测变体(masked_face),包含 1280/640/320 三种分辨率下的 ONNX 与 PyTorch 预训练模型及其检测脚本 masked_face/detect_imgs.py。
3. 参考项目
模型训练与结构设计参考了 pytorch-ssd、libfacedetection、RFBNet、RFSong-779 与 Retinaface 等工作;WIDER FACE 训练标签源自 Retinaface 提供的清洗版本,相关标注文件已随仓库提供在 data/retinaface_labels。
九、小结
UltraFace-1MB 用 1MB 级的模型体积换来了接近主流轻量检测方案的精度,并通过完整的多框架推理代码(NCNN / MNN / ONNX / Caffe / OpenCV DNN / TFLite)覆盖了从树莓派、手机到 K210 等边缘设备的部署需求。实战中的关键决策点可以归纳为三句话:按场景选版本(要速度选 slim,要精度选 RFB)、按距离选分辨率(近距离大脸用 320 档,远距离小脸用 640 档)、训练与推理分辨率保持一致——这些原则在 README.md、vision/ssd/config/fd_config.py 与 train.py 中均有源码级支撑,可直接据此开展数据集制作、模型训练与端侧集成。



