comments: true

PaddleX 高性能推理指南

在实际生产环境中，许多应用对部署策略的性能指标（尤其是响应速度）有着较严苛的标准，以确保系统的高效运行与用户体验的流畅性。为此，PaddleX 提供高性能推理插件，通过自动配置和多后端推理功能，让用户无需关注复杂的配置和底层细节，即可显著提升模型的推理速度。

1. 基础使用方法

使用高性能推理插件前，请确保您已经按照PaddleX本地安装教程完成了PaddleX的安装，且按照PaddleX产线命令行使用说明或PaddleX产线Python脚本使用说明跑通了产线的快速推理。

高性能推理支持处理 PaddlePaddle 静态图模型( .pdmodel、 .json ) 和 ONNX 格式模型( .onnx )。对于 ONNX 格式模型，建议使用Paddle2ONNX 插件转换得到。如果模型目录中存在多种格式的模型，PaddleX 会根据需要自动选择。

1.1 安装高性能推理插件

目前高性能推理支持的处理器架构、操作系统、设备类型和 Python 版本如下表所示：

操作系统	处理器架构	设备类型	Python 版本
Linux	x86-64
		CPU	3.8–3.12
		GPU （CUDA 11.8 + cuDNN 8.9）	3.8–3.12
		NPU	3.10
	aarch64	NPU	3.10

(1) 基于 Docker 安装高性能推理插件（强烈推荐）：

参考基于Docker获取PaddleX 使用 Docker 启动 PaddleX 容器。启动容器后，根据设备类型，执行如下指令，安装高性能推理插件：

  <thead>
      <tr>
          <th>设备类型</th>
          <th>安装指令</th>
          <th>说明</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>CPU</td>
          <td><code>paddlex --install hpi-cpu</code></td>
          <td>安装 CPU 版本的高性能推理功能。</td>
      </tr>
      <tr>
          <td>GPU</td>
          <td><code>paddlex --install hpi-gpu</code></td>
          <td>安装 GPU 版本的高性能推理功能。<br />包含了 CPU 版本的所有功能。</td>
      </tr>
      <tr>
          <td>NPU</td>
          <td><code>paddlex --install hpi-npu</code></td>
          <td>安装 NPU 版本的高性能推理功能。<br />使用说明请参考<a href="../practical_tutorials/high_performance_npu_tutorial.md">昇腾 NPU 高性能推理教程</a>。</td>
      </tr>
  </tbody>

(2) 本地安装高性能推理插件：

安装 CPU 版本的高性能推理插件：

执行：

paddlex --install hpi-cpu

安装 GPU 版本的高性能推理插件：

参考 NVIDIA 官网本地安装 CUDA 和 cuDNN，再执行：

paddlex --install hpi-gpu

所需的 CUDA 和 cuDNN 版本可以通过如下方式获取：

# CUDA 版本
pip list | grep nvidia-cuda
# cuDNN 版本
pip list | grep nvidia-cudnn

安装 CUDA 11.8 和 cuDNN 8.9 的参考文档：

注意：

GPU 只支持 CUDA 11.8 + cuDNN8.9，CUDA 12.6 已经在支持中。
同一环境下只应该存在一个高性能推理插件版本。
NPU 设备的高性能推理使用说明参考昇腾 NPU 高性能推理教程。
Windows 只支持基于 Docker 安装和使用高性能推理插件。

1.2 启用高性能推理插件

以下是使用 PaddleX CLI 和 Python API 在通用图像分类产线和图像分类模块中启用高性能推理功能的示例。

对于 PaddleX CLI，指定 --use_hpip，即可启用高性能推理。

通用图像分类产线：

paddlex \
    --pipeline image_classification \
    --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_image_classification_001.jpg \
    --device gpu:0 \
    --use_hpip

图像分类模块：

python main.py \
    -c paddlex/configs/modules/image_classification/ResNet18.yaml \
    -o Global.mode=predict \
    -o Predict.model_dir=None \
    -o Predict.input=https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_image_classification_001.jpg \
    -o Global.device=gpu:0 \
    -o Predict.use_hpip=True

对于 PaddleX Python API，启用高性能推理的方法类似。以通用图像分类产线和图像分类模块为例：

通用图像分类产线：

from paddlex import create_pipeline

pipeline = create_pipeline(
    pipeline="image_classification",
    device="gpu",
    use_hpip=True
)

output = pipeline.predict("https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_image_classification_001.jpg")

图像分类模块：

from paddlex import create_model

model = create_model(
    model_name="ResNet18",
    device="gpu",
    use_hpip=True
)

output = model.predict("https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_image_classification_001.jpg")

启用高性能推理插件得到的推理结果与未启用插件时一致。对于部分模型，在首次启用高性能推理插件时，可能需要花费较长时间完成推理引擎的构建。PaddleX 将在推理引擎的第一次构建完成后将相关信息缓存在模型目录，并在后续复用缓存中的内容以提升初始化速度。

启用高性能推理默认作用于整条产线/整个模块，若想细粒度控制作用范围，如只对产线中某条子产线或某个子模块启用高性能推理插件，可以在产线配置文件中不同层级的配置里设置use_hpip，请参考 2.5 高性能推理在子产线/子模块中的启用/禁用。

2. 进阶使用方法

本节介绍高性能推理的进阶使用方法，适合对模型部署有一定了解或希望进行手动配置调优的用户。用户可以参照配置说明和示例，根据自身需求自定义使用高性能推理。接下来将对进阶使用方法进行详细介绍。

2.1 高性能推理工作模式

高性能推理分为两种工作模式：

(1) 安全自动配置模式

安全自动配置模式，具有保护机制，默认自动选用当前环境性能较优的配置。在这种模式下，用户可以覆盖默认配置，但用户提供的配置将受到检查，PaddleX将根据先验知识拒绝不可用的配置。这是默认的工作模式。

(2) 无限制手动配置模式

无限制手动配置模式，提供完全的配置自由，可以自由选择推理后端、修改后端配置等，但无法保证推理一定成功。此模式适合有经验和对推理后端及其配置有明确需求的用户，建议在熟悉高性能推理的情况下使用。

2.2 高性能推理配置

常用高性能推理配置包含以下字段：

参数	参数说明	参数类型	默认值
`auto_config`	是否启用安全自动配置模式。 `True`为启用安全自动配置模式，`False`为启用无限制手动配置模式。	`bool`	`True`
`backend`	用于指定要使用的推理后端。在无限制手动配置模式下不能为`None`。	`str \| None`	`None`
`backend_config`	推理后端的配置，若不为`None`则可以覆盖推理后端的默认配置项。	`dict \| None`	`None`
`auto_paddle2onnx`	是否启用Paddle2ONNX插件将Paddle模型自动转换为ONNX模型。	`bool`	`True`

backend 可选值如下表所示：

选项	描述	支持设备
`paddle`	Paddle Inference 推理引擎，支持 Paddle Inference TensorRT 子图引擎的方式提升模型的 GPU 推理性能。	CPU, GPU
`openvino`	OpenVINO，Intel 提供的深度学习推理工具，优化了多种 Intel 硬件上的模型推理性能。	CPU
`onnxruntime`	ONNX Runtime，跨平台、高性能的推理引擎。	CPU, GPU
`tensorrt`	TensorRT，NVIDIA 提供的高性能深度学习推理库，针对 NVIDIA GPU 进行优化以提升速度。	GPU
`om`	华为昇腾NPU定制的离线模型格式对应的推理引擎，针对硬件进行了深度优化，减少算子计算时间和调度时间，能够有效提升推理性能。	NPU

backend_config 根据不同后端有不同的可选值，如下表所示：

后端	可选值
`paddle`	参考PaddleX单模型Python脚本使用说明: 4. 推理后端设置。
`openvino`	`cpu_num_threads`：CPU推理使用的逻辑处理器数量。默认为`8`。
`onnxruntime`	`cpu_num_threads`：CPU推理时算子内部的并行计算线程数。默认为`8`。
`tensorrt`	`precision`：使用的精度，`fp16`或`fp32`。默认为`fp32`。 `dynamic_shapes`：动态形状。动态形状包含最小形状、最优形状以及最大形状，是 TensorRT 延迟指定部分或全部张量维度直到运行时的能力。格式为：`{输入张量名称}: [{最小形状}, [{最优形状}], [{最大形状}]]`。更多介绍请参考 TensorRT 官方文档。
`om`	暂无

2.3 如何修改高性能推理配置

由于实际部署环境和需求的多样性，默认配置可能无法满足所有要求。这时，可能需要手动调整高性能推理配置。以下是两种常见的情况：

需要更换推理后端。
- 例如在OCR产线中，指定text_detection模块使用onnxruntime后端，text_recognition模块使用tensorrt后端。
需要修改 TensorRT 的动态形状配置：
- 当默认的动态形状配置无法满足需求（例如，模型可能需要范围外的输入形状），就需要为每一个输入张量指定动态形状。修改完成后，需要清理模型的.cache缓存目录。

在这些情况下，用户可以通过修改产线/模块配置文件、CLI或Python API所传递参数中的 hpi_config 字段内容来修改配置。通过 CLI 或 Python API 传递的参数将覆盖产线/模块配置文件的设置。

2.4 修改高性能推理配置示例

(1) 更换推理后端。

