PaddleOCR 高性能推理（HPI）实战指南：一键开启多后端推理加速-迪斯科星球

PaddleOCR 高性能推理（HPI）实战指南：一键开启多后端推理加速

【免费下载链接】PaddleOCR飞桨多语言OCR工具包（实用超轻量OCR系统，支持80+种语言识别，提供数据标注与合成工具，支持服务器、移动端、嵌入式及IoT设备端的训练与部署） Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80+ languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR

导读：在生产环境中，OCR 服务的响应速度往往直接决定系统体验与业务吞吐。PaddleOCR 提供了开箱即用的高性能推理（High Performance Inference, HPI）能力：用户无需手动配置底层推理细节，即可让模型自动匹配最优推理后端（如 Paddle Inference、OpenVINO、ONNX Runtime、TensorRT），并叠加线程、FP16 精度等加速策略。本文以官方高性能推理文档为主体，结合仓库源码，完整介绍 HPI 的依赖安装、GPU 环境准备、CLI 与 Python API 两种启用方式，以及引擎缓存、ONNX 转换等实战要点，帮助你在自己的环境中快速落地加速方案。

1. 高性能推理能做什么

在实际生产环境中，许多应用对部署策略的性能指标（尤其是响应速度）有着较严苛的标准，以确保系统的高效运行与用户体验的流畅性。PaddleOCR 提供高性能推理能力，让用户无需关注复杂的配置和底层细节，一键提升模型的推理速度。具体而言，PaddleOCR 的高性能推理功能能够：

自动选择推理后端：结合先验知识自动选择合适的推理后端（Paddle Inference、OpenVINO、ONNX Runtime、TensorRT 等），并配置加速策略（如增大推理线程数、设置 FP16 精度推理）；
自动完成模型格式转换：根据需要自动将飞桨静态图模型转换为 ONNX 格式，以使用更优的推理后端实现加速；
直接使用 ONNX 模型：支持加载用户准备好的 ONNX 模型完成推理。

从源码层面看，该能力并非从零实现，而是深度依托于 PaddleX。PaddleOCR 在推理部署环节复用 PaddleX 的底层能力：高性能推理通过 PaddleX 的 Paddle2ONNX 插件及高性能推理插件实现，相关说明可参见 PaddleOCR 与 PaddleX 的区别与联系。同时，得益于 PaddleX 的可选依赖安装机制，安装paddleocr分发包时只会安装 OCR 类任务所需依赖，不会因高性能推理引入过大的体积膨胀。

2. 前置条件：飞桨框架与高性能推理依赖

2.1 安装高性能推理依赖

高性能推理功能依赖于飞桨框架，因此在执行后续步骤前，需要确保环境中已经安装飞桨框架。

通过 PaddleOCR CLI 安装高性能推理所需依赖：

paddleocr install_hpi_deps {设备类型}

从 CLI 命令注册与实现可以看出，该命令内部实际上执行了两步操作：

调用paddlex --install hpi-{设备类型}安装对应设备类型的高性能推理插件；
调用paddlex --install paddle2onnx安装 Paddle2ONNX 插件，用于后续的模型格式转换。

当前支持的设备类型包括：

cpu：仅使用 CPU 推理。目前支持 Linux 系统、x86-64 架构处理器、Python 3.8-3.12。
gpu：使用 CPU 或 NVIDIA GPU 推理。目前支持 Linux 系统、x86-64 架构处理器、Python 3.8-3.12。如果希望使用完整的高性能推理功能，还需要确保环境中安装有符合要求的 TensorRT（见 2.3 小节详细说明）。

从仓库源码看，该子命令还同时支持npu设备类型选项（见 paddleocr/_cli.py 中的choices=["cpu", "gpu", "npu"]），具体可用性以对应设备的官方支持情况为准。

注意：同一环境中只应该存在一种设备类型的依赖。对于 Windows 系统，目前建议在 Docker 容器或者 WSL 环境中安装。

2.2 推荐使用 PaddleX 官方 Docker 镜像

推荐使用 PaddleX 官方 Docker 镜像安装高性能推理依赖。各设备类型对应的镜像如下：

cpu：ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlex/paddlex:paddlex3.0.1-paddlepaddle3.0.0-cpu
gpu（CUDA 11.8）：ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlex/paddlex:paddlex3.0.1-paddlepaddle3.0.0-gpu-cuda11.8-cudnn8.9-trt8.6
gpu（CUDA 12.6）：ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlex/paddlex:paddlex3.0.1-paddlepaddle3.0.0-gpu-cuda12.6-cudnn9.5-trt10.5

