PaddleFormers 人脸检测模型库实战指南：PyramidBox-Lite 与超轻量人脸检测的安装、预测与服务化部署

PaddleFormers 人脸检测模型库实战指南PyramidBox-Lite 与超轻量人脸检测的安装、预测与服务化部署【免费下载链接】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 仓库中 modules/image/face_detection 目录下的人脸检测模型模块系统讲解基于 PaddleHub 的人脸检测技术栈包括百度自研 PyramidBox-Lite 系列通用人脸检测、口罩人脸检测以及面向边缘设备的 Ultra-Light-Fast-Generic-Face-Detector-1MB 超轻量模型。读完本文你将掌握这些模型的安装方式、face_detectionAPI 的全部参数含义、命令行与 Python 两种预测方法、返回结果结构以及基于 PaddleHub Serving 和 Gradio 的服务化部署流程并能结合仓库源码理解预处理与后处理的底层实现原理。一、人脸检测与仓库中的推荐模型人脸检测Face Detection是目标检测的一个重要分支任务目标是定位输入图像中所有人脸的边界框位置。由于安防监控、人脸识别、人脸安全等场景的持续需求它已成为目标检测领域最重要的任务之一。PaddleFormers 仓库的 modules/image/face_detection 目录下按模型分别组织了完整的 PaddleHub Module 实现每个子目录都包含module.py模型类定义与预测 API、processor.py后处理与可视化、data_feed.py数据读取与预处理以及独立的 README 文档。仓库推荐的三个核心模型如下模型名称模型简介pyramidbox_lite_server百度自研基于 ECCV 2018 论文 PyramidBox 的轻量级人脸检测模型在 WIDER Face 数据集上具有竞争力表现ultra_light_fast_generic_face_detector_1mb_640针对边缘计算设备或低算力设备如用 ARM 推理设计的实时超轻量级通用人脸检测模型可在低算力设备中进行实时的通用场景人脸检测推理pyramidbox_lite_server_mask开源口罩人脸检测与识别模型可同时完成人脸定位与是否佩戴口罩的二分类判断三个模型在 face_detection 目录下均以独立子目录提供完整实现例如 pyramidbox_lite_server、ultra_light_fast_generic_face_detector_1mb_640 与 pyramidbox_lite_server_mask。二、模型基本信息与选型对比1. pyramidbox_lite_server通用人脸检测属性内容模型名称pyramidbox_lite_server类别图像 - 人脸检测网络PyramidBox数据集WIDER FACE 数据集 百度自采人脸数据集是否支持 Fine-tuning否模型大小8MB最新更新日期2021-02-26PyramidBox-Lite 是基于 2018 年百度发表于计算机视觉顶级会议 ECCV 2018 的论文 PyramidBox 而研发的轻量级模型模型基于主干网络 FaceBoxes对光照、口罩遮挡、表情变化、尺度变化等常见问题具有很强的鲁棒性。该 PaddleHub Module 基于 WIDER FACE 数据集和百度自采人脸数据集训练支持预测可用于通用人脸检测。2. ultra_light_fast_generic_face_detector_1mb_640超轻量人脸检测属性内容模型名称ultra_light_fast_generic_face_detector_1mb_640类别图像 - 人脸检测网络Ultra-Light-Fast-Generic-Face-Detector-1MB数据集WIDER FACE 数据集是否支持 Fine-tuning否模型大小2.9MB最新更新日期2021-02-26该模型专为边缘计算设备或低算力设备如用 ARM 推理设计可以在低算力设备中进行实时的通用场景人脸检测推理。其预训练数据集为 WIDER FACE 数据集预测时会将输入图片缩放为 640×480——这一点可从源码 data_feed.py 得到印证preprocess中执行cv2.resize(image, (640, 480))并先由 BGR 转 RGB减去均值 127 后除以 128 完成归一化再转为 CHW 布局。3. pyramidbox_lite_server_mask口罩人脸检测属性内容模型名称pyramidbox_lite_server_mask类别图像 - 人脸检测网络PyramidBox数据集WIDER FACE 数据集 百度自采人脸数据集是否支持 Fine-tuning否模型大小1.2MB最新更新日期2021-02-26口罩检测模型同样基于 PyramidBox-Lite 架构但输出为「是否佩戴口罩」的二分类结果。从源码 module.py 可以看到该模块内部组合了一个人脸检测底座模型默认即pyramidbox_lite_server先由底座模型检测出所有人脸框再对每张人脸区域做 128×128 的裁剪与归一化送入口罩分类网络最后由 processor.py 中的label_list [NO MASK, MASK]完成标签映射。选型建议追求通用场景高精度、对光照遮挡鲁棒选 pyramidbox_lite_server需要 ARM 等低算力设备实时推理选 ultra_light_fast_generic_face_detector_1mb_640需要同时判断是否佩戴口罩选 pyramidbox_lite_server_mask。三、环境依赖与模型安装1. 环境依赖paddlepaddle 1.6.2paddlehub 1.6.0PaddleHub 的安装方法可参考 docs/docs_ch/get_start/installation.rst。如安装遇到问题可按操作系统查阅 零基础 Windows 安装、零基础 Linux 安装 或 零基础 MacOS 安装。2. 安装模型以 pyramidbox_lite_server 为例通过hub install命令安装$ hub install pyramidbox_lite_server其余两个模型同理$ hub install ultra_light_fast_generic_face_detector_1mb_640 $ hub install pyramidbox_lite_server_mask如需安装指定版本可在模型名后附加版本号例如hub install pyramidbox_lite_server1.4.0。需要说明的是本文所述命令与 API 均以仓库 README 记录的 PaddleHub 使用方式为准实际使用时请以对应版本的 PaddleHub 与 PaddlePaddle 环境为准。四、模型预测命令行与 Python API1. 命令行预测$ hub run pyramidbox_lite_server --input_path /PATH/TO/IMAGEhub run是 PaddleHub 的命令行运行入口更多指令用法见 docs/docs_ch/tutorial/cmd_usage.rst。从源码 module.py 的run_cmd实现看命令行实际会透传--use_gpu、--output_dir、--visualization、--shrink、--confs_threshold等参数到face_detection方法最终对--input_path指定的图片执行检测。2. Python 预测代码示例import paddlehub as hub import cv2 face_detector hub.Module(namepyramidbox_lite_server) result face_detector.face_detection(images[cv2.imread(/PATH/TO/IMAGE)]) # or # result face_detector.face_detection(paths[/PATH/TO/IMAGE])口罩检测模型用法类似import paddlehub as hub import cv2 mask_detector hub.Module(namepyramidbox_lite_server_mask) result mask_detector.face_detection(images[cv2.imread(/PATH/TO/IMAGE)])3. face_detection API 详解pyramidbox_lite_server 的完整 API 签名如下def face_detection(imagesNone, pathsNone, use_gpuFalse, output_dirdetection_result, visualizationFalse, shrink0.5, confs_threshold0.6)参数说明images (list[numpy.ndarray])图片数据ndarray.shape 为 [H, W, C]BGR 格式paths (list[str])图片路径列表use_gpu (bool)是否使用 GPU。需要注意使用 GPU 前必须正确设置CUDA_VISIBLE_DEVICES环境变量否则源码 module.py 会抛出 RuntimeErroroutput_dir (str)可视化结果保存路径默认detection_resultvisualization (bool)是否将识别结果保存为图片文件shrink (float)图片缩放比例。该值越大对输入图片中的小尺寸人脸检测效果越好模型计算成本越高反之对大尺寸人脸效果更好。其作用可见 data_feed.py预处理时会按shrink等比缩放原图再减去均值[104, 117, 123]并乘以0.007843完成归一化confs_threshold (float)置信度阈值低于该阈值的检测框会被过滤。NOTEpaths和images两个参数选择其一提供数据即可两者同时传入时会合并处理源码reader中会依次读取 paths 列表和 images 列表。返回结果返回res (list[dict])列表中每个元素为 dictpath (str)原输入图片的路径data (list)检测结果列表每个元素为 dictconfidence (float)识别置信度left (int)边界框左上角 x 坐标top (int)边界框左上角 y 坐标right (int)边界框右下角 x 坐标bottom (int)边界框右下角 y 坐标。坐标换算与置信度过滤的逻辑实现在 processor.py模型输出经过shrink逆缩放回原图尺寸再经clip_bbox裁剪到图像范围内只有置信度大于confs_threshold的框才会被保留。4. 超轻量模型 API 的差异点ultra_light_fast_generic_face_detector_1mb_640 的 API 略有不同def face_detection(imagesNone, pathsNone, batch_size1, use_gpuFalse, output_dirface_detector_640_predict_output, visualizationFalse, confs_threshold0.5)多出batch_size (int)参数用于控制批量预测大小默认 1output_dir默认值为face_detector_640_predict_outputconfs_threshold默认值为 0.5返回结果中当visualizationTrue时额外包含save_path字段为可视化图片的保存路径。从源码 module.py 看该模型会读取两个网络输出confidences 与 boxes分别用于置信度判断和边界框回归这与 PyramidBox-Lite 的单输出结构不同。5. 口罩检测 API 的特殊能力pyramidbox_lite_server_mask 除了face_detection外还提供了底座模型的管理接口def __init__(face_detector_moduleNone)face_detector_module (class)人脸检测底座模型默认为pyramidbox_lite_server。def face_detection(imagesNone, pathsNone, batch_size1, use_gpuFalse, visualizationFalse, output_dirdetection_result, use_multi_scaleFalse, shrink0.5, confs_threshold0.6)与通用检测模型相比多出use_multi_scale (bool)是否开启多尺度人脸检测。开启后能更好地检测输入图像中不同尺寸的人脸但会增加模型计算量、降低预测速度。多尺度实现见 data_feed.py内部按multi_scales [0.3, 0.6, 0.9]三档尺度分别检测再通过bbox_vote基于 IoU 的加权投票 NMS融合结果返回结果中每个框包含label (str)字段取值为NO MASK或MASK。同时该模型还支持更换与查询底座检测模型def set_face_detector_module(face_detector_module) # 设置底座模型 def get_face_detector_module() # 获取当前底座模型6. 导出推理模型三个模型均支持将模型保存到指定路径便于离线部署def save_inference_model(dirname)参数dirname为模型保存路径。例如import paddlehub as hub mask_detector hub.Module(namepyramidbox_lite_server_mask) mask_detector.save_inference_model(dirnametest_program)五、服务化部署PaddleHub Serving 可以将上述人脸检测模型部署为在线服务。第一步启动 PaddleHub Serving$ hub serving start -m pyramidbox_lite_server执行后即完成人脸检测服务化 API 的部署默认端口号为 8866。NOTE如使用 GPU 预测需要在启动服务之前设置CUDA_VISIBLE_DEVICES环境变量否则无需设置。第二步发送预测请求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(urlurl, headersheaders, datajson.dumps(data)) # 打印预测结果 print(r.json()[results])服务端接收到 base64 图片后会通过base64_to_cv2解码还原为 BGR 图像见各模型的 processor.py再调用face_detection完成预测。其他模型的请求地址分别对应/predict/ultra_light_fast_generic_face_detector_1mb_640与/predict/pyramidbox_lite_server_mask。Gradio APP 支持从 PaddleHub 2.3.1 开始Serving 服务还支持通过浏览器访问模型的 Gradio APP 进行交互式体验pyramidbox_lite_serverhttp://127.0.0.1:8866/gradio/pyramidbox_lite_serverpyramidbox_lite_server_maskhttp://127.0.0.1:8866/gradio/pyramidbox_lite_server_mask从源码看Gradio 界面内置了shrink与confs_threshold两个滑块取值范围 0.0~1.0上传图片后即可实时查看检测框绘制结果见 module.py 的create_gradio_app。六、可视化与后处理原理通用检测模型的可视化pyramidbox_lite_server 的可视化由 processor.py 完成当visualizationTrue时会先通过check_dir创建输出目录再调用cv2.rectangle以黄色线框BGR 颜色(255, 255, 0)线宽 2绘制检测框并保存图片。保存文件名与源图同名若文件已存在则会追加时间戳避免覆盖。口罩检测的可视化口罩模型的可视化更为丰富processor.py 中的draw_bounding_box_on_image会对MASK标签绘制绿色边框对NO MASK绘制红色边框在边框上方绘制白色底、黑色文字的标签文本格式如MASK: 95.23%其中置信度以百分比展示。口罩分类的结果由np.argmax(confidence_out[index])决定即取二分类置信度最高的类别作为最终标签。超轻量模型的后处理ultra_light_fast_generic_face_detector_1mb_640 的后处理在 processor.py 中实现除置信度阈值外还引入iou_threshold默认 0.5用于非极大值抑制NMS以合并同一人脸上的重叠框。七、口罩检测模型的 Paddle Lite 端侧部署pyramidbox_lite_server_mask 的 README 还给出了从服务端到端侧的部署路径保存模型通过save_inference_model(dirnametest_program)导出推理模型模型转换使用 PaddleLite 提供的模型优化工具 OPT 对预测模型进行转换转换后即可在手机等端侧硬件上部署端侧部署参考 Paddle-Lite 提供的口罩检测模型部署教程完成落地。八、更新历史与版本演进以 pyramidbox_lite_server 为例其版本演进记录了模型的维护轨迹1.0.0初始发布1.2.0修复 numpy 数据读取问题1.2.1移除 fluid api1.3.0修复无法导出推理模型的问题1.4.0添加 Gradio APP 支持hub install pyramidbox_lite_server1.4.0ultra_light_fast_generic_face_detector_1mb_640 与 pyramidbox_lite_server_mask 也经历了类似的「移除 fluid api → 修复导出推理模型 → 添加 Gradio APP 支持」演进路径反映出 PaddleHub 生态逐步向新版 Paddle 推理接口与交互式体验迁移的历程。九、源码结构速览如需深入阅读实现可在仓库中定位以下文件pyramidbox_lite_server/module.py通用人脸检测模型类face_detectionAPI 与 Serving/命令行入口pyramidbox_lite_server/data_feed.py预处理缩放、均值减除、HWC→CHW与数据读取pyramidbox_lite_server/processor.py后处理、坐标换算、置信度过滤与可视化pyramidbox_lite_server_mask/module.py口罩检测模型内部组合底座人脸检测模型pyramidbox_lite_server_mask/data_feed.py多尺度检测与 bbox_vote 融合ultra_light_fast_generic_face_detector_1mb_640/module.py超轻量模型双输出confidences boxes结构三个模型目录中还提供了test.py与label_list.txt等文件label_list.txt记录了模型使用的类别标签可作为验证输出标签顺序的参考依据。总结PaddleFormers 的 face_detection 模块族为开发者提供了从服务端高精度检测到端侧超轻量实时检测、再到口罩佩戴识别的完整方案。通过hub install一键安装、face_detection统一 API 调用、PaddleHub Serving 服务化部署以及 Paddle Lite 端侧迁移可以快速把人脸检测能力接入安防、考勤、智慧园区、边缘终端等各类实际业务场景。建议开发者在实际使用前结合 PaddleHub 命令行指令文档 与各模型的 README重点调优shrink小脸检测与confs_threshold误检率与召回率平衡两个参数以获得符合业务需求的检测效果。【免费下载链接】PaddleFormersPaddleFormers is an easy-to-use library of pre-trained large language model zoo based on PaddlePaddle.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleFormers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考