PaddleOCR 推理部署全攻略：五大部署方案选型与 Python、C++、Serving、Lite、ONNX 实战

PaddleOCR（PP-OCR）在提供训练能力之外，围绕"推理部署"打通了多条产品级路径：面向服务端/云端的 Python 预测引擎与 C++ 高性能推理、面向高并发场景的 Serving 服务化部署、面向移动端/边缘端的 Paddle-Lite 轻量化部署，以及面向跨框架生态的 Paddle2ONNX 转换。本文以官方部署导航文档（docs/version2.x/ppstructure/infer_deploy/index.md）为主线，逐条展开五大部署方式的环境准备、模型准备、启动命令、核心参数与 FAQ，并辅以 ppstructure/utility.py、ppstructure/predict_system.py、deploy/hubserving 等仓库源码佐证，帮助你根据业务场景（CPU/GPU 服务器、大流量服务、手机端、第三方推理框架）快速选定方案并完成落地。

一、Paddle 推理部署方案总览

飞桨（PaddlePaddle）提供了多种部署方案，覆盖从云端到端侧、从单机到服务化的全场景。官方部署方案对比如下：

部署方案	特色	适用场景	典型硬件
Paddle Inference（Python/C++）	通用性	模型算法复杂、硬件高性能的服务端/云端	X86 CPU、NVIDIA GPU、龙芯/飞腾等国产 CPU、昆仑/昇腾/海光 DCU 等 AI 加速芯片
Paddle Lite	轻量化	模型小、硬件杂、资源少、功耗低的移动端/边缘端	Arm CPU、Arm/高通/苹果 GPU、昆仑/昇腾/麒麟/瑞芯微/寒武纪/比特大陆等加速硬件
Paddle Serving	高并发	大流量、高并发、低延时、高吞吐、资源弹性调控、模型组合/加密/热更新	X86/Arm CPU、NVIDIA GPU、昆仑/昇腾等
Paddle.js	浏览器推理	Chrome、Safari、Firefox 等浏览器前端	浏览器环境
Paddle2ONNX	开放兼容	第三方推理框架、长尾硬件支持	地平线旭日 X3、鲲云星空 X3、全志 R329 等国产芯片

从仓库文档结构可以确认，PP-OCR 模型已打通上述多种场景部署方案，对应的官方教程分别位于：

• Python 推理：ppstructure/predict_system.py 驱动的版面分析与关键信息抽取；
• C++ 推理：deploy/cpp_infer 下的高性能预测 demo；
• Serving 服务化部署（Python/C++）：deploy/hubserving 服务包；
• Paddle-Lite 端侧部署（ARM CPU/OpenCL ARM GPU）：deploy/lite 移动端 demo；
• Paddle2ONNX 推理：跨框架模型转换与 ONNXRuntime 推理。

如果部署的是 PP-OCR 以外的学术算法模型（如各类检测/识别算法），需要直接进入相应算法主页面查看，入口见算法总览。

二、基于 Python 预测引擎推理（PP-Structure 版面信息抽取）

Python 推理是最快捷的验证与落地方式，核心入口是 ppstructure/predict_system.py。从源码看，该脚本通过 --mode 参数（可选 structure 或 kie，默认 structure，定义于 ppstructure/utility.py）区分"版面信息抽取"与"关键信息抽取"两大任务。

2.1 模型下载与目录准备

进入 ppstructure 目录并下载 PP-StructureV2 系列推理模型（推理模型为 Paddle 静态图格式，由 inference.pdmodel 与 inference.pdiparams 组成）：

cd ppstructure

mkdir inference && cd inference
# 下载PP-StructureV2版面分析模型并解压
wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_layout_infer.tar && tar xf picodet_lcnet_x1_0_layout_infer.tar
# 下载PP-OCRv3文本检测模型并解压
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_det_infer.tar && tar xf PP-OCRv3_mobile_det_infer.tar
# 下载PP-OCRv3文本识别模型并解压
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_rec_infer.tar && tar xf PP-OCRv3_mobile_rec_infer.tar
# 下载PP-StructureV2表格识别模型并解压
wget https://paddleocr.bj.bcebos.com/ppstructure/models/slanet/paddle3.0b2/ch_ppstructure_mobile_v2.0_SLANet_infer.tar && tar xf ch_ppstructure_mobile_v2.0_SLANet_infer.tar
cd ..

2.2 版面分析 + 表格识别

同时启用版面分析、文本检测/识别与表格识别，对整页文档完成结构化抽取：

python3 predict_system.py --det_model_dir=inference/PP-OCRv3_mobile_det_infer \
                          --rec_model_dir=inference/PP-OCRv3_mobile_rec_infer \
                          --table_model_dir=inference/ch_ppstructure_mobile_v2.0_SLANet_infer \
                          --layout_model_dir=inference/picodet_lcnet_x1_0_layout_infer \
                          --image_dir=./docs/table/1.png \
                          --rec_char_dict_path=../ppocr/utils/ppocr_keys_v1.txt \
                          --table_char_dict_path=../ppocr/utils/dict/table_structure_dict_ch.txt \
                          --output=../output \
                          --vis_font_path=../doc/fonts/simfang.ttf

运行完成后，每张图片会在 output 指定目录下的 structure 子目录中生成同名目录：图片里的每个表格会存储为一个 Excel 文件，图片区域会被裁剪保存，Excel 与图片文件名即表格在图片中的坐标；详细结果存储在 res.txt 中。

2.3 仅版面分析

通过 --table=false --ocr=false 关闭表格识别与 OCR，只输出版面区域（--layout 默认开启，定义见 ppstructure/utility.py）：

python3 predict_system.py --layout_model_dir=inference/picodet_lcnet_x1_0_layout_infer \
                          --image_dir=./docs/table/1.png \
                          --output=../output \
                          --table=false \
                          --ocr=false

