PaddleDetection 模型 Python Serving 服务化部署实战:基于 Paddle Serving Pipeline 框架的完整部署指南
PaddleDetection 模型 Python Serving 服务化部署实战:基于 Paddle Serving Pipeline 框架的完整部署指南
导读
本文围绕 PaddleDetection 仓库中 deploy/serving/python 目录下的 Python Serving 预测部署方案展开,完整讲解如何将 PaddleDetection 训练好的检测模型(以 yolov3_darknet53_270e_coco 为例)通过 Paddle Serving 的 Python Pipeline 框架部署为工业级在线推理服务。读完本文后,你将掌握:Paddle Serving 环境安装、带服务化配置的模型导出、服务端配置文件的每个关键参数含义、web_service.py 服务端代码的完整工作流程(预处理 → 推理 → 后处理 → 结果返回),以及基于 HTTP 的客户端调用方式,并了解如何在服务端自定义预处理与后处理逻辑以适配不同模型架构。
1. 简介:Python Pipeline 服务化部署方案
Paddle Serving 是飞桨开源的服务化部署框架,提供了 C++ Serving 与 Python Pipeline 两套框架:C++ Serving 框架更倾向于追求极致性能,适合对延迟和吞吐有严苛要求的场景;Python Pipeline 框架则倾向于二次开发的便捷性,开发者可以方便地用 Python 自定义预处理、后处理逻辑,快速把新模型接入服务。本文档介绍的内容即基于 Python Pipeline 框架实现模型的服务化部署。
仓库中的 Python 服务化部署样例程序位于 deploy/serving/python 目录,目录结构如下:
deploy/
├── serving/
│ ├── python/ # Python 服务化部署样例程序目录
│ │ ├── config.yml # 服务端模型预测相关配置文件
│ │ ├── pipeline_http_client.py # 客户端代码
│ │ ├── postprocess_ops.py # 用户自定义后处理代码
│ │ ├── preprocess_ops.py # 用户自定义预处理代码
│ │ ├── README.md # 说明文档
│ │ ├── web_service.py # 服务端代码
│ ├── cpp/ # C++ 服务化部署样例程序目录
│ │ ├── preprocess/ # C++ 自定义 OP
│ │ ├── build_server.sh # C++ Serving 编译脚本
│ │ ├── serving_client.py # 客户端代码
│ │ └── ...
│ └── ...
└── ...
各文件职责清晰:config.yml 负责服务运行参数;web_service.py 定义服务端推理流程;preprocess_ops.py 与 postprocess_ops.py 分别封装图像预处理算子与结果后处理算子;pipeline_http_client.py 是 HTTP 客户端示例。
说明:仓库中还提供了 C++ Serving 部署样例(deploy/serving/cpp)以及一个通用测试客户端 deploy/serving/test_client.py(配合 deploy/serving/label_list.txt 使用,对应 C++/经典 Serving 部署方式),本文聚焦 Python Pipeline 方案,C++ 方案可参考对应 README。
2. 环境准备:安装 Paddle Serving 与 PaddlePaddle
进行服务化部署前,需要安装 Paddle Serving 的四个安装包,分别是:paddle-serving-server(CPU/GPU 版本二选一)、paddle-serving-client、paddle-serving-app 和 paddlepaddle(CPU/GPU 版本二选一):
pip install paddle-serving-client
# pip install paddle-serving-server # CPU
pip install paddle-serving-server-gpu # GPU 默认 CUDA10.2 + TensorRT6,其他环境需手动指定版本号
pip install paddle-serving-app
# pip install paddlepaddle # CPU
pip install paddlepaddle-gpu
几点实用提示:
- 安装速度慢时可使用国内镜像源(例如百度源,在 pip 命令中添加
-i https://mirror.baidu.com/pypi/simple)加速下载; - GPU 版本默认对应 CUDA 10.2 + TensorRT 6,如果实际环境不同,需要手动指定与本地 CUDA/TensorRT 匹配的版本号;
- 从仓库代码看,服务端 web_service.py 通过
from paddle_serving_server.web_service import WebService, Op引入 Pipeline 框架基类,因此安装包版本需要与代码兼容(README 对应示例基于 Serving v0.7.0 系列,实际使用请以官方发布版本为准)。
3. 服务化部署模型导出
3.1 导出命令
PaddleDetection 训练得到的是包含前向与优化器参数的模型,部署时只需要前向推理参数,因此需要先用 tools/export_model.py 导出推理模型,具体流程可参考 deploy/EXPORT_MODEL.md。与普通导出不同,导出服务化部署模型需要额外添加 --export_serving_model True 参数,示例如下:
python tools/export_model.py -c configs/yolov3/yolov3_darknet53_270e_coco.yml \
--export_serving_model True \
-o weights=https://paddledet.bj.bcebos.com/models/yolov3_darknet53_270e_coco.pdparams
命令中:-c 指定模型配置文件(本例为 configs/yolov3/yolov3_darknet53_270e_coco.yml),-o weights=... 指定权重(既可以是本地权重路径,也可以是预训练模型下载地址)。
3.2 导出产物的结构
查看 tools/export_model.py 的源码可知,当 FLAGS.export_serving_model 为真时,脚本会调用 paddle_serving_client.io.inference_model_to_serving,以 output_inference/<模型名> 目录下的 model.pdmodel 与 model.pdiparams 为输入,在该目录下额外生成 serving_server 与 serving_client 两个子目录。最终导出目录结构为:
output_inference
│ ├── yolov3_darknet53_270e_coco
│ │ ├── infer_cfg.yml
│ │ ├── model.pdiparams
│ │ ├── model.pdiparams.info
│ │ ├── model.pdmodel
│ │ ├── serving_client
│ │ │ ├── serving_client_conf.prototxt
│ │ │ ├── serving_client_conf.stream.prototxt
│ │ ├── serving_server
│ │ │ ├── __model__
│ │ │ ├── __params__
│ │ │ ├── serving_server_conf.prototxt
│ │ │ ├── serving_server_conf.stream.prototxt
│ │ │ ├── ...
其中:
serving_server目录是服务端真正加载的模型目录,__model__与__params__是转换后的模型文件;serving_client目录是客户端配置目录;serving_server_conf.prototxt详细描述了模型的输入输出信息。以 YOLOv3 为例,输入为im_shape、image(形状 3×608×608)、scale_factor,输出为 NMS 结果(multiclass_nms3_0.tmp_0,LoD 张量)与multiclass_nms3_0.tmp_2。
关于导出的输入输出约定,deploy/EXPORT_MODEL.md 中说明:模型输入为 image([None, 3, H, W])、im_shape([None, 2],resize 后的 H、W)、scale_factor([None, 2],scale_y、scale_x);统一输出为 bbox(形状 [N, 6],每行是 class_id, score, x1, y1, x2, y2)、bbox_num(每张图片的预测框个数),若网络包含 mask 分支还会输出 mask。
4. 启动服务端模型预测服务
4.1 启动命令
完成环境准备与模型导出后,按如下命令启动模型预测服务:
python deploy/serving/python/web_service.py --model_dir output_inference/yolov3_darknet53_270e_coco &
--model_dir 指向导出目录(tools/export_model.py 的默认输出目录为 output_inference)。& 表示后台运行。此外 web_service.py 还支持 -c/--config 指定服务配置文件(默认即 deploy/serving/python/config.yml)与 -o 命令行覆盖配置参数。
4.2 服务端配置文件 config.yml 详解
服务端模型预测相关配置在 config.yml 中修改,开发者最常关注三个配置:http_port(服务的 http 端口)、device_type(计算硬件类型)、devices(计算硬件 ID)。完整配置项及含义如下:
# worker_num, 最大并发数。当build_dag_each_worker=True时, 框架会创建worker_num个进程,
# 每个进程内构建grpcServer和DAG;当build_dag_each_worker=False时,
# 框架会设置主线程grpc线程池的max_workers=worker_num
worker_num: 20
# http端口, rpc_port和http_port不允许同时为空。当rpc_port可用且http_port为空时,不自动生成http_port
http_port: 18093
rpc_port: 9993
dag:
# op资源类型, True, 为线程模型;False,为进程模型
is_thread_op: False
op:
# op名称,与web_service中DetectorService初始化name参数一致
ppdet:
# 并发数,is_thread_op=True时,为线程并发;否则为进程并发
concurrency: 1
# 当op配置没有server_endpoints时,从local_service_conf读取本地服务配置
local_service_conf:
# 模型路径(web_service.py 启动时会被自动改写为 --model_dir 下的 serving_server 目录)
model_config: "./serving_server"
# 计算硬件类型: 空缺时由devices决定(CPU/GPU),0=cpu, 1=gpu, 2=tensorRT, 3=arm cpu, 4=kunlun xpu
device_type:
# 计算硬件ID,当devices为""或不写时为CPU预测;
# 当devices为"0", "0,1,2"时为GPU预测,表示使用的GPU卡
devices: "0" # "0,1"
# client类型,包括brpc, grpc和local_predictor。
# local_predictor不启动Serving服务,进程内预测
client_type: local_predictor
关键参数速查表:
| 配置项 | 位置 | 默认值/示例 | 含义 |
|---|---|---|---|
worker_num |
顶层 | 20 |
最大并发数,决定 worker 进程/线程规模 |
http_port |
顶层 | 18093 |
HTTP 服务端口(与 rpc_port 不能同时为空) |
rpc_port |
顶层 | 9993 |
RPC 服务端口 |
dag.is_thread_op |
dag | False |
True 为线程模型,False 为进程模型 |
op.<name>.concurrency |
op | 1 |
OP 并发数(线程并发或进程并发,取决于 is_thread_op) |
op.<name>.local_service_conf.model_config |
op | ./serving_server |
服务端模型路径,运行时被自动改写为导出目录下的 serving_server |
op.<name>.local_service_conf.device_type |
op | 空 | 0=cpu、1=gpu、2=tensorRT、3=arm cpu、4=kunlun xpu;空缺时由 devices 决定 |
op.<name>.local_service_conf.devices |
op | "0" |
计算硬件 ID;为空/不写为 CPU,"0" 或 "0,1,2" 为 GPU 卡号 |
op.<name>.local_service_conf.client_type |
op | local_predictor |
brpc、grpc 或 local_predictor;local_predictor 为进程内预测 |
注:
op下的键名ppdet必须与 web_service.py 中DetectorService.get_pipeline_response里DetectorOp(name="ppdet", ...)的name参数保持一致,同时与服务端DetectorService(name="ppdet")的 name 一致,否则配置无法正确关联到 OP。
4.3 服务端启动流程源码解读
web_service.py 的启动主流程(__main__ 部分)可以分为五步:
- 解析参数:
ArgsParser().parse_args()读取命令行参数;若指定了-o key=value,会通过_parse_opt将其写入 yaml 配置(devices会强制转为字符串); - 读取导出配置:
PredictConfig解析--model_dir下的 infer_cfg.yml(即导出时随模型生成的推理配置),读取arch(模型架构)、Preprocess(预处理算子序列)、label_list、use_dynamic_shape、draw_threshold、mask等字段;check_model会校验arch是否在SUPPORT_MODELS集合(YOLO、PPYOLOE、RCNN、SSD、Face、FCOS、SOLOv2、TTFNet、S2ANet、JDE、FairMOT、DeepSORT、GFL、PicoDet、CenterNet、TOOD、RetinaNet、StrongBaseline、STGCN、YOLOX、HRNet)中,不支持的架构会抛出ValueError; - 解析模型输入输出:
get_model_vars将local_service_conf.model_config改写为<model_dir>/serving_server,并解析serving_server_conf.prototxt得到feed_vars与fetch_vars(后续用它们过滤预处理输入、定位推理输出); - 构建服务:
DetectorService(name="ppdet")继承自WebService,其get_pipeline_response将DetectorOp(name="ppdet", input_ops=[read_op])接入 Pipeline DAG; - 启动:
prepare_pipeline_config加载 yml 配置后调用run_service()正式对外提供服务。
5. 启动客户端访问服务
当模型预测服务成功启动后,另开终端执行:
python deploy/serving/python/pipeline_http_client.py --image_file demo/000000014439.jpg
客户端代码 pipeline_http_client.py 支持的参数包括:
| 参数 | 默认值 | 含义 |
|---|---|---|
--image_file |
无 | 单张图片路径(优先级高于 --image_dir) |
--image_dir |
无 | 图片目录,会递归收集 jpg/jpeg/png/bmp(含大写)图片 |
--http_port |
18093 |
与服务端 config.yml 中 http_port 一致 |
--service_name |
ppdet |
与服务端 OP 名称一致 |
客户端请求流程为:
- 拼接请求 URL:
http://127.0.0.1:{http_port}/{service_name}/prediction; - 读取图片字节流,进行 base64 编码;
- 构造
{"key": ["image_0"], "value": [image], "logid": logid}的 JSON 数据,通过requests.post发送到服务端; - 打印服务端返回的 JSON 结果。
对应地,服务端 DetectorOp.preprocess 会做镜像处理:对收到的 value 执行 base64.b64decode 还原字节流,再用 PIL.Image 打开并转为 RGB,送入预处理流水线。
6. 服务端处理流程与自定义 OP 机制
6.1 一条请求的完整生命周期
以 yolov3_darknet53_270e_coco 为例,请求在服务端的处理链路如下:
- 预处理:
DetectorOp.init_op中通过Compose(GLOBAL_VAR['preprocess_ops'])构建预处理流水线,其中preprocess_ops正是从导出模型infer_cfg.yml的Preprocess字段解析出来的算子序列;preprocess对 base64 图片解码后逐个调用算子,collate_inputs只保留feed_vars中的输入项并np.stack成 batch; - 推理:
local_predictor(进程内预测)直接以 batch 化的image、im_shape、scale_factor喂入模型; - 后处理:
postprocess根据架构分流——HRNet 类走parse_keypoint_result(关键点解析),其余检测类模型走parse_detection_result; - 结果返回:
parse_detection_result按bboxes_num切分每个 batch 样本的预测框,过滤掉低于draw_threshold(默认 0.5)的框,输出格式为"class_id score x1 y1 x2 y2"的字符串列表;若无目标则返回'No object detected!'。
6.2 预处理算子(preprocess_ops.py)
preprocess_ops.py 中的算子与训练/推理时使用的数据变换一一对应,Compose 会根据 infer_cfg.yml 中每个算子的 type 字段动态实例化(eval(op_type)(**new_op_info)),因此换用不同模型时无需修改服务端代码,只需重新导出模型,预处理流水线会自动匹配。主要算子包括:
decode_image:将PIL.Image转为np.ndarray,初始化im_shape与scale_factor信息;Resize:按target_size等比/非等比缩放,keep_ratio=True时短边对齐目标尺寸并限制长边不超过max(target_size),同时更新im_shape与scale_factor;NormalizeImage:is_scale控制是否除以 255,norm_type='mean_std'时执行(im - mean) / std;Permute:将 HWC 转 CHW;PadStride:将图像 padding 到最粗 stride(如 FPN 网络的 32)的整数倍;LetterBoxResize:YOLO 系模型常用的 letterbox 缩放,按min(ratio_h, ratio_w)等比缩放后以(127.5,127.5,127.5)填充到目标尺寸;Pad:padding 到指定尺寸,填充值默认为[114, 114, 114];WarpAffine与TopDownEvalAffine:CenterNet 等中心点检测与 HRNet 关键点模型使用的仿射变换(含get_affine_transform等工具函数)。
6.3 后处理算子(postprocess_ops.py)
postprocess_ops.py 中实现了 HRNetPostProcess 关键点后处理,包含:get_max_preds(从 heatmap 取最大响应位置)、gaussian_blur(高斯模糊)、dark_postprocess/dark_parse(DarkPose 亚像素精修,use_dark=True 时启用)、get_final_preds(通过 get_affine_transform(..., inv=1) 将预测坐标逆变换回原图)以及 transform_preds/affine_transform。检测类模型(YOLO/RCNN 等)的 NMS 与坐标解析则由导出的预测程序内完成(fetch_vars 直接取 NMS 输出),服务端只做阈值过滤与格式整理,这正是 Python Pipeline 二次开发便捷性的体现——开发者可在此自由扩展自己的后处理。
7. 验证部署链路(可选:经典 Serving 测试方式)
除了 Python Pipeline 客户端,仓库还提供了基于 Serving C++ 风格的通用测试客户端 deploy/serving/test_client.py,其处理流程与 pipeline_http_client.py 不同(使用 paddle_serving_client.Client 直连 RPC 端口 9393,预处理使用 paddle_serving_app.reader.Sequential),可作为链路验证的补充参考。测试方式(对应 deploy/serving/README.md):
cd output_inference/yolov3_darknet53_270e_coco/
python -m paddle_serving_server.serve --model serving_server --port 9393 --gpu_ids 0 # GPU
# python -m paddle_serving_server.serve --model serving_server --port 9393 # CPU
python ../../deploy/serving/test_client.py ../../deploy/serving/label_list.txt ../../demo/000000014439.jpg
测试代码会自动创建 output 文件夹,并在其中生成 bbox.json 与带检测框的可视化图片 000000014439.jpg。
8. 常见问题与注意事项
- 端口冲突与配置一致性:
http_port/rpc_port不能同时为空;客户端--http_port必须与服务端config.yml中的http_port一致,--service_name必须与服务端 OP 名称(默认ppdet)一致; - 模型目录结构:
--model_dir必须指向包含infer_cfg.yml、model.pdmodel、model.pdiparams以及serving_server子目录的导出目录,web_service.py启动时会校验并解析serving_server_conf.prototxt; - 硬件配置:
devices为空/不写时走 CPU 预测;"0"表示使用 0 号 GPU;device_type空缺时由devices推断;TensorRT 推理需将device_type设为 2 并确保环境安装对应版本; - 模型架构支持范围:
SUPPORT_MODELS中列出了服务端内置支持的架构,导出模型的arch不在集合内会直接报错,遇到不支持的架构需自行扩展 OP 逻辑; - 图像输入约定:客户端发送的图片需 base64 编码后放入
value字段,服务端用 PIL 解码并转为 RGB,因此本地测试图片请使用常见格式(jpg/jpeg/png/bmp); - 后台运行与日志:启动命令末尾的
&将服务放入后台,建议在正式环境中结合 nohup 与日志重定向运行,并通过http_port的健康检查确认服务就绪后再发起客户端请求。