注意：目前 CUDA 12.6 + cuDNN 9.5 的高性能推理仅支持 OpenVINO 和 ONNX Runtime 后端，暂不支持 TensorRT 后端。需要 TensorRT 加速时请选择 CUDA 11.8 对应的镜像。

2.3 GPU 环境详细说明

首先，需要确保环境中安装有符合要求的 CUDA 与 cuDNN。目前 PaddleOCR 支持与以下组合兼容的 CUDA 和 cuDNN 版本：

CUDA 11.8 + cuDNN 8.9
CUDA 12.6 + cuDNN 9.5

如果使用飞桨官方镜像，镜像中的 CUDA 和 cuDNN 版本已满足要求，无需额外安装。

如果通过 pip 安装飞桨，通常 CUDA、cuDNN 的相关 Python 包会被自动安装。在这种情况下，仍需通过安装非 Python 专用的 CUDA 与 cuDNN（即系统级安装）。同时，建议安装的 CUDA 和 cuDNN 版本与环境中存在的 Python 包版本保持一致，以避免不同版本的库共存导致的潜在问题。可以通过如下方式查看 CUDA 和 cuDNN 相关 Python 包的版本：

# CUDA 相关 Python 包版本 pip list | grep nvidia-cuda # cuDNN 相关 Python 包版本 pip list | grep nvidia-cudnn

其次，建议确保环境中安装有符合要求的 TensorRT，否则 Paddle Inference TensorRT 子图引擎将不可用，程序可能无法取得最佳推理性能。目前 PaddleOCR 仅支持在 CUDA 11.8 环境使用 TensorRT 8.6.1.6。如果使用飞桨官方 3.0 镜像，可执行如下命令安装 TensorRT wheel 包：

python -m pip install /usr/local/TensorRT-*/python/tensorrt-*-cp310-none-linux_x86_64.whl

对于其他环境，请参考 TensorRT 官方文档安装对应版本的 TensorRT，示例如下：

# 下载 TensorRT tar 文件 wget https://developer.nvidia.com/downloads/compute/machine-learning/tensorrt/secure/8.6.1/tars/TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-11.8.tar.gz # 解压 TensorRT tar 文件 tar xvf TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-11.8.tar.gz # 安装 TensorRT wheel 包 python -m pip install TensorRT-8.6.1.6/python/tensorrt-8.6.1-cp310-none-linux_x86_64.whl # 添加 TensorRT 的 `lib` 目录的绝对路径到 LD_LIBRARY_PATH 中 export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:TensorRT-8.6.1.6/lib"

3. 执行高性能推理

3.1 CLI 方式：一条命令开启加速

对于 PaddleOCR CLI，指定--enable_hpi为True即可执行高性能推理。例如：

paddleocr ocr --enable_hpi True ...

从公共 CLI 参数定义可以看到，--enable_hpi接受布尔值（通过str2bool解析），默认值由各模块的_DEFAULT_ENABLE_HPI决定。在 CLI 调用过程中，该开关会与以下配套参数一起被解析并下发给底层 PaddleX 预测器：

参数	默认值	说明
`--device`	自动选择（默认 GPU 0，不可用则 CPU）	推理设备，如`cpu`、`gpu`、`gpu:0`
`--enable_hpi`	模块默认值	是否启用高性能推理
`--use_tensorrt`	`False`	是否使用 Paddle Inference TensorRT 子图引擎
`--precision`	`fp32`	使用 TensorRT 子图引擎时的推理精度，支持`fp32`/`fp16`
`--enable_mkldnn`	`True`	是否启用 MKL-DNN 加速（CPU 场景）
`--mkldnn_cache_capacity`	`10`	MKL-DNN 缓存容量
`--cpu_threads`	`10`	CPU 推理线程数
`--enable_cinn`	`False`	是否使用 CINN 编译器

上述默认值定义在 paddleocr/_constants.py 中。从引擎配置构建逻辑可以看到，当设备为 GPU 且启用 TensorRT 时，会根据precision自动映射trt_fp32或trt_fp16运行模式；当设备为 CPU 时，则会应用cpu_threads、mkldnn_cache_capacity等配置——这正是 HPI "自动配置加速策略"的底层实现。

3.2 Python API 方式：初始化即开启

对于 PaddleOCR Python API，在初始化产线对象或者模块对象时，设置enable_hpi为True即可在调用推理方法时执行高性能推理。例如：

