TensorRT 执行提供程序

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

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

目录

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

安装

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

从源代码构建

请参阅构建说明。

要求

注意

从版本 1.19 开始，在分发 ONNX Runtime GPU 包时，CUDA 12 成为默认版本。

从 ORT 1.22 开始，只发布 CUDA 12 GPU 包。

ONNX Runtime	TensorRT	CUDA
main	10.9	12.0-12.8
1.22	10.9	12.0-12.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 上运行	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

注意：对于布尔类型选项，在 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 算子使用 FP32。

trt_cuda_graph_enable

• 描述：启用 TensorRT 时序缓存。
  • 请查看时序缓存了解详细信息。

trt_timing_cache_path

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

trt_force_timing_cache

• 描述：即使设备配置文件不匹配，也强制使用 TensorRT 时序缓存。
  • 完美匹配是指与生成时序缓存的 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 运行之外。（在 ORT 1.21.0 中可用）
  • 格式为op_type_1,op_type_2,op_type_3...
  • 一个用例是缓解下面提到的性能问题，它允许用户阻止 DDS 操作在 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
    

  • 另一个用例是试验将操作分配给 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 (Deep Learning Accelerator)。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 操作回退到 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 插件库（即libnvinfer_plugin.so）中 TRT 注册表中的任何 TRT 插件。此外，如果用户想使用不在 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 时序缓存
• TRT 引擎缓存
• 嵌入式引擎模型 / EPContext 模型

缓存有助于将会话创建时间从几分钟缩短到几秒钟

以下数字是在使用 TRT EP 初始化 SD UNet 模型会话时测量的。

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

如何设置缓存

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

缓存的文件夹结构

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

注意：此示例未指定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

推理完成后，嵌入式引擎模型将保存到磁盘。用户可以像运行原始模型一样运行此模型，但会话创建时间会显著加快。

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

更多关于嵌入式引擎模型 / EPContext 模型

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

性能调优

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

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

TensorRT 子图的形状推理

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

TensorRT 插件支持

ORT TRT 可以利用官方版本中 TRT 插件库附带的 TRT 插件。要使用 TRT 插件，首先用户需要在 ONNX 模型中创建一个自定义节点（与 TRT 插件的一一映射），并使用注册的插件名称和trt.plugins域。因此，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以了解更多详细信息。

时序缓存

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

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

以下示例展示了使用时序缓存缩短构建时间的效果

模型	无缓存	有缓存
efficientnet-lite4-11	34.6 s	7.7 s
yolov4	108.62 s	9.4 s

单击下方查看 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 网络输入的维度范围以及自动调优器将用于优化的维度。使用运行时维度时，您必须在构建时创建至少一个优化配置文件）。

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

单击下方查看 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
   

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

已知问题

• TensorRT 8.6 内置解析器和 TensorRT OSS 解析器行为不同。具体来说，内置解析器无法识别某些自定义插件操作，而 OSS 解析器可以。参见EfficientNMS_TRT 在 TensorRT 8.6 中缺少属性 class_agnostic。
• 当运行包含数据依赖形状 (DDS) 操作（如 NonMaxSuppression、NonZero 和 RoiAlign）的模型（如 Faster-RCNN）时，TensorRT 10.0 至 10.5 版本存在性能问题，
  • 包含数据依赖形状 (DDS) 操作，如 NonMaxSuppression、NonZero 和 RoiAlign，并且
  • DDS 操作使用 TRT 执行