运行完成后，每张图片会在 output 目录下的 structure 子目录中生成同名目录，图片区域被裁剪保存（文件名为区域坐标），版面分析结果存储在 res.txt 中。

2.4 仅表格识别

通过 --layout=false 关闭版面分析，直接对整图做表格结构识别：

python3 predict_system.py --det_model_dir=inference/PP-OCRv3_mobile_det_infer \
                          --rec_model_dir=inference/PP-OCRv3_mobile_rec_infer \
                          --table_model_dir=inference/ch_ppstructure_mobile_v2.0_SLANet_infer \
                          --image_dir=./docs/table/table.jpg \
                          --rec_char_dict_path=../ppocr/utils/ppocr_keys_v1.txt \
                          --table_char_dict_path=../ppocr/utils/dict/table_structure_dict_ch.txt \
                          --output=../output \
                          --vis_font_path=../doc/fonts/simfang.ttf \
                          --layout=false

运行完成后，表格会存储为 Excel 文件，文件名形如 [0,0,img_h,img_w]（即表格区域占整图的坐标）。

2.5 关键信息抽取（SER 与 RE+SER）

关键信息抽取（KIE）通过 --mode=kie 开启，算法默认 LayoutXLM（--kie_algorithm 默认值见 ppstructure/utility.py），predict_system.py 会据此进入 kie 分支初始化 SER/RE 模型。

SER（语义实体识别）：

cd ppstructure

mkdir inference && cd inference
# 下载SER XFUND 模型并解压
wget https://paddleocr.bj.bcebos.com/ppstructure/models/vi_layoutxlm/ser_vi_layoutxlm_xfund_infer.tar && tar -xf ser_vi_layoutxlm_xfund_infer.tar
cd ..
python3 predict_system.py \
  --kie_algorithm=LayoutXLM \
  --ser_model_dir=./inference/ser_vi_layoutxlm_xfund_infer \
  --image_dir=./docs/kie/input/zh_val_42.jpg \
  --ser_dict_path=../ppocr/utils/dict/kie_dict/xfund_class_list.txt \
  --vis_font_path=../doc/fonts/simfang.ttf \
  --ocr_order_method="tb-yx" \
  --mode=kie

运行完成后，每张图片会在 output 目录下的 kie 子目录中存放可视化图片，图片名与输入图片名一致。

RE+SER（关系抽取 + 语义实体识别）：在 SER 基础上增加 --re_model_dir：

cd ppstructure

mkdir inference && cd inference
# 下载RE SER XFUND 模型并解压
wget https://paddleocr.bj.bcebos.com/ppstructure/models/vi_layoutxlm/ser_vi_layoutxlm_xfund_infer.tar && tar -xf ser_vi_layoutxlm_xfund_infer.tar
wget https://paddleocr.bj.bcebos.com/ppstructure/models/vi_layoutxlm/re_vi_layoutxlm_xfund_infer.tar && tar -xf re_vi_layoutxlm_xfund_infer.tar
cd ..

python3 predict_system.py \
  --kie_algorithm=LayoutXLM \
  --re_model_dir=./inference/re_vi_layoutxlm_xfund_infer \
  --ser_model_dir=./inference/ser_vi_layoutxlm_xfund_infer \
  --image_dir=./docs/kie/input/zh_val_42.jpg \
  --ser_dict_path=../ppocr/utils/dict/kie_dict/xfund_class_list.txt \
  --vis_font_path=../doc/fonts/simfang.ttf \
  --ocr_order_method="tb-yx" \
  --mode=kie

运行完成后，每张图片会在 output 目录下的 kie 子目录中生成同名目录，目录内包含可视化图片和预测结果。

参数速查：--ocr_order_method 需为 None 或 tb-yx（自上而下再自左向右的阅读顺序，用于 KIE 前的文本行排序，见 ppstructure/utility.py）；--output 默认 ./output；--table_max_len 默认 488（表格识别输入长边）。

三、服务器端 C++ 预测部署

C++ 在性能上优于 Python，因此在大多数 CPU/GPU 部署场景下优先采用 C++ 部署。本节基于 docs/version2.x/ppstructure/infer_deploy/cpp_infer.md 与 deploy/cpp_infer 源码目录，介绍 Linux/Windows（CPU/GPU）环境下的完整流程。

3.1 准备环境

• Linux 环境（推荐使用 Docker）；Windows 环境下基于预测库的 C++ 编译方法参考 Windows VS2019 编译教程。

3.2 编译 OpenCV 库

以下载 opencv-3.4.7 源码为例：

cd deploy/cpp_infer
wget https://paddleocr.bj.bcebos.com/libs/opencv/opencv-3.4.7.tar.gz
tar -xf opencv-3.4.7.tar.gz

然后设置源码路径（root_path）与安装路径（install_path）并编译：

root_path="your_opencv_root_path"
install_path=${root_path}/opencv3
build_dir=${root_path}/build

rm -rf ${build_dir}
mkdir ${build_dir}
cd ${build_dir}

cmake .. \
    -DCMAKE_INSTALL_PREFIX=${install_path} \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=OFF \
    -DWITH_IPP=OFF \
    -DBUILD_IPP_IW=OFF \
    -DWITH_LAPACK=OFF \
    -DWITH_EIGEN=OFF \
    -DCMAKE_INSTALL_LIBDIR=lib64 \
    -DWITH_ZLIB=ON \
    -DBUILD_ZLIB=ON \
    -DWITH_JPEG=ON \
    -DBUILD_JPEG=ON \
    -DWITH_PNG=ON \
    -DBUILD_PNG=ON \
    -DWITH_TIFF=ON \
    -DBUILD_TIFF=ON

make -j
make install

也可以直接运行仓库提供的 deploy/cpp_infer/tools/build_opencv.sh：

