企业官网建设流程全解析

PaddleFormers 人脸检测实战：PyramidBox-Lite Server 模块的安装、API 调用与 Serving 在线部署

【免费下载链接】PaddleFormersPaddleFormers is an easy-to-use library of pre-trained large language model zoo based on PaddlePaddle.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleFormers

本篇技术指南以 PaddleFormers 仓库中的 pyramidbox_lite_server 模块文档 为骨架，围绕 PaddleHub 生态下 PyramidBox-Lite 轻量人脸检测模型展开，覆盖环境安装、命令行与 Python API 预测、关键参数调优，以及 PaddleHub Serving 在线服务化部署与 Gradio 交互界面。读完本文，你将能够在一台装有 PaddlePaddle 与 PaddleHub 的机器上，从零跑通单图人脸检测、批量推理，并把模型快速封装成可对外提供 HTTP 服务的人脸检测接口。

一、模块基本信息：PyramidBox-Lite Server 是什么

pyramidbox_lite_server 是 PaddleHub 官方提供的一个**人脸检测（face detection）**模块，其核心信息如下表：

模型的技术来源是百度在 ECCV 2018 发表的 PyramidBox 论文。PyramidBox-Lite 是基于 PyramidBox 研制的轻量级模型，对光照变化、口罩遮挡、表情变化、尺度变化等常见干扰具有较强的鲁棒性，可在 CPU 上流畅运行，适合作为服务端人脸检测的基础能力。

在仓库中，该模块的完整实现位于 modules/image/face_detection/pyramidbox_lite_server/ 目录，包含以下文件：

• module.py：模块主实现，定义了PyramidBoxLiteServer类，包含预测、命令行、Serving 与 Gradio 四类入口；
• data_feed.py：图像读取与预处理（缩放、减均值、通道变换）；
• processor.py：后处理（坐标恢复、阈值过滤、可视化绘制、base64 编解码）；
• label_list.txt：标签表（BACKGROUND与face）；
• test.py：模块的单元测试，可验证安装与 API 正确性。

二、安装与环境依赖

1、环境依赖

使用该模块前需要满足以下版本要求：

• paddlepaddle >= 1.6.2
• paddlehub >= 1.6.0，PaddleHub 的安装方法见 installation.rst

需要说明的是，模块的 Serving 与 Gradio 功能随 PaddleHub 版本演进：从 PaddleHub 2.3.1 起才支持 Gradio APP 访问，因此若要用到下文第四节的 Gradio 能力，建议使用较新的 PaddleHub 版本。

2、安装模块

执行以下命令安装人脸检测模块：

$ hub install pyramidbox_lite_server

如需安装指定版本（例如 1.4.0），可追加版本号：

$ hub install pyramidbox_lite_server==1.4.0

安装过程中如遇到问题，可参考官方快速入门文档：Windows_Quickstart | Linux_Quickstart | Mac_Quickstart。

三、模块 API 预测

1、命令行预测

安装完成后，可通过命令行直接对单张图片进行人脸检测：

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

命令行入口由 module.py 中的run_cmd方法注册（通过@runnable装饰器暴露）。从源码可以看到，命令行支持以下可选参数（module.py）：

关于 PaddleHub 命令行指令的完整用法，可参考 cmd_usage.rst。

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与paths两种数据来源二选一即可：前者直接传入 BGR 格式的 numpy 数组，后者传入图片文件路径列表。仓库中的 test.py 对两种调用方式都编写了对应的单元测试（test_face_detection1走paths、test_face_detection2走images），并断言置信度大于 0.5、坐标落在合理区间，可作为调用结果的正确性参照。

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)

功能：检测输入图片中的所有可见人脸，返回每个人脸的检测框坐标与置信度。

参数说明：

• images(list[numpy.ndarray])：图片数据列表，每个 ndarray 的 shape 为 [H, W, C]，颜色空间为BGR；
• paths(list[str])：图片路径列表；
• use_gpu(bool)：是否使用 GPU。使用 GPU 前必须先设置CUDA_VISIBLE_DEVICES环境变量；
• output_dir(str)：可视化结果的保存目录，默认detection_result；
• visualization(bool)：是否将检测结果保存为图片文件；
• shrink(float)：输入图片的缩放比例。该值越大，对输入图片中的小尺寸人脸检测效果越好（模型计算成本越高）；值越小，则对大尺寸人脸检测效果更好；
• confs_threshold(float)：置信度阈值，只有置信度超过该值的检测框才会被保留。

注意：paths与images只需提供其中之一，不要同时依赖二者传入数据。

返回值：

res(list[dict])：检测结果列表，每个元素为一个 dict：

• path(str)：输入图片的路径；
• data(list)：检测结果，每个元素为 dict：
  • confidence(float)：检测置信度；
  • left(int)：检测框左上角 x 坐标；
  • top(int)：检测框左上角 y 坐标；
  • right(int)：检测框右下角 x 坐标；
  • bottom(int)：检测框右下角 y 坐标。

源码级原理：预处理与后处理

从源码看，一次face_detection调用内部完成了「预处理 → 推理 → 后处理」三个环节：

预处理（data_feed.py）：reader逐张读取图片后，preprocess会按shrink比例使用cv2.resize（最近邻插值）缩放图像；随后将 HWC 布局转为 CHW，再减去均值mean = [104., 117., 123.]并乘以缩放系数scale = 0.007843（即 1/127.5），最后转为 float32 送入网络。因此shrink直接影响网络输入尺寸，进而影响小目标人脸的召回率与推理耗时。

推理（module.py）：模块通过 Paddle Inference 加载模型。_set_config中默认创建 CPU predictor，并检测CUDA_VISIBLE_DEVICES环境变量：若其首字符可转为整数则认为可用 GPU，额外创建显存池 1000MB 的 GPU predictor。face_detection中若use_gpu=True但环境变量未正确设置，会直接抛出 RuntimeError 提示先设置CUDA_VISIBLE_DEVICES。

后处理（processor.py）：网络原始输出为[label, confidence, left, top, right, bottom]形式的行向量，postprocess会先按confs_threshold过滤低置信度结果，再将归一化坐标乘以原图宽高并除以shrink，恢复为原始图像尺寸下的像素坐标；随后通过clip_bbox把越界坐标裁剪到图像范围内。若visualization=True，则用 OpenCV 在图像上绘制黄色矩形框（cv2.rectangle，颜色 (255, 255, 0)，线宽 2）并保存到output_dir，文件已存在时会自动追加时间戳避免覆盖。

4、导出推理模型：save_inference_model

def save_inference_model(dirname)

功能：将当前模块的预测模型保存为 Paddle Inference 可直接加载的推理模型文件。

参数：

• dirname(str)：模型保存路径。

从 test.py 的test_save_inference_model用例可以看到，调用save_inference_model('./inference/model')后，会在目标目录下生成model.pdmodel与model.pdiparams两个文件，与 module.py 中_set_config加载的model.pdmodel/model.pdiparams命名约定一致，方便将人脸检测能力集成进自有推理服务。

四、Server 服务化部署

PaddleHub Serving 可以将人脸检测模型一键部署为在线服务，对外提供 HTTP 接口。

Step 1：启动 PaddleHub Serving

运行启动命令：

$ hub serving start -m pyramidbox_lite_server

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

注意：若使用 GPU 预测，需要在启动服务之前设置CUDA_VISIBLE_DEVICES环境变量；仅用 CPU 时无需设置。

服务端的数据处理入口是 module.py 中的serving_method（通过@serving装饰器暴露）：它接收 HTTP 请求中 base64 编码的图片列表，先经base64_to_cv2解码为 numpy 数组（见 processor.py），再转调face_detection完成检测并返回结构化结果。

Step 2：发送预测请求

服务启动后，使用以下代码发送 HTTP 请求并获取结果：

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"])

请求体中的images字段为图片的 base64 字符串列表，接口路径为/predict/pyramidbox_lite_server，返回的results即为每个检测框的置信度与坐标信息。关于 PaddleHub Serving 的更多配置（如端口、并发等），可查阅 serving.md。

Gradio APP 支持

从 PaddleHub 2.3.1 开始，pyramidbox_lite_server 支持通过 Gradio 在浏览器中以可视化方式交互，访问地址为：

http://127.0.0.1:8866/gradio/pyramidbox_lite_server

其界面逻辑定义在 module.py 的create_gradio_app方法中：页面提供图片上传框、shrink滑块（0.0～1.0，默认 0.5）与confs_threshold滑块（0.0～1.0，默认 0.6），提交后调用face_detection并将带框结果图返回给浏览器，非常适合快速演示与人工验收检测效果。

五、版本更新记录

当前仓库中 module.py 的@moduleinfo装饰器标注的模块版本即为 1.4.0（module.py），与 README 中最新版本一致。若需回退到带 Gradio 支持前的稳定版本，可执行hub install pyramidbox_lite_server==1.3.0。

六、快速验证与最佳实践小结

• 正确性自检：安装完成后，可直接运行仓库自带的 test.py（python test.py），它覆盖了paths/images两种输入、CPU/GPU 两种设备、可视化开关、非法路径断言以及推理模型导出共 6 组用例，快速确认模块可用；
• 小脸检测调优：若图片中人脸较小且漏检明显，可适当调大shrink（如 0.7～1.0）；若误检较多，可调高confs_threshold（如 0.7）；
• 服务化落地：本地验证通过后，用hub serving start -m pyramidbox_lite_server即可在 8866 端口获得标准 HTTP 接口，方便与业务系统集成；需要离线部署时，用save_inference_model导出model.pdmodel/model.pdiparams接入自有推理管线。

【免费下载链接】PaddleFormersPaddleFormers is an easy-to-use library of pre-trained large language model zoo based on PaddlePaddle.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleFormers