TensorRT 执行提供程序

借助 TensorRT 执行提供程序，与通用 GPU 加速相比，ONNX Runtime 在相同的硬件上提供更好的推理性能。

ONNX Runtime 中的 TensorRT 执行提供程序利用 NVIDIA 的 TensorRT 深度学习推理引擎来加速其 GPU 系列中的 ONNX 模型。 Microsoft 和 NVIDIA 紧密合作，将 TensorRT 执行提供程序与 ONNX Runtime 集成。

目录

• 安装
• 从源代码构建
• 要求
• 用法
• 配置
• TensorRT EP 缓存
• 性能调优
• 示例
• 已知问题

安装

请选择 Onnx Runtime 的 GPU (CUDA/TensorRT) 版本：https://runtime.onnx.org.cn/docs/install。 预构建的软件包和 Docker 镜像可在 Jetson Zoo 中用于 Jetpack。

从源代码构建

请参阅 构建说明。

要求

注意：从 1.19 版本开始，CUDA 12 成为分发 ONNX Runtime GPU 软件包时的默认版本。

ONNX Runtime	TensorRT	CUDA
主分支	10.9	12.0-12.8, 11.8
1.21	10.8	12.0-12.8, 11.8
1.20	10.4	12.0-12.6, 11.8
1.19	10.2	12.0-12.6, 11.8
1.18	10.0	11.8, 12.0-12.6
1.17	8.6	11.8, 12.0-12.6
1.16	8.6	11.8
1.15	8.6	11.8
1.14	8.5	11.6
1.12-1.13	8.4	11.4
1.11	8.2	11.4
1.10	8.0	11.4
1.9	8.0	11.4
1.7-1.8	7.2	11.0.3
1.5-1.6	7.1	10.2
1.2-1.4	7.0	10.1
1.0-1.1	6.0	10.0

有关 CUDA/cuDNN 版本的更多详细信息，请参阅 CUDA EP 要求。

用法

C/C++

Ort::Env env = Ort::Env{ORT_LOGGING_LEVEL_ERROR, "Default"};
Ort::SessionOptions sf;
int device_id = 0;
Ort::ThrowOnError(OrtSessionOptionsAppendExecutionProvider_Tensorrt(sf, device_id));
Ort::ThrowOnError(OrtSessionOptionsAppendExecutionProvider_CUDA(sf, device_id));
Ort::Session session(env, model_path, sf);

C API 详细信息请参阅此处。

Python

要使用 TensorRT 执行提供程序，您必须在实例化 InferenceSession 时显式注册 TensorRT 执行提供程序。 请注意，建议您也注册 CUDAExecutionProvider，以允许 Onnx Runtime 将 TensorRT 不支持的节点分配给 CUDA 执行提供程序。

import onnxruntime as ort
# set providers to ['TensorrtExecutionProvider', 'CUDAExecutionProvider'] with TensorrtExecutionProvider having the higher priority.
sess = ort.InferenceSession('model.onnx', providers=['TensorrtExecutionProvider', 'CUDAExecutionProvider'])

配置

有两种方法可以配置 TensorRT 设置，可以通过 TensorRT 执行提供程序会话选项 或 环境变量（已弃用）。

以下是示例以及设置 TensorRT EP 会话选项的不同场景

点击下方查看 Python API 示例

import onnxruntime as ort

model_path = '<path to model>'

# note: for bool type options in python API, set them as False/True
providers = [
    ('TensorrtExecutionProvider', {
        'device_id': 0,                       # Select GPU to execute
        'trt_max_workspace_size': 2147483648, # Set GPU memory usage limit
        'trt_fp16_enable': True,              # Enable FP16 precision for faster inference  
    }),
    ('CUDAExecutionProvider', {
        'device_id': 0,
        'arena_extend_strategy': 'kNextPowerOfTwo',
        'gpu_mem_limit': 2 * 1024 * 1024 * 1024,
        'cudnn_conv_algo_search': 'EXHAUSTIVE',
        'do_copy_in_default_stream': True,
    })
]

sess_opt = ort.SessionOptions()
sess = ort.InferenceSession(model_path, sess_options=sess_opt, providers=providers)

点击下方查看 C++ API 示例

Ort::SessionOptions session_options;

const auto& api = Ort::GetApi();
OrtTensorRTProviderOptionsV2* tensorrt_options;
Ort::ThrowOnError(api.CreateTensorRTProviderOptions(&tensorrt_options));

std::vector<const char*> option_keys = {
    "device_id",
    "trt_max_workspace_size",
    "trt_max_partition_iterations",
    "trt_min_subgraph_size",
    "trt_fp16_enable",
    "trt_int8_enable",
    "trt_int8_use_native_calibration_table",
    "trt_dump_subgraphs",
    // below options are strongly recommended !
    "trt_engine_cache_enable",
    "trt_engine_cache_path",
    "trt_timing_cache_enable",
    "trt_timing_cache_path",
};
std::vector<const char*> option_values = {
    "1",
    "2147483648",
    "10",
    "5",
    "1",
    "1",
    "1",
    "1",
    "1",
    "1",
    "/path/to/cache",
    "1",
    "/path/to/cache", // can be same as the engine cache folder
};

Ort::ThrowOnError(api.UpdateTensorRTProviderOptions(tensorrt_options,
                                                    option_keys.data(), option_values.data(), option_keys.size()));


cudaStream_t cuda_stream;
cudaStreamCreate(&cuda_stream);
// this implicitly sets "has_user_compute_stream"
Ort::ThrowOnError(api.UpdateTensorRTProviderOptionsWithValue(cuda_options, "user_compute_stream", cuda_stream))

session_options.AppendExecutionProvider_TensorRT_V2(*tensorrt_options);
/// below code can be used to print all options
OrtAllocator* allocator;
char* options;
Ort::ThrowOnError(api.GetAllocatorWithDefaultOptions(&allocator));
Ort::ThrowOnError(api.GetTensorRTProviderOptionsAsString(tensorrt_options,          allocator, &options));

场景

场景	TensorRT EP 会话选项	类型
设备和计算配置
指定用于执行的 GPU ID	device_id	int
为 GPU 操作设置自定义计算流	user_compute_stream	string
引擎缓存和兼容性
启用 TensorRT 引擎缓存	trt_engine_cache_enable	bool
设置存储缓存的 TensorRT 引擎的路径	trt_engine_cache_path	string
设置缓存引擎文件的前缀	trt_engine_cache_prefix	string
最大化 Ampere+ GPU 之间的引擎兼容性	trt_engine_hw_compatible	bool
精度和性能
设置 TensorRT EP GPU 内存使用限制	trt_max_workspace_size	int
启用 FP16 精度以获得更快的性能	trt_fp16_enable	bool
启用 INT8 精度以进行量化推理	trt_int8_enable	bool
为非 QDQ 模型命名 INT8 校准表	trt_int8_calibration_table_name	string
使用原生 TensorRT 校准表	trt_int8_use_native_calibration_table	bool
使用启发式方法加速引擎构建	trt_build_heuristics_enable	bool
启用稀疏性以利用零值	trt_sparsity_enable	bool
在边缘 SoC 上启用深度学习加速器 (DLA)	trt_dla_enable	bool
指定要使用的 DLA 核心	trt_dla_core	int
子图和图优化
限制模型转换的分区迭代次数	trt_max_partition_iterations	int
设置分区中子图的最小大小	trt_min_subgraph_size	int
转储优化的子图以进行调试	trt_dump_subgraphs	bool
在多 GPU 下强制顺序引擎构建	trt_force_sequential_engine_build	bool
从 TRT 运行中排除特定的 op 类型	trt_op_types_to_exclude	string
高级配置和性能分析
启用子图之间上下文内存共享	trt_context_memory_sharing_enable	bool
强制层归一化计算回退到 FP32	trt_layer_norm_fp32_fallback	bool
捕获 CUDA 图以减少启动开销	trt_cuda_graph_enable	bool
设置 TensorRT 构建器的优化级别	trt_builder_optimization_level	int
设置用于计算的辅助流的数量	trt_auxiliary_streams	int
指定 TensorRT 的策略来源	trt_tactic_sources	string
为 TensorRT 添加额外的插件库路径	trt_extra_plugin_lib_paths	string
启用构建步骤的详细日志记录	trt_detailed_build_log	bool
时序缓存
启用时序缓存的使用以加速构建	trt_timing_cache_enable	bool
设置用于存储时序缓存的路径	trt_timing_cache_path	string
强制使用时序缓存，而无需考虑 GPU 匹配	trt_force_timing_cache	bool
动态形状分析
定义最小形状	trt_profile_min_shapes	string
定义最大形状	trt_profile_max_shapes	string
定义最佳形状	trt_profile_opt_shapes	string

注意：对于 bool 类型选项，在 python 中使用 True/False 分配它们，或者在 C++ 中使用 1/0。

执行提供程序选项

TensorRT 配置可以通过执行提供程序选项进行设置。 当每个模型和推理会话都有自己的配置时，这非常有用。 在这种情况下，执行提供程序选项设置将覆盖任何环境变量设置。 所有配置都应显式设置，否则将采用默认值。

device_id

• 描述：GPU 设备 ID。
• 默认值：0

user_compute_stream

• 描述：定义推理运行所在的计算流。 它隐式设置 has_user_compute_stream 选项。 它不能通过 UpdateTensorRTProviderOptions 设置，而是通过 UpdateTensorRTProviderOptionsWithValue 设置。

• 这不能与外部分配器结合使用。

• 这也可以使用 python API 进行设置。

  • 即，从 pytorch 捕获的 cuda 流可以传递到 ORT-TRT 中。 点击下方查看示例代码

    import onnxruntime as ort
    import torch
    ...
    sess = ort.InferenceSession('model.onnx')
    if torch.cuda.is_available():
        s = torch.cuda.Stream()
        option = {"user_compute_stream": str(s.cuda_stream)}
        sess.set_providers(["TensorrtExecutionProvider"], [option])
        options = sess.get_provider_options()
        
        assert "TensorrtExecutionProvider" in options
        assert options["TensorrtExecutionProvider"].get("user_compute_stream", "") == str(s.cuda_stream)
        assert options["TensorrtExecutionProvider"].get("has_user_compute_stream", "") == "1"
    ...
    

• 为了利用用户计算流，建议使用 I/O 绑定 将输入和输出绑定到设备中的张量。

trt_max_workspace_size

• 描述：TensorRT 引擎的最大工作区大小。

• 默认值：1073741824 (1GB)。

trt_max_partition_iterations

• 描述：TensorRT 模型分区中允许的最大迭代次数。
• 如果达到最大迭代次数时目标模型无法成功分区，则整个模型将回退到其他执行提供程序，例如 CUDA 或 CPU。
• 默认值：1000。

trt_min_subgraph_size

• 描述：分区后子图中的最小节点大小。

• 较小子图将回退到其他执行提供程序。
• 默认值：1。

trt_fp16_enable

• 描述：在 TensorRT 中启用 FP16 模式。

  注意：并非所有 Nvidia GPU 都支持 FP16 精度。

trt_int8_enable

• 描述：在 TensorRT 中启用 INT8 模式。

  注意：并非所有 Nvidia GPU 都支持 INT8 精度。

trt_int8_calibration_table_name

• 描述：在 INT8 模式下为非 QDQ 模型指定 INT8 校准表文件。

  注意：不应为 QDQ 模型提供校准表，因为如果模型中存在任何 Q/DQ 节点，TensorRT 不允许加载校准表。 默认情况下，名称为空。

trt_int8_use_native_calibration_table

• 描述：选择用于 INT8 模式下非 QDQ 模型的校准表。

  • 如果 True，则使用原生 TensorRT 生成的校准表；
  • 如果 False，则使用 ONNXRUNTIME 工具生成的校准表。

  注意：请在推理前将最新的校准表文件复制到 trt_engine_cache_path。 校准表特定于模型和校准数据集。 每当生成新的校准表时，应清理或替换路径中的旧文件。

trt_dla_enable

• 描述：启用 DLA（深度学习加速器）。

  注意：并非所有 Nvidia GPU 都支持 DLA。

trt_dla_core

• 描述：指定要在其上执行的 DLA 核心。 默认值：0。

trt_engine_cache_enable

• 描述：启用 TensorRT 引擎缓存。

• 使用引擎缓存的目的是在 TensorRT 可能需要很长时间来优化和构建引擎的情况下，节省引擎构建时间。

• 引擎将在首次构建时进行缓存，以便下次创建新的推理会话时，可以直接从缓存加载引擎。 为了验证加载的引擎是否可用于当前推理，引擎配置文件也会与引擎一起缓存和加载。 如果当前的输入形状在引擎配置文件的范围内，则可以安全地使用加载的引擎。 否则，如果输入形状超出范围，则配置文件缓存将更新以覆盖新形状，并且将基于新配置文件重新创建引擎（并在引擎缓存中刷新）。

  • 注意：每个引擎都是为特定设置（例如模型路径/名称、精度（FP32/FP16/INT8 等）、工作区、配置文件等）和特定 GPU 创建的，并且不可移植，因此必须确保这些设置不会更改，否则需要重建引擎并再次缓存。

  警告：如果以下任何一项发生更改，请清理任何旧的引擎和配置文件缓存文件（.engine 和 .profile）

  • 模型更改（如果模型拓扑、opset 版本、运算符等有任何更改）
  • ORT 版本更改（即从 ORT 版本 1.8 移动到 1.9）
  • TensorRT 版本更改（即从 TensorRT 7.0 移动到 8.0）

trt_engine_cache_path

• 描述：如果 trt_engine_cache_enable 为 True，则指定 TensorRT 引擎和配置文件路径；如果 trt_int8_enable 为 True，则指定 INT8 校准表文件路径。

trt_engine_cache_prefix

• 描述：当 trt_engine_cache_enable 为 True 时，自定义引擎缓存前缀。
  • 只有当 trt_engine_cache_prefix 中分配了相同的前缀时，ORT-TRT 才会重用带有自定义前缀的现有引擎缓存。 如果此选项为空，将生成带有默认前缀的新引擎缓存。

trt_dump_subgraphs

• 描述：将转换为 onnx 格式的 TRT 引擎的子图转储到文件系统。
  • 这可以帮助调试子图，例如，通过使用 trtexec --onnx my_model.onnx 并检查解析器的输出。

trt_force_sequential_engine_build

• 描述：在多 GPU 环境中跨提供程序实例顺序构建 TensorRT 引擎。

trt_context_memory_sharing_enable

• 描述：在 TensorRT 子图之间共享执行上下文内存。

trt_layer_norm_fp32_fallback

• 描述：强制层归一化中的 Pow + Reduce ops 回退到 FP32。

trt_timing_cache_enable

• 描述：启用 TensorRT 时序缓存。
  • 有关详细信息，请查看 时序缓存。

trt_timing_cache_path

• 描述：如果 trt_timing_cache_enable 为 True，则指定 TensorRT 时序缓存的路径。
  • 不指定 trt_timing_cache_path 将导致使用工作目录

trt_force_timing_cache

• 描述：强制使用 TensorRT 时序缓存，即使设备配置文件不匹配。
  • 完美匹配仅指与生成时序缓存的 GPU 型号完全相同的 GPU 型号。

trt_detailed_build_log

• 描述：在 TensorRT EP 上启用详细的构建步骤日志记录，其中包含每个引擎构建的时序。

trt_build_heuristics_enable

• 描述：使用启发式方法构建引擎以减少构建时间。

trt_cuda_graph_enable

• 描述：这将捕获一个 CUDA 图，这对于具有许多小层的网络非常有帮助，因为它减少了 CPU 上的启动开销。

trt_sparsity_enable

• 描述：控制 TRT 是否可以使用稀疏性。
  • 有关详细信息，请查看 trtexec 命令行标志中的 --sparsity。

trt_builder_optimization_level

• 描述：设置构建器优化级别。

  警告：低于 3 的级别不能保证良好的引擎性能，但可以大大缩短构建时间。 默认值为 3，有效范围为 [0-5]。 有关详细信息，请查看 trtexec 命令行标志中的 --builderOptimizationLevel。

trt_auxiliary_streams

• 描述：设置每个推理流的最大辅助流数。
  • 将此值设置为 0 将导致最佳内存使用。
  • 默认值 -1 = 启发式。
  • 有关详细信息，请查看 trtexec 命令行标志中的 --maxAuxStreams。

trt_tactic_sources

• 描述：通过从默认策略来源（默认值 = 所有可用策略）添加 (+) 或删除 (-) 策略来指定要使用的策略
  • 例如，“-CUDNN,+CUBLAS” 可用键：“CUBLAS”、“CUBLAS_LT”、“CUDNN”或“EDGE_MASK_CONVOLUTIONS”。

trt_extra_plugin_lib_paths

• 描述：指定额外的 TensorRT 插件库路径。
  • 默认情况下，ORT TRT 支持 TRT 插件库（即 libnvinfer_plugin.so）中 TRT 注册表中的任何 TRT 插件。
  • 此外，如果用户想要使用 TRT 插件库中没有的其他 TRT 插件，
    • 例如，FasterTransformer 具有许多用于不同模型的 TRT 插件实现，用户可以这样指定 ORT_TENSORRT_EXTRA_PLUGIN_LIB_PATHS=libvit_plugin.so;libvit_int8_plugin.so。

trt_profile_min_shapes

trt_profile_max_shapes

trt_profile_opt_shapes

• 描述：使用配置文件和提供的最小/最大/最佳形状构建动态形状。
  • 配置文件形状的格式为 input_tensor_1:dim_1xdim_2x...,input_tensor_2:dim_3xdim_4x...,...
    • 应提供所有这三个标志以启用显式配置文件形状功能。
  • 有关更多详细信息，请查看 动态形状输入的显式形状范围 和 TRT 文档 优化配置文件。

trt_engine_hw_compatible

• 描述：如果启用了 trt_engine_cache_enable，则启用 Ampere+ 硬件兼容性
  • 硬件兼容的引擎可以在所有 Ampere+ GPU 环境中重用（可能具有较低的吞吐量和/或较高的延迟）。
  • 引擎将使用 sm80+ 名称后缀生成和加载，而不是实际的计算能力。
  • Turing 和以前的 Nvidia GPU 架构以及 Nvidia Jetson Orin 平台不符合此选项。

trt_op_types_to_exclude

• 描述：从 TRT 运行中排除特定的 op 类型。 （在 ORT 1.21.0 中可用）
  • 格式为 op_type_1,op_type_2,op_type_3...
  • 一个用例是缓解 下方 提到的性能问题，它允许用户阻止 DDS ops 在 TensorRT 上运行，确保它们由 CUDA EP 或 CPU EP 执行

    ./onnxruntime_perf_test -r 1 -e tensorrt -i "trt_op_types_to_exclude|NonMaxSuppression,NonZero,RoiAlign" /path/to/onnx/your_model.onnx
    

  • 另一个用例是实验性地将 ops 分配给 CUDA EP 与 TRT EP

环境变量（已弃用）

可以为 TensorRT 执行提供程序设置以下环境变量。 点击下方了解更多详情。

• ORT_TENSORRT_MAX_WORKSPACE_SIZE：TensorRT 引擎的最大工作区大小。 默认值：1073741824 (1GB)。

• ORT_TENSORRT_MAX_PARTITION_ITERATIONS：TensorRT 模型分区中允许的最大迭代次数。 如果达到最大迭代次数时目标模型无法成功分区，则整个模型将回退到其他执行提供程序，例如 CUDA 或 CPU。 默认值：1000。

• ORT_TENSORRT_MIN_SUBGRAPH_SIZE：分区后子图中的最小节点大小。 较小子图将回退到其他执行提供程序。 默认值：1。

• ORT_TENSORRT_FP16_ENABLE：在 TensorRT 中启用 FP16 模式。 1：启用，0：禁用。 默认值：0。 注意：并非所有 Nvidia GPU 都支持 FP16 精度。

• ORT_TENSORRT_INT8_ENABLE：在 TensorRT 中启用 INT8 模式。 1：启用，0：禁用。 默认值：0。 注意：并非所有 Nvidia GPU 都支持 INT8 精度。

• ORT_TENSORRT_INT8_CALIBRATION_TABLE_NAME：在 INT8 模式下为非 QDQ 模型指定 INT8 校准表文件。 注意：不应为 QDQ 模型提供校准表，因为如果模型中存在任何 Q/DQ 节点，TensorRT 不允许加载校准表。 默认情况下，名称为空。

• ORT_TENSORRT_INT8_USE_NATIVE_CALIBRATION_TABLE：选择用于 INT8 模式下非 QDQ 模型的校准表。 如果为 1，则使用原生 TensorRT 生成的校准表；如果为 0，则使用 ONNXRUNTIME 工具生成的校准表。 默认值：0。
  • 注意：请在推理前将最新的校准表文件复制到 ORT_TENSORRT_CACHE_PATH。 校准表特定于模型和校准数据集。 每当生成新的校准表时，应清理或替换路径中的旧文件。

• ORT_TENSORRT_DLA_ENABLE：启用 DLA（深度学习加速器）。 1：启用，0：禁用。 默认值：0。 注意：并非所有 Nvidia GPU 都支持 DLA。

• ORT_TENSORRT_DLA_CORE：指定要在其上执行的 DLA 核心。 默认值：0。

• ORT_TENSORRT_ENGINE_CACHE_ENABLE：启用 TensorRT 引擎缓存。 使用引擎缓存的目的是在 TensorRT 可能需要很长时间来优化和构建引擎的情况下，节省引擎构建时间。 引擎将在首次构建时进行缓存，以便下次创建新的推理会话时，可以直接从缓存加载引擎。 为了验证加载的引擎是否可用于当前推理，引擎配置文件也会与引擎一起缓存和加载。 如果当前的输入形状在引擎配置文件的范围内，则可以安全地使用加载的引擎。 否则，如果输入形状超出范围，则配置文件缓存将更新以覆盖新形状，并且将基于新配置文件重新创建引擎（并在引擎缓存中刷新）。 注意：每个引擎都是为特定设置（例如模型路径/名称、精度（FP32/FP16/INT8 等）、工作区、配置文件等）和特定 GPU 创建的，并且不可移植，因此必须确保这些设置不会更改，否则需要重建引擎并再次缓存。 1：启用，0：禁用。 默认值：0。
  • 警告：如果以下任何一项发生更改，请清理任何旧的引擎和配置文件缓存文件（.engine 和 .profile）
    • 模型更改（如果模型拓扑、opset 版本、运算符等有任何更改）
    • ORT 版本更改（即从 ORT 版本 1.8 移动到 1.9）
    • TensorRT 版本更改（即从 TensorRT 7.0 移动到 8.0）
    • 硬件更改。 （引擎和配置文件不可移植，并且针对特定的 Nvidia 硬件进行了优化）

• ORT_TENSORRT_CACHE_PATH：如果 ORT_TENSORRT_ENGINE_CACHE_ENABLE 为 1，则指定 TensorRT 引擎和配置文件的路径；如果 ORT_TENSORRT_INT8_ENABLE 为 1，则指定 INT8 校准表文件的路径。

• ORT_TENSORRT_DUMP_SUBGRAPHS：将转换为 onnx 格式的 TRT 引擎的子图转储到文件系统。 这可以帮助调试子图，例如，通过使用 trtexec --onnx my_model.onnx 并检查解析器的输出。 1：启用，0：禁用。 默认值：0。

• ORT_TENSORRT_FORCE_SEQUENTIAL_ENGINE_BUILD：在多 GPU 环境中跨提供程序实例顺序构建 TensorRT 引擎。 1：启用，0：禁用。 默认值：0。

• ORT_TENSORRT_CONTEXT_MEMORY_SHARING_ENABLE：在 TensorRT 子图之间共享执行上下文内存。 默认值 0 = false，非零值 = true。

• ORT_TENSORRT_LAYER_NORM_FP32_FALLBACK：强制层归一化中的 Pow + Reduce ops 回退到 FP32。 默认值 0 = false，非零值 = true。

• ORT_TENSORRT_TIMING_CACHE_ENABLE：启用 TensorRT 时序缓存。 默认值 0 = false，非零值 = true。 有关详细信息，请查看 时序缓存。

• ORT_TENSORRT_FORCE_TIMING_CACHE_ENABLE：强制使用 TensorRT 时序缓存，即使设备配置文件不匹配。 默认值 0 = false，非零值 = true。

• ORT_TENSORRT_DETAILED_BUILD_LOG_ENABLE：在 TensorRT EP 上启用详细的构建步骤日志记录，其中包含每个引擎构建的时序。 默认值 0 = false，非零值 = true。

• ORT_TENSORRT_BUILD_HEURISTICS_ENABLE：使用启发式方法构建引擎以减少构建时间。 默认值 0 = false，非零值 = true。

• ORT_TENSORRT_SPARSITY_ENABLE：控制 TRT 是否可以使用稀疏性。 默认值 0 = false，1 = true。 有关详细信息，请查看 trtexec 命令行标志中的 --sparsity。

• ORT_TENSORRT_BUILDER_OPTIMIZATION_LEVEL：设置构建器优化级别。 警告：低于 3 的级别不能保证良好的引擎性能，但可以大大缩短构建时间。 默认值为 3，有效范围为 [0-5]。 有关详细信息，请查看 trtexec 命令行标志中的 --builderOptimizationLevel。

• ORT_TENSORRT_AUXILIARY_STREAMS：设置每个推理流的最大辅助流数。 将此值设置为 0 将导致最佳内存使用。 默认值 -1 = 启发式。 有关详细信息，请查看 trtexec 命令行标志中的 --maxAuxStreams。

• ORT_TENSORRT_TACTIC_SOURCES: 指定要使用的策略，方法是从默认策略源（默认值 = 所有可用策略）添加 (+) 或删除 (-) 策略，例如“-CUDNN,+CUBLAS”。可用键：“CUBLAS”、“CUBLAS_LT”、“CUDNN”或“EDGE_MASK_CONVOLUTIONS”。

• ORT_TENSORRT_EXTRA_PLUGIN_LIB_PATHS: 指定额外的 TensorRT 插件库路径。默认情况下，ORT TRT 支持 TRT 插件库中 TRT 注册表中注册的任何 TRT 插件（即，libnvinfer_plugin.so）。此外，如果用户想要使用 TRT 插件库中没有的其他 TRT 插件，例如，FasterTransformer 针对不同的模型有许多 TRT 插件实现，用户可以像这样指定：ORT_TENSORRT_EXTRA_PLUGIN_LIB_PATHS=libvit_plugin.so;libvit_int8_plugin.so。

• ORT_TENSORRT_PROFILE_MIN_SHAPES、ORT_TENSORRT_PROFILE_MAX_SHAPES 和 ORT_TENSORRT_PROFILE_OPT_SHAPES：使用配置文件和提供的最小/最大/最佳形状构建动态形状。配置文件形状的格式为“input_tensor_1:dim_1xdim_2x…，input_tensor_2:dim_3xdim_4x…，…”，并且应提供这三个标志以启用显式配置文件形状功能。查看 动态形状输入的显式形状范围 和 TRT 文档 优化配置文件 以获取更多详细信息。

可以通过设置环境变量来覆盖默认值。例如，在 Linux 上

# Override default max workspace size to 2GB
export ORT_TENSORRT_MAX_WORKSPACE_SIZE=2147483648

# Override default maximum number of iterations to 10
export ORT_TENSORRT_MAX_PARTITION_ITERATIONS=10

# Override default minimum subgraph node size to 5
export ORT_TENSORRT_MIN_SUBGRAPH_SIZE=5

# Enable FP16 mode in TensorRT
export ORT_TENSORRT_FP16_ENABLE=1

# Enable INT8 mode in TensorRT
export ORT_TENSORRT_INT8_ENABLE=1

# Use native TensorRT calibration table
export ORT_TENSORRT_INT8_USE_NATIVE_CALIBRATION_TABLE=1

# Enable TensorRT engine caching
export ORT_TENSORRT_ENGINE_CACHE_ENABLE=1
# Please Note warning above. This feature is experimental.
# Engine cache files must be invalidated if there are any changes to the model, ORT version, TensorRT version or if the underlying hardware changes. Engine files are not portable across devices.

# Specify TensorRT cache path
export ORT_TENSORRT_CACHE_PATH="/path/to/cache"

# Dump out subgraphs to run on TensorRT
export ORT_TENSORRT_DUMP_SUBGRAPHS=1

# Enable context memory sharing between TensorRT subgraphs. Default 0 = false, nonzero = true
export ORT_TENSORRT_CONTEXT_MEMORY_SHARING_ENABLE=1

TensorRT EP 缓存

有三个主要的 TRT EP 缓存

• TRT timing 缓存
• TRT engine 缓存
• 嵌入式 engine 模型 / EPContext 模型

缓存可以帮助将 Session 创建时间从分钟缩短到秒

以下数字是通过使用 TRT EP 初始化 SD UNet 模型的 Session 测量的。

• 无缓存（默认）  – 384 秒
  • 首次运行（预热）可能非常耗时，因为构建 engine 涉及对每个内核进行详尽的分析以选择最佳内核。
• 使用 Timing 缓存 – 42 秒
  • 保留层分析信息并重用它们以加快构建时间
  • 如果层相同，Timing 缓存可以在多个模型之间共享
• 使用 Engine 缓存 – 9 秒
  • 将 engine 从内存序列化到磁盘以供以后使用
  • 跳过整个 engine 构建并将 engine 缓存反序列化到内存
• 使用嵌入式 engine（无需构建器实例化）- 1.9 秒
  • 序列化的 engine 缓存包装在 ONNX 模型中
  • 不会实例化构建器，也不会构建 engine
  • 以更少的进程快速加载 engine

如何设置缓存

• 使用 Timing 缓存 (.timing)
  • trt_timing_cache_enable = true
  • trt_timing_cache_path = .\
  • trt_force_timing_cache = true（接受 CC 内的轻微 GPU 不匹配）
• 使用 Engine 缓存 (.engine)
  • trt_engine_cache_enable = true
  • trt_engine_cache_path = .\trt_engines
• 使用 Embed Engine (_ctx.onnx)
  • 通过使用原始模型进行预热运行来获取 embed engine 模型
  • trt_engine_cache_enable = true
  • trt_dump_ep_context_model = true
  • trt_ep_context_file_path = .\
  • 将使用与原始模型相同的输入/输出生成
  • 运行 embed engine 模型作为原始模型！

缓存的文件夹结构

使用以下命令，嵌入式 engine 模型 (model_ctx.onnx) 将与 engine 缓存在同一目录中生成。

注意：该示例未指定 `trt_engine_cache_path`，因为 `onnxruntime_perf_test` 需要特定的文件夹结构才能运行推理。但是，我们仍然建议指定 `trt_engine_cache_path` 以更好地组织缓存。

$./onnxruntime_perf_test -e tensorrt -r 1 -i "trt_engine_cache_enable|true trt_dump_ep_context_model|true" /model_database/transformer_model/model.onnx

推理完成后，嵌入式 engine 模型将保存到磁盘。然后，用户可以像运行原始模型一样运行此模型，但 Session 创建时间会显着缩短。

$./onnxruntime_perf_test -e tensorrt -r 1 /model_database/transformer_model/model_ctx.onnx

有关嵌入式 engine 模型 / EPContext 模型的更多信息

• 一个限制是整个模型需要符合 TRT 条件
• 运行嵌入式 engine 模型时，默认设置为 `trt_ep_context_embed_mode=0`，其中嵌入了 engine 缓存路径，TRT EP 将在磁盘上查找 engine 缓存。或者，用户可以设置 `trt_ep_context_embed_mode=1`，将整个 engine 二进制数据作为字符串嵌入到模型中。但是，由于 ORT 图优化对长字符串进行哈希处理，此模式会增加初始化时间。因此，我们建议使用 `trt_ep_context_embed_mode=0`。
• 嵌入式 engine 模型的默认名称将在末尾附加 `_ctx.onnx`。用户可以指定 `trt_ep_context_file_path=my_ep_context_model.onnx` 以覆盖此默认名称。
• 如果使用嵌入式 engine，则 不需要 TensorRT 的 `nvinfer_builder_resource` 库，这是迄今为止最大的库。这使得在固定模型集的情况下可以运送最少量的库，这些模型集打包为预编译的 engine。
• 除了嵌入式 engine 实现的所有加速加载时间的功能外，它们还支持使用例如 `trtexec` 打包外部编译的 engine。python 工具中包含一个 python 脚本，该脚本能够将此类预编译的 engine 打包到 ONNX 文件中。

性能调优

有关性能调优，请参阅此页面上的指南：ONNX Runtime 性能调优

当/如果使用 onnxruntime_perf_test 时，请使用标志 `-e tensorrt`。查看下面的示例。

TensorRT 子图的形状推断

如果模型中的某些运算符不受 TensorRT 支持，ONNX Runtime 将对图进行分区，并且仅将受支持的子图发送到 TensorRT 执行提供程序。由于 TensorRT 要求子图的所有输入都指定了形状，因此如果缺少输入形状信息，ONNX Runtime 将抛出错误。在这种情况下，请首先通过运行 此处的 脚本为整个模型运行形状推断（查看下面的示例）。

TensorRT 插件支持

ORT TRT 可以利用官方版本 TRT 插件库中附带的 TRT 插件。要使用 TRT 插件，首先用户需要在 ONNX 模型中使用注册的插件名称和 `trt.plugins` 域创建自定义节点（与 TRT 插件的一对一映射）。这样，ORT TRT 可以识别此自定义节点，并将该节点与子图一起传递给 TRT。请参阅以下 python 示例，以在 ONNX 模型中创建新的自定义节点

点击下方查看 Python API 示例

from onnx import TensorProto, helper

def generate_model(model_name):
    nodes = [
        helper.make_node(
            "DisentangledAttention_TRT", # The registered name is from https://github.com/NVIDIA/TensorRT/blob/main/plugin/disentangledAttentionPlugin/disentangledAttentionPlugin.cpp#L36
            ["input1", "input2", "input3"],
            ["output"],
            "DisentangledAttention_TRT",
            domain="trt.plugins", # The domain has to be "trt.plugins"
            factor=0.123,
            span=128,
        ),
    ]

    graph = helper.make_graph(
        nodes,
        "trt_plugin_custom_op",
        [  # input
            helper.make_tensor_value_info("input1", TensorProto.FLOAT, [12, 256, 256]),
            helper.make_tensor_value_info("input2", TensorProto.FLOAT, [12, 256, 256]),
            helper.make_tensor_value_info("input3", TensorProto.FLOAT, [12, 256, 256]),
        ],
        [  # output
            helper.make_tensor_value_info("output", TensorProto.FLOAT, [12, 256, 256]),
        ],
    )

    model = helper.make_model(graph)
    onnx.save(model, model_name)

注意：如果用户想要使用官方版本 TRT 插件库中没有的 TRT 插件，请参阅 ORT TRT 提供程序选项 `trt_extra_plugin_lib_paths` 以获取更多详细信息。

Timing 缓存

启用 `trt_timing_cache_enable` 将使 ORT TRT 能够使用 TensorRT timing 缓存来加速具有相同计算能力的设备上的 engine 构建时间。这将在多个模型中起作用，因为它只是存储特定配置和 cubin 的内核延迟（TRT 9.0+）。这些文件通常非常小（只有几 KB 或 MB），这使得它们非常容易随应用程序一起发布，以加速用户端的构建时间。

注意： timing 缓存可以跨一个 GPU 计算能力 使用，类似于 engine。尽管如此，首选方法是每个 GPU 模型使用一个，但实践表明，在大多数情况下，跨一个计算能力共享效果良好。

以下示例显示了使用 timing 缓存减少构建时间

模型	无缓存	使用缓存
efficientnet-lite4-11	34.6 秒	7.7 秒
yolov4	108.62 秒	9.4 秒

点击下方查看 Python 示例

import onnxruntime as ort

ort.set_default_logger_severity(0) # Turn on verbose mode for ORT TRT
sess_options = ort.SessionOptions()

trt_ep_options = {
    "trt_timing_cache_enable": True,
}

sess = ort.InferenceSession(
    "my_model.onnx",
    providers=[
        ("TensorrtExecutionProvider", trt_ep_options),
        "CUDAExecutionProvider",
    ],
)

# Once inference session initialization is done (assume no dynamic shape input, otherwise you must wait until inference run is done)
# you can find timing cache is saved in the 'trt_engine_cache_path' directory, e.g., TensorrtExecutionProvider_cache_cc75.timing, please note
# that the name contains information of compute capability.

sess.run(
    None,
    {"input_ids": np.zeros((1, 77), dtype=np.int32)}
)

动态形状输入的显式形状范围

