PaddleDetection 模型 Python Serving 服务化部署实战:基于 Paddle Serving Pipeline 框架的完整部署指南

原创2026-09-22 20:05:121,648 阅读
文章标签:计算机视觉深度学习人工智能机器学习模型量化模型蒸馏

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__ 部分)可以分为五步:

  1. 解析参数:ArgsParser().parse_args() 读取命令行参数;若指定了 -o key=value,会通过 _parse_opt 将其写入 yaml 配置(devices 会强制转为字符串);
  2. 读取导出配置: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;
  3. 解析模型输入输出:get_model_vars 将 local_service_conf.model_config 改写为 <model_dir>/serving_server,并解析 serving_server_conf.prototxt 得到 feed_vars 与 fetch_vars(后续用它们过滤预处理输入、定位推理输出);
  4. 构建服务:DetectorService(name="ppdet") 继承自 WebService,其 get_pipeline_response 将 DetectorOp(name="ppdet", input_ops=[read_op]) 接入 Pipeline DAG;
  5. 启动: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 名称一致

客户端请求流程为:

  1. 拼接请求 URL:http://127.0.0.1:{http_port}/{service_name}/prediction;
  2. 读取图片字节流,进行 base64 编码;
  3. 构造 {"key": ["image_0"], "value": [image], "logid": logid} 的 JSON 数据,通过 requests.post 发送到服务端;
  4. 打印服务端返回的 JSON 结果。

对应地,服务端 DetectorOp.preprocess 会做镜像处理:对收到的 value 执行 base64.b64decode 还原字节流,再用 PIL.Image 打开并转为 RGB,送入预处理流水线。

6. 服务端处理流程与自定义 OP 机制

6.1 一条请求的完整生命周期

以 yolov3_darknet53_270e_coco 为例,请求在服务端的处理链路如下:

  1. 预处理:DetectorOp.init_op 中通过 Compose(GLOBAL_VAR['preprocess_ops']) 构建预处理流水线,其中 preprocess_ops 正是从导出模型 infer_cfg.yml 的 Preprocess 字段解析出来的算子序列;preprocess 对 base64 图片解码后逐个调用算子,collate_inputs 只保留 feed_vars 中的输入项并 np.stack 成 batch;
  2. 推理:local_predictor(进程内预测)直接以 batch 化的 image、im_shape、scale_factor 喂入模型;
  3. 后处理:postprocess 根据架构分流——HRNet 类走 parse_keypoint_result(关键点解析),其余检测类模型走 parse_detection_result;
  4. 结果返回: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 的健康检查确认服务就绪后再发起客户端请求。
登录后查看全文
PaddleDetection