命令行程序#

`trtexec`#

在 samples 目录中包含一个名为 trtexec 的命令行包装工具。trtexec 是一个无需开发应用程序即可快速使用 TensorRT 的工具。trtexec 工具主要有三个用途

它可用于在随机或用户提供的输入数据上对网络进行基准测试。
它可用于从模型生成序列化引擎。
它可用于从构建器生成序列化计时缓存。

基准测试网络#

如果您有一个模型保存为 ONNX 文件，则可以使用 trtexec 工具来测试使用 TensorRT 在网络上运行推理的性能。trtexec 工具具有许多选项，用于指定输入和输出、性能计时的迭代次数、允许的精度和其他选项。

为了最大化 GPU 利用率，trtexec 会提前一个批次排队推理。换句话说，它执行以下操作

enqueue batch 0 -> enqueue batch 1 -> wait until batch 0 is done -> enqueue batch 2 -> wait until batch 1 is done -> enqueue batch 3 -> wait until batch 2 is done -> enqueue batch 4 -> ...

如果使用跨推理多流（--infStreams=N 标志），则 trtexec 在每个流上分别遵循此模式。

trtexec 工具会打印以下性能指标。下图显示了 trtexec 运行的 Nsight System 配置文件示例，其中标记显示了每个性能指标。

吞吐量：观察到的吞吐量是通过将推理次数除以总主机运行时间来计算的。如果这明显低于 GPU 计算时间的倒数，则可能是由于主机端开销或数据传输导致 GPU 未充分利用。CUDA 图（使用 --useCudaGraph）或禁用 H2D/D2H 传输（使用 --noDataTransfer）可能会提高 GPU 利用率。当 trtexec 检测到 GPU 未充分利用时，输出日志会指导使用哪个标志。
主机延迟：H2D 延迟、GPU 计算时间和 D2H 延迟的总和。这是推断单次推理的延迟。
入队时间：将推理入队的主机延迟，包括调用 H2D/D2H CUDA API、运行主机端启发式方法和启动 CUDA 内核。如果这比 GPU 计算时间长，则 GPU 可能未充分利用，并且吞吐量可能由主机端开销主导。使用 CUDA 图（使用 --useCudaGraph）可能会减少入队时间。
H2D 延迟：单次推理的输入张量的主机到设备数据传输延迟。添加 --noDataTransfer 以禁用 H2D/D2H 数据传输。
D2H 延迟：单次推理的输出张量的设备到主机数据传输延迟。添加 --noDataTransfer 以禁用 H2D/D2H 数据传输。
GPU 计算时间：GPU 执行推理的 CUDA 内核的延迟。
总主机运行时间：从第一个推理（预热后）入队到最后一个推理完成的主机运行时间。
总 GPU 计算时间：所有推理的 GPU 计算时间总和。如果这明显短于总主机运行时间，则可能是由于主机端开销或数据传输导致 GPU 未充分利用。

注意

在最新的 Nsight Systems 中，GPU 行出现在 CPU 行上方，而不是下方。

Performance Metrics in a Normal trtexec Run under Nsight Systems

添加 --dumpProfile 标志到 trtexec 以显示逐层性能配置文件，这允许用户了解网络中哪些层在 GPU 执行中花费的时间最多。逐层性能分析也适用于将推理作为 CUDA 图启动。此外，使用 --profilingVerbosity=detailed 标志构建引擎，并添加 --dumpLayerInfo 标志以显示详细的引擎信息，包括逐层详细信息和绑定信息。这使您可以了解引擎中每个层对应的操作及其参数。

序列化引擎生成#

如果您生成保存的序列化引擎文件，则可以将其拉入另一个推理应用程序。例如，您可以使用 NVIDIA Triton 推理服务器以完全流水线异步方式从多个线程运行具有多个执行上下文的引擎，以测试并行推理性能。有一些注意事项；例如，在 INT8 模式下，除非使用 --calib=<file> 标志提供校准缓存文件，否则 trtexec 会为张量设置随机动态范围，因此结果精度将不如预期。

序列化计时缓存生成#

如果您向 --timingCacheFile 选项提供计时缓存文件，则构建器可以从中加载现有的分析数据，并在层分析期间添加新的分析数据条目。计时缓存文件可以在其他构建器实例中重复使用，以提高执行时间。建议仅在相同的硬件/软件配置（例如，CUDA/cuDNN/TensorRT 版本、设备型号和时钟频率）中重复使用此缓存；否则，可能会发生功能或性能问题。

常用命令行标志#

本节列出了常用的 trtexec 命令行标志。

构建阶段的标志

