TensorRT 執行提供程式

使用 TensorRT 執行提供程式，ONNX Runtime 在相同硬體上提供比通用 GPU 加速更好的推理效能。

ONNX Runtime 中的 TensorRT 執行提供程式利用 NVIDIA 的 TensorRT 深度學習推理引擎，以加速其 GPU 系列中的 ONNX 模型。微軟和 NVIDIA 緊密合作，將 TensorRT 執行提供程式整合到 ONNX Runtime 中。

安裝

請選擇 Onnx Runtime 的 GPU (CUDA/TensorRT) 版本：https://onnxruntime.llms.tw/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

效能調優

有關效能調優，請參閱此頁面上的指南：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 模型。

從 ONNX 模型庫此處下載 Faster R-CNN onnx 模型。

透過執行形狀推理指令碼推斷模型中的形狀

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

要使用示例輸入測試模型並驗證輸出，請在 ONNX Runtime 構建目錄下執行onnx_test_runner。

模型和 test_data_set 資料夾需要儲存在同一路徑下。onnx_test_runner將測試此路徑下的所有模型。
```
 ./onnx_test_runner -e tensorrt /path/to/onnx/model/
```

要測試模型效能，請在您的形狀推斷 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 執行

TensorRT 執行提供程式

目錄

安裝

從原始碼構建

要求

用法

C/C++

Python

配置

單擊下方檢視 Python API 示例

單擊下方檢視 C++ API 示例

場景

執行提供程式選項

device_id

user_compute_stream

trt_max_workspace_size

trt_max_partition_iterations

trt_min_subgraph_size

trt_fp16_enable

trt_int8_enable

trt_int8_calibration_table_name

trt_int8_use_native_calibration_table

trt_dla_enable

trt_dla_core

trt_engine_cache_enable

trt_engine_cache_path

trt_engine_cache_prefix

trt_dump_subgraphs

trt_force_sequential_engine_build

trt_context_memory_sharing_enable

trt_layer_norm_fp32_fallback

trt_cuda_graph_enable

trt_timing_cache_path

trt_force_timing_cache

trt_detailed_build_log

trt_build_heuristics_enable

trt_cuda_graph_enable

trt_sparsity_enable

trt_builder_optimization_level

trt_auxiliary_streams

trt_tactic_sources

trt_extra_plugin_lib_paths

trt_profile_min_shapes

trt_profile_max_shapes

trt_profile_opt_shapes

trt_engine_hw_compatible

trt_op_types_to_exclude

環境變數（已棄用）

TensorRT EP 快取

快取有助於將會話建立時間從幾分鐘縮短到幾秒鐘

如何設定快取

更多關於嵌入式引擎模型 / EPContext 模型

效能調優

TensorRT 子圖的形狀推理

TensorRT 外掛支援

時序快取

動態形狀輸入的顯式形狀範圍

資料依賴形狀 (DDS) 操作

示例

已知問題