sh tools/build_opencv.sh

make install 完成后，安装路径下会生成 bin、include、lib、lib64、share 等目录，其中头文件与库文件用于后续 OCR 代码编译。

3.3 下载或编译 Paddle 预测库

方式一：直接下载。从 Paddle 预测库官网选择对应 CUDA 版本的 Linux 预测库（建议选择 paddle 版本 ≥ 2.0.1），解压：

tar -xf paddle_inference.tgz

解压后生成 paddle_inference/ 目录。

方式二：源码编译。克隆 Paddle 仓库并编译最新预测库：

git clone https://github.com/PaddlePaddle/Paddle.git
git checkout develop

rm -rf build
mkdir build
cd build

cmake .. \
    -DWITH_CONTRIB=OFF \
    -DWITH_MKL=ON \
    -DWITH_MKLDNN=ON  \
    -DWITH_TESTING=OFF \
    -DCMAKE_BUILD_TYPE=Release \
    -DWITH_INFERENCE_API_TEST=OFF \
    -DON_INFER=ON \
    -DWITH_PYTHON=ON
make -j
make inference_lib_dist

编译完成后，在 build/paddle_inference_install_dir/ 下可以看到 paddle（C++ 预测所需的 Paddle 库）、third_party、version.txt（预测库版本信息）、CMakeCache.txt 等文件。

3.4 准备模型并编译 C++ demo

模型可直接从 PaddleOCR 模型库下载，或按模型导出说明将训练好的模型导出为推理模型。导出后 inference 目录结构如下：

inference/
|-- det_db
|   |--inference.pdiparams
|   |--inference.pdmodel
|-- rec_rcnn
|   |--inference.pdiparams
|   |--inference.pdmodel
|-- cls
|   |--inference.pdiparams
|   |--inference.pdmodel
|-- table
|   |--inference.pdiparams
|   |--inference.pdmodel
|-- layout
|   |--inference.pdiparams
|   |--inference.pdmodel

修改 deploy/cpp_infer/tools/build.sh 中的环境路径（注意写绝对路径），然后编译：

OPENCV_DIR=your_opencv_dir
LIB_DIR=your_paddle_inference_dir
CUDA_LIB_DIR=your_cuda_lib_dir
CUDNN_LIB_DIR=/your_cudnn_lib_dir

sh tools/build.sh

• OPENCV_DIR：OpenCV 编译安装地址；
• LIB_DIR：下载的 paddle_inference 目录或编译生成的 build/paddle_inference_install_dir 目录；
• CUDA_LIB_DIR：CUDA 库地址，Docker 中为 /usr/local/cuda/lib64；
• CUDNN_LIB_DIR：cuDNN 库地址，Docker 中为 /usr/lib/x86_64-linux-gnu/。

编译完成后，build 目录下生成可执行文件 ppocr。

3.5 运行 demo（9 种调用模式）

demo 支持系统串联调用，也支持单个功能调用。运行方式为 ./build/ppocr [--param1] [--param2] [...]。

注意：ppocr 默认使用 PP-OCRv3 模型，识别模型输入 shape 为 3,48,320；如需使用旧版本 PP-OCR 模型，需设置 --rec_img_h=32。

1. 检测 + 分类 + 识别：

./build/ppocr --det_model_dir=inference/det_db \
    --rec_model_dir=inference/rec_rcnn \
    --cls_model_dir=inference/cls \
    --image_dir=../../doc/imgs/12.jpg \
    --use_angle_cls=true \
    --det=true \
    --rec=true \
    --cls=true

2. 检测 + 识别（关闭方向分类）：

./build/ppocr --det_model_dir=inference/det_db \
    --rec_model_dir=inference/rec_rcnn \
    --image_dir=../../doc/imgs/12.jpg \
    --use_angle_cls=false \
    --det=true \
    --rec=true \
    --cls=false

3. 仅检测：

./build/ppocr --det_model_dir=inference/det_db \
    --image_dir=../../doc/imgs/12.jpg \
    --det=true \
    --rec=false

4. 分类 + 识别：

./build/ppocr --rec_model_dir=inference/rec_rcnn \
    --cls_model_dir=inference/cls \
    --image_dir=../../doc/imgs_words/ch/word_1.jpg \
    --use_angle_cls=true \
    --det=false \
    --rec=true \
    --cls=true

5. 仅识别：

./build/ppocr --rec_model_dir=inference/rec_rcnn \
    --image_dir=../../doc/imgs_words/ch/word_1.jpg \
    --use_angle_cls=false \
    --det=false \
    --rec=true \
    --cls=false

6. 仅分类：

./build/ppocr --cls_model_dir=inference/cls \
    --image_dir=../../doc/imgs_words/ch/word_1.jpg \
    --use_angle_cls=true \
    --det=false \
    --rec=false \
    --cls=true

7. 版面分析 + 表格识别（--type=structure）：

./build/ppocr --det_model_dir=inference/det_db \
    --rec_model_dir=inference/rec_rcnn \
    --table_model_dir=inference/table \
    --image_dir=../../ppstructure/docs/table/table.jpg \
    --layout_model_dir=inference/layout \
    --type=structure \
    --table=true \
    --layout=true

8. 仅版面分析：

./build/ppocr --layout_model_dir=inference/layout \
    --image_dir=../../ppstructure/docs/table/1.png \
    --type=structure \
    --table=false \
    --layout=true \
    --det=false \
    --rec=false

9. 仅表格识别：

./build/ppocr --det_model_dir=inference/det_db \
    --rec_model_dir=inference/rec_rcnn \
    --table_model_dir=inference/table \
    --image_dir=../../ppstructure/docs/table/table.jpg \
    --type=structure \
    --table=true

3.6 C++ 推理参数详解

通用参数：

参数名称	类型	默认参数	意义
use_gpu	bool	false	是否使用 GPU
gpu_id	int	0	GPU id，使用 GPU 时有效
gpu_mem	int	4000	申请的 GPU 内存（MB）
cpu_math_library_num_threads	int	10	CPU 预测线程数，核数充足时该值越大预测越快
enable_mkldnn	bool	true	是否使用 MKLDNN 库
output	str	./output	可视化结果保存路径

前向开关：

参数名称	类型	默认参数	意义
det	bool	true	前向是否执行文字检测
rec	bool	true	前向是否执行文字识别
cls	bool	false	前向是否执行文字方向分类

检测模型相关：

参数名称	类型	默认参数	意义
det_model_dir	string	-	检测模型 inference model 地址
max_side_len	int	960	输入图像长宽大于 960 时等比缩放，使最长边为 960
det_db_thresh	float	0.3	过滤 DB 预测二值化图像的阈值，0-0.3 对结果影响不明显
det_db_box_thresh	float	0.5	DB 后处理过滤 box 的阈值，漏框时可酌情减小
det_db_unclip_ratio	float	1.6	文本框紧致程度，越小文本框越靠近文本
det_db_score_mode	string	slow	slow 用多边形框计算 bbox score；fast 用矩形框，速度更快
visualize	bool	true	是否可视化，结果保存在 output 目录下与输入同名的图像上

方向分类器相关：

参数名称	类型	默认参数	意义
use_angle_cls	bool	false	是否使用方向分类器
cls_model_dir	string	-	方向分类器 inference model 地址
cls_thresh	float	0.9	方向分类器得分阈值
cls_batch_num	int	1	方向分类器 batchsize

文字识别模型相关：

参数名称	类型	默认参数	意义
rec_model_dir	string	-	文字识别模型 inference model 地址
rec_char_dict_path	string	../../ppocr/utils/ppocr_keys_v1.txt	字典文件
rec_batch_num	int	6	文字识别模型 batchsize
rec_img_h	int	48	文字识别模型输入图像高度（旧模型需 32）
rec_img_w	int	320	文字识别模型输入图像宽度

版面分析模型相关：

参数名称	类型	默认参数	意义
layout_model_dir	string	-	版面分析模型 inference model 地址
layout_dict_path	string	../../ppocr/utils/dict/layout_dict/layout_publaynet_dict.txt	字典文件
layout_score_threshold	float	0.5	检测框分数阈值
layout_nms_threshold	float	0.5	NMS 阈值

表格识别模型相关：

参数名称	类型	默认参数	意义
table_model_dir	string	-	表格识别模型 inference model 地址
table_char_dict_path	string	../../ppocr/utils/dict/table_structure_dict_ch.txt	字典文件
table_max_len	int	488	表格识别模型输入图像长边，网络输入为 (table_max_len, table_max_len)
merge_no_span_structure	bool	true	是否合并 <td> 和 </td> 为 <td></td>

多语言支持：PaddleOCR 支持多语言预测，更多语言与模型见多语言识别文档。多语言预测只需同时修改 rec_char_dict_path（字典文件路径）与 rec_model_dir（inference 模型路径）。

运行后屏幕会输出检测结果，例如 OCR 串联模式：

predict img: ../../doc/imgs/12.jpg
../../doc/imgs/12.jpg
0       det boxes: [[74,553],[427,542],[428,571],[75,582]] rec text: 打浦路252935号 rec score: 0.947724
1       det boxes: [[23,507],[513,488],[515,529],[24,548]] rec text: 绿洲仕格维花园公寓 rec score: 0.993728
...
The detection visualized image saved in ./output//12.jpg

structure 模式（版面分析 + 表格识别）则会输出每个区域的 type（text/title/table/figure 等）、region 坐标、置信度以及表格的 HTML 字符串，可视化结果保存为 ./output/ 下的同名图片。

3.7 C++ 部署 FAQ

遇到报错 unable to access 'https://github.com/LDOUBLEV/AutoLog.git/': gnutls_handshake() failed: The TLS connection was non-properly terminated. 时，将 deploy/cpp_infer/external-cmake/auto-log.cmake 中的 github 地址改为国内镜像地址即可。

四、基于 PaddleHub Serving 的服务化部署

服务化部署适合需要对外提供 HTTP API、支撑高并发调用的生产场景。PaddleOCR 提供两种服务部署方式：

• 基于 PaddleHub Serving：代码路径为 deploy/hubserving，按本节使用；
• 基于 PaddleServing：代码路径为 deploy/pdserving，使用方法参考 PaddleServing 部署文档。

4.1 服务包目录结构

deploy/hubserving 下共提供九种服务包：

deploy/hubserving/
  └─  ocr_cls     文本方向分类模块服务包
  └─  ocr_det     文本检测模块服务包
  └─  ocr_rec     文本识别模块服务包
  └─  ocr_system  文本检测+文本方向分类+文本识别串联服务包
  └─  structure_layout  版面分析服务包
  └─  structure_table  表格识别服务包
  └─  structure_system  PP-Structure服务包
  └─  kie_ser  关键信息抽取-SER服务包
  └─  kie_ser_re  关键信息抽取-SER+RE服务包

每个服务包包含 3~4 个文件（以 ocr_system 为例，见 deploy/hubserving/ocr_system）：

deploy/hubserving/ocr_system/
  └─  __init__.py    空文件，必选
  └─  config.json    配置文件，可选，使用配置启动服务时作为参数传入
  └─  module.py      主模块，必选，包含服务的完整逻辑
  └─  params.py      参数文件，必选，包含模型路径、前后处理参数等参数

功能更新历史：2022.10.09 新增关键信息抽取服务；2022.08.23 新增版面分析服务；2022.05.05 新增 PP-OCRv3 检测和识别模型；2022.03.30 新增 PP-Structure 和表格识别两种服务。

