PaddleClas 图像识别模型服务化部署指南:基于 Paddle Serving 的 PP-ShiTu 在线预测实践

原创2026-10-05 14:24:521,917 阅读
文章标签:计算机视觉深度学习人工智能机器学习模型蒸馏

PaddleClas 图像识别模型服务化部署指南:基于 Paddle Serving 的 PP-ShiTu 在线预测实践

导读

本文以 PaddleClas 开源仓库中的识别模型服务化部署文档为核心,完整讲解如何使用 Paddle Serving 将 PP-ShiTu 图像识别系统(主体检测 + 特征提取 + 向量检索)部署为工业级在线预测服务。读者将掌握 Serving 环境安装、inference 模型到 Serving 模型的双模型转换、Python Pipeline 与 C++ Serving 两套服务启动/请求/关闭流程,以及典型踩坑问题的排查方法,可直接用于商品识别、安防检索等实际业务场景的线上部署。

1. 简介:为什么用 Paddle Serving 部署识别服务

PP-ShiTu 是一个由主体检测、特征提取、向量检索三个模块构成的通用图像识别系统,部署时涉及多个模型协同工作。Paddle Serving 是飞桨生态中面向工业级在线预测的服务化框架,支持一键部署服务能力、客户端与服务端之间高并发高效通信,并允许用多种编程语言开发客户端。

本文以 HTTP 预测服务部署为例,介绍在 PaddleClas 中使用 Paddle Serving 部署模型服务。部署方式上,由于识别服务涉及多个模型,出于性能考虑采用 PipeLine(流水线)部署方式,需要特别注意的是:

  • 目前仅支持 Linux 平台部署,暂不支持 Windows 平台(Pipeline 部署方式当前也不支持 Windows);
  • 使用 PaddleServing 做图像识别服务化部署时,需要将保存的多个 inference 模型全部转换为 Serving 模型,而不是只转换某一个。

从仓库中的PP-ShiTu 系统文档可以看到,PP-ShiTuV2 由 PicoDet-LCNet_x2_5 轻量主体检测模型与 PPLCNetV2_base 特征提取模型构成,本文即以这一对"超轻量识别模型"为示例展开。

2. Serving 安装

Serving 官网推荐使用 docker 安装并部署 Serving 环境。首先拉取 docker 镜像并创建基于 Serving 的容器,分为 GPU 与 CPU 两种情形:

# 启动GPU docker
docker pull paddlepaddle/serving:0.7.0-cuda10.2-cudnn7-devel
nvidia-docker run -p 9292:9292 --name test -dit paddlepaddle/serving:0.7.0-cuda10.2-cudnn7-devel bash
nvidia-docker exec -it test bash

# 启动CPU docker
docker pull paddlepaddle/serving:0.7.0-devel
docker run -p 9292:9292 --name test -dit paddlepaddle/serving:0.7.0-devel bash
docker exec -it test bash

进入 docker 后,需要安装 Serving 相关的 python 包(示例基于 python3.7):

python3.7 -m pip install paddle-serving-client==0.7.0
python3.7 -m pip install paddle-serving-app==0.7.0
python3.7 -m pip install faiss-cpu==1.7.1post2

#若为CPU部署环境:
python3.7 -m pip install paddle-serving-server==0.7.0 # CPU
python3.7 -m pip install paddlepaddle==2.2.0          # CPU

#若为GPU部署环境
python3.7 -m pip install paddle-serving-server-gpu==0.7.0.post102 # GPU with CUDA10.2 + TensorRT6
python3.7 -m pip install paddlepaddle-gpu==2.2.0     # GPU with CUDA10.2

#其他GPU环境需要确认环境再选择执行哪一条
python3.7 -m pip install paddle-serving-server-gpu==0.7.0.post101 # GPU with CUDA10.1 + TensorRT6
python3.7 -m pip install paddle-serving-server-gpu==0.7.0.post112 # GPU with CUDA11.2 + TensorRT8

安装要点:

  • 如果安装速度太慢,可以通过 -i https://pypi.tuna.tsinghua.edu.cn/simple 更换镜像源加速安装;
  • 其他环境配置安装请参考 Paddle Serving 官方"使用Docker安装Paddle Serving"文档;
  • paddle-serving-client 与 paddle-serving-app 是客户端与工具包,服务端还需要根据 CPU/GPU 选择对应的 paddle-serving-server 或 paddle-serving-server-gpu,并配套安装对应版本的 paddlepaddle/paddlepaddle-gpu;
  • faiss-cpu 用于向量检索环节,是识别服务 Pipeline 中不可或缺的依赖。