##### 通用OCR产线的所有模型使用onnxruntime后端：

👉 1. 修改产线配置文件方式（点击展开）

  pipeline_name: OCR

  use_hpip: True
  hpi_config:
    backend: onnxruntime

  ...

👉 2. CLI传参方式（点击展开）

  paddlex \
      --pipeline image_classification \
      --input https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_image_classification_001.jpg \
      --device gpu:0 \
      --use_hpip \
      --hpi_config '{"backend": "onnxruntime"}'

👉 3. Python API传参方式（点击展开）

  from paddlex import create_pipeline

  pipeline = create_pipeline(
      pipeline="OCR",
      device="gpu",
      use_hpip=True,
      hpi_config={"backend": "onnxruntime"}
  )

##### 图像分类模块的模型使用onnxruntime后端：

👉 1. 修改产线配置文件方式（点击展开）

  # paddlex/configs/modules/image_classification/ResNet18.yaml
  ...
  Predict:
    ...
    use_hpip: True
    hpi_config:
        backend: onnxruntime
    ...
  ...

👉 2. CLI传参方式（点击展开）

  python main.py \
      -c paddlex/configs/modules/image_classification/ResNet18.yaml \
      -o Global.mode=predict \
      -o Predict.model_dir=None \
      -o Predict.input=https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_image_classification_001.jpg \
      -o Global.device=gpu:0 \
      -o Predict.use_hpip=True \
      -o Predict.hpi_config='{"backend": "onnxruntime"}'

👉 3. Python API传参方式（点击展开）

  from paddlex import create_model

  model = create_model(
      model_name="ResNet18",
      device="gpu",
      use_hpip=True,
      hpi_config={"backend": "onnxruntime"}
  )

##### 通用OCR产线的text_detection模块使用onnxruntime后端，text_recognition模块使用tensorrt后端：

👉 1. 修改产线配置文件方式（点击展开）

  pipeline_name: OCR

  ...

  SubModules:
    TextDetection:
      module_name: text_detection
      model_name: PP-OCRv4_mobile_det
      model_dir: null
      limit_side_len: 960
      limit_type: max
      thresh: 0.3
      box_thresh: 0.6
      unclip_ratio: 2.0
      # 当前子模块启用高性能推理
      use_hpip: True
      # 当前子模块使用如下高性能推理配置
      hpi_config:
          backend: onnxruntime
    TextLineOrientation:
      module_name: textline_orientation
      model_name: PP-LCNet_x0_25_textline_ori
      model_dir: null
      batch_size: 6
    TextRecognition:
      module_name: text_recognition
      model_name: PP-OCRv4_mobile_rec
      model_dir: null
      batch_size: 6
      score_thresh: 0.0
      # 当前子模块启用高性能推理
      use_hpip: True
      # 当前子模块使用如下高性能推理配置
      hpi_config:
          backend: tensorrt

(2) 修改 TensorRT 的动态形状配置

##### 通用图像分类产线修改动态形状配置：

👉 点击展开

    ...
    SubModules:
      ImageClassification:
        ...
        hpi_config:
          backend: tensorrt
          backend_config:
            precision: fp32
            dynamic_shapes:
              x:
                - [1, 3, 300, 300]
                - [4, 3, 300, 300]
                - [32, 3, 1200, 1200]
              ...
    ...

##### 图像分类模块修改动态形状配置：

👉 点击展开

  ...
  Predict:
    ...
    use_hpip: True
    hpi_config:
        backend: tensorrt
        backend_config:
          precision: fp32
          dynamic_shapes:
            x:
              - [1, 3, 300, 300]
              - [4, 3, 300, 300]
              - [32, 3, 1200, 1200]
    ...
  ...

2.5 高性能推理在子产线/子模块中的启用/禁用

高性能推理支持通过在子产线/子模块级别使用 use_hpip，实现仅产线中的某个子产线/子模块使用高性能推理。示例如下：

通用OCR产线的`text_detection`模块使用高性能推理，`text_recognition`模块不使用高性能推理：

👉 点击展开

  pipeline_name: OCR

  ...

  SubModules:
    TextDetection:
      module_name: text_detection
      model_name: PP-OCRv4_mobile_det
      model_dir: null
      limit_side_len: 960
      limit_type: max
      thresh: 0.3
      box_thresh: 0.6
      unclip_ratio: 2.0
      use_hpip: True # 当前子模块启用高性能推理
    TextLineOrientation:
      module_name: textline_orientation
      model_name: PP-LCNet_x0_25_textline_ori
      model_dir: null
      batch_size: 6
    TextRecognition:
      module_name: text_recognition
      model_name: PP-OCRv4_mobile_rec
      model_dir: null
      batch_size: 6
      score_thresh: 0.0
      use_hpip: False # 当前子模块不启用高性能推理