4.2 快速启动服务（以检测+识别串联为例）

1. 安装 PaddleHub（需要 python > 3.6.2）：

pip3 install paddlehub==2.1.0 --upgrade -i https://mirror.baidu.com/pypi/simple

2. 下载推理模型。默认使用 PP-OCRv3 模型，默认模型路径如下（可在 params.py 中查看和修改）：

模型	路径
检测模型	./inference/PP-OCRv3_mobile_det_infer/
识别模型	./inference/PP-OCRv3_mobile_rec_infer/
方向分类器	./inference/ch_ppocr_mobile_v2.0_cls_infer/
版面分析模型	./inference/picodet_lcnet_x1_0_fgd_layout_infer/
表格结构识别模型	./inference/ch_ppstructure_mobile_v2.0_SLANet_infer/
关键信息抽取SER模型	./inference/ser_vi_layoutxlm_xfund_infer/
关键信息抽取RE模型	./inference/re_vi_layoutxlm_xfund_infer/

更多模型可从 PP-OCR 模型库与 PP-Structure 模型库 下载，也可替换为自己训练转换好的模型。

3. 安装服务模块（Linux 环境；Windows 请将 / 替换为 \）：

服务模块	命令
检测	hub install deploy/hubserving/ocr_det
分类	hub install deploy/hubserving/ocr_cls
识别	hub install deploy/hubserving/ocr_rec
检测+识别串联	hub install deploy/hubserving/ocr_system
表格识别	hub install deploy/hubserving/structure_table
PP-Structure	hub install deploy/hubserving/structure_system
版面分析	hub install deploy/hubserving/structure_layout
关键信息抽取SER	hub install deploy/hubserving/kie_ser
关键信息抽取SER+RE	hub install deploy/hubserving/kie_ser_re

4. 启动服务，两种方式：

• 命令行启动（仅支持 CPU）：

hub serving start --modules Module1==Version1, Module2==Version2, ... \
                  --port 8866 \
                  --use_multiprocess \
                  --workers

参数	用途
--modules/-m	以 Module==Version 键值对列出服务模块；不指定 Version 时默认选最新版本
--port/-p	服务端口，默认 8866
--use_multiprocess	是否启用并发方式（默认单进程），多核 CPU 机器推荐使用；Windows 只支持单进程
--workers	并发方式下的并发任务数，默认 2*cpu_count-1

例如启动串联服务：

hub serving start -m ocr_system

• 配置文件启动（支持 CPU、GPU）：

hub serving start -c config.json

config.json 格式（示例见 deploy/hubserving/ocr_system/config.json）：

{
    "modules_info": {
        "ocr_system": {
            "init_args": {
                "version": "1.0.0",
                "use_gpu": true
            },
            "predict_args": {
            }
        }
    },
    "port": 8868,
    "use_multiprocess": false,
    "workers": 2
}

要点：

• init_args 中的可配参数与 module.py 中 _initialize 函数接口一致，use_gpu=true 表示 GPU 启动；
• predict_args 中的可配参数与 module.py 中 predict 函数接口一致；
• 使用配置文件启动时，其他参数会被忽略；
• GPU 预测需先设置环境变量，如 export CUDA_VISIBLE_DEVICES=0；
• use_gpu 不可与 use_multiprocess 同时为 true。

例如使用 GPU 3 号卡启动串联服务：

export CUDA_VISIBLE_DEVICES=3
hub serving start -c deploy/hubserving/ocr_system/config.json

4.3 发送预测请求

使用仓库自带的测试脚本（tools/test_hubserving.py）：

python tools/test_hubserving.py --server_url=server_url --image_dir=image_path

• server_url：服务地址，格式为 http://[ip_address]:[port]/predict/[module_name]。例如各模块 URL 示例：http://127.0.0.1:8865/predict/ocr_det、http://127.0.0.1:8866/predict/ocr_cls、http://127.0.0.1:8867/predict/ocr_rec、http://127.0.0.1:8868/predict/ocr_system、http://127.0.0.1:8869/predict/structure_table、http://127.0.0.1:8870/predict/structure_system（以及 structure_layout）、http://127.0.0.1:8871/predict/kie_ser、http://127.0.0.1:8872/predict/kie_ser_re；
• image_dir：测试图像路径，可为单张图片或图像集合目录；
• visualize：是否可视化结果，默认 False；
• output：可视化结果保存路径，默认 ./hubserving_result。

访问示例：

python tools/test_hubserving.py --server_url=http://127.0.0.1:8868/predict/ocr_system --image_dir=./doc/imgs/ --visualize=false

4.4 返回结果格式说明

返回结果为列表（list），每一项为词典（dict），可能包含以下字段：

字段名称	数据类型	意义
angle	str	文本角度
text	str	文本内容
confidence	float	文本识别置信度或文本角度分类置信度
text_region	list	文本位置坐标
html	str	表格的 html 字符串
regions	list	版面分析+表格识别+OCR 的结果，每项含区域坐标 bbox、区域类型 type、区域结果 res
layout	list	版面分析结果，每项含区域坐标 bbox、区域类型 label

不同模块返回字段不同（✔ 表示该模块返回该字段）：

字段名/模块名	ocr_det	ocr_cls	ocr_rec	ocr_system	structure_table	structure_system	structure_layout	kie_ser	kie_re
angle		✔		✔
text			✔	✔		✔		✔	✔
confidence		✔	✔	✔		✔		✔	✔
text_region	✔			✔		✔		✔	✔
html					✔	✔
regions					✔	✔
layout							✔
ser_res								✔
re_res									✔

如需增删改返回字段，可在对应模块的 module.py 中修改（完整流程见下节）。

4.5 自定义修改服务模块

以修改 deploy/hubserving/ocr_system 为例：