ORT TRT 允许您通过三个提供程序选项 `trt_profile_min_shapes`、`trt_profile_max_shapes` 和 `trt_profile_opt_shapes` 为每个动态形状输入显式指定最小/最大/最佳形状。如果未指定这三个提供程序选项，并且模型具有动态形状输入，则 ORT TRT 将根据传入的输入张量确定动态形状输入的最小/最大/最佳形状。TRT 优化配置文件需要最小/最大/最佳形状（优化配置文件描述了每个 TRT 网络输入的维度范围以及自动调谐器将用于优化的维度。当使用运行时维度时，您必须在构建时创建至少一个优化配置文件。）

要使用使用显式形状范围指定的优化配置文件构建的 engine 缓存，用户仍然需要提供这三个提供程序选项以及 engine 缓存启用标志。ORT TRT 将首先比较这三个提供程序选项的形状范围与保存在 .profile 文件中的形状范围，然后如果形状范围不匹配，则重建 engine。

点击下方查看 Python 示例

import onnxruntime as ort

ort.set_default_logger_severity(0) # Turn on verbose mode for ORT TRT
sess_options = ort.SessionOptions()

trt_ep_options = {
    "trt_fp16_enable": True,
    "trt_engine_cache_enable": True,
    "trt_profile_min_shapes": "sample:2x4x64x64,encoder_hidden_states:2x77x768",
    "trt_profile_max_shapes": "sample:32x4x64x64,encoder_hidden_states:32x77x768",
    "trt_profile_opt_shapes": "sample:2x4x64x64,encoder_hidden_states:2x77x768",
}

sess = ort.InferenceSession(
    "my_model.onnx",
    providers=[
        ("TensorrtExecutionProvider", trt_ep_options),
        "CUDAExecutionProvider",
    ],
)

batch_size = 1
unet_dim = 4
max_text_len = 77
embed_dim = 768
latent_height = 64
latent_width = 64

args = {
    "sample": np.zeros(
        (2 * batch_size, unet_dim, latent_height, latent_width), dtype=np.float32
    ),
    "timestep": np.ones((1,), dtype=np.float32),
    "encoder_hidden_states": np.zeros(
        (2 * batch_size, max_text_len, embed_dim),
        dtype=np.float32,
    ),
}
sess.run(None, args)
# you can find engine cache and profile cache are saved in the 'trt_engine_cache_path' directory, e.g.
# TensorrtExecutionProvider_TRTKernel_graph_torch_jit_1843998305741310361_0_0_fp16.engine and TensorrtExecutionProvider_TRTKernel_graph_torch_jit_1843998305741310361_0_0_fp16.profile.

请注意，使用此显式形状范围功能有一个限制，即，所有动态形状输入都应提供相应的最小/最大/最佳形状。

数据相关形状 (DDS) 算子

DDS 操作 — *NonMaxSuppression*、*NonZero* 和 *RoiAlign* — 具有仅在运行时确定的输出形状。

为确保 DDS 算子由 TRT-EP/TRT 而不是 CUDA EP 或 CPU EP 执行，请检查以下内容

• 对于 TensorRT < 10.7：使用 onnx-tensorrt OSS 解析器 构建 ORT，并使用 `10.X-GA-ORT-DDS` 分支。
• 对于 TensorRT >= 10.7：默认情况下，DDS 算子将由 TRT 执行。
• 对于 ORT：默认情况下，ORT 依赖于 TRT 解析器来决定 DDS 算子是否与 TRT 一起运行。但是，请注意，由于 已知的性能问题，ORT 1.20.1 和 1.20.2 将不会与 TRT 一起运行 DDS 算子。

示例

此示例展示了如何在 TensorRT 执行提供程序上运行 Faster R-CNN 模型。

1. 从 ONNX 模型动物园 此处 下载 Faster R-CNN onnx 模型。

2. 通过运行 形状推断脚本 推断模型中的形状

    python symbolic_shape_infer.py --input /path/to/onnx/model/model.onnx --output /path/to/onnx/model/new_model.onnx --auto_merge
   

3. 要使用示例输入测试模型并验证输出，请在 ONNX Runtime 构建目录下运行 `onnx_test_runner`。

   模型和 test_data_set_ 文件夹需要存储在同一路径下。`onnx_test_runner` 将测试此路径下的所有模型。

    ./onnx_test_runner -e tensorrt /path/to/onnx/model/
   

4. 要测试模型性能，请在形状推断的 Faster-RCNN 模型上运行 `onnxruntime_perf_test`

   从 模型动物园 下载带有模型的示例测试数据，并将 test_data_set 文件夹放在推断模型旁边

    # e.g.
    # -r: set up test repeat time
    # -e: set up execution provider
    # -i: set up params for execution provider options
    ./onnxruntime_perf_test -r 1 -e tensorrt -i "trt_fp16_enable|true" /path/to/onnx/your_inferred_model.onnx
   

请参阅 此 Notebook，了解有关通过 Azure 机器学习服务在 GPU 上使用 ONNX Runtime 运行模型的示例。

已知问题

• TensorRT 8.6 内置解析器和 TensorRT oss 解析器的行为有所不同。即，内置解析器无法识别某些自定义插件算子，而 OSS 解析器可以。请参阅 EfficientNMS_TRT missing attribute class_agnostic w/ TensorRT 8.6 。
• 当运行诸如 Faster-RCNN 之类的模型时，TensorRT 版本 10.0 到 10.5 存在性能问题，这些模型
  • 包含数据相关形状 (DDS) 操作，例如 NonMaxSuppression、NonZero 和 RoiAlign，并且
  • DDS 算子与 TRT 一起执行