企业官网建设流程全解析

• 人工智能
• 大模型
• 微调
• 模型推理服务

导读

本文围绕 PaddleFormers 仓库中的人脸检测模块ultra_light_fast_generic_face_detector_1mb_320，系统讲解基于 Ultra-Light-Fast-Generic-Face-Detector-1MB 网络的超轻量实时人脸检测方案：从环境安装、命令行与 Python API 预测、结果解析，到基于 PaddleHub Serving 的在线服务部署，并深入对应源码剖析预处理、推理与后处理的完整调用链。读完本文，你将掌握如何在低算力设备（如 ARM 端）场景下，用 2.6MB 的轻量模型快速完成人脸检测与线上化部署。

一、模块基本信息

该模块面向边缘计算设备或低算力设备（如使用 ARM 进行推理）设计，是一款实时、超轻量级的通用人脸检测模型，可在低算力设备上实现通用场景的人脸检测推理。模型预训练数据集为 WIDER FACE，支持直接预测；预测时会将输入图片统一缩放为320 × 240（这也是模块名中320的由来）。由于是纯粹的检测模型而非分类网络，该模块不支持 Fine-tuning。

模块元信息定义在源码 module.py 中，通过@moduleinfo装饰器注册：

@moduleinfo( name="ultra_light_fast_generic_face_detector_1mb_320", type="CV/face_detection", author="paddlepaddle", author_email="paddle-dev@baidu.com", summary="Ultra-Light-Fast-Generic-Face-Detector-1MB is a high-performance " "object detection model ...", version="1.2.0") class FaceDetector320: ...

二、环境依赖与模块安装

1. 环境依赖

• paddlepaddle >= 1.6.2：底层深度学习框架，负责模型推理执行；
• paddlehub >= 1.6.0：模块管理与预测框架，提供hub命令行工具。

PaddleHub 的安装方式可参考仓库文档 安装指南。不同平台的基础环境搭建参见 Windows 快速开始、Linux 快速开始 与 Mac 快速开始。

2. 安装模块

$ hub install ultra_light_fast_generic_face_detector_1mb_320

hub install会从 PaddleHub 模型仓库下载模块并完成本地注册。如需安装指定历史版本，可显式指定版本号：

$ hub install ultra_light_fast_generic_face_detector_1mb_320==1.2.0

三、模块 API 预测

1. 命令行预测

使用hub run命令，通过--input_path指定输入图片路径即可完成单张图片的人脸检测：

$ hub run ultra_light_fast_generic_face_detector_1mb_320 --input_path "/PATH/TO/IMAGE"

命令行模式下支持的配置参数（定义于 module.py 的add_module_config_arg）包括：

更多hub run的用法参见 PaddleHub 命令行指令。

2. 预测代码示例

import paddlehub as hub import cv2 face_detector = hub.Module(name="ultra_light_fast_generic_face_detector_1mb_320") result = face_detector.face_detection(images=[cv2.imread('/PATH/TO/IMAGE')]) # or # result = face_detector.face_detection(paths=['/PATH/TO/IMAGE'])

images与paths两种数据传入方式二选一：前者直接传入numpy.ndarray列表（BGR 格式），后者传入图片路径字符串列表。

3. 核心 API 详解

face_detection是模块的主预测接口，其完整签名（含源码中的iou_threshold参数）为：

def face_detection(images=None, paths=None, data=None, batch_size=1, use_gpu=False, output_dir='face_detector_320_predict_output', visualization=False, confs_threshold=0.5, iou_threshold=0.5)

参数说明

返回值结构

返回res (list[dict])，每个元素对应一张输入图片，字段如下：

• path(str)：输入图片路径（通过images传入时为None）；
• data(list)：检测结果列表，每个元素为 dict：
  • confidence(float)：检测置信度；
  • left/top(int)：边界框左上角 x / y 坐标；
  • right/bottom(int)：边界框右下角 x / y 坐标；
• save_path(str)：可视化图片的保存路径（仅当visualization=True时存在）。

save_inference_model接口用于将模块导出为 Paddle Inference 格式的模型文件：

def save_inference_model(dirname)

参数dirname为模型保存路径。该接口的通用实现定义于 paddlehub/module/module.py，导出后会生成.pdmodel与.pdiparams文件（模块测试 test.py 中通过断言验证了这两个文件的存在）。

4. 从源码看完整推理链路

在 module.py 中，face_detection的执行流程可以拆解为四个阶段：

1. 数据读取与预处理（data_feed.py）：

   • reader对每条输入调用preprocess：先cvtColor将 BGR 转 RGB，再resize到 320×240，随后减均值[127,127,127]并除以 128 归一化，最后转置为[C, H, W]布局；
   • 同时保留orig_im、orig_im_shape、orig_im_path供后处理恢复原始坐标与可视化使用。

2. 推理执行：通过create_predictor创建 CPU/GPU 预测器（模型路径为模块目录下的model.pdmodel/model.pdiparams），将归一化后的 batch 数据写入输入句柄并执行predictor.run()，得到两个输出：confidences与boxes。

3. 后处理（processor.py）：

   • 按confs_threshold过滤低置信度候选框；
   • 调用自实现的hard_nms（基于iou_of计算交并比）进行非极大值抑制，消除重叠框；
   • 将归一化坐标乘回原始图片尺寸orig_im_shape，得到像素坐标；
   • 若visualization=True，用 OpenCVcv2.rectangle绘制检测框（BGR 颜色(255, 255, 0)）并保存到output_dir。

4. 结果封装：按上述返回结构组装path、data、save_path字段。

GPU 使用前提：源码在use_gpu=True时会校验环境变量CUDA_VISIBLE_DEVICES是否被正确设置（首字符须为数字），否则抛出RuntimeError提示；模块初始化时也会读取该环境变量决定是否创建 GPU 预测器。

5. 测试用例验证

仓库为该模块提供了完整单元测试 test.py，覆盖了以下场景，可作为使用范本：

• paths方式调用（test_face_detection1）；
• images方式调用（test_face_detection2）；
• visualization=True可视化输出（test_face_detection3）；
• use_gpu=TrueGPU 推理（test_face_detection4）；
• 非法路径触发AssertionError（test_face_detection5）；
• 非 ndarray 输入触发AttributeError（test_face_detection6）；
• save_inference_model导出model.pdmodel与model.pdiparams（test_save_inference_model）。

测试中对置信度阈值（>0.5）与检测框坐标范围（left/right 在 1000~4000、top/bottom 在 0~2000）的断言，可帮助你理解正常检测结果的量级范围。

四、基于 PaddleHub Serving 的在线服务部署

PaddleHub Serving 提供一键式模型服务化部署能力，可以在不关注网络框架选型与实现的前提下，将人脸检测模型快速发布为在线预测服务。整体架构为：前端通过 Flask 与 Gunicorn 处理网络请求，后台直接调用 PaddleHub 预测接口，并支持多进程并发以利用多核 CPU 提升吞吐。相关机制可参考 PaddleHub Serving 部署文档。

第一步：启动 PaddleHub Serving

$ hub serving start -m ultra_light_fast_generic_face_detector_1mb_320

执行后即在默认端口8866上完成人脸检测服务化 API 的部署。

注意事项：如使用 GPU 预测，需要在启动服务之前设置CUDA_VISIBLE_DEVICES环境变量（并确保安装了 paddlepaddle-gpu）；否则无需设置。

hub serving start的常用参数还包括：

第二步：发送预测请求

服务端就绪后，通过 HTTP POST 请求即可完成预测，请求地址格式为http://127.0.0.1:8866/predict/<MODULE>：

import requests import json import cv2 import base64 def cv2_to_base64(image): data = cv2.imencode('.jpg', image)[1] return base64.b64encode(data.tostring()).decode('utf8') # 发送HTTP请求 data = {'images':[cv2_to_base64(cv2.imread("/PATH/TO/IMAGE"))]} headers = {"Content-type": "application/json"} url = "http://127.0.0.1:8866/predict/ultra_light_fast_generic_face_detector_1mb_320" r = requests.post(url=url, headers=headers, data=json.dumps(data)) # 打印预测结果 print(r.json()["results"])

服务端收到请求后，会经由模块中的serving_method（见 module.py）完成 base64 解码、face_detection推理与结果回传。请求体中的images字段为图片 base64 字符串列表，也可额外传入batch_size、use_gpu、visualization、confs_threshold等预测参数。

停止服务使用：

$ hub serving stop --port 8866

不指定端口时默认关闭 8866 端口上的服务。

五、更新历史

需要回退到指定版本时：

$ hub install ultra_light_fast_generic_face_detector_1mb_320==1.2.0

六、总结与适用场景

ultra_light_fast_generic_face_detector_1mb_320是 PaddleFormers 中极具代表性的超轻量人脸检测模块：模型仅 2.6MB，输入统一缩放至 320×240，天然面向 ARM 等低算力设备上的实时推理。通过本文介绍的安装、命令行/代码预测与 Serving 部署三步走，你可以快速将人脸检测能力集成进本地脚本或线上服务。相关源码与测试位于 modules/image/face_detection/ultra_light_fast_generic_face_detector_1mb_320，仓库中的中文版说明见 README.md。

• 人工智能
• 大模型
• 微调
• 模型推理服务