3. 图像识别服务部署

使用 PaddleServing 做图像识别服务化部署时,需要将保存的多个 inference 模型都转换为 Serving 模型。下面以 PP-ShiTu 中的超轻量图像识别模型为例(通用识别模型 general_PPLCNetV2_base + 通用检测模型 picodet_PPLCNet_x2_5_mainbody_lite),介绍完整的部署流程。

3.1 模型转换

3.1.1 下载 inference 模型

进入工作目录并下载两个 inference 模型:

cd deploy/
# 创建并进入models文件夹
mkdir models
cd models
# 下载并解压通用识别模型
wget https://paddle-imagenet-models-name.bj.bcebos.com/dygraph/rec/models/inference/PP-ShiTuV2/general_PPLCNetV2_base_pretrained_v1.0_infer.tar
tar -xf general_PPLCNetV2_base_pretrained_v1.0_infer.tar
# 下载并解压通用检测模型
wget https://paddle-imagenet-models-name.bj.bcebos.com/dygraph/rec/models/inference/picodet_PPLCNet_x2_5_mainbody_lite_v1.0_infer.tar
tar -xf picodet_PPLCNet_x2_5_mainbody_lite_v1.0_infer.tar

这两份 inference 模型也可以参考 PP-ShiTu 推理部署文档中的方式直接下载,或通过 export_model.py 从训练权重导出。

3.1.2 转换通用识别模型

使用 paddle_serving_client.convert 命令将通用识别 inference 模型转换为 Serving 模型:

# 转换通用识别模型
python3.7 -m paddle_serving_client.convert \
--dirname ./general_PPLCNetV2_base_pretrained_v1.0_infer/ \
--model_filename inference.pdmodel  \
--params_filename inference.pdiparams \
--serving_server ./general_PPLCNetV2_base_pretrained_v1.0_serving/ \
--serving_client ./general_PPLCNetV2_base_pretrained_v1.0_client/

转换完成后,当前文件夹会多出 general_PPLCNetV2_base_pretrained_v1.0_serving/ 和 general_PPLCNetV2_base_pretrained_v1.0_client/ 两个文件夹,结构如下:

├── general_PPLCNetV2_base_pretrained_v1.0_serving/
│   ├── inference.pdiparams
│   ├── inference.pdmodel
│   ├── serving_server_conf.prototxt
│   └── serving_server_conf.stream.prototxt
│
└── general_PPLCNetV2_base_pretrained_v1.0_client/
      ├── serving_client_conf.prototxt
      └── serving_client_conf.stream.prototxt

接下来分别修改 serving/ 与 client/ 目录下的 serving_server_conf.prototxt 中的 alias 名字:将 fetch_var 中的 alias_name 改为 features。修改后的内容如下:

feed_var {
name: "x"
alias_name: "x"
is_lod_tensor: false
feed_type: 1
shape: 3
shape: 224
shape: 224
}
fetch_var {
  name: "batch_norm_25.tmp_2"
  alias_name: "features"
  is_lod_tensor: false
  fetch_type: 1
  shape: 512
}

关键说明:alias_name: "features" 必须与服务端/客户端代码中的 fetch_list 保持一致。在仓库的 config.yml 中,rec 服务的 fetch_list: ["features"] 正是以此 alias 为准,特征提取服务的返回即由该 fetch_var 定义。

3.1.3 转换通用检测模型

# 转换通用检测模型
python3.7 -m paddle_serving_client.convert --dirname ./picodet_PPLCNet_x2_5_mainbody_lite_v1.0_infer/ \
--model_filename inference.pdmodel  \
--params_filename inference.pdiparams \
--serving_server ./picodet_PPLCNet_x2_5_mainbody_lite_v1.0_serving/ \
--serving_client ./picodet_PPLCNet_x2_5_mainbody_lite_v1.0_client/

转换完成后同样生成 picodet_..._serving/ 与 picodet_..._client/ 两个文件夹(结构同上,包含 inference 模型文件与两份 prototxt 配置文件)。

3.1.4 convert 命令参数说明

上述转换命令的参数含义如下表所示:

参数 类型 默认值 描述
dirname str - 需要转换的模型文件存储路径,Program 结构文件和参数文件均保存在此目录
model_filename str None 存储需要转换的模型 Inference Program 结构的文件名称。如果设置为 None,则使用 __model__ 作为默认文件名
params_filename str None 存储需要转换的模型所有参数的文件名称。当且仅当所有模型参数被保存在一个单独的二进制文件中时才需要指定;如果模型参数是存储在各自分离的文件中,设置其值为 None
serving_server str "serving_server" 转换后的模型文件和配置文件存储路径,默认值为 serving_server
serving_client str "serving_client" 转换后的客户端配置文件存储路径,默认值为 serving_client

3.1.5 准备检索库 index

识别服务最后一步是向量检索,需要下载已经构建完成的检索库 index(以饮料识别数据集为例):

# 回到deploy目录
cd ../
# 下载构建完成的检索库 index
wget https://paddle-imagenet-models-name.bj.bcebos.com/dygraph/rec/data/drink_dataset_v2.0.tar
# 解压构建完成的检索库 index
tar -xf drink_dataset_v2.0.tar

解压后的 drink_dataset_v2.0/ 中包含了 index/vector.index(Faiss 向量索引)与 index/id_map.pkl(索引到类别名的映射文件),以及测试图片目录 test_images/。若需要从零构建自己的索引库,可以参考 PP-ShiTu 快速体验文档 中 paddleclas --build_gallery 的方式。

3.2 服务部署和请求

进入服务部署工作目录:

cd ./deploy/paddleserving/recognition

该目录包含启动 Python Pipeline 服务、C++ Serving 服务和发送预测请求的完整代码,各文件职责如下(对应仓库实际文件):

__init__.py
config.yml                  # 启动python pipeline服务的配置文件
pipeline_http_client.py     # http方式发送pipeline预测请求的脚本
pipeline_rpc_client.py      # rpc方式发送pipeline预测请求的脚本
recognition_web_service.py  # 启动pipeline服务端的脚本
run_cpp_serving.sh          # 启动C++ Pipeline Serving部署的脚本
test_cpp_serving_client.py  # rpc方式发送C++ Pipeline serving预测请求的脚本

3.2.1 Python Serving

启动服务:

# 启动服务,运行日志保存在 log.txt
python3.7 recognition_web_service.py &>log.txt &

发送请求(HTTP 方式):

python3.7 pipeline_http_client.py

成功运行后,模型预测的结果会打印在客户端中,如下所示:

{'err_no': 0, 'err_msg': '', 'key': ['result'], 'value': ["[{'bbox': [438, 71, 660, 712], 'rec_docs': '元气森林', 'rec_scores': 0.7581642}, {'bbox': [220, 72, 449, 689], 'rec_docs': '元气森林', 'rec_scores': 0.68961805}, {'bbox': [794, 104, 978, 652], 'rec_docs': '元气森林', 'rec_scores': 0.63075215}]"], 'tensors': []}

其中 bbox 表示检测框坐标([x1, y1, x2, y2]),rec_docs 表示检索库中最相似的类别名,rec_scores 为对应的相似度分数。

仓库中还提供了 pipeline_rpc_client.py,它以 RPC 方式向 127.0.0.1:9994 端口发送 feed_dict={"image": image_base64} 的请求并拉取 result,适用于需要更高效通信的 RPC 场景。

理解 Python Pipeline 服务端实现: 从 recognition_web_service.py 源码可以看清完整的服务编排逻辑:

  • DetOp(检测算子):init_op 中构造 Sequential([BGR2RGB(), Div(255.0), Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]), Resize((640, 640)), Transpose((2, 0, 1))]) 预处理链,并用 RCNNPostprocess 做检测后处理,阈值 threshold = 0.2、最多保留 max_det_results = 5 个检测框;preprocess 中同时计算 im_shape 与 scale_factor 作为检测模型输入;
  • RecOp(识别算子):init_op 中加载 Faiss 索引(faiss.read_index("vector.index"))与 id_map.pkl,设定 rec_nms_thresold = 0.05、rec_score_thres = 0.5、return_k = 1;preprocess 将检测结果中每个 bbox 裁剪后按 224×224 预处理拼接成 batch 送入特征提取模型;postprocess 对特征做 L2 归一化后调用 searcher.search,并实现自定义 nms_to_rec_results 对识别结果做 NMS 去重;
  • RecognitionService.get_pipeline_response 将算子串联为 DAG:det_op = DetOp(name="det", input_ops=[read_op]),rec_op = RecOp(name="rec", input_ops=[det_op]),最终返回 rec_op。

理解 config.yml 配置: config.yml 是 Python Pipeline 的核心配置文件,关键字段含义如下:

worker_num: 1          # 最大并发数;build_dag_each_worker=True时创建worker_num个进程
http_port: 18081       # HTTP端口(pipeline_http_client.py 即请求该端口)
rpc_port: 9994         # RPC端口(pipeline_rpc_client.py 即连接该端口)
dag:
    is_thread_op: False   # op资源类型:True为线程模型,False为进程模型
op:
    rec:                  # 识别op
        concurrency: 1
        local_service_conf:
            model_config: ../../models/general_PPLCNetV2_base_pretrained_v1.0_serving  # 模型路径
            device_type: 1   # 计算硬件类型:0=cpu, 1=gpu, 2=tensorRT, 3=arm cpu, 4=kunlun xpu
            devices: "0"     # 使用的GPU卡号,为空/不写时为CPU预测
            client_type: local_predictor  # brpc/grpc/local_predictor;local_predictor不启动Serving服务,进程内预测
            fetch_list: ["features"]      # Fetch结果列表,以client_config中fetch_var的alias_name为准
    det:                  # 检测op
        concurrency: 1
        local_service_conf:
            client_type: local_predictor
            device_type: 1
            devices: "0"
            fetch_list:
                - save_infer_model/scale_0.tmp_1   # 检测模型输出tensor名
            model_config: ../../models/picodet_PPLCNet_x2_5_mainbody_lite_v1.0_serving/

注意 rec 的 model_config 指向通用识别 Serving 模型目录,det 的 model_config 指向检测 Serving 模型目录,FAQ 中提到的路径配置错误排查即针对此处。

3.2.2 C++ Serving

与 Python Serving 不同,C++ Serving 客户端调用 C++ OP 来预测,因此在启动服务之前,需要编译并安装 serving server 包,并设置 SERVING_BIN。

编译并安装 Serving server 包:

# 进入工作目录
cd ./deploy/paddleserving

# 一键编译安装Serving server、设置 SERVING_BIN
source ./build_server.sh python3.7

注: build_server.sh 所设定的路径可能需要根据实际机器上的环境如 CUDA、python 版本等作一定修改,然后再编译。该脚本的流程是:安装依赖与 OpenSSL 库 → 安装 go 依赖(grpc-gateway 等插件)→ 下载 opencv3 库并设置 OPENCV_DIR → clone Serving 源码 → 将仓库中的自定义 OP 代码 general_clas_op. 复制到 Serving 的 core/general-server/op,将 preprocess_op. 复制到 core/predictor/tools/pp_shitu_tools → cmake 编译并安装 server 包 → export SERVING_BIN=$PWD/core/general-server/serving。如果执行过程中遇到非网络原因的报错,可以手动将脚本中的命令逐条复制到终端执行。

覆盖 prototxt 文件:

C++ Serving 使用的输入输出格式与 Python 不同,因此需要将 deploy/paddleserving/recognition/preprocess/ 下预置的 4 个 prototxt 文件复制到 3.1 节生成的 serving/client 文件夹中,覆盖对应文件:

# 回到deploy目录
cd ../