1. 停止服务：hub serving stop --port/-p XXXX；
2. 修改 module.py 和 params.py。例如替换部署模型时，在 params.py 中修改 det_model_dir 和 rec_model_dir；关闭文本方向分类器则将 use_angle_cls 置为 False。强烈建议修改后先直接运行 module.py 调试，能正确运行预测后再启动服务；
3. 注意：PP-OCRv3 识别模型输入 shape 为 3,48,320，需要修改 params.py 中 cfg.rec_image_shape = "3, 48, 320"；不使用 PP-OCRv3 识别模型则无需修改；
4. （可选）重命名模块需要同步修改 deploy/hubserving/ocr_system/module.py 中的 import 语句与 name="ocr_system" 字段；
5. （可选）删除 __pycache__ 目录以强制刷新 CPython 缓存：find deploy/hubserving/ocr_system -name '__pycache__' -exec rm -r {} \;；
6. 安装修改后的新服务包：hub install deploy/hubserving/ocr_system；
7. 重新启动服务：hub serving start -m ocr_system。

五、Paddle-Lite 端侧部署（移动端/边缘端）

Paddle Lite 是飞桨轻量化推理引擎，为手机、IoT 端提供高效推理能力，并广泛整合跨平台硬件。本节基于 docs/version2.x/legacy/lite.md 与 deploy/lite 目录，介绍在安卓手机上部署超轻量中文检测、识别模型的完整流程。

5.1 准备环境与预测库

运行准备：一台电脑（用于编译 Paddle Lite）与一台安卓手机（armv7 或 armv8）。交叉编译环境支持 Docker/Linux/Mac OS 等多种开发环境。

预测库两种获取方式：

1. 直接下载（推荐）：Android 平台 inference_lite_lib.android.armv7.gcc.c++_shared.with_extra.with_cv.tar.gz（arm7）/ inference_lite_lib.android.armv8.gcc.c++_shared.with_extra.with_cv.tar.gz（arm8），建议使用 paddlelite ≥ 2.10 版本的预测库；
2. 源码编译：

git clone https://github.com/PaddlePaddle/Paddle-Lite.git
cd Paddle-Lite
git checkout release/v2.10
./lite/tools/build_android.sh  --arch=armv8  --with_cv=ON --with_extra=ON

注意编译时需要打开 --with_cv=ON --with_extra=ON，--arch 指定 arm 版本（此处为 armv8）。

解压后的预测库目录结构：

inference_lite_lib.android.armv8/
|-- cxx                                        C++ 预测库和头文件
|   |-- include                                C++ 头文件（paddle_api.h 等）
|   `-- lib                                    C++预测库
|       |-- libpaddle_api_light_bundled.a      C++静态库
|       `-- libpaddle_light_api_shared.so      C++动态库
|-- java                                       Java预测库（PaddlePredictor.jar、libpaddle_lite_jni.so 等）
|-- demo                                       C++和Java示例代码

5.2 模型优化（inference 模型转 .nb）

Paddle-Lite 通过 opt 工具自动对 inference 模型进行量化、子图融合、混合调度、Kernel 优选等优化，优化后的模型更轻量、运行更快。如果已有 .nb 结尾的模型可跳过此步。仓库同时提供一系列可直接下载的中文移动端模型（PP-OCRv3 蒸馏版超轻量模型约 16.2M，slim 量化版约 5.9M），包含检测、方向分类、识别三个 .nb 文件。

如需自行转换，步骤如下：

步骤 1：安装与预测库版本一致的 paddlelite（例如 2.10）：

pip install paddlelite==2.10
paddle_lite_opt   # 查看帮助

paddle_lite_opt 主要参数：

选项	说明
--model_dir	待优化的 PaddlePaddle 模型（非 combined 形式）路径
--model_file	combined 形式的网络结构文件路径
--param_file	combined 形式的权重文件路径
--optimize_out_type	输出模型类型：protobuf 或 naive_buffer；移动端预测应设为 naive_buffer（更轻量的序列化实现），默认 protobuf
--optimize_out	优化模型的输出路径
--valid_targets	可执行 backend，默认为 arm；可同时指定多个（x86、arm、opencl、npu、xpu），华为 NPU 应设置为 npu, arm
--record_tailoring_info	使用模型裁剪库文件功能时设为 true，记录 kernel 和 OP 信息，默认 false

PaddleOCR 的 inference 模型为 combined 方式（结构与参数分别单独存储），因此使用 --model_file / --param_file 参数。

步骤 2：转换模型：

# 下载 PP-OCRv3 版本的中英文 inference 模型
wget https://paddleocr.bj.bcebos.com/PP-OCRv3/chinese/ch_PP-OCRv3_det_slim_infer.tar && tar xf ch_PP-OCRv3_det_slim_infer.tar
wget https://paddleocr.bj.bcebos.com/PP-OCRv3/chinese/ch_PP-OCRv3_rec_slim_infer.tar && tar xf ch_PP-OCRv2_rec_slim_quant_infer.tar
wget https://paddleocr.bj.bcebos.com/dygraph_v2.0/slim/ch_ppocr_mobile_v2.0_cls_slim_infer.tar && tar xf ch_ppocr_mobile_v2.0_cls_slim_infer.tar
# 转换检测模型
paddle_lite_opt --model_file=./ch_PP-OCRv3_det_slim_infer/inference.pdmodel  --param_file=./ch_PP-OCRv3_det_slim_infer/inference.pdiparams  --optimize_out=./ch_PP-OCRv3_det_slim_opt --valid_targets=arm  --optimize_out_type=naive_buffer
# 转换识别模型
paddle_lite_opt --model_file=./ch_PP-OCRv3_rec_slim_infer/inference.pdmodel  --param_file=./ch_PP-OCRv3_rec_slim_infer/inference.pdiparams  --optimize_out=./ch_PP-OCRv3_rec_slim_opt --valid_targets=arm  --optimize_out_type=naive_buffer
# 转换方向分类器模型
paddle_lite_opt --model_file=./ch_ppocr_mobile_v2.0_cls_slim_infer/inference.pdmodel  --param_file=./ch_ppocr_mobile_v2.0_cls_slim_infer/inference.pdiparams  --optimize_out=./ch_ppocr_mobile_v2.0_cls_slim_opt --valid_targets=arm  --optimize_out_type=naive_buffer

