PaddleOCR 高性能推理（HPI）部署指南：依赖安装、GPU 环境配置与 CLI/Python API 实战

PaddleOCR 高性能推理（HPI）部署指南：依赖安装、GPU 环境配置与 CLI/Python API 实战

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR

在生产环境中，OCR 服务对响应速度往往有严苛要求。PaddleOCR 提供的高性能推理（High Performance Inference，HPI）能力，可以让用户无需关心复杂的底层配置，一键完成推理加速：系统会自动结合先验知识选择合适的推理后端（Paddle Inference、OpenVINO、ONNX Runtime、TensorRT 等），自动配置线程数、FP16 精度等加速策略，必要时还会自动将飞桨静态图模型转换为 ONNX 格式以启用更优后端。读完本文，你将掌握 HPI 依赖的完整安装方法（CPU/GPU、Docker 镜像、TensorRT 选型）、PaddleOCR CLI 与 Python API 两条使用路径，以及引擎缓存、模型限制、ONNX 模型获取与 PaddleX 产线配置等关键注意事项。

1. 高性能推理功能概览

PaddleOCR 的高性能推理功能建立在 PaddleX 及其高性能推理插件之上，核心能力可归纳为三点：

• 推理后端自动选择：结合模型与硬件先验知识，自动从 Paddle Inference、OpenVINO、ONNX Runtime、TensorRT 等后端中挑选合适的实现，并自动应用加速策略，例如增大推理线程数、开启 FP16 精度推理；
• 模型格式自动转换：在需要时自动将飞桨静态图模型转换为 ONNX 格式，以便接入更优的推理后端实现加速；
• ONNX 模型推理：支持直接使用 ONNX 模型完成推理，用户也可以自行指定 ONNX 模型。

从源码实现看，HPI 的开关贯穿模型与产线两级封装。在 paddleocr/_common_args.py 中，parse_common_args将enable_hpi等公共参数归一化，并在prepare_common_init_args中将其映射为 PaddleX 侧的use_hpip参数（见 paddleocr/_common_args.py）；随后PaddleXPredictorWrapper（paddleocr/_models/base.py）与PaddleXPipelineWrapper（paddleocr/_pipelines/base.py）在创建 predictor / pipeline 时将该参数透传给 PaddleX，从而在初始化阶段即完成推理引擎的构建与后端选择。

2. 前置条件

2.1 安装高性能推理依赖

HPI 功能依赖飞桨（PaddlePaddle）框架，因此环境中必须已安装飞桨。在此基础上，通过 PaddleOCR CLI 安装 HPI 所需依赖：

paddleocr install_hpi_deps {设备类型}

支持的设备类型如下：

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

从命令实现看，paddleocr install_hpi_deps子命令在 paddleocr/_cli.py 中注册，variant参数支持cpu、gpu、npu三种取值。其底层逻辑为依次调用：

paddlex --install hpi-{variant} paddlex --install paddle2onnx

即先安装与设备类型对应的 PaddleX 高性能推理插件（hpi-cpu/hpi-gpu/hpi-npu），再安装模型格式转换所需的paddle2onnx工具，为静态图模型转 ONNX 提供支持。

推荐使用 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 后端。

2.2 GPU 环境详细说明

若使用 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，且建议安装版本与环境中存在的 Python 包版本保持一致，避免不同版本库共存引发潜在问题。可通过以下命令查看相关 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 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 通过 PaddleOCR CLI 启用

对于 PaddleOCR CLI，在任意推理子命令（如ocr）后指定--enable_hpi True即可执行高性能推理：

paddleocr ocr --enable_hpi True ...

从 CLI 参数解析实现看，--enable_hpi在 paddleocr/_common_args.py 中通过add_common_cli_opts注册，取值经str2bool转换后进入parse_common_args归一化流程，最终以use_hpip键传入 predictor / pipeline 的初始化参数。这一开关对所有使用公共参数体系的子命令（文本检测、文本识别、文档方向分类、表格结构识别、版面分析、OCR 产线等）均生效。

3.2 通过 Python API 启用

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

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

同样的参数体系也适用于各独立模块对象（如TextDetection、TextRecognition、TableStructureRecognition等）。以模块对象为例，paddleocr/_models/base.py 中的_create_paddlex_predictor会基于prepare_common_init_args的结果调用 PaddleX 的create_predictor完成推理器构建；产线对象则在 paddleocr/_pipelines/base.py 中通过create_pipeline(config=..., **kwargs)完成构建。若初始化时缺少依赖，代码会捕获 PaddleX 的DependencyError并提示参考安装文档补齐依赖。

3.3 与相关推理参数的配合

启用 HPI 后，仍可通过其他公共参数进一步约束推理行为，这些参数同样在 paddleocr/_common_args.py 中处理：

• device：推理设备，如cpu、gpu、gpu:0，默认在有 GPU 时使用 GPU 0，否则使用 CPU；
• engine：显式指定推理引擎，可选paddle、paddle_static、onnxruntime、openvino、tensorrt等（以 paddleocr/_common_args.py 中的SUPPORTED_INFERENCE_ENGINE_LIST为准），CLI 场景下引擎级配置应在 PaddleX YAML 配置文件中设置；
• use_tensorrt：是否使用 Paddle Inference 的 TensorRT 子图引擎，若模型不支持 TensorRT 加速，即使开启也不会生效；
• precision：推理精度（如fp32、fp16），GPU 下会映射为trt_fp32/trt_fp16运行模式；
• enable_mkldnn、cpu_threads：CPU 侧的 MKL-DNN 加速开关与推理线程数。

需要注意的是，HPI 模式下 PaddleOCR 会自动完成后端选择与模型格式转换，上述参数主要用于更细粒度的约束；当enable_hpi未开启而用户手动指定engine时，行为将回退到常规推理路径。

4. 使用说明与注意事项

1. 首次推理耗时较长属正常现象：对于部分模型，首次执行高性能推理时可能花费较长时间完成推理引擎的构建。引擎相关信息会在第一次构建完成后缓存在模型目录中，后续初始化可直接复用缓存内容以显著提速。
2. 部分模型无法获得加速：由于模型并非静态图格式、存在不支持算子等原因，部分模型可能无法获得推理加速，这是后端算子覆盖范围的客观限制。
3. ONNX 模型支持：高性能推理时 PaddleOCR 会自动处理模型格式转换并尽可能选择最优后端；同时 PaddleOCR 也支持用户直接指定 ONNX 模型。关于如何将飞桨静态图模型转换为 ONNX 格式，可参考 获取 ONNX 模型。
4. 通过 PaddleX 产线配置文件自定义后端：PaddleOCR 的高性能推理能力依托于 PaddleX 及其高性能推理插件。通过传入自定义 PaddleX 产线配置文件，可以对推理后端等细节进行配置。产线配置的加载与合并逻辑见 paddleocr/_pipelines/base.py：当传入paddlex_config（可为 dict 或 YAML 路径）时，会与 PaddleX 内置产线配置合并后创建产线。相关用法请参考 使用 PaddleX 产线配置文件 与 PaddleX 高性能推理指南。
5. 依赖环境唯一性：同一环境只应安装一种设备类型的 HPI 依赖；GPU 场景下请严格遵循 CUDA 11.8 + cuDNN 8.9 + TensorRT 8.6.1.6 或 CUDA 12.6 + cuDNN 9.5（仅 OpenVINO / ONNX Runtime）的版本约束，以保证后端可用性与最佳性能。

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR