PaddleFormers 人脸检测实战：PyramidBox-Lite Server 模块的安装、预测与服务化部署完全指南

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

本指南以 PaddleFormers 仓库中的pyramidbox_lite_server人脸检测模块为对象，系统讲解该基于 PyramidBox 轻量级模型的 PaddleHub Module 从环境安装、命令行与 Python API 预测、返回结果解析，到 PaddleHub Serving 在线服务化部署与 Gradio 交互的完整链路。读完本文，你将能够独立完成一次人脸检测模块的调用、参数调优与 HTTP 服务发布，并通过仓库源码理解其预处理与后处理的底层实现。

一、模型基本信息

pyramidbox_lite_server是 PaddleFormers 仓库 modules/image/face_detection 目录下的人脸检测 PaddleHub Module，其核心信息如下表所示：

PyramidBox-Lite 是基于百度发表于计算机视觉顶级会议 ECCV 2018 的论文PyramidBox研发的轻量级模型，主干网络采用 FaceBoxes。该模型对光照变化、口罩遮挡、表情变化、尺度变化等实际场景中的常见干扰具有很强的鲁棒性。模块基于 WIDER FACE 数据集与百度自采人脸数据集训练而成，支持直接预测，可用于通用的人脸检测任务。

从仓库源码看，模块实现位于 modules/image/face_detection/pyramidbox_lite_server/module.py，其中通过@moduleinfo装饰器声明了模块名称pyramidbox_lite_server、类型CV/face_detection、版本号1.4.0等元信息，模块类名为PyramidBoxLiteServer。

二、环境依赖与模块安装

1、环境依赖

运行该模块需要满足以下版本要求：

• paddlepaddle >= 1.6.2
• paddlehub >= 1.6.0，PaddleHub 的安装方式参见 PaddleHub 安装指南

2、安装模块

在终端执行以下命令即可从 PaddleHub 模型仓库安装该模块：

$ hub install pyramidbox_lite_server

如需安装指定版本（例如带 Gradio APP 支持的 1.4.0），可以显式指定版本号：

$ hub install pyramidbox_lite_server==1.4.0

安装过程中如遇到问题，可参考仓库内的零基础安装文档：Windows 安装、Linux 安装、MacOS 安装。

三、模型 API 预测

1、命令行预测

通过 PaddleHub 命令行即可直接调用人脸检测模型，无需编写代码：

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

其中--input_path指定待检测图片的路径。命令行方式更完整的指令说明见 PaddleHub 命令行指令。

从源码看，命令行入口由模块内的run_cmd方法（module.py）提供，它通过argparse解析参数并最终调用face_detection方法。命令行支持的参数包括--use_gpu、--output_dir、--visualization、--input_path、--shrink、--confs_threshold，其默认值与 Python API 保持一致。

2、预测代码示例

在 Python 环境中加载模块并执行人脸检测：

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

两种数据传入方式等价：images直接传 BGR 格式的numpy.ndarray，paths传图片文件路径列表，二者选择其一即可。

3、API 详解：face_detection

def face_detection(images=None, paths=None, use_gpu=False, output_dir='detection_result', visualization=False, shrink=0.5, confs_threshold=0.6)

该 API 用于检测输入图片中的所有（置信度超过阈值）人脸位置。各参数含义如下：

NOTE：paths与images两个参数选择其一提供数据即可，两者可同时传入，模块会依次处理。

从源码实现看（module.py），该 API 对data参数还保留了与旧版本的兼容逻辑：若传入的 dict 中包含image键则并入paths，包含data键则并入images。此外，当use_gpu=True时，模块会检查环境变量CUDA_VISIBLE_DEVICES是否设置正确，否则抛出RuntimeError提示用户先配置 GPU 设备号。

4、返回结果结构

face_detection返回res（list[dict]），列表中每个元素对应一张输入图片，字段为：

• path(str)：原输入图片的路径
• data(list)：检测结果列表，每个元素为 dict，字段包括：
  • confidence(float)：识别置信度
  • left(int)：边界框左上角 x 坐标
  • top(int)：边界框左上角 y 坐标
  • right(int)：边界框右下角 x 坐标
  • bottom(int)：边界框右下角 y 坐标

上述坐标已经过边界裁剪（clip_bbox）并换算回原图尺寸，可直接用于 OpenCV 画框等下游操作。仓库提供的单元测试 test.py 验证了返回的置信度大于 0.5 且坐标位于合理范围内（0 到 2000 之间），同时覆盖了paths传入、images传入、可视化输出、GPU 预测及非法输入（不存在的文件路径抛出AssertionError、非 ndarray 图片抛出AttributeError）等场景，可作为调用该 API 的参考范本。

5、save_inference_model：导出推理模型

def save_inference_model(dirname)

将模型保存到指定路径，dirname为模型保存路径。保存后会在目标目录下生成model.pdmodel与model.pdiparams两个文件，便于在 Paddle Inference 环境中独立加载部署。对应测试见 test.py。

四、源码级实现解析

为了更好地使用与调参，这里结合仓库源码说明模块内部的推理链路。模块的完整目录结构如下：

• module.py：模块主体，负责预测器初始化与 API 封装
• data_feed.py：图片读取与预处理
• processor.py：后处理、可视化与结果序列化
• test.py：单元测试
• label_list.txt：类别标签（BACKGROUND / face）

预处理：缩放、去均值与归一化

data_feed.py中的preprocess函数（data_feed.py）完成三步操作：按shrink比例对原图做cv2.resize（最近邻插值）；将 HWC 布局转换为 CHW（通过两次swapaxes）；再减去均值[104., 117., 123.]并乘以scale = 0.007843，得到可直接送入网络的 float32 张量。shrink之所以影响小/大尺寸人脸的检测效果，正是因为该值决定了送入网络的图像分辨率。

后处理：坐标还原与可视化

processor.py中的postprocess函数（processor.py）遍历网络输出的每条检测记录（格式为[label, confidence, left, top, right, bottom]），仅保留置信度高于confs_threshold的框，并将网络输出的归一化坐标乘回预处理后的宽高再除以shrink，还原到原图坐标系，最后经clip_bbox裁剪到图片边界内。若visualization=True，则用 OpenCV 在原图上绘制黄绿色矩形框并保存到output_dir，保存文件名自动去重（重名时追加时间戳）。

预测器初始化：CPU/GPU 双通道

_set_config方法（module.py）默认加载模块目录下的pyramidbox_lite_server_face_detection/model（.pdmodel+.pdiparams）构建 CPU 预测器；同时通过检测CUDA_VISIBLE_DEVICES环境变量决定是否额外构建 GPU 预测器（GPU 显存池初始 1000MB）。face_detection根据use_gpu参数在两者间切换，输入输出通过 Paddle Inference 的get_input_handle/get_output_handle完成数据搬运。

五、服务化部署：PaddleHub Serving

PaddleHub Serving 可以将该人脸检测模块部署为在线服务，供 HTTP 请求远程调用。

第一步：启动 PaddleHub Serving

执行以下命令：

$ hub serving start -m pyramidbox_lite_server

执行完成后即完成了人脸检测服务化 API 的部署，默认端口号为8866。

NOTE：如需使用 GPU 预测，请在启动服务之前设置CUDA_VISIBLE_DEVICES环境变量；仅使用 CPU 则无需设置。

服务端启动后，Serving 逻辑由模块中的serving_method方法（module.py）承载：请求中的 base64 图片字符串先经base64_to_cv2（见 processor.py）解码为 ndarray，再调用face_detection完成预测。

第二步：发送预测请求

配置好服务端后，以下代码即可发送预测请求并获取结果：

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/pyramidbox_lite_server" r = requests.post(url=url, headers=headers, data=json.dumps(data)) # 打印预测结果 print(r.json()["results"])

请求以 JSON 格式发送，images字段为 base64 编码后的图片列表；返回的results字段即人脸检测结果（结构与 Python API 返回值一致）。

Gradio APP 支持

从 PaddleHub 2.3.1 开始，该模块支持 Gradio APP。服务启动后，可在浏览器中直接访问：

http://127.0.0.1:8866/gradio/pyramidbox_lite_server

即可通过可视化界面交互式地调节shrink（0.0～1.0，步长 0.01，默认 0.5）与confs_threshold（0.0～1.0，步长 0.01，默认 0.6）两个滑块并实时查看检测结果。其界面由模块中的create_gradio_app方法（module.py）构建，内部以临时目录保存可视化结果图并返回给前端展示。

六、版本更新历史

该模块历经多次迭代，各版本变更如下：

• 1.0.0：初始发布
• 1.2.0：修复 numpy 数据读取问题
• 1.2.1：移除 fluid api（从 PaddlePaddle 旧版 fluid 接口迁移至新版预测接口）
• 1.3.0：修复无法导出推理模型的问题（即save_inference_model相关缺陷）
• 1.4.0：添加 Gradio APP 支持

如需使用最新功能，建议通过hub install pyramidbox_lite_server==1.4.0安装 1.4.0 及以上版本。

七、小结

pyramidbox_lite_server是一个开箱即用、轻量（8MB）的人脸检测 PaddleHub Module：它继承了 ECCV 2018 PyramidBox 方案对光照、遮挡、表情与尺度变化的鲁棒性，支持命令行、Python API、HTTP Serving 与 Gradio 四种调用形态。结合仓库源码可以看到，其预处理（缩放、去均值、归一化）与后处理（阈值过滤、坐标还原、可视化）链路清晰，shrink与confs_threshold是影响检测效果的两个核心参数，值得在实际场景中根据人脸尺度与误检容忍度进行调优。相关源码与测试均可在本仓库的 modules/image/face_detection/pyramidbox_lite_server 目录下找到，作为进一步研究与二次开发的基础。

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