from paddleocr import PaddleOCR pipeline = PaddleOCR(enable_hpi=True) result = pipeline.predict(...)

3.3 从源码看 enable_hpi 的传递链路

理解参数流转有助于排查问题。从源码看，enable_hpi的传递路径如下：

公共参数解析：parse_common_args将enable_hpi等参数合并进默认值字典，并校验engine、precision的合法性；
初始化参数准备：prepare_common_init_args将enable_hpi转换为 PaddleX 预测器认识的use_hpip字段，同时根据设备类型构建paddle_static引擎配置（TensorRT / MKL-DNN / CINN 等）；
预测器创建：PaddleXPredictorWrapper基类调用 PaddleX 的create_predictor完成预测器构建，最终由 PaddleX 高性能推理插件接管推理加速。

简而言之：enable_hpi=True→use_hpip=True→ PaddleX 高性能推理插件加载并执行加速推理。

4. 使用说明与注意事项

首次构建耗时与缓存复用：对于部分模型，在首次执行高性能推理时，可能需要花费较长时间完成推理引擎的构建。推理引擎相关信息将在第一次构建完成后被缓存在模型目录，后续可复用缓存中的内容以提升初始化速度。
部分模型无法加速：目前，由于使用的不是静态图格式模型、存在不支持算子等原因，部分模型可能无法获得推理加速。
模型格式自动转换：在进行高性能推理时，PaddleOCR 会自动处理模型格式的转换，并尽可能选择最优的推理后端。同时，PaddleOCR 也支持用户指定 ONNX 模型。

4.1 手动获取 ONNX 模型

如需手动完成飞桨静态图模型到 ONNX 格式的转换，可参考获取 ONNX 模型。转换前先安装 Paddle2ONNX 插件：

paddlex --install paddle2onnx

然后执行如下命令完成模型转换：

paddlex \ --paddle2onnx \ # 使用 paddle2onnx 功能 --paddle_model_dir /your/paddle_model/dir \ # 指定 Paddle 模型所在的目录 --onnx_model_dir /your/onnx_model/output/dir \ # 指定转换后 ONNX 模型的输出目录 --opset_version 7 # 指定要使用的 ONNX opset 版本

参数说明如下：

参数	类型	描述
`paddle_model_dir`	str	包含 Paddle 模型的目录。
`onnx_model_dir`	str	ONNX 模型的输出目录，可以与 Paddle 模型目录相同。默认为`onnx`。
`opset_version`	int	使用的 ONNX opset 版本。当使用低版本 opset 无法完成转换时，将自动选择更高版本的 opset 进行转换。默认为`7`。

注意：上述手动转换操作与 HPI 内部的自动转换是两条可选的路径——日常使用中你无需手动转换，HPI 会自动完成；手动转换适用于需要固定 ONNX 产物（如后续接入其他推理框架或指定 ONNX 模型推理）的场景。

4.2 通过 PaddleX 产线配置文件精细调优

PaddleOCR 的高性能推理能力依托于 PaddleX 及其高性能推理插件。通过传入自定义 PaddleX 产线配置文件，可以对推理后端等进行配置。相关细节可参考以下两份资料：

PaddleOCR 与 PaddleX 的区别与联系：了解 PaddleOCR 与 PaddleX 的协作关系、版本对应关系（例如 PaddleOCR3.0.x对应 PaddleX3.0.x及飞桨>= 3.0.0，各版本对应关系以文档中的表格为准）以及安装时的依赖控制；
PaddleX 高性能推理指南：了解如何调整高性能推理配置（如指定推理后端、线程数、精度等）。

5. 小结

PaddleOCR 高性能推理的核心价值在于"免配置、自动加速"：通过paddleocr install_hpi_deps一键补齐依赖，通过--enable_hpi True（CLI）或enable_hpi=True（Python API）一键启用，底层由 PaddleX 高性能推理插件自动完成后端选择、模型格式转换与加速策略配置。结合仓库源码可以看到，enable_hpi最终以use_hpip字段传递给 PaddleX 预测器，并与 TensorRT 精度、CPU 线程数、MKL-DNN 等配置协同生效。部署时需重点关注两点：一是同一环境只保留一种设备类型的依赖；二是 CUDA 12.6 环境暂不支持 TensorRT 后端，需要 TensorRT 加速时应选用 CUDA 11.8 + TensorRT 8.6.1.6 的组合。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析