--onnx=<model>：指定输入 ONNX 模型。
如果输入模型为 ONNX 格式，请使用 --minShapes、--optShapes 和 --maxShapes 标志来控制输入形状的范围，包括批大小。
--minShapes=<shapes>、--optShapes=<shapes> 和 --maxShapes=<shapes>：指定用于构建引擎的输入形状范围。仅当输入模型为 ONNX 格式时才需要。
–-memPoolSize=<pool_spec>：指定允许使用的最大工作区策略大小以及 DLA 将为每个可加载项分配的内存池大小。支持的池类型包括 workspace、dlaSRAM、dlaLocalDRAM、dlaGlobalDRAM 和 tacticSharedMem。
--saveEngine=<file>：指定保存引擎的路径。
--fp16、--bf16、``–int8``、--fp8、``–noTF32`` 和 --best：指定网络级精度。
--stronglyTyped：创建强类型网络。
--sparsity=[disable|enable|force]：指定是否使用支持结构化稀疏性的策略。
- disable：禁用所有使用结构化稀疏性的策略。这是默认设置。
- enable：启用使用结构化稀疏性的策略。仅当 ONNX 文件权重满足结构化稀疏性要求时，才会使用策略。
- force：启用使用结构化稀疏性的策略，并允许 trtexec 覆盖 ONNX 文件中的权重以强制它们具有结构化稀疏性模式。请注意，精度不会保留，因此这仅用于获得推理性能。
注意

此功能已弃用。使用 Polygraphy (polygraphy surgeon prune) 重写 ONNX 模型的权重为结构化稀疏模式，然后使用 --sparsity=enable 运行。
--timingCacheFile=<file>：指定要从中加载和保存到的计时缓存。
--noCompilationCache：禁用构建器中的编译缓存，它是计时缓存的一部分（默认设置为启用编译缓存）。
--verbose：打开详细日志记录。
--skipInference：构建并保存引擎，但不运行推理。
--profilingVerbosity=[layer_names_only|detailed|none]：指定用于构建引擎的分析详细程度。
--dumpLayerInfo、--exportLayerInfo=<file>：打印/保存引擎的层信息。
--precisionConstraints=spec：控制精度约束设置。
- none：无约束。
- prefer：如果可能，满足由 --layerPrecisions 或 --layerOutputTypes 设置的精度约束。
- obey：满足由 --layerPrecisions 或 --layerOutputTypes 设置的精度约束，否则失败。
--layerPrecisions=spec：控制逐层精度约束。仅当 precisionConstraints 设置为 obey 或 prefer 时有效。规范从左到右读取，后面的规范会覆盖前面的规范。“*”可以用作 layerName 以指定所有未指定层的默认精度。
- 例如：--layerPrecisions=*:fp16,layer_1:fp32 将除 layer_1 之外的所有层的精度设置为 FP16，layer_1 将设置为 FP32。
--layerOutputTypes=spec：控制逐层输出类型约束。仅当 precisionConstraints 设置为 obey 或 prefer 时有效。规范从左到右读取，后面的规范会覆盖前面的规范。“*”可以用作 layerName 以指定所有未指定层的默认精度。如果一个层有多个输出，则可以为此层提供用“+”分隔的多种类型。
- 例如：--layerOutputTypes=*:fp16,layer_1:fp32+fp16 将除 layer_1 之外的所有层输出的精度设置为 FP16，layer_1 的第一个输出将设置为 FP32，第二个输出将设置为 FP16。
--layerDeviceTypes=spec：显式设置逐层设备类型为 GPU 或 DLA。规范从左到右读取，后面的规范会覆盖前面的规范。
-–useDLACore=N：为支持 DLA 的层使用指定的 DLA 核心。
–-allowGPUFallback：允许在 GPU 上运行 DLA 不支持的层。
--versionCompatible、--vc：启用版本兼容模式以进行引擎构建和推理。任何使用此标志构建的引擎在同一主机操作系统上的较新 TensorRT 版本上运行时，都与 TensorRT 的调度和精简运行时兼容。仅在显式批处理模式下受支持。
--excludeLeanRuntime：当启用 --versionCompatible 时，此标志指示生成的引擎不应包含嵌入式精简运行时。如果设置了此标志，则在加载引擎时必须显式指定有效的精简运行时。仅在显式批处理和引擎内权重的情况下受支持。
--tempdir=<dir>：覆盖 TensorRT 在创建临时文件时将使用的默认临时目录。有关更多信息，请参阅 IRuntime::setTemporaryDirectory API 文档。
--tempfileControls=controls：控制 TensorRT 在创建临时可执行文件时可以使用的内容。它应该是一个逗号分隔的列表，条目格式为 [in_memory|temporary]:[allow|deny]。
- 选项包括
  in_memory：控制 TensorRT 是否可以创建临时内存可执行文件。
  
  temporary：控制 TensorRT 是否可以在文件系统（在 --tempdir 给定的目录中）中创建临时可执行文件。