# 覆盖prototxt文件
\cp ./paddleserving/recognition/preprocess/general_PPLCNetV2_base_pretrained_v1.0_serving/*.prototxt ./models/general_PPLCNetV2_base_pretrained_v1.0_serving/
\cp ./paddleserving/recognition/preprocess/general_PPLCNetV2_base_pretrained_v1.0_client/*.prototxt ./models/general_PPLCNetV2_base_pretrained_v1.0_client/
\cp ./paddleserving/recognition/preprocess/picodet_PPLCNet_x2_5_mainbody_lite_v1.0_client/*.prototxt ./models/picodet_PPLCNet_x2_5_mainbody_lite_v1.0_client/
\cp ./paddleserving/recognition/preprocess/picodet_PPLCNet_x2_5_mainbody_lite_v1.0_serving/*.prototxt ./models/picodet_PPLCNet_x2_5_mainbody_lite_v1.0_serving/

仓库中预置的 general_PPLCNetV2_base_pretrained_v1.0_serving/serving_server_conf.prototxt 内容展示了 C++ Serving 需要同时支持 x 与 boxes 两个 feed、以及 features 与 boxes 两个 fetch 的输入输出结构,这正是它与 Python 服务格式差异的根源。

启动服务:

# 进入工作目录
cd ./paddleserving/recognition

# 端口号默认为9400;运行日志默认保存在 log_PPShiTu.txt 中
# CPU部署
bash run_cpp_serving.sh
# GPU部署,并指定第0号卡
bash run_cpp_serving.sh 0

从 run_cpp_serving.sh 的实现可以看到,其本质是通过 paddle_serving_server.serve 同时加载检测与识别两个 Serving 模型目录,并指定 GeneralPicodetOp GeneralFeatureExtractOp 两个 C++ 自定义 OP,--port 9400 为服务端口;传入 GPU 卡号参数时自动追加 --gpu_id。

发送请求:

# 发送服务请求
python3.7 test_cpp_serving_client.py

成功运行后,模型预测的结果会打印在客户端中,如下所示:

WARNING: Logging before InitGoogleLogging() is written to STDERR
I0903 16:03:20.020586 35600 naming_service_thread.cpp:202] brpc::policy::ListNamingService("127.0.0.1:9400"): added 1
I0903 16:03:21.346057 35600 general_model.cpp:490] [client]logid=0,client_cost=1306.26ms,server_cost=1293.65ms.
[{'bbox': [437, 71, 660, 727], 'rec_docs': '元气森林', 'rec_scores': 0.76902336}, {'bbox': [222, 72, 449, 700], 'rec_docs': '元气森林', 'rec_scores': 0.69347066}, {'bbox': [794, 104, 979, 652], 'rec_docs': '元气森林', 'rec_scores': 0.6305151}]

从 test_cpp_serving_client.py 源码可见,C++ 客户端通过 Client().load_client_config([...两个client目录]) 加载配置并 connect(['127.0.0.1:9400']),client.predict(feed={"image": im, "im_shape": im_shape}, fetch=["features", "boxes"]) 一次取回特征与检测框,然后在客户端侧完成 Faiss 检索与 nms_to_rec_results 后处理,最终打印识别结果。

关闭服务:

如果服务程序在前台运行,可以按下 Ctrl+C 终止服务端程序;如果在后台运行,可以使用 kill 命令关闭相关进程,也可以在启动服务程序的路径下执行以下命令:

python3.7 -m paddle_serving_server.serve stop

执行完毕后出现 Process stopped 信息表示成功关闭服务。

4. FAQ

Q1:发送请求后没有结果返回或者提示输出解码报错

A1: 启动服务和发送请求时不要设置代理,可以在启动服务前和发送请求前关闭代理,关闭代理的命令是:

unset https_proxy
unset http_proxy

Q2:启动服务后没有任何反应

A2: 可以检查 config.yml 中 model_config 对应的路径是否存在,文件夹命名是否正确。该字段分别指向 ../../models/general_PPLCNetV2_base_pretrained_v1.0_serving 与 ../../models/picodet_PPLCNet_x2_5_mainbody_lite_v1.0_serving/,请确保 3.1 节模型转换的输出目录名与配置严格一致。

5. 小结:识别服务部署的完整链路

回顾整条部署链路:Serving 环境安装(docker + pip 包)→ inference 模型转换(两个模型分别 convert)→ alias 修改(features)→ 检索库准备(vector.index + id_map.pkl)→ 启动服务(Python Pipeline 或 C++ Serving)→ 发送请求(HTTP/RPC 客户端)→ 结果解析(bbox + rec_docs + rec_scores)→ 关闭服务。

两种部署方式的选择建议:Python Serving 无需编译自定义 OP,适合快速验证与二次开发,其算子逻辑全部在 recognition_web_service.py 中可见、易修改;C++ Serving 需要编译安装带自定义 OP(GeneralPicodetOp、GeneralFeatureExtractOp)的 server 包,但预测阶段由 C++ 引擎执行,适合追求更高性能的工业场景。二者共享同一套模型转换产物,仅 prototxt 输入输出格式与请求协议不同。更多的服务部署类型(如 RPC 预测服务等)可参考 Paddle Serving 官方示例。

登录后查看全文
PaddleClas