企业官网建设流程全解析

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

本篇技术指南以 PaddleFormers 仓库中ultra_light_fast_generic_face_detector_1mb_640人脸检测模块为主线，系统讲解该基于 Ultra-Light-Fast-Generic-Face-Detector-1MB 网络的超轻量级人脸检测模型的安装、命令行预测、Python API 调用、底层推理实现原理以及 PaddleHub Serving 服务化部署全流程。读完本文，你将掌握在低算力设备（如 ARM）与常规服务器环境下，如何用一套 2.9MB 的模型完成通用场景的人脸检测，并能读懂其源码级实现细节，具备直接上手复现与二次集成的能力。

一、模型基本信息与适用场景

Ultra-Light-Fast-Generic-Face-Detector-1MB 是专门为边缘计算设备或低算力设备（如使用 ARM 推理）设计的实时超轻量级通用人脸检测模型，可以在低算力设备上实现实时通用场景的人脸检测推理。该 PaddleHub Module 的预训练数据集为 WIDER FACE 数据集，可支持预测，在预测时会将图片输入缩放为 640 × 480。

这一"1MB 级 + 640 输入"的定位决定了其典型的应用形态：在资源受限的嵌入式环境、移动端、树莓派等 ARM 设备上做人脸检测的实时推理，也可以作为常规服务器上轻量人脸框检测的前置步骤。需要注意，该模块不支持微调（Fine-tuning），它的价值在于"拿来即用"的快速推理与部署，而非训练定制。

二、环境依赖与安装

1、环境依赖

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

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

2、安装模型

在满足上述依赖后，通过 PaddleHub 命令行工具安装该人脸检测模块：

$ hub install ultra_light_fast_generic_face_detector_1mb_640

如安装时遇到问题，可参考零基础安装教程：Windows 安装 | Linux 安装 | MacOS 安装。

如果需要安装指定版本（例如 1.2.0），可以使用==指定版本号：

$ hub install ultra_light_fast_generic_face_detector_1mb_640==1.2.0

从hub install的语义看，模块安装后将进入本地模块管理器，后续hub run、hub serving等命令都可以直接按模块名调用。

三、命令行预测

安装完成后，最简单的验证方式是使用 PaddleHub 命令行进行预测：

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

其中--input_path指定待检测图片的路径。PaddleHub 命令行指令的完整用法可参考 PaddleHub 命令行指令文档。

从源码实现看，命令行预测的入口对应 module.py 中带@runnable装饰器的run_cmd方法，它通过 argparse 定义了如下命令行参数：

• --input_path：输入图片路径（必填）；
• --use_gpu：是否使用 GPU，默认False；
• --output_dir：输出图片保存目录，默认face_detector_640_predict_output；
• --visualization：是否将结果保存为图片，默认False；
• --batch_size：批大小，默认1。

这些参数最终都会透传给face_detectionAPI 完成推理。底层命令分发逻辑可参见 run.py 中的RunCommand，它会按模块名加载 Module 并调用其可运行入口。

四、Python API 预测

1、预测代码示例

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

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

images与paths两种传参方式二选一：前者直接传入解码后的图像数组（BGR 格式），后者传入图片文件路径列表。

2、API 说明

模块核心接口为face_detection，其完整签名（以 module.py 源码为准）为：

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

该接口用于检测输入图片中的所有人脸位置，其参数说明如下：

• images (list[numpy.ndarray])：图片数据，ndarray.shape 为[H, W, C]，BGR 格式；
• paths (list[str])：图片路径列表；
• data：兼容旧版本调用的字段（若传入且包含'image'键，会并入paths处理）；
• batch_size (int)：batch 的大小；
• use_gpu (bool)：是否使用 GPU，使用前需设置CUDA_VISIBLE_DEVICES环境变量；
• output_dir (str)：图片的保存路径，默认face_detector_640_predict_output；
• visualization (bool)：是否将识别结果保存为图片文件；
• confs_threshold (float)：置信度阈值，默认0.5；
• iou_threshold (float)：NMS 去重时的 IoU 阈值，默认0.5。

NOTE:paths和images两个参数选择其一进行提供数据。

3、返回值结构

返回结果为res (list[dict])，列表中每一个元素对应一张输入图片，各字段为：

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

4、导出推理模型

除在线预测外，模块还提供模型导出接口：

def save_inference_model(dirname)

将模型保存到指定路径dirname。依据 test.py 中的test_save_inference_model测试用例，导出后会在目标目录生成model.pdmodel与model.pdiparams两个文件，即标准的 Paddle Inference 推理模型格式（模型结构文件 + 参数文件），可供后续在 Paddle Inference 推理框架中直接加载使用。这一功能对应模块更新历史中的 1.2.0 版本（"修复无法导出推理模型的问题"）。

五、源码级实现原理：从预处理到后处理

该模块源码位于 modules/image/face_detection/ultra_light_fast_generic_face_detector_1mb_640/，由module.py、data_feed.py、processor.py、test.py等文件组成，整条推理链路可以拆解为四个阶段。

1、预处理（data_feed.py）

data_feed.py 中的preprocess完成图像标准化：

1. cv2.cvtColor(orig_image, cv2.COLOR_BGR2RGB)：将 BGR 转为 RGB；
2. cv2.resize(image, (640, 480))：统一缩放至 640 × 480（这就是模型名中 "640" 的含义，也解释了文档中"将图片输入缩放为 640 × 480"的说明）；
3. 减去均值[127, 127, 127]并除以128.0进行归一化；
4. np.transpose(image, [2, 0, 1])：将 HWC 布局转为 CHW 布局以送入网络。

