Ultra-Light-Fast-Generic-Face-Detector-1MB 的 TFLite 端侧部署指南:模型、推理 API 与后处理原理
Ultra-Light-Fast-Generic-Face-Detector-1MB 的 TFLite 端侧部署指南:模型、推理 API 与后处理原理
本篇技术指南围绕 Ultra-Light-Fast-Generic-Face-Detector-1MB 仓库中的 tflite 实现(tflite/README.md),系统讲解如何将 1MB 轻量人脸检测模型转换为 TFLite 格式并在边缘计算设备上完成图片/视频推理,涵盖预训练模型、UltraLightFaceDetecion 检测器类的全部构造参数、命令行推理脚本,以及 anchor 生成、回归解码、NMS 后处理的底层实现原理。读完本文,你将能独立完成 TFLite 模型的人脸检测集成,并理解 320x240 输入下的完整数据流。
为什么需要 TFLite 版本
Ultra-Light-Fast-Generic-Face-Detector-1MB 是面向边缘计算设备设计的轻量人脸检测模型:默认 FP32 精度下 .pth 权重约 1.04~1.1MB,320x240 输入分辨率下计算量约 90~109 MFlops,并提供 version-slim(主干精简、速度略快)与 version-RFB(引入修改版 RFB 模块、精度更高)两个版本(见 项目说明 README_CN.md)。
TFLite 是 TensorFlow 面向移动端/嵌入式设备推出的推理格式,其模型适合在内存与算力受限的硬件上运行。仓库 tflite/ 目录正是为此提供的一套开箱即用方案:预训练权重已从 PyTorch 一路转换为 onnx -> protobuf -> tflite,无需再次做模型转换,下载仓库后即可直接调用 Python API 完成推理。
目录结构速览
tflite/
├── model # keras 定义的模型架构(不含后处理)
│ ├── tflite_RFB_320_without_postprocessing.py
│ └── tflite_slim_320_without_postprocessing.py
├── pretrained # 不含后处理的预训练 TFLite 模型
│ ├── version-RFB-320_without_postprocessing.tflite
│ └── version-slim-320_without_postprocessing.tflite
├── README.md
├── inference_test.py # 检测器测试脚本(图片/视频推理)
└── TFLiteFaceDetector.py # TFLite 检测器类文件
- TFLiteFaceDetector.py:核心类
UltraLightFaceDetecion,封装了 TFLite Interpreter 调用、图像预处理、anchor 生成与后处理。 - inference_test.py:命令行入口,支持图片与视频两种推理模式。
- tflite_RFB_320_without_postprocessing.py 与 tflite_slim_320_without_postprocessing.py:用 Keras 复刻的 RFB / slim 网络结构。
pretrained/下两个.tflite文件:均为 不含后处理 的模型,输出为原始的回归值与分类分数,由 Python 侧统一解码。
模型转换链路:pytorch → tensorflow → tflite
文档说明预训练权重是经过 onnx -> protobuf -> tflite 转换得到的。结合仓库源码,可以还原出完整的转换路径:
- PyTorch → TensorFlow:仓库
tf/目录中的 convert_tensorflow.py 使用--net_type <RFB|slim>选择网络,读取 version-RFB-320.pth / version-slim-320.pth,配合 rfb_320.json / slim_320.json 映射表,通过 load_weight(tf/backend/utils.py) 将 PyTorch 权重按 conv / dconv / bn / convbias / dconvbias 类型做维度转置后写入 Keras 模型,导出到tf/export_models/。 - TensorFlow → ONNX → TFLite:
tflite/model/下的两个架构文件从 tf/backend/op.py 导入conv_bn、conv_dw、basic_rfb、separable_conv基础算子,构建与 TF 版一致的网络(此处不再内置后处理),权重再经onnx -> protobuf -> tflite完成格式落地。
其中 tflite_RFB_320_without_postprocessing.py 的 create_rfb_net(input_shape, base_channel, num_classes) 以 (240, 320, 3) 为输入,输出两个张量:reg(4 个尺度的框回归值拼接)与 cls(softmax 后的分类分数),输出名分别为 face_boxes 与 face_scores——这正是 TFLiteFaceDetector.py 中 get_output_details() 读取的两个输出端。
环境准备
运行 TFLite 推理需要:
- Python 3 环境;
- TensorFlow(提供
tf.lite.Interpreter)与tf.image.non_max_suppression; - OpenCV(
cv2.resize、cv2.imread、cv2.normalize、图像显示); - NumPy。
仓库根目录的 requirements.txt 已声明 numpy、opencv_python 等基础依赖,TFLite 推理在此之上额外需要 tensorflow 运行时(import tensorflow as tf),请按所用 TensorFlow 版本的安装方式自行安装。
命令行推理:图片与视频
在 tflite/ 目录下运行:
# 图片推理
python3 inference_test.py --net_type <RFB|slim> --img_path <IMG_PATH>
# 视频推理
python3 inference_test.py --net_type <RFB|slim> --video_path <VIDEO_PATH>
inference_test.py 中三个命令行参数的含义:
| 参数 | 可选值 | 说明 |
|---|---|---|
--net_type |
RFB(默认)或 slim |
网络架构:RFB 精度更高,slim 速度更快 |
--img_path |
图片路径 | 指定后执行图片推理 |
--video_path |
视频路径 | 指定后执行视频推理 |
脚本会按 pretrained/version-{net_type}-320_without_postprocessing.tflite 自动拼接模型路径。两点值得注意的差异:
- 图片推理使用
conf_threshold=0.6,视频推理使用conf_threshold=0.88——视频场景更保守的阈值可有效抑制连续帧中的误检; - 视频推理循环中会用
time.perf_counter()打印每帧耗时,便于在目标设备上实测性能; - 若
--img_path与--video_path均未提供,脚本打印提示--ima_path or --video_path must be filled。
图片推理流程为:cv2.imread 读取 → fd.inference(img) 得到 boxes 与 scores → 对每个 boxes.astype(int) 画矩形框 → cv2.imshow 显示。视频推理则在 while True 循环中逐帧 cap.read(),按 q 键退出。
UltraLightFaceDetecion 检测器类:参数与用法
构造函数与全部参数
from TFLiteFaceDetector import UltraLightFaceDetecion
fd = UltraLightFaceDetecion(model_path,
input_size=(320, 240), conf_threshold=0.6,
center_variance=0.1, size_variance=0.2,
nms_max_output_size=200, nms_iou_threshold=0.3)
各参数在 TFLiteFaceDetector.py 中的实际作用:
| 参数 | 默认值 | 作用 |
|---|---|---|
filepath |
必填 | TFLite 模型路径,如 pretrained/version-RFB-320_without_postprocessing.tflite |
input_size |
(320, 240) |
送入网络的输入尺寸,注意是 (W, H) 顺序;由 cv2.resize 完成缩放 |
conf_threshold |
0.6 |
置信度阈值,后处理中过滤分数低于该值的候选框 |
center_variance |
0.1 |
回归解码时中心点偏移的缩放系数,与训练时 fd_config.py 中 center_variance=0.1 一致 |
size_variance |
0.2 |
回归解码时宽高缩放的指数系数,与训练配置 size_variance=0.2 一致 |
nms_max_output_size |
200 |
NMS 最多输出的框数量 |
nms_iou_threshold |
0.3 |
NMS 的 IoU 阈值,高于该值视为重叠框被抑制 |
注意:
center_variance与size_variance是模型训练时(vision/ssd/config/fd_config.py 中center_variance=0.1, size_variance=0.2)就固定的超参数,正常情况下不需要修改;若网络输出已包含完整解码(带后处理的模型),则不应再传入这些参数。
推理调用
boxes, scores = fd.inference(img)
inference()(TFLiteFaceDetector.py)内部完成四步:
_pre_processing:cv2.resize到input_size→ BGR 转 RGB → 转 float32 →cv2.normalize归一化到 [-1, 1](alpha=-1, beta=1, NORM_MINMAX),并扩展 batch 维度;set_tensor+invoke()执行 TFLite 推理;- 读取
output_details[0](boxes 回归值)与output_details[1](scores 分类分数); - 后处理得到左上角/右下角格式的框,最后乘以原图像宽高
img.shape[1::-1]还原到原图坐标系。
推理结果
boxes:(N, 4)数组,每行[x1, y1, x2, y2],已是原图像素坐标;scores:(N,)数组,为对应框的人脸置信度分数。
底层原理:anchor 生成、回归解码与 NMS
anchor 生成
检测器初始化时(TFLiteFaceDetector.py)会预先计算全部 prior anchor。四个特征层的配置与训练配置(fd_config.py)完全一致:
self._feature_maps = np.array([[40, 30], [20, 15], [10, 8], [5, 4]]) # 特征图尺寸 (W, H)
self._min_boxes = np.array([[10, 16, 24], [32, 48], # 每层 anchor 的基础边长
[64, 96], [128, 192, 256]])
anchor 中心为每个特征图格子中心加 0.5 偏移后除以特征图尺寸(归一化到 [0,1]),anchor 宽高为基础边长除以 input_size。四个特征层共生成 40×30×3 + 20×15×2 + 10×8×2 + 5×4×3 = 3600 + 600 + 160 + 60 = 4420 个 anchor,坐标被 np.clip 限制在 [0,1]。
回归解码(center → corner)
模型输出的 reg 是相对 anchor 的编码偏移,_decode_regression(TFLiteFaceDetector.py)按 SSD 风格解码:
center_xy = reg[:, :2] * center_variance * anchors_wh + anchors_xy
center_wh = np.exp(reg[:, 2:] * size_variance) * anchors_wh / 2
start_xy = center_xy - center_wh # 左上角
end_xy = center_xy + center_wh # 右下角
置信度过滤与 NMS
_post_processing(TFLiteFaceDetector.py):
- 解码回归值得到归一化框;
scores = scores[:, 1]取“人脸”类别的分数;- 用
conf_mask = self._conf_threshold < scores过滤低置信度框; - 调用
tf.image.non_max_suppression(max_output_size=200, iou_threshold=0.3)抑制重叠框。
网络架构:RFB 与 slim 的差异
两个架构文件均从 tf/backend/op.py 复用算子,主干一致地由 conv_bn + conv_dw 堆叠构成(深度可分离卷积,是模型轻量的关键),核心差异在 header 层:
- slim 版(tflite_slim_320_without_postprocessing.py):
header_0 = conv_dw(net, base_channel*4, stride=1, prefix='basenet.7'),即直接用深度可分离卷积提取第一个检测特征层; - RFB 版(tflite_RFB_320_without_postprocessing.py):
header_0 = basic_rfb(...),改用basic_rfb模块——它包含 3 条分支,分别使用 dilation=2、3、5(vision + 1/2/4)的空洞卷积扩大感受野,多分支拼接后经 1x1 卷积线性融合,再与 shortcut 残差相加(out = out * scale + shortcut),这正是 RFB 版精度更高而速度略慢的原因。
两种网络的检测头均为 4 个尺度:前 3 层用 separable_conv(深度可分离 + 1x1 点卷积),最后一层(header_3,由 extras 模块下采样产生)用普通 Conv2D。回归通道数为 anchor数×4,分类通道数为 anchor数×num_classes(本任务 num_classes=2,即背景 + 人脸),最终 face_boxes 与 face_scores 两个输出经 Reshape + Concatenate + Softmax 拼装。
参数调优与部署建议
- 输入分辨率:
input_size默认(320, 240)。小输入(如160x120、128x96)推理更快但小人脸召回率低;大输入(如640x480)对小人脸更敏感但误报与耗时上升。生产场景建议与训练分辨率保持一致(详见 README_CN.md 的 PS 说明)。 - 置信度阈值:静态图片场景 0.6 即可;视频/监控流建议调高至 0.88 附近(脚本默认行为),以抑制连续帧误检。
- NMS 参数:
nms_iou_threshold=0.3偏严格,适合多人脸重叠少的场景;人脸密集重叠时可视情况放宽到 0.4~0.5,同时配合nms_max_output_size限制输出数量。
相关资源
- TFLite 目录说明文档:tflite/README.md
- 检测器实现与推理脚本:TFLiteFaceDetector.py、inference_test.py
- 模型架构定义:tflite_RFB_320_without_postprocessing.py、tflite_slim_320_without_postprocessing.py
- 预训练模型:version-RFB-320_without_postprocessing.tflite、version-slim-320_without_postprocessing.tflite
- 上游 TensorFlow 转换链路:convert_tensorflow.py、tf/backend/utils.py、tf/model/rfb_320.py
- 训练侧超参数(variance、IoU、min_boxes 的源头):vision/ssd/config/fd_config.py
- 本 TFLite 实现的权重转换参考自开源项目 Ultra-Light-Fast-Generic-Face-Detector_Tensorflow-Model-Converter,仓库已在文档致谢部分说明。