转换成功后，inference 模型目录下会多出 .nb 结尾的文件。

5.3 与手机联调

准备工作：arm8 安卓手机（若预测库/opt 文件为 armv7 则需 arm7 手机并修改 Makefile 中 ARM_ABI = arm7）；打开手机 USB 调试并选择文件传输模式；电脑安装 adb（Mac：brew cask install android-platform-tools；Linux：sudo apt install -y wget adb）；用 adb devices 确认设备连接（出现 device 即成功）。

准备优化后的模型、预测库、测试图像与字典文件：

git clone https://github.com/PaddlePaddle/PaddleOCR.git
cd PaddleOCR/deploy/lite/
# 运行prepare.sh，准备预测库文件、测试图像和使用的字典文件
sh prepare.sh /{lite prediction library path}/inference_lite_lib.android.armv8

cd /{lite prediction library path}/inference_lite_lib.android.armv8/
cd demo/cxx/ocr/
# 将C++预测动态库so文件复制到debug文件夹中
cp ../../../cxx/lib/libpaddle_light_api_shared.so ./debug/

将测试图像（如 doc/imgs/11.jpg）与 opt 优化后的 .nb 模型文件复制到 demo/cxx/ocr/debug/。完成后 demo/cxx/ocr/ 目录结构如下：

demo/cxx/ocr/
|-- debug/
|   |--ch_PP-OCRv3_det_slim_opt.nb           优化后的检测模型文件
|   |--ch_PP-OCRv3_rec_slim_opt.nb           优化后的识别模型文件
|   |--ch_ppocr_mobile_v2.0_cls_slim_opt.nb  优化后的文字方向分类器模型文件
|   |--11.jpg                                待测试图像
|   |--ppocr_keys_v1.txt                     中文字典文件
|   |--libpaddle_light_api_shared.so         C++预测库文件
|   |--config.txt                            超参数配置
|-- config.txt                   超参数配置
|-- cls_process.cc               方向分类器的预处理和后处理文件
|-- cls_process.h
|-- crnn_process.cc              识别模型CRNN的预处理和后处理文件
|-- crnn_process.h
|-- db_post_process.cc           检测模型DB的后处理文件
|-- db_post_process.h
|-- Makefile                     编译文件
|-- ocr_db_crnn.cc               C++预测源文件

注意：

1. ppocr_keys_v1.txt 是中文字典；若使用英文/数字或其他语言模型，需更换为对应语言字典（如 dict/french_dict.txt、dict/german_dict.txt、ic15_dict.txt、dict/japan_dict.txt、dict/korean_dict.txt 等）；
2. deploy/lite/config.txt 包含检测器、分类器、识别器超参数：

max_side_len  960         # 输入图像长宽大于960时，等比例缩放图像，使得图像最长边为960
det_db_thresh  0.3        # 用于过滤DB预测的二值化图像，设置为0-0.3对结果影响不明显
det_db_box_thresh  0.5    # 检测器后处理过滤box的阈值，漏框时可酌情减小
det_db_unclip_ratio  1.6  # 表示文本框的紧致程度，越小则文本框更靠近文本
use_direction_classify  0  # 是否使用方向分类器，0表示不使用，1表示使用
rec_image_height  48      # 识别模型输入图像的高度，PP-OCRv3模型设置为48，PP-OCRv2模型需要设置为32

3. 编译并 push 到手机运行：

# 执行编译，得到可执行文件ocr_db_crnn；第一次执行会下载opencv等依赖库，下载完成后需再执行一次
make -j
mv ocr_db_crnn ./debug/
adb push debug /data/local/tmp/
adb shell
cd /data/local/tmp/debug
export LD_LIBRARY_PATH=${PWD}:$LD_LIBRARY_PATH
# 用法：./ocr_db_crnn 预测模式 检测模型 方向分类器模型 识别模型 运行硬件 运行精度 线程数 batchsize 测试图像路径 参数配置路径 字典文件路径 是否使用benchmark参数
./ocr_db_crnn system  ch_PP-OCRv3_det_slim_opt.nb  ch_PP-OCRv3_rec_slim_opt.nb  ch_ppocr_mobile_v2.0_cls_slim_opt.nb  arm8 INT8 10 1  ./11.jpg  config.txt  ppocr_keys_v1.txt  True

# 仅使用文本检测模型
./ocr_db_crnn det ch_PP-OCRv3_det_slim_opt.nb arm8 INT8 10 1 ./11.jpg config.txt

# 仅使用文本识别模型
./ocr_db_crnn rec ch_PP-OCRv3_rec_slim_opt.nb arm8 INT8 10 1 word_1.jpg ppocr_keys_v1.txt config.txt

如果修改了代码，需重新编译并 push 到手机。

5.4 Lite 部署 FAQ

• Q1：如何更换模型？ 已走通流程后，只需替换 .nb 模型文件并同步更新字典；
• Q2：如何换图测试？ 替换 debug 下的 .jpg 测试图像并重新 adb push 到手机；
• Q3：如何封装到手机 APP？ 本 demo 提供核心算法部分，deploy/android_demo 是将该 demo 封装到手机 App 的示例；
• Q4：报错 Error: This model is not supported, because kernel for 'io_copy' is not supported by Paddle-Lite.？ 原因是 paddlelite 版本与预测库版本不匹配，确保 paddle_lite_opt 工具与预测库版本一致后重新转 nb 模型。

