PaddleX 高性能推理指南¶

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

目录¶

1. 安装与基础使用方法
1.1 安装高性能推理插件
1.2 启用高性能推理插件
2. 进阶使用方法
2.1 高性能推理工作模式
2.2 高性能推理配置
2.3 修改高性能推理配置
2.4 在配置文件中启用/禁用高性能推理插件
2.5 模型缓存说明
2.6 定制模型推理库
3. 常见问题

1. 安装与基础使用方法¶

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

高性能推理插件支持处理 PaddlePaddle 静态图（.pdmodel、 .json）、ONNX（.onnx）、华为 OM（.om） 等多种模型格式。对于 ONNX 模型，可以使用 Paddle2ONNX 插件转换得到。如果模型目录中存在多种格式的模型，PaddleX 会根据需要自动选择，并可能进行自动模型转换。建议在安装高性能推理插件前，首先安装 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.1.1 在 Docker 容器中安装高性能推理插件（强烈推荐）¶

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

设备类型	安装指令	说明
CPU	`paddlex --install hpi-cpu`	安装 CPU 版本的高性能推理功能。
GPU	`paddlex --install hpi-gpu`	安装 GPU 版本的高性能推理功能。包含了 CPU 版本的所有功能。

PaddleX 官方 Docker 镜像中默认安装了 TensorRT，高性能推理插件可以使用 Paddle Inference TensorRT 子图引擎进行推理加速。

请注意，以上提到的镜像指的是基于Docker获取PaddleX 中描述的 PaddleX 官方镜像，而非飞桨PaddlePaddle本地安装教程中描述的飞桨框架官方镜像。对于后者，请参考高性能推理插件本地安装说明。

1.1.2 本地安装高性能推理插件¶

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

执行：

paddlex --install hpi-cpu

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

在安装前，需要确保环境中安装有 CUDA 与 cuDNN。目前 PaddleX 官方仅提供 CUDA 11.8 + cuDNN 8.9 的预编译包，请保证安装的 CUDA 和 cuDNN 版本与编译版本兼容。以下分别是 CUDA 11.8 和 cuDNN 8.9 的安装说明文档：

如果使用的是飞桨框架官方镜像，则镜像中的 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

如果希望使用 Paddle Inference TensorRT 子图引擎，需额外安装 TensorRT。请参考飞桨PaddlePaddle本地安装教程中的相关说明。需要注意的是，由于高性能推理插件的底层推理库也集成了 TensorRT，建议安装相同版本的 TensorRT 以避免版本冲突。目前，高性能推理插件的底层推理库集成的 TensorRT 版本为 8.6.1.6。如果使用的是飞桨框架官方镜像，则无需关心版本冲突问题。

确认安装了正确版本的 CUDA、cuDNN、以及 TensorRT （可选）后，执行：

paddlex --install hpi-gpu

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

请参考昇腾 NPU 高性能推理教程。

注意：

目前 PaddleX 官方仅提供 CUDA 11.8 + cuDNN 8.9 的预编译包；CUDA 12 已经在支持中。
同一环境中只应该存在一个版本的高性能推理插件。
对于 Windows 系统，目前建议在 Docker 容器或者 WSL 环境中安装和使用高性能推理插件。

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 \
    --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 Predict.use_hpip=True

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

通用图像分类产线：

from paddlex import create_pipeline

pipeline = create_pipeline(
    pipeline="image_classification",
    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",
    use_hpip=True
)

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

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

通过 PaddleX CLI 和 Python API 启用高性能推理插件默认作用于整条产线/模块，若想细粒度控制作用范围，如只对产线中某条子产线或某个子模块启用高性能推理插件，可以在产线配置文件中不同层级的配置里设置 use_hpip，请参考 2.4 在配置文件中启用/禁用高性能推理插件。如果 CLI 参数、API 参数以及配置文件中均未指定 use_hpip，默认不启用高性能推理插件。

2. 进阶使用方法¶

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

2.1 高性能推理工作模式¶

高性能推理插件支持两种工作模式。通过修改高性能推理配置，可以切换不同的工作模式。

2.1.1 安全自动配置模式¶

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

2.1.2 无限制手动配置模式¶

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

2.2 高性能推理配置¶

常用高性能推理配置项包括：

名称	说明	类型	默认值
`auto_config`	是否启用安全自动配置模式。 `True` 为启用安全自动配置模式，`False` 为启用无限制手动配置模式。	`bool`	`True`
`backend`	用于指定要使用的推理后端。在无限制手动配置模式下不能为 `None`。	`str \| None`	`None`
`backend_config`	推理后端的配置，若不为 `None` 则可以覆盖推理后端的默认配置项。	`dict \| None`	`None`
`auto_paddle2onnx`	是否将 PaddlePaddle 静态图模型自动转换为 ONNX 模型。当 Paddle2ONNX 插件不可用时，不执行转换。	`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脚本使用说明。可通过键值对配置 `PaddlePredictorOption` 对象的属性，例如 `run_mode`。
`openvino`	`cpu_num_threads`（`int`）：CPU 推理使用的逻辑处理器数量。默认为 `8`。
`onnxruntime`	`cpu_num_threads`（`int`）：CPU 推理时算子内部的并行计算线程数。默认为 `8`。
`tensorrt`	`precision`（`str`）：使用的精度，`"fp16"` 或 `"fp32"`。默认为 `"fp32"`。 `dynamic_shapes`（`dict`）：动态形状配置，指定每个输入对应的最小形状、优化形状以及最大形状。格式为：`{输入张量名称}: [{最小形状}, {优化形状}, {最大形状}]`。动态形状是 TensorRT 延迟指定部分或全部张量维度直到运行时的能力，更多介绍请参考 TensorRT 官方文档。
`om`	暂无

2.3 修改高性能推理配置¶

由于实际部署环境和需求的多样性，默认配置可能无法满足所有要求。这时，可能需要手动调整高性能推理配置。用户可以通过修改**产线/模块配置文件**、CLI**或**Python API**所传递参数中的 hpi_config 字段内容来修改配置。**通过 CLI 或 Python API 传递的参数将覆盖产线/模块配置文件中的设置。以下将结合一些例子介绍如何修改配置。

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

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

...
hpi_config:
  backend: onnxruntime

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

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

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

from paddlex import create_pipeline

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

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

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

Predict:
  ...
  hpi_config:
    backend: onnxruntime

👉 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 Predict.use_hpip=True \
    -o Predict.hpi_config='{"backend": "onnxruntime"}'

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

from paddlex import create_model

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

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

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

SubModules:
  TextDetection:
    ...
    hpi_config:
      backend: onnxruntime
  TextRecognition:
    ...
    hpi_config:
      backend: tensorrt

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

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

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

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

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

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

2.4 在配置文件中启用/禁用高性能推理插件¶

在配置文件中，可以使用 use_hpip 控制高性能推理插件的启用和禁用。与通过 CLI 和 API 配置不同的是，这种方式支持通过在子产线/子模块级别使用 use_hpip，实现**仅产线中的某个子产线/子模块使用高性能推理**。示例如下：

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

👉 点击展开

SubModules:
  TextDetection:
    ...
    use_hpip: True # 当前子模块使用高性能推理
  TextLineOrientation:
    ...
    # 当前子模块未单独配置，默认与全局配置一致（如果配置文件和 CLI、API 参数均未设置，则不使用高性能推理）
  TextRecognition:
    ...
    use_hpip: False # 当前子模块不使用高性能推理

注意：

在配置文件中的多个层级设置 use_hpip 时，将以最深层的配置为准。
当通过修改产线配置文件的方式启用/禁用高性能推理插件时，不建议同时使用 CLI 或 Python API 的方式进行设置。 通过 CLI 或 Python API 设置 use_hpip 等同于修改配置文件顶层的 use_hpip。

2.5 模型缓存说明¶

模型缓存会存放在模型目录下的 .cache 目录中。

修改 Paddle Inference TensorRT 子图引擎或 TensorRT 相关配置后，建议清理缓存，以避免出现缓存导致新配置不生效的情况。

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

2.6 定制模型推理库¶

ultra-infer 是高性能推理底层依赖的模型推理库，在 PaddleX/libs/ultra-infer 目录以子项目形式维护。PaddleX 提供 ultra-infer 的构建脚本，位于 PaddleX/libs/ultra-infer/scripts/linux/set_up_docker_and_build_py.sh 。编译脚本默认构建 GPU 版本的 ultra-infer，集成 OpenVINO、TensorRT、ONNX Runtime 三种推理后端。

如果需要自定义构建 ultra-infer，可根据需求修改构建脚本的如下选项：

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

示例：

# 构建
cd PaddleX/libs/ultra-infer/scripts/linux
# export PYTHON_VERSION=...
# export WITH_GPU=...
# export ENABLE_ORT_BACKEND=...
# export ...
bash set_up_docker_and_build_py.sh

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

3. 常见问题¶

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

高性能推理插件通过智能选择和配置后端来实现推理加速。由于模型结构复杂或存在不支持算子等情况，部分模型可能无法实现加速。此时，PaddleX 会在日志中给出相应提示。可以使用 PaddleX benchmark 功能测量模块中各部分的推理耗时情况，以便更准确地评估性能。此外，对于产线而言，推理的性能瓶颈可能不在模型推理上，而在串联逻辑上，这也可能导致加速效果不明显。

2. 是否所有产线与模块均支持高性能推理？

所有使用静态图模型的产线与模块都支持启用高性能推理插件，但部分模型在某些情况下可能无法获得推理加速，具体原因可以参考问题1。

3. 为什么安装高性能推理插件会失败，日志显示：“You are not using PaddlePaddle compiled with CUDA 11. Currently, CUDA versions other than 11.x are not supported by the high-performance inference plugin.”？

对于 GPU 版本的高性能推理插件，目前 PaddleX 官方仅提供 CUDA 11.8 + cuDNN 8.9 的预编译包。CUDA 12 目前正在支持中。

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

在初始化模型时，子图优化等操作可能会导致程序耗时较长，并生成一些“WARNING”和“ERROR”信息。然而，只要程序没有自动退出，建议耐心等待，程序通常会继续运行至完成。

PaddleX 高性能推理指南¶

目录¶

1. 安装与基础使用方法¶

1.1 安装高性能推理插件¶

1.1.1 在 Docker 容器中安装高性能推理插件（强烈推荐）¶

1.1.2 本地安装高性能推理插件¶

1.2 启用高性能推理插件¶

2. 进阶使用方法¶

2.1 高性能推理工作模式¶

2.1.1 安全自动配置模式¶

2.1.2 无限制手动配置模式¶

2.2 高性能推理配置¶

2.3 修改高性能推理配置¶

2.4 在配置文件中启用/禁用高性能推理插件¶

2.5 模型缓存说明¶

2.6 定制模型推理库¶

3. 常见问题¶

评论