Ultra-Light-Fast-Generic-Face-Detector-1MB 的 TensorFlow 模型转换与推理实践
Ultra-Light-Fast-Generic-Face-Detector-1MB 的 TensorFlow 模型转换与推理实践
导读
本文围绕 tf/README.md 中描述的 TensorFlow 实现展开,讲解如何将 Ultra-Light-Fast-Generic-Face-Detector-1MB 官方 PyTorch 预训练模型(version-RFB-320 与 version-slim-320)转换为 TensorFlow SavedModel,并用转换后的模型完成单张图片的人脸检测推理。读完本文,你将掌握 convert_tensorflow.py 与 det_image.py 两个脚本的完整用法、权重迁移与后处理的实现原理,并能在自己的 TensorFlow 环境中复现"转换 → 推理 → 可视化"的完整链路。
目录概览:TensorFlow 子工程的结构
仓库中的 tf 目录 是一个独立的 TensorFlow 子工程,文件组织如下:
- tf/convert_tensorflow.py:模型转换入口,将 PyTorch
.pth权重迁移进重建的 Keras 网络; - tf/det_image.py:图片推理入口,加载转换产物并绘制检测框;
- tf/model/:网络结构定义,rfb_320.py 与 slim_320.py 分别对应两个版本;
- tf/backend/:底层算子与工具,op.py 提供卷积/BN/深度可分离卷积等算子,utils.py 提供权重装载与后处理;
- tf/mapping_tables/:PyTorch 层名 → TensorFlow 层名的对照表;
- tf/export_models/:转换后 SavedModel 的输出目录(RFB 与 slim 各一份);
- tf/imgs/:官方测试输入图与转换模型的检测输出图。
整个流程的依赖关系是:convert_tensorflow.py 读取 models/pretrained/ 下的 PyTorch 权重,依据 mapping_tables/ 中的对照关系,将权重逐层装入由 tf/model/ 重建的 Keras 网络中,最后保存为 SavedModel;det_image.py 再加载该 SavedModel 完成端到端推理。
一、环境与前置准备
1. 依赖说明
该子工程需要同时具备 PyTorch(读取源权重)与 TensorFlow(构建与保存模型)两套框架,另需 OpenCV 用于图片读写。仓库根目录的 requirements.txt 列出的通用依赖包括 torch、opencv_python、numpy 等;在此基础上还需要自行安装 tensorflow(含 tf.keras API)方可运行本子工程。
2. 所需模型文件
转换脚本默认从相对路径读取以下两个 PyTorch 预训练模型(均已存在于仓库 models/pretrained/ 中):
version-RFB-320.pth:RFB 版本(带改进型 RFB 模块,精度更高);version-slim-320.pth:slim 版本(主干简化,速度更快)。
这两个 .pth 文件正是原文档"把原始模型转换到 TensorFlow 版本"的转换源。
二、模型转换:convert_tensorflow.py 实战
原文档给出的转换命令为:
python3 ./convert_tensorflow.py --net_type <RFB|slim>
即通过在 tf/convert_tensorflow.py 中执行命令,并将 --net_type 指定为 RFB 或 slim,即可把对应 PyTorch 模型转换为 TensorFlow 版本。
1. 参数与内部逻辑
从 tf/convert_tensorflow.py 的源码可以看到:
--net_type为唯一参数,默认RFB,帮助信息明确说明RFB (higher precision)与slim (faster)的取舍关系;- 输入分辨率固定为
(240, 320)(H, W),即 320×240; base_channel = 8 * 2 = 16,num_classes = 2(背景 + 人脸);- 当
--net_type == 'slim'时加载version-slim-320.pth与mapping_tables/slim_320.json,并调用create_slim_net; - 当
--net_type == 'RFB'时加载version-RFB-320.pth与mapping_tables/rfb_320.json,并调用create_rfb_net; - 其余取值会打印 "The net type is wrong!" 并以退出码 1 终止。
转换结果通过 model.save(f'export_models/{args.net_type}/', include_optimizer=False) 保存为 SavedModel 格式,分别落在 tf/export_models/RFB/ 与 tf/export_models/slim/(目录内含 saved_model.pb 与 variables/)。
2. 转换核心:层名映射与权重装载
PyTorch 与 TensorFlow 的层命名约定不同,因此需要一份映射表。以 tf/mapping_tables/rfb_320.json 为例,其条目格式如下:
[
{
"name": "basenet.0.0_conv",
"weight": ["base_net.0.0.weight"]
},
{
"name": "basenet.0.1_bn",
"weight": [
"base_net.0.1.weight",
"base_net.0.1.bias",
"base_net.0.1.running_mean",
"base_net.0.1.running_var"
]
}
]
其中 name 是 Keras 模型中的层名,weight 数组列出该层对应的一组 PyTorch 参数名。映射表共覆盖数百层(rfb_320.json 约 646 行、slim_320.json 约 496 行),几乎涵盖主干网络、检测头与 extras 层的所有卷积、深度卷积与 BN 层。
真正执行装载的是 tf/backend/utils.py 中的 load_weight 函数,其逻辑为:
- 用
torch.load(..., map_location='cpu')读取.pth权重; - 解析 JSON 映射表,构建
layer_name -> torch_param_names字典; - 遍历
model.layers,对每个层按名称后缀判断类型并设置权重:conv:将 PyTorch 权重按[2, 3, 1, 0]转置为 Keras 的[H, W, in, out]布局;dconv(深度卷积):按[2, 3, 0, 1]转置;bn:依次设置gamma / beta / running_mean / running_var四组参数;convbias/dconvbias:同时设置权重与偏置;- 未知类型则抛出
RuntimeError。
这一层层的转置与装载,正是"PyTorch → TensorFlow"迁移中权重布局差异被消除的关键所在。
3. 网络结构:两个版本的差异
转换脚本会调用 tf/model/rfb_320.py 或 tf/model/slim_320.py 中对应的 create_*_net 构建 Keras 模型。两版网络共用以下检测参数:
conf_threshold = 0.6
nms_iou_threshold = 0.3
nms_max_output_size = 200
top_k = 100
center_variance = 0.1
size_variance = 0.2
image_size = [320, 240]
feature_map_wh_list = [[40, 30], [20, 15], [10, 8], [5, 4]]
min_boxes = [[10, 16, 24], [32, 48], [64, 96], [128, 192, 256]]
两者主干都由 conv_bn 与 conv_dw(深度可分离卷积 + 点卷积 + BN + ReLU)堆叠而成,输出 40×30、20×15、10×8、5×4 四层特征图;主要差异在第一个检测头之前:
- slim 版:
header_0直接由conv_dw得到(见 slim_320.py); - RFB 版:
header_0经过basic_rfb模块(见 rfb_320.py)。该模块在 tf/backend/op.py 中实现,包含三条不同空洞率的分支(vision+1、vision+2、vision+4),拼接后经 1×1 卷积线性映射,再与 shortcut 相加并乘以scale,以扩大感受野提升精度——这正是两个版本"精度更高 / 速度更快"取舍的底层来源。
四个检测头分别通过 separable_conv 或普通 Conv2D 输出回归量(每格 4 个坐标)与分类量(每格 2 类),送入后处理模块。
4. 端到端后处理已内嵌进模型
值得注意:转换出的 SavedModel 并不是"裸"主干网络,而是把置信度阈值、NMS、top-k 等后处理全部以 TensorFlow 算子形式固化进了计算图。该逻辑位于 tf/backend/utils.py 的 post_processing 中:
- 将各层
reg/cls输出Reshape后按通道维度Concatenate; - 对分类输出做
Softmax; - 调用
decode_regression将回归量解码为归一化坐标框; - 用
conf_threshold < cls[..., 1]过滤低置信度框; - 用
tf.image.non_max_suppression做 NMS(iou_threshold=0.3,max_output_size=100); - 用
tf.nn.top_k保留得分最高的top_k个结果。
其中 decode_regression(tf/backend/utils.py)负责基于 feature_map_wh_list 与 min_boxes 生成 SSD 风格先验框,再按 center_variance / size_variance 解码出中心点与宽高,最后将坐标裁剪到 [0, 1]。这意味着转换后的模型输出即"最终检测结果",推理侧无需再重复实现后处理。
三、图片推理:det_image.py 实战
原文档给出的推理命令为:
python3 ./det_image.py --net_type <RFB|slim> --img_path <path>
其中 --img_path 指定待检测图片路径,--net_type 指定使用哪个版本的转换模型。
1. 推理流程拆解
从 tf/det_image.py 的源码可见完整流程:
- 加载模型:根据
--net_type选择export_models/slim/或export_models/RFB/,调用tf.keras.models.load_model加载转换产物; - 预处理:读取图片(OpenCV,BGR),统一
resize到 320×240,再cvtColor转为 RGB,最后执行img = (img - 127.0) / 128.0归一化——这与 MNN、onnx 等其他子工程的预处理约定一致; - 前向推理:
model.predict(np.expand_dims(img_resize, axis=0)),输出形状为[背景得分, 人脸得分, x1, y1, x2, y2]; - 坐标还原:将归一化的
x1/y1/x2/y2乘回原图宽高w/h,得到像素坐标; - 绘制与保存:用
cv2.rectangle画出绿色检测框,并保存为imgs/test_output_{net_type}.jpg。
2. 默认参数与输出约定
--net_type默认RFB,--img_path默认imgs/test_input.jpg(该测试图已存在于 tf/imgs/);- 非法
--net_type会打印错误并退出; - 输出图片固定命名为
imgs/test_output_{net_type}.jpg,仓库 tf/imgs/ 中已提供 RFB 与 slim 两个版本的官方检测结果图。
四、转换结果可视化
原文档以 RFB 版本的检测结果图作为展示。下图是使用转换后的 TensorFlow 模型对测试图执行上述推理得到的输出,绿色方框为检测到的人脸:
可以看出,权重迁移后模型仍保持了可用的检测效果(检测框稳定贴合人脸区域),说明 mapping_tables + load_weight 的转换方案是正确且可复现的。仓库 tf/imgs/ 中还提供了 slim 版本的输出图(test_output_slim.jpg)以及原图对比(test_output_origin_*.jpg)供进一步比对。
五、常见问题与排查建议
- 未生成 export_models 目录:请确认已执行转换脚本且
--net_type拼写正确(仅接受RFB/slim,大小写敏感); - 权重装载报
Unknown Layer type:说明映射表中出现了未预期的层名后缀,可检查对应网络的 tf/model/ 定义与 tf/mapping_tables/ 是否版本一致; - 推理无检测框:注意预处理必须与转换时代码保持一致(RGB、
(x - 127.0) / 128.0、320×240 输入),同时确认conf_threshold(默认 0.6)是否过高; - 多图/视频扩展:
det_image.py本身针对单张图片,如需批处理可复用其预处理与坐标还原逻辑,结合 OpenCV 的VideoCapture即可扩展到视频流场景。
总结
tf/README.md 给出的是"转换 + 推理"两条简洁的命令入口,而其背后由 tf/convert_tensorflow.py、tf/backend/utils.py、tf/backend/op.py 与两张 JSON 映射表构成了一套完整的权重迁移方案:层名映射解决命名差异,张量转置解决布局差异,内嵌后处理则让导出的 SavedModel 开箱即用。对需要在 TensorFlow / Keras 生态中部署 1MB 级轻量人脸检测模型的开发者而言,这是一条可直接落地的路径。
