InsightFace RetinaFace 人脸检测器：基于 MXNet 的数据准备、训练、测试与模型部署全指南

InsightFace RetinaFace 人脸检测器基于 MXNet 的数据准备、训练、测试与模型部署全指南【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface导读RetinaFace 是 InsightFace 仓库GitHub_Trending/in/insightface中提供的经典单阶段人脸检测器最早以技术报告发表于 arXiv并被 CVPR 2020 收录。它在单次前向推理中同时输出人脸边界框bounding box和五个面部关键点landmark是整个人脸分析流水线检测 → 对齐 → 识别的第一环。本文以 detection/retinaface/README.md 为骨架结合仓库内的训练脚本、检测器实现与配置模板完整讲解基于 MXNet 的 RetinaFace 从数据集组织、环境安装、模型训练、测试评估到预训练模型使用的全流程并补充源码级原理说明帮助读者在自己的数据上复现训练并正确调用检测器。RetinaFace 是什么单阶段多任务人脸定位RetinaFace 的核心思路是在一个单阶段检测器中同时完成三件事人脸分类区分前景/背景、边界框回归定位人脸、五关键点回归左右眼、鼻尖、左右嘴角。这一多任务设计使得它在推理阶段只需要一次网络前向即可同时拿到人脸框与关键点为后续的人脸对齐和识别提供直接输入。仓库 detection/retinaface/retinaface.py 中的RetinaFace类封装了完整的推理逻辑模型加载mx.model.load_checkpoint(prefix, epoch)加载 MXNet 训练产物前后处理图像归一化、多尺度缩放、水平翻转、候选框解码、NMS 去重输出格式detect()返回(det, landmarks)其中det为N×5数组x1, y1, x2, y2, scorelandmarks为N×5×2数组5 个关键点的 x/y 坐标。从源码结构看检测器通过len(sym) // len(feat_stride_fpn)的比值自动判断模型是否输出关键点use_landmarks以及是否包含级联分支cascade这使得同一套推理代码可以兼容不同配置下训练出的模型。网络变体与特征金字塔RetinaFace.__init__通过network参数选择不同的网络配置仓库支持以下变体见 detection/retinaface/retinaface.pynetworkFPN 层数fmc特征步长feat_stride说明ssh/vgg332, 16, 8使用 VGG 风格均值[103.939, 116.779, 123.68]预处理net3332, 16, 8默认推理网络anchor 宽高比(1.,)net3a332, 16, 8在 net3 基础上增加宽高比1.5net4/net4a432, 16, 8, 4增加 stride4 的高分辨率层net5/net5a564, 32, 16, 8, 4对应论文中的 RetinaFace 结构anchor 尺度按2^(1/3)递增生成net66128, 64, 32, 16, 8, 4类似 PyramidBox/S3FD 的深金字塔x3/x3a/x53 / 5—使用 ImageNet 风格均值和方差预处理每个 FPN 层级的 anchor 配置以字典形式给出例如 stride 32 层的默认配置为SCALES(32, 16)、BASE_SIZE16、RATIOS(1.,)、ALLOWED_BORDER9999参见 detection/retinaface/retinaface.py。net5系列的 anchor 尺度通过_basescale逐级乘以2.0**(1.0/3)生成三个尺度构成更密集的覆盖。SSH 检测头与上下文模块网络头部采用 SSHSingle Stage Headless结构实现在 detection/retinaface/rcnn/symbol/symbol_ssh.pyssh_detection_module由一个 3×3 卷积与ssh_context_module输出的 5×5、7×7 感受野分支拼接而成实现多尺度上下文感知ssh_context_module通过1×1 → 3×35×5 等效与1×1 → 3×3 → 3×37×7 等效两条路径扩大感受野cpmContext Prediction Module残差结构 SSH 检测模块用于增强高层特征get_out在每个 stride 上生成分类分支2 × num_anchors通道、边界框分支4 × num_anchors通道以及可选的关键点分支10 × num_anchors通道并分别接入 Softmax 分类损失与 smooth-L1 回归损失。训练符号通过get_ssh_train()组织将每个 FPN 层的输出用mx.sym.Group拼接为多输出符号detection/retinaface/rcnn/symbol/symbol_ssh.py。数据准备组织 WIDERFACE 训练/验证集RetinaFace 的训练数据基于 WIDERFACE 数据集并额外提供了包含人脸边界框与五个关键点标注的标注文件下载地址见原 README 中的百度网盘与 Google Drive 链接。完成下载后需要在insightface/RetinaFace/目录即仓库的detection/retinaface/下按如下结构组织数据data/retinaface/ train/ images/ label.txt val/ images/ label.txt test/ images/ label.txt其中images/存放图片label.txt存放对应的标注。数据集相关路径在 detection/retinaface/rcnn/sample_config.py 中由dataset.retinaface配置定义dataset retinafaceimage_set traintest_image_set valroot_path datadataset_path data/retinaface训练时 detection/retinaface/train.py 会调用load_gt_roidb读取标注并构建 roidb默认启用水平翻转数据增强可通过--no_flip关闭。环境安装MXNet、DCN 算子与 C 工具安装步骤按原 README 分为三步安装支持 GPU 的 MXNet如果使用基于 DCNDeformable Convolution的 backbone需要从 Deformable-ConvNets 项目编译安装 Deformable Convolution V2 算子。在源码中DCN 卷积通过mx.contrib.symbol.DeformableConvolution实现并配套生成3×3的 offset 卷积层detection/retinaface/rcnn/symbol/symbol_ssh.py是否启用由配置项USE_DCN控制在detection/retinaface/目录下执行make编译 cython 加速模块。查看 Makefile 可知其内部执行cd rcnn/cython/; python setup.py build_ext --inplace; rm -rf build; cd ../../ cd rcnn/pycocotools/; python setup.py build_ext --inplace; rm -rf build; cd ../../这两步分别编译 NMS、bbox 等 cython 算子如rcnn/processing/bbox_transform.py中bbox_overlaps实际调用 cython 实现bbox_overlaps_cython以及 pycocotools 工具。模型训练从配置到多卡并行第一步生成配置文件训练前需将rcnn/sample_config.py复制为rcnn/config.pycp rcnn/sample_config.py rcnn/config.py该文件是 RetinaFace 训练的全部配置中心detection/retinaface/rcnn/sample_config.py 中核心参数如下配置项默认值含义PIXEL_MEANS[103.939, 116.779, 123.68]图像均值按网络覆盖resnet/mnet 覆盖为 0PIXEL_STDS/PIXEL_SCALE[1.0,1.0,1.0]/1.0图像方差与缩放PRE_SCALES[(1200, 1600)]预训练阶段短边/最大边长SCALES[(640, 640)]训练输入尺寸短边, 最大边NUM_CLASSES2前景 背景RPN_ANCHOR_CFGRAC_SSHFPN 各层的 anchor 配置HEAD_MODULESSH检测头类型HEAD_FILTER_NUM256检测头卷积通道数LANDMARK_LR_MULT2.0关键点分支学习率倍率USE_CROP/USE_FPNTrue / True是否裁剪训练 / 是否使用 FPNUSE_DCN0是否使用可变形卷积resnet 配置覆盖为 2FACE_LANDMARKTrue是否训练关键点分支MORE_SMALL_BOXTrue是否采样更多小目标LAYER_FIXFalse是否冻结部分层CASCADE0级联检测深度TRAIN.BATCH_IMAGES8每卡训练 batchmnet 覆盖为 16TRAIN.RPN_ENABLE_OHEM2OHEM 难例挖掘模式TRAIN.RPN_BATCH_SIZE256RPN 采样数TRAIN.RPN_FG_FRACTION0.25正样本比例TRAIN.RPN_POSITIVE_OVERLAP0.5正样本 IoU 阈值级联模式下为 0.7TRAIN.RPN_NEGATIVE_OVERLAP0.3负样本 IoU 阈值TRAIN.BBOX_STDS/TRAIN.LANDMARK_STD(1.0,1.0,1.0,1.0)/1.0回归目标标准化系数TEST.RPN_NMS_THRESH/TEST.NMS0.3 / 0.3测试 NMS 阈值TEST.SCORE_THRESH0.05测试得分阈值TEST.IOU_THRESH0.5评估 IoU 阈值网络级配置通过network.resnet、network.mnet两个预设覆盖上述默认值network.resnetpretrainedmodel/resnet-50文件中可见resnet-152与resnet-50两套注释与覆盖默认生效为后者、BATCH_IMAGES8、HEAD_FILTER_NUM256、USE_DCN0、FIXED_PARAMS[^stage1, ^.*upsampling]、RPN_ANCHOR_CFGRAC_SSH用于中等/大型模型network.mnetpretrainedmodel/mobilenet025fd0、BATCH_IMAGES16、HEAD_FILTER_NUM64、LAYER_FIXTrue、LANDMARK_LR_MULT2.5、RPN_ANCHOR_CFGRAC_SSH用于轻量模型。generate_config(_network, _dataset)detection/retinaface/rcnn/sample_config.py会根据命令行传入的--network与--dataset合并对应配置并据此推导RPN_FEAT_STRIDE、每个 stride 的NUM_ANCHORS等派生值。第二步准备 ImageNet 预训练权重预训练模型仅用于训练时的参数初始化不参与检测推理。README 提供两个选择下载地址见原 READMEImageNet ResNet50ImageNet ResNet152下载后将模型放入model/目录并在配置中通过network.resnet.pretrained指定路径例如model/resnet-50pretrained_epoch0表示加载 epoch 0 的权重。第三步启动训练README 给出的标准训练命令为CUDA_VISIBLE_DEVICES0,1,2,3 python -u train.py --prefix ./model/retina --network resnetdetection/retinaface/train.py 定义的完整命令行参数如下参数默认值说明--networkresnet网络预设resnet/mnet--datasetretinaface数据集名--image_settrain训练集标识--root_path/--dataset_pathdata/data/retinaface数据路径--frequent20日志打印频率--kvstoredeviceMXNet kvstore 类型--work_load_listNone多卡负载分配--no_flip/--no_shuffleFalse关闭翻转 / 关闭打乱--pretrained/--pretrained_epoch配置默认预训练模型前缀与 epoch--prefixmodel/retinaface输出模型前缀--begin_epoch/--end_epoch0 / 10000起止 epoch可断点续训--lr0.01resnet 覆盖为 0.001基础学习率--lr_step55,68,80resnet 覆盖为1,2,3,4,5,55,68,80学习率衰减轮次--wd0.0005权重衰减训练流程的关键实现细节GPU 推导train_net从环境变量CUDA_VISIBLE_DEVICES推导上下文按逗号分隔创建mx.gpu(i)无 GPU 时回退 CPUdetection/retinaface/train.py数据装载CropLoader按config.SCALES裁剪缩放图片batch_size config.TRAIN.BATCH_IMAGES * len(ctx)参数冻结get_fixed_params根据config.FIXED_PARAMS将 backbone 前 7 个参数及upsampling相关参数加入fixed_param_names冻结detection/retinaface/train.py上采样初始化对含upsampling的参数使用双线性初始化init._init_bilinear训练指标每个 FPN stride 上分别注册RPNAccMetric分类准确率、RPNL1LossMetric边界框 smooth-L1 损失开启FACE_LANDMARK时追加关键点 L1 损失开启CASCADE时按CASCADE_CLS_STRIDES/CASCADE_BBOX_STRIDES追加级联分支指标detection/retinaface/train.py学习率策略lr_steps由--lr_step的 epoch 序列换算为迭代步数5 个衰减点使用因子[0.5, 0.5, 0.4, 0.1, 0.1]8 个衰减点含 warmup前 5 个使用1.5849倍增、后 3 个按0.1衰减detection/retinaface/train.py优化器SGDmomentum0.9rescale_grad1.0/len(ctx)做梯度平均模型保存save_model将分类分支经SoftmaxActivation归一化后与 bbox、landmark 分支Group打包保存使推理阶段可直接使用detection/retinaface/train.py。训练前可先检查rcnn/config.py中resnet网络的预训练模型路径、anchor 设置与学习率策略是否符合预期README 明确提示了这一步骤。模型测试单图推理与 WIDERFACE 评估单图推理README 提示查看test.py了解测试方式。detection/retinaface/test.py 是完整的最小推理示例import cv2 from retinaface import RetinaFace thresh 0.8 scales [1024, 1980] gpuid 0 detector RetinaFace(./model/R50, 0, gpuid, net3) img cv2.imread(t1.jpg) im_shape img.shape target_size, max_size scales[0], scales[1] im_size_min np.min(im_shape[0:2]) im_size_max np.max(im_shape[0:2]) im_scale float(target_size) / float(im_size_min) if np.round(im_scale * im_size_max) max_size: im_scale float(max_size) / float(im_size_max) faces, landmarks detector.detect(img, thresh, scales[im_scale], do_flipFalse)要点说明RetinaFace(prefix, epoch, ctx_id, network)的构造参数与 detection/retinaface/retinaface.py 一致ctx_id0使用 GPU 及 GPU NMS否则回退 CPUdetect(img, threshold0.5, scales[1.0], do_flipFalse)支持多尺度与水平翻转推理多尺度时各尺度结果统一缩放回原图坐标后合并经排序与 NMS 得到最终输出detection/retinaface/retinaface.py测试脚本对每个检测框绘制矩形红色对五个关键点绘制圆点其中左右眼索引 0、3用绿色区分结果写入./detector_test.jpg该类还提供detect_center返回最接近图像中心的人脸、check_large_pose基于关键点几何判断大姿态方向等实用方法。WIDERFACE 批量评估仓库提供 detection/retinaface/test_widerface.py 用于在验证集上批量测试并输出评估文件关键参数--network默认net3、--prefix、--epoch指定模型--gpu默认 0、--thresh默认 0.02检测阈值--mode0 为快速模式1 为精确模式启用图像金字塔与 bbox vote--pyramid测试尺度为[500, 800, 1100, 1400, 1700]并开启水平翻转--output输出目录默认./wout每张图生成同名 txt格式为图片名、人脸数、每行x y w h scoredetection/retinaface/test_widerface.py--part/--parts支持将验证集分片并行处理。预训练模型与第三方实现README 提供的官方预训练模型为RetinaFace-R50ResNet50 backbone中等规模单次前向同时输出人脸框与五个关键点下载地址见原 README其在 WIDERFace 验证集上的 mAP 为难度EasyMediumHardmAP96.595.690.4README 同时说明为避免与 ICCV 2019 WIDERFace Challenge 的冲突最佳模型的发布时间被推迟。此外还收录了以下第三方成果RetinaFace-MobileNet0.25由 yangfly 提供轻量模型模型大小仅约 1.68MBWIDERFace Hard 难度 mAP 82.5C 版本由 clancylian 提供ModelScope 上的 RetinaFace 模型cv_resnet50_face-detection_retinaface。在 InsightFace 生态中的实际使用ONNX 推理路径除了 MXNet 训练路径RetinaFace 在 InsightFace 的 Python 发行包中还以 ONNX 形式提供推理实现位于 python-package/insightface/model_zoo/retinaface.py内部通过 onnxruntime 加载模型实现了distance2bbox/distance2kps解码该实现对应 SCRFD 风格的回归输出。它与人脸识别模块python-package/insightface/model_zoo/arcface_onnx.py、人脸对齐工具python-package/insightface/utils/face_align.py一起被 python-package/insightface/app/face_analysis.py 组装成端到端的人脸分析流水线供检测 → 对齐 → 识别一体化调用。这意味着本文介绍的训练产物既可以按 MXNet 原生方式推理也可以通过模型转换接入 ONNX 生态服务于生产部署。参考引用若在学术工作中使用 RetinaFace可按原 README 提供的引用信息标注inproceedings{Deng2020CVPR, title {RetinaFace: Single-Shot Multi-Level Face Localisation in the Wild}, author {Deng, Jiankang and Guo, Jia and Ververas, Evangelos and Kotsia, Irene and Zafeiriou, Stefanos}, booktitle {CVPR}, year {2020} }小结本文围绕 detection/retinaface/README.md 完整梳理了 InsightFace 中 RetinaFace 检测器的使用链路从 WIDERFACE 数据组织、MXNet/DCN/cython 环境安装到rcnn/config.py配置详解、ImageNet 预训练加载与多卡训练命令再到单图推理与 WIDERFACE 批量评估最后介绍了官方 R50 预训练模型的精度与 ONNX 生态接入方式。结合 detection/retinaface/train.py、detection/retinaface/retinaface.py、detection/retinaface/rcnn/sample_config.py 等源码读者既可以复现论文训练流程也能直接调用检测器并理解其多尺度 anchor 解码、NMS 与关键点回归的底层实现。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考