注意：

在子产线或子模块中设置 use_hpip 时，将以最深层的配置为准。
强烈建议通过修改产线配置文件的方式开启高性能推理，不建议使用CLI或Python API的方式进行设置。如果通过CLI或Python API启用 use_hpip，等同于在配置文件的最上层设置 use_hpip。

2.6 模型缓存说明

模型缓存会存放在模型目录下的 .cache 目录下，包括使用 tensorrt 或 paddle 后端时产生的 shape_range_info.pbtxt与trt_serialized开头的文件。

当启用auto_paddle2onnx选项时，可能会在模型目录下自动生成inference.onnx文件。

2.7 定制模型推理库

ultra-infer是高性能推理底层依赖的模型推理库，位于 PaddleX/libs/ultra-infer 目录。编译脚本位于 PaddleX/libs/ultra-infer/scripts/linux/set_up_docker_and_build_py.sh ，编译默认编译GPU版本和包含 OpenVINO、TensorRT、ONNX Runtime 三种推理后端的 ultra-infer。

自定义编译时可根据需求修改如下选项：

选项	说明
http_proxy	在下载三方库时使用具体的http代理，默认空
PYTHON_VERSION	Python版本，默认 `3.10.0`
WITH_GPU	是否编译支持Nvidia-GPU，默认 `ON`
ENABLE_ORT_BACKEND	是否编译集成ONNX Runtime后端，默认 `ON`
ENABLE_TRT_BACKEND	是否编译集成TensorRT后端（仅支持GPU），默认 `ON`
ENABLE_OPENVINO_BACKEND	是否编译集成OpenVINO后端（仅支持CPU），默认 `ON`

编译示例：

# 编译
# export PYTHON_VERSION=...
# export WITH_GPU=...
# export ENABLE_ORT_BACKEND=...
# export ...

cd PaddleX/libs/ultra-infer/scripts/linux
bash set_up_docker_and_build_py.sh

# 安装
python -m pip install ../../python/dist/ultra_infer*.whl

3. 常见问题

1. 为什么开启高性能推理插件前后，感觉推理速度没有明显提升？

高性能推理插件通过智能选择后端来加速推理。

对于单功能模块，由于模型复杂性或不支持算子等情况，部分模型可能无法使用加速后端（如OpenVINO、TensorRT等）。此时日志中会提示相关内容，并选择已知最快的可用后端，因此可能退回到普通推理。

对于模型产线，性能瓶颈可能不在模型推理阶段。

可以使用 PaddleX benchmark 工具进行实际速度测试，以便更准确地评估性能。

2: 高性能推理功能是否支持所有模型产线与单功能模块？

高性能推理功能支持所有模型产线与单功能模块，但部分模型可能无法加速推理，具体原因可以参考问题1。

3: 为什么安装高性能推理插件会失败，日志显示：Currently, the CUDA version must be 11.x for GPU devices.？

高性能推理功能目前支持的环境如 1.1节的表所示。如果安装失败，可能是高性能推理功能不支持当前环境。另外，CUDA 12.6 已经在支持中。

4. 为什么使用高性能推理功能后，程序在运行过程中会卡住或者显示一些 WARNING 和 ERROR 信息？这种情况下应该如何处理？

在引擎构建过程中，由于子图优化和算子处理，可能会导致程序耗时较长，并生成一些 WARNING 和 ERROR 信息。然而，只要程序没有自动退出，建议耐心等待，程序通常会继续运行至完成。

high_performance_inference.md 22 KB 文件历史 原始文件

comments: true

PaddleX 高性能推理指南

目录

1. 基础使用方法

1.1 安装高性能推理插件

(1) 基于 Docker 安装高性能推理插件（强烈推荐）：

(2) 本地安装高性能推理插件：

安装 CPU 版本的高性能推理插件：

安装 GPU 版本的高性能推理插件：

1.2 启用高性能推理插件

2. 进阶使用方法

2.1 高性能推理工作模式

(1) 安全自动配置模式

(2) 无限制手动配置模式

2.2 高性能推理配置

2.3 如何修改高性能推理配置

2.4 修改高性能推理配置示例

(1) 更换推理后端。

(2) 修改 TensorRT 的动态形状配置

2.5 高性能推理在子产线/子模块中的启用/禁用

通用OCR产线的text_detection模块使用高性能推理，text_recognition模块不使用高性能推理：

2.6 模型缓存说明

2.7 定制模型推理库

3. 常见问题

high_performance_inference.md 22 KB

文件历史原始文件

通用OCR产线的`text_detection`模块使用高性能推理，`text_recognition`模块不使用高性能推理：