reader函数同时支持images（numpy 数组列表）与paths（文件路径列表）两种输入，逐张产出包含原始图像、原始尺寸（orig_im_shape，即 height/width/channel）、路径与预处理后图像的OrderedDict。若路径不存在，会直接断言报错，这与 test.py 中test_face_detection5对非法路径抛出AssertionError的测试用例一致。

2、推理执行（module.py）

module.py 中通过@moduleinfo声明模块元信息（名称、类型CV/face_detection、版本1.2.0），FaceDetector640类在初始化时：

• 定位默认预训练模型文件ultra_light_fast_generic_face_detector_1mb_640/model.pdmodel与model.pdiparams；
• 用 Paddle Inference 的Config分别构建CPU predictor（disable_gpu()）与GPU predictor（enable_use_gpu(memory_pool_init_size_mb=1000, device_id=0)）；
• 通过读取环境变量CUDA_VISIBLE_DEVICES判断是否具备 GPU 使用条件。

face_detection方法按batch_size分批填充输入：将批内图像堆叠为 float32 的 batch 数组，通过input_handle.copy_from_cpu喂入，predictor.run()执行后取出两个输出——confidences（形状为[num, 2]的置信度）与boxes（形状为[num, 4]的边界框坐标）。如果use_gpu=True但未正确设置CUDA_VISIBLE_DEVICES，会抛出RuntimeError提示用户先设置该环境变量。

3、后处理与 NMS（processor.py）

processor.py 中的postprocess逐张图片处理后处理逻辑：

1. 对每个类别（从 class_index=1 开始，跳过背景类）用confs_threshold过滤低置信度框；
2. 对保留下来的框执行hard_nms——一个基于 IoU 的经典非极大值抑制实现（候选框上限 200，IoU 阈值即iou_threshold），去除重叠框；
3. 将归一化的框坐标乘以orig_im_shape还原回原图尺寸；
4. 组装left/top/right/bottom/confidence字典；
5. 当visualization=True时，用cv2.rectangle绘制黄色（BGR(255, 255, 0)）检测框，并写入output_dir，同时在结果中返回save_path字段。

4、自动化验证（test.py）

test.py 提供了完整的单元测试，覆盖：通过paths与images两种方式检测、use_gpu开关、可视化输出、非法路径断言、非法输入类型断言，以及save_inference_model导出产物检查。测试中还会校验检测框坐标与置信度（confidence > 0.5），可作为理解该模块行为与回归验证的参考。

六、服务化部署（PaddleHub Serving）

PaddleHub Serving 可以将该人脸检测模型部署为一个在线 HTTP 服务。

第一步：启动 PaddleHub Serving

运行启动命令：

$ hub serving start -m ultra_light_fast_generic_face_detector_1mb_640

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

NOTE:如使用 GPU 预测，需要在启动服务之前设置CUDA_VISIBLE_DEVICES环境变量，否则不用设置。

从 Serving 命令实现（serving.py）来看，该命令还支持更多可选参数：--port/-p指定端口（默认 8866）、--use_gpu启用 GPU、--use_multiprocess启用多进程模式（Windows 不可用）、--workers指定 worker 数（默认按cpu_count() * 2 + 1计算）、--config/-c使用 JSON 配置文件启动（指定后其余参数被忽略）。服务启动时通过preinstall_modules预加载模块，并在模块的serving_func_name上绑定对外暴露的预测方法——对本模块而言正是带@serving装饰器的serving_method（见 module.py），它会将请求中的 base64 图片解码为 cv2 图像后调用face_detection。停止服务可使用hub serving stop -p 8866。

第二步：发送预测请求

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

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

请求以 JSON 形式提交images字段（base64 编码的图像列表），响应中的results字段即人脸检测结果列表，结构与 Python API 的返回一致（每个元素含path、data，其中data内的每个框包含confidence、left、top、right、bottom坐标信息）。

七、更新历史

• 1.0.0：初始发布。
• 1.1.3：移除 fluid api（适配新版 PaddlePaddle 的接口变更）。
• 1.2.0：修复无法导出推理模型（save_inference_model）的问题，可通过hub install ultra_light_fast_generic_face_detector_1mb_640==1.2.0安装该版本。

八、使用注意事项与限制

1. 不支持微调：该模块预训练于 WIDER FACE 数据集，仅提供预测能力，如需训练定制请另行构建训练流程；
2. 输入尺寸固定：无论原图尺寸如何，推理前都会被缩放为 640 × 480，检测框坐标会在后处理阶段映射回原图坐标系，因此返回的left/top/right/bottom是原图尺度下的坐标；
3. GPU 使用前提：无论调用 API 还是启动 Serving，使用 GPU 前都必须正确设置CUDA_VISIBLE_DEVICES环境变量；
4. 环境版本：本文所述命令与 API 基于paddlepaddle >= 1.6.2、paddlehub >= 1.6.0及模块 1.2.0 版本，使用前请确认环境满足依赖；
5. 轻量定位：2.9MB 的模型体量在换取低算力设备实时推理能力的同时，其精度表现与更大规模的检测模型存在差异，生产环境请结合具体场景评估阈值参数（confs_threshold、iou_threshold）以平衡召回与误检。

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