六、Paddle2ONNX 跨框架模型转换与预测

当目标运行环境属于第三方推理框架或长尾硬件时，可通过 Paddle2ONNX 将 Paddle 模型转为 ONNX 格式，再基于 ONNXRuntime 推理。本节基于 docs/version2.x/legacy/paddle2onnx.md。

6.1 环境准备

需要准备三部分环境：PaddleOCR（克隆仓库并安装，git clone -b main ... && cd PaddleOCR && python3 -m pip install -e .）、Paddle2ONNX、ONNXRuntime：

python3 -m pip install paddle2onnx
python3 -m pip install onnxruntime

Paddle2ONNX 支持将 PaddlePaddle 模型格式转化到 ONNX 模型格式，算子稳定支持导出 ONNX Opset 7~19，部分 Paddle 算子支持更低 Opset 转换。

6.2 模型转换

获取 Paddle 静态图模型：可从模型列表下载预测模型，或按模型导出说明把训练权重转为推理模型。以 PP-OCRv3 中文检测/识别/分类模型为例：

wget -nc -P ./inference https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_det_infer.tar
cd ./inference && tar xf PP-OCRv3_mobile_det_infer.tar && cd ..

wget -nc -P ./inference https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_rec_infer.tar
cd ./inference && tar xf PP-OCRv3_mobile_rec_infer.tar && cd ..

wget -nc -P ./inference https://paddleocr.bj.bcebos.com/dygraph_v2.0/ch/ch_ppocr_mobile_v2.0_cls_infer.tar
cd ./inference && tar xf ch_ppocr_mobile_v2.0_cls_infer.tar && cd ..

（也可下载 PP-OCRv4 对应模型包。）如需自己导出，使用 tools/export_model.py，例如：

python3 tools/export_model.py -c configs/det/PP-OCRv4/PP-OCRv4_mobile_det.yml \
-o Global.pretrained_model=./pretrained/PP-OCRv4_mobile_det_pretrained \
Global.save_inference_dir=./inference/PP-OCRv4_mobile_det_infer/

使用 Paddle2ONNX 转换：

paddle2onnx --model_dir ./inference/PP-OCRv3_mobile_det_infer \
--model_filename inference.pdmodel \
--params_filename inference.pdiparams \
--save_file ./inference/det_onnx/model.onnx \
--opset_version 11 \
--enable_onnx_checker True

paddle2onnx --model_dir ./inference/PP-OCRv3_mobile_rec_infer \
--model_filename inference.pdmodel \
--params_filename inference.pdiparams \
--save_file ./inference/rec_onnx/model.onnx \
--opset_version 11 \
--enable_onnx_checker True

paddle2onnx --model_dir ./inference/ch_ppocr_mobile_v2.0_cls_infer \
--model_filename inference.pdmodel \
--params_filename inference.pdiparams \
--save_file ./inference/cls_onnx/model.onnx \
--opset_version 11 \
--enable_onnx_checker True

执行完毕后，ONNX 模型分别保存在 ./inference/det_onnx/、./inference/rec_onnx/、./inference/cls_onnx/ 路径下。

注意事项：

• 对 OCR 模型，转换必须采用动态 shape，否则预测结果可能与 Paddle 预测有细微不同；
• 以下模型暂不支持转换为 ONNX：NRTR、SAR、RARE、SRN；
• Paddle2ONNX v1.2.3 之后已默认支持动态 shape（float32[p2o.DynamicDimension.0,3,p2o.DynamicDimension.1,p2o.DynamicDimension.2]），--input_shape_dict 选项已废弃；如需调整 shape 可使用 python3 -m paddle2onnx.optimize --input_model model.onnx --output_model model.onnx --input_shape_dict "{'x': [-1,3,-1,-1]}"；
• 如需进一步优化 ONNX 模型，可使用 onnxslim：pip install onnxslim && onnxslim model.onnx slim.onnx。

6.3 推理预测

使用 ONNXRuntime 预测（--use_onnx=True）：

python3 tools/infer/predict_system.py --use_gpu=False --use_onnx=True \
--det_model_dir=./inference/det_onnx/model.onnx  \
--rec_model_dir=./inference/rec_onnx/model.onnx  \
--cls_model_dir=./inference/cls_onnx/model.onnx  \
--image_dir=./docs/infer_deploy/images/lite_demo.png

使用 Paddle Inference 预测（对照实验）：

python3 tools/infer/predict_system.py --use_gpu=False \
--cls_model_dir=./inference/ch_ppocr_mobile_v2.0_cls_infer \
--rec_model_dir=./inference/PP-OCRv3_mobile_rec_infer \
--det_model_dir=./inference/PP-OCRv3_mobile_det_infer \
--image_dir=./docs/infer_deploy/images/lite_demo.png

执行后终端打印识别信息，并在 ./inference_results/ 下保存可视化结果。两套引擎终端输出的识别内容一致，可据此验证转换前后结果一致性。

七、部署方案选型小结

场景	推荐方案	关键入口
快速验证 / 科研调试 / 单机脚本	Python 推理	ppstructure/predict_system.py
服务器端高性能（CPU/GPU）	C++ 推理	deploy/cpp_infer
对外提供 HTTP API、高并发生产	Serving 服务化	deploy/hubserving
手机 / IoT / 边缘端	Paddle-Lite	deploy/lite
第三方框架 / 国产长尾硬件	Paddle2ONNX	tools/infer/predict_system.py

各方案共享同一套 PP-OCR 推理模型格式（inference.pdmodel + inference.pdiparams），因此从训练导出推理模型后，可依据上表在不同部署形态间平滑迁移。更多模型获取与替换方式，可参考 PP-OCR 模型库与 PP-Structure 模型库。