- 用法示例
  --tempfileControls=in_memory:allow,temporary:deny
--dynamicPlugins=<file>：动态加载插件库并在包含在 --setPluginsToSerialize 中时将其与引擎序列化（可以多次指定）。
--setPluginsToSerialize=<file>：设置要与引擎序列化的插件库（可以多次指定）。
--builderOptimizationLevel=N：设置用于构建引擎的构建器优化级别。更高的级别允许 TensorRT 花费更多构建时间来获得更多优化选项。
--maxAuxStreams=N：设置每个推理流的最大辅助流数，TensorRT 可以使用它们并行运行内核（如果网络包含可以并行运行的操作），但会增加内存使用量。将其设置为 0 可获得最佳内存使用率。有关更多信息，请参阅推理内多流部分。
--stripWeights：从计划中剥离权重。此标志适用于 refit 或 refit with identical weights。它默认为 refit with identical weights；但是，您可以通过同时启用 stripWeights 和 refit 来切换到 refit。
--markDebug：指定要标记为调试张量的张量名称列表。用逗号分隔名称。
--allowWeightStreaming：启用可以流式传输其权重的引擎。必须与 --stronglyTyped 一起指定。TensorRT 将在运行时自动选择适当的权重流式传输预算，以确保模型执行。可以使用 --weightStreamingBudget 设置特定量。

推理阶段的标志

--loadEngine=<file>：从序列化计划文件加载引擎，而不是从输入 ONNX 模型构建引擎。
--asyncFileReader=<file>：使用异步流读取器加载序列化引擎。此方法使用 IStreamReaderV2 接口。
如果输入模型为 ONNX 格式或引擎是使用显式批处理维度构建的，请改用 --shapes。
--shapes=<shapes>：指定用于运行推理的输入形状。
--loadInputs=<specs>：从文件加载输入值。默认设置为生成随机输入。
--warmUp=<duration in ms>、--duration=<duration in seconds>、--iterations=<N>：指定预热运行的最短持续时间、推理运行的最短持续时间和推理运行的最少迭代次数。例如，设置 --warmUp=0 --duration=0 --iterations=N 允许您精确控制运行推理的迭代次数。
--useCudaGraph：将推理捕获到 CUDA 图并启动该图来运行推理。当构建的 TensorRT 引擎包含 CUDA 图捕获模式下不允许的操作时，可能会忽略此参数。
--noDataTransfers：关闭主机到设备和设备到主机的数据传输。
--useSpinWait：主动同步 GPU 事件。此选项使延迟测量更稳定，但会增加 CPU 使用率和功耗。
--infStreams=<N>：并行运行具有多个跨推理流的推理。有关更多信息，请参阅跨推理多流部分。
--verbose：打开详细日志记录。
--dumpProfile、--exportProfile=<file>：打印/保存逐层性能配置文件。
--dumpLayerInfo、--exportLayerInfo=<file>：打印引擎的层信息。
--profilingVerbosity=[layer_names_only|detailed|none]：指定运行推理的分析详细程度。
--useRuntime=[full|lean|dispatch]：用于执行引擎的 TensorRT 运行时。lean 和 dispatch 需要启用 --versionCompatible，并用于加载 VC 引擎。所有引擎（VC 或非 VC）都必须使用完整运行时构建。
--leanDLLPath=<file>：在版本兼容模式下使用的外部精简运行时 DLL。需要 --useRuntime=[lean|dispatch]。
--dynamicPlugins=<file>：当库未包含在引擎计划文件中时，动态加载插件库（可以多次指定）。
--getPlanVersionOnly：打印加载的计划创建时的 TensorRT 版本。无需反序列化计划即可工作。与 --loadEngine 一起使用。仅支持使用 8.6 及更高版本创建的引擎。
--saveDebugTensors：指定张量名称列表以打开调试状态，并指定文件名以保存原始输出。这些张量必须在构建时指定为调试张量。
--allocationStrategy：指定如何分配用于推理的内部设备内存。您可以从 static、profile 和 runtime 中进行选择。第一个选项是默认行为，它为所有配置文件和输入形状预先分配足够的空间。第二个选项使 trtexec 仅分配配置文件所需的内容。第三个选项使 trtexec 仅分配实际输入形状所需的内容。
--weightStreamingBudget：手动设置权重流式传输预算。支持以 2 为底的单位后缀：B（字节）、G（吉比字节）、K（千比字节）和 M（兆比字节）。如果权重不适合设备，则值 0 将选择可能的最小预算。值 -1 将在运行时禁用权重流式传输。

请参阅 trtexec --help，其中包含所有受支持的标志和详细说明。

有关构建此工具及其用法示例的详细信息，请参阅 GitHub: trtexec/README.md 文件。