Ultra-Light-Fast-Generic-Face-Detector-1MB 的 TensorFlow 模型转换与推理实践

原创2026-10-14 16:33:041,388 阅读
文章标签:人工智能计算机视觉深度学习边缘计算模型量化

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 子工程,文件组织如下:

整个流程的依赖关系是: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 函数,其逻辑为:

  1. 用 torch.load(..., map_location='cpu') 读取 .pth 权重;
  2. 解析 JSON 映射表,构建 layer_name -> torch_param_names 字典;
  3. 遍历 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 中:

  1. 将各层 reg/cls 输出 Reshape 后按通道维度 Concatenate;
  2. 对分类输出做 Softmax;
  3. 调用 decode_regression 将回归量解码为归一化坐标框;
  4. 用 conf_threshold < cls[..., 1] 过滤低置信度框;
  5. 用 tf.image.non_max_suppression 做 NMS(iou_threshold=0.3,max_output_size=100);
  6. 用 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 的源码可见完整流程:

  1. 加载模型:根据 --net_type 选择 export_models/slim/ 或 export_models/RFB/,调用 tf.keras.models.load_model 加载转换产物;
  2. 预处理:读取图片(OpenCV,BGR),统一 resize 到 320×240,再 cvtColor 转为 RGB,最后执行 img = (img - 127.0) / 128.0 归一化——这与 MNN、onnx 等其他子工程的预处理约定一致;
  3. 前向推理:model.predict(np.expand_dims(img_resize, axis=0)),输出形状为 [背景得分, 人脸得分, x1, y1, x2, y2];
  4. 坐标还原:将归一化的 x1/y1/x2/y2 乘回原图宽高 w/h,得到像素坐标;
  5. 绘制与保存:用 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 模型对测试图执行上述推理得到的输出,绿色方框为检测到的人脸:

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 级轻量人脸检测模型的开发者而言,这是一条可直接落地的路径。

登录后查看全文
Ultra-Light-Fast-Generic-Face-Detector-1MB