4、环境搭建与工具准备：CUDA、cuDNN、TensorRT版本选择、Python与C++ API对比、常用工具（trtexec、polygraphy）

TensorRT 的性能优化能力高度依赖底层软硬件栈的协同。在开始动态 shape 与 batch size 配置之前，必须先建立一个稳定、匹配且可复现的实验环境。版本错配是 TensorRT 开发中最常见的问题来源——CUDA 驱动与运行时库不一致、cuDNN 版本过新或过旧、TensorRT 与 PyTorch 的编译版本不匹配，都会导致推理结果错误、性能回退甚至直接加载失败。本章将系统梳理环境搭建的关键决策点，对比 Python 与 C++ API 的适用场景，并深入讲解 trtexec 与 Polygraphy 这两个核心工具的实际用法。

上图展示了 TensorRT 开发环境的完整技术栈。从底层硬件到上层应用，每一层都有严格的版本依赖关系。实际项目中，我们通常从 GPU 的 compute capability 出发，反向推导出合适的 CUDA、cuDNN 与 TensorRT 版本组合。下面将逐一拆解每个环节的关键决策点。

4.1 核心原理：版本兼容性矩阵与依赖关系

TensorRT 的版本兼容性遵循“向下兼容、向上不保证”的原则。这意味着：使用 CUDA 11.8 编译的 TensorRT 8.6 可以在 CUDA 12.x 驱动下运行（只要驱动版本足够新），但反过来，使用 CUDA 12.x 编译的 TensorRT 10.0 则无法在 CUDA 11.x 环境下工作。这种不对称性要求我们在项目初期就锁定目标部署环境的 CUDA 版本。

选择版本时，需要关注三个关键维度：GPU 架构（决定 compute capability）、CUDA 运行时版本（决定编译与运行时的 API 兼容性）、cuDNN 版本（影响卷积与循环网络层的性能）。TensorRT 官方发布说明中会明确列出每个版本对应的 CUDA 与 cuDNN 最低要求，但实际工程中，我们更推荐使用“已验证组合”而非“最低要求”。

一个常见的误区是盲目追求最新版本。TensorRT 10.x 引入了新的 API 和更激进的算子融合策略，但部分旧版 ONNX 模型可能无法直接解析。在动态 shape 场景下，TensorRT 8.6 的优化器对 shape 范围的处理更加成熟，而 10.x 则提供了更细粒度的 shape 约束控制。建议在项目启动时，先使用目标模型在 2-3 个 TensorRT 版本上做快速基准测试，再决定最终版本。

4.2 判断方法：CUDA、cuDNN 与 TensorRT 的安装与验证

环境搭建的核心操作流程可以归纳为以下五个步骤。每一步都需要验证，不能跳过。

1. 确认 GPU 与驱动：运行 nvidia-smi，记录 GPU 型号、驱动版本、CUDA 版本（驱动自带的最高 CUDA 版本）。驱动版本必须 ≥ TensorRT 要求的 CUDA 最低驱动版本。
2. 安装 CUDA Toolkit：从 NVIDIA 官网下载 runfile 或 deb 包。推荐使用 runfile 方式，可以自定义安装路径，避免污染系统目录。安装后设置 LD_LIBRARY_PATH 和 PATH。
3. 安装 cuDNN：下载与 CUDA 版本匹配的 cuDNN 库，解压后将 lib64 和 include 目录复制到 CUDA 安装目录，或通过 LD_LIBRARY_PATH 指向解压目录。
4. 安装 TensorRT：使用 tar 包或 pip 安装。tar 包方式更灵活，可以同时保留多个版本；pip 方式更简单，但版本切换不便。安装后验证 trtexec 是否可用。
5. 验证环境：运行一个简单的 ONNX 模型转换，确认 TensorRT 能正确加载 cuDNN 与 CUDA 运行时。

# 环境验证命令序列
nvidia-smi | grep "CUDA Version"
nvcc --version | grep "release"
python -c "import tensorrt as trt; print(trt.__version__)"
trtexec --version
# 如果 trtexec 不在 PATH 中，需要手动添加
export PATH=/opt/TensorRT-8.6.1.6/bin:$PATH
export LD_LIBRARY_PATH=/opt/TensorRT-8.6.1.6/lib:$LD_LIBRARY_PATH

在动态 shape 场景下，还需要额外验证 TensorRT 是否能正确识别模型的动态维度。可以使用 trtexec --onnx=model.onnx --shapes=input:1x3x224x224 进行快速测试，观察是否报错或警告。

4.3 Python 与 C++ API 对比：适用场景与性能差异

TensorRT 同时提供 Python 与 C++ API，两者在功能上几乎完全对齐，但在使用场景、性能开销和开发效率上有显著差异。选择哪种 API 取决于项目的部署形态和团队技术栈。

在动态 batch size 场景下，Python API 的一个常见陷阱是：当使用 binding 设置输入 shape 时，如果 Python 对象被垃圾回收，可能导致 CUDA 内存访问错误。因此，在 Python 中管理动态 shape 时，必须保持输入输出 buffer 的引用。C++ API 则通过显式的 IExecutionContext::setBindingDimensions 和 enqueueV2 调用，避免了这类问题。

4.4 常用工具实战：trtexec 与 Polygraphy 的深度应用

trtexec 是 TensorRT 自带的命令行工具，用于模型转换、性能基准测试和 shape 验证。Polygraphy 是 NVIDIA 官方推荐的模型调试与精度对比工具，支持层级别输出比对。两者结合，可以覆盖从模型转换到精度验证的完整流程。

trtexec 的核心用法：在动态 shape 场景下，trtexec 的 --shapes 参数可以指定多个输入 shape，用于验证引擎在不同 shape 下的正确性。同时，--minShapes、--optShapes、--maxShapes 三个参数定义了优化器的搜索范围。

# 动态 shape 转换与基准测试
trtexec --onnx=model.onnx \
        --minShapes=input:1x3x224x224 \
        --optShapes=input:8x3x224x224 \
        --maxShapes=input:32x3x224x224 \
        --saveEngine=model.engine \
        --workspace=4096 \
        --verbose

# 使用已保存的引擎进行性能测试
trtexec --loadEngine=model.engine \
        --shapes=input:4x3x224x224 \
        --duration=10 \
        --avgRuns=100

Polygraphy 的精度对比流程：当模型转换后出现精度下降时，Polygraphy 可以逐层对比 TensorRT 引擎与 ONNX Runtime 的输出，快速定位误差来源。

# 安装 Polygraphy
pip install polygraphy

# 运行精度对比
polygraphy run model.onnx \
        --trt --onnxrt \
        --input-shape input:1x3x224x224 \
        --atol 1e-3 --rtol 1e-3 \
        --validate

# 导出层级别输出进行详细分析
polygraphy run model.onnx \
        --trt --onnxrt \
        --trt-outputs mark all \
        --onnxrt-outputs mark all \
        --output-dir ./polygraphy_output

在动态 shape 场景下，Polygraphy 的 --input-shape 参数支持多次指定，用于测试不同 shape 下的精度一致性。如果某个 shape 下误差超标，可以结合 --trt-min-shape 和 --trt-max-shape 缩小排查范围。

4.5 案例拆解：从零搭建动态 shape 推理环境

某自动驾驶公司的感知团队需要部署一个实时目标检测模型，输入为摄像头图像，batch size 在 1 到 8 之间动态变化。团队现有 GPU 为 RTX 4090，驱动版本 535.104，CUDA 版本 12.2。初始目标是实现端到端延迟小于 15ms，且 batch size 切换时延迟波动不超过 2ms。

初始现象与目标：使用 PyTorch 原生推理时，batch size 从 1 切换到 8 时，延迟从 8ms 飙升到 35ms，且显存占用波动大。团队决定使用 TensorRT 进行加速，但不确定选择哪个版本。

关键输入数据：模型为 YOLOv8s，ONNX 导出后输入为动态 shape input:1x3x640x640，实际部署需要支持 batch 1-8。GPU 为 Ada Lovelace 架构，compute capability 8.9。

分析判断过程：根据 GPU 架构，CUDA 12.2 与 cuDNN 8.9.x 是匹配组合。TensorRT 版本方面，8.6.1 对 Ada 架构支持成熟，且动态 shape 优化器稳定；10.0 虽然更新，但 YOLOv8 的某些算子（如 DFL）在 10.0 中需要额外插件支持。因此选择 TensorRT 8.6.1。

实际操作步骤：

1. 安装 CUDA 12.2（runfile 方式），设置环境变量。
2. 安装 cuDNN 8.9.5，复制库文件到 CUDA 目录。
3. 下载 TensorRT 8.6.1 tar 包，解压到 /opt/TensorRT-8.6.1.6。
4. 使用 trtexec 转换 ONNX 模型，设置 --minShapes=input:1x3x640x640、--optShapes=input:4x3x640x640、--maxShapes=input:8x3x640x640。
5. 使用 Polygraphy 对比 TensorRT 引擎与 ONNX Runtime 的输出，设置 --atol 1e-2 --rtol 1e-2（目标检测任务允许较大误差）。
6. 编写 C++ 推理服务，使用 setBindingDimensions 动态调整 batch size。

结果对比：转换后，batch size 1 时延迟 4.2ms，batch size 8 时延迟 11.8ms，满足 15ms 要求。batch size 切换时延迟波动约 1.5ms，符合预期。显存占用从 PyTorch 的 4.2GB 降至 2.1GB。

风险与代价：TensorRT 8.6.1 对 YOLOv8 的 DFL 层使用了自定义插件，后续升级 TensorRT 版本时需要重新验证插件兼容性。此外，动态 shape 引擎的构建时间比静态 shape 长 3 倍，需要提前在 CI 流程中预留时间。

复盘经验：版本选择不能只看最新，要结合模型算子兼容性、部署环境 GPU 架构和团队维护成本综合判断。动态 shape 场景下，--optShapes 的选择对性能影响显著，建议使用实际部署中最常见的 batch size 作为优化目标。

4.6 常见误区与总结复盘

在环境搭建与工具使用过程中，以下误区需要特别注意：

• 误区一：CUDA 版本越高越好。实际上，TensorRT 的某些算子实现依赖特定 CUDA 版本的内部行为，过新的 CUDA 可能导致 TensorRT 回退到性能较差的 kernel。
• 误区二：忽略 cuDNN 的存在。cuDNN 的版本直接影响卷积层的性能。在动态 shape 场景下，cuDNN 的算法选择策略会影响不同 shape 下的延迟稳定性。
• 误区三：trtexec 只用于基准测试。trtexec 的 --dumpProfile 和 --dumpLayerInfo 参数可以输出每层的耗时与显存占用，是定位性能瓶颈的利器。
• 误区四：Polygraphy 只做精度对比。Polygraphy 的 --check-error-statistics 可以输出误差分布统计，帮助判断误差是系统性偏移还是随机噪声。

总结而言，环境搭建的核心是建立一条从 GPU 硬件到应用层的完整兼容链。工具使用的核心是理解每个工具在动态 shape 场景下的独特价值：trtexec 负责转换与基准，Polygraphy 负责精度与调试，Python/C++ API 的选择则决定了部署形态。建议团队在项目初期就建立标准化的环境配置文件（Dockerfile 或 shell 脚本），确保所有成员使用一致的版本组合，避免“在我机器上能跑”的尴尬局面。