Featured image of post TensorRT 官方样例学习笔记（一）环境搭建与项目结构解析
编程开发 算法解析

TensorRT 官方样例学习笔记（一）环境搭建与项目结构解析

从零构建高性能推理环境：深度解析 TensorRT 开发环境配置、项目架构设计及核心工作流原理。

TensorRT 官方样例学习笔记系列

  1. TensorRT 官方样例学习笔记（一）环境搭建与项目结构解析
  2. TensorRT 官方样例学习笔记（二）核心 API 详解：从 sampleOnnxMNIST 构建推理引擎
  3. TensorRT 官方样例学习笔记（三）ONNX 解析器：sampleOnnxMNIST 与模型导入
  4. TensorRT 官方样例学习笔记（四）动态 Shape 模式：sampleDynamicReshape 深度解析
  5. TensorRT 官方样例学习笔记（五）低精度推理：sampleINT8 量化与校准实战
  6. TensorRT 官方样例学习笔记（六）自定义插件开发：samplePlugin 算子扩展
  7. TensorRT 官方样例学习笔记（七）Transformer 优化：sampleBERT 与多头注意力机制

前言：为什么我们需要深入 TensorRT？

在深度学习的落地征程中，模型训练只是完成了“从 0 到 1”的知识提取，而模型部署则是实现“从 1 到 N”的价值规模化。NVIDIA TensorRT 作为当前 GPU 推理事实上的标准，其本质是一个高性能深度学习推理优化器和运行时（Runtime）。

很多开发者止步于“调用 API”或“运行转换脚本”，一旦遇到性能瓶颈或精度异常便束手无策。本系列《TensorRT 官方样例学习笔记》旨在打破这一僵局。我们将摒弃浅尝辄止的调包式学习，回归官方源码（Samples），从编译器视角理解 TensorRT 如何通过算子融合（Layer Fusion）、内核自动调优（Kernel Auto-Tuning）和显存优化来榨干 GPU 的每一滴算力。

本文作为开篇，将构建一个稳健的开发环境，并设计一套利于长期学习的项目架构。

核心原理：TensorRT 的“编译”哲学

在动手之前，必须理解 TensorRT 的核心工作流。与 PyTorch 的动态图（Eager Mode）不同，TensorRT 的核心在于“构建期（Build Phase）” 与“运行期（Runtime Phase）”的分离。

  1. 网络定义（Network Definition）：这是模型的逻辑表示，TensorRT 需要知道计算图的结构（层、输入输出、参数）。
  2. 构建引擎（Build Engine）：这是最核心的优化阶段。TensorRT 会针对目标 GPU 架构（如 Ampere, Ada Lovelace）进行：
    • 算子融合：将 Conv+Bias+ReLU 合并为一个 Kernel，减少显存读写。
    • 精度校准：在保证精度的前提下，将 FP32 转换为 FP16 或 INT8。
    • 内核自动调优：在成百上千种算法实现中，通过试跑找到当前硬件下的最优解。
  3. 序列化与反序列化：生成的 Plan 文件（即 Engine）是硬件绑定的二进制文件。
  4. 执行上下文（Execution Context）：加载 Engine，管理显存，执行推理。

理解了这个流程，你就会明白为什么环境一致性如此重要——Engine 是不可移植的。

稳健的开发环境配置

深度学习部署环境的“版本地狱”众所周知。为了保证学习过程的可复现性，我们锁定以下经过验证的“黄金组合”。这套配置兼顾了稳定性与新特性支持。

关键组件版本

组件版本选型逻辑
TensorRT8.6.18.x 系列的成熟版本，API 稳定，支持动态 Shape 和 Transformer 优化完善。
CUDA11.8工业界目前最广泛使用的稳定版，与 PyTorch 2.x 生态兼容性极佳。
cuDNN8.9.7.29提供了最新的卷积算法优化，需严格匹配 CUDA 11.x。
trtexec8.6.1TensorRT 的瑞士军刀，用于基准测试和快速验证。

环境验证

环境配置完成后，首先验证工具链是否可用。通过查看 trtexec 版本信息，可以快速确认环境变量（PATH/LD_LIBRARY_PATH）是否配置正确，避免后续运行时出现链接错误。

1
2

# 验证版本与环境链接
trtexec --help | head -n 5

工程化项目结构设计

为了避免学习过程中的代码混乱，我们采用“官方参照（Reference） + 实验沙盒（Sandbox）”的双目录结构。这种设计既能随时查阅官方的最佳实践，又能保留我们自己的探索记录。

目录规划

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

TensorRT-Learning/
├── TensorRT/               # [Reference] 官方源码库（只读/查阅）
│   ├── include/            # 核心头文件 (NvInfer.h 等)
│   ├── samples/            # 官方样例库（这是最好的教科书）
│   │   ├── sampleMNIST/    # 基础 C++ API 示例
│   │   ├── python/         # Python API 示例
│   │   └── ...
│   ├── quickstart/         # 快速上手脚本
│   └── bin/                # 编译好的工具 (trtexec)
│
└── Learning-Lab/           # [实验沙盒Sandbox] 个人实验工作区
    ├── README.md
    ├── TensorRT-v8.6.1/    # 8.x 系列学习环境
    │   ├── build/          # 编译输出目录
    │   ├── cmake/          # CMake 配置文件
    │   ├── CMakeLists.txt  # 项目构建配置
    │   ├── data/           # 模型与测试数据（从官方安装目录拷贝）
    │   ├── quickstart/     # 快速上手实验（从官方源码拷贝）
    │   └── samples/        # 复现的官方样例库（从官方源码拷贝）
    │
    └── TensorRT-v10.14/    # 10.x 系列学习环境
        ├── build/          # 编译输出目录
        ├── cmake/          # CMake 配置文件
        ├── data/           # 模型与测试数据（从 GitHub 下载）
        ├── quickstart/     # 快速上手实验
        ├── samples/        # 官方样例复现
        └── shared/         # 共享工具代码

为什么重点关注 samples？

TensorRT/samples/ 目录是官方文档的具象化。相比于枯燥的 API 文档，这里的代码展示了：

  • 内存管理：如何正确地分配 Device Memory。
  • 错误处理：标准的 TensorRT 错误捕获机制。
  • 插件机制：如何通过 Plugin 扩展 TensorRT 不支持的算子。

在后续的文章中,我们将把 samples 中的经典案例拆解到 Learning-Lab 中进行重构和实验。

多版本学习环境说明

考虑到 TensorRT 的快速迭代，我们在实验沙盒中设计了多版本并存的学习环境。这不仅能帮助我们理解 API 演进，更能应对实际项目中"历史代码维护"与"新特性探索"并存的现实需求。

TensorRT v8.6.1 学习环境

这是我们的主战场，代表了当前工业界最成熟的部署方案：

  • TensorRT 版本：8.6.1.6
  • CUDA 版本：11.8
  • cuDNN 版本：8.9.7.29
  • 学习目标：
    • 掌握从 PyTorch/ONNX 到 TensorRT Engine 的完整工作流
    • 深入理解 FP16/INT8 量化的精度-性能权衡
    • 熟练运用动态 Shape 处理变长输入

资源获取说明：

  • quickstart/ 与 samples/：直接从官方源码仓库拷贝
  • data/：从安装目录 /opt/TensorRT-8.6.1.6/data 获取（包含预处理好的测试数据集）

TensorRT v10.14 学习环境

这是前瞻性实验区，用于探索 TensorRT 的未来形态：

  • TensorRT 版本：10.14.1.48
  • CUDA 版本：13.0
  • cuDNN 版本：9.17.0
  • 学习目标：
    • 体验 Strongly Typed API（强类型接口重构）
    • 理解 TensorRT-LLM 的推理优化机制
    • 对比 8.x 与 10.x 的设计哲学差异

资源获取说明：

  • quickstart/, samples/, shared/：从官方源码仓库拷贝
  • data/：从 TensorRT GitHub 仓库下载（10.x 版本的示例数据）

版本切换策略

为了避免环境污染，我们通过修改 ~/.bashrc 中的环境变量来实现无缝切换：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# CUDA and TensorRT version switcher
# Helper to clear all CUDA/TRT paths
_clean_cuda_env() {
    export PATH=$(echo $PATH | sed -e 's|/usr/local/cuda-13.0/bin:||g' -e 's|/opt/TensorRT-10.14.1.48/bin:||g' -e 's|/usr/local/cuda-11.8/bin:||g' -e 's|/opt/TensorRT-8.6.1.6/bin:||g')
    export LD_LIBRARY_PATH=$(echo $LD_LIBRARY_PATH | sed -e 's|/usr/local/cuda-13.0/lib64:||g' -e 's|/opt/TensorRT-10.14.1.48/lib:||g' -e 's|/usr/local/cuda-11.8/lib64:||g' -e 's|/opt/TensorRT-8.6.1.6/lib:||g')
}

# CUDA and TensorRT version switcher
use_cuda13() {
    _clean_cuda_env
    export PATH=/opt/TensorRT-10.14.1.48/bin:/usr/local/cuda-13.0/bin:$PATH
    export LD_LIBRARY_PATH=/opt/TensorRT-10.14.1.48/lib:/usr/local/cuda-13.0/lib64:$LD_LIBRARY_PATH
    # echo -e "\033[1;32m✓ Switched to CUDA 13.0 + TensorRT 10.14.1.48\033[0m"
}

use_cuda11() {
    _clean_cuda_env
    export PATH=/opt/TensorRT-8.6.1.6/bin:/usr/local/cuda-11.8/bin:$PATH
    export LD_LIBRARY_PATH=/opt/TensorRT-8.6.1.6/lib:/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH
    # echo -e "\033[1;32m✓ Switched to CUDA 11.8 + TensorRT 8.6.1.6\033[0m"
}

# Default to CUDA 13
use_cuda13

切换步骤：

  1. 在终端直接输入 use_cuda11 或 use_cuda13。
  2. 验证切换结果：执行 nvcc --version 和 trtexec --help | head -n 5 确认路径是否指向目标版本。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

❯ nvcc --version
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2022 NVIDIA Corporation
Built on Wed_Sep_21_10:33:58_PDT_2022
Cuda compilation tools, release 11.8, V11.8.89
Build cuda_11.8.r11.8/compiler.31833905_0

❯ trtexec --help | head -n 5
&&&& RUNNING TensorRT.trtexec [TensorRT v8601] # trtexec --help
=== Model Options ===
  --uff=<file>                UFF model
  --onnx=<file>               ONNX model
  --model=<file>              Caffe model (default = no model, random weights used)

⚠️ 关键提醒：切换环境后，之前编译的 Engine 文件将不可用（硬件绑定特性）。务必为不同版本维护独立的 build/ 目录。

进阶学习路线图

本系列将遵循“原理优先，实践驱动”的原则，逐步攻克以下技术高地：

  1. 基础构建篇：
    • 深入理解 IBuilder, INetworkDefinition, ICudaEngine 的生命周期。
    • 掌握 C++ 与 Python API 的异同与协作。
  2. 全流程打通篇：
    • ONNX 解析器详解：如何处理导出失败与算子不支持问题。
    • 动态 Shape (Dynamic Shapes)：解决变长输入（如 NLP 序列、不同分辨率图像）的推理难题。
  3. 性能极致篇：
    • 低精度量化：实战 FP16 与 INT8 Post-Training Quantization (PTQ)。
    • 性能分析：使用 Nsight Systems 定位推理瓶颈（Kernel 耗时 vs. 显存传输耗时）。

下一步

环境已就绪，蓝图已绘就。下一篇，我们将深入 quickstart，阅读 TensorRT 相关代码，体验从"定义网络"到"执行推理"的完整闭环。

👉 点击这里阅读下一篇：《TensorRT 官方样例学习笔记（二）核心 API 详解：从 sampleOnnxMNIST 构建推理引擎》

常见问题解答

在配置和学习 TensorRT 的过程中，这些问题值得提前澄清。

Q1: .trt 和 .engine 文件有什么区别？

本质上没有区别。它们都是 TensorRT 序列化后的推理引擎文件（Serialized Engine），都是二进制格式，包含了针对特定 GPU 架构优化过的网络结构和 Kernel 代码。

  • .trt：在早期教程和某些 NVIDIA 产品（如 DeepStream）中较为常见
  • .engine：官方文档和最新示例代码推荐的后缀

选择建议：优先使用 .engine 后缀，与官方文档保持一致，提高代码可读性。

⚠️ 重要特性：这两种文件都是硬件绑定的。在 A100 上生成的 Engine 无法在 V100 上运行，不同 TensorRT 版本之间也不兼容。这是"构建期优化"带来的必然代价。

Q2: 为什么要同时学习 8.x 和 10.x 版本？

这是工程现实与技术前瞻的平衡：

  • 8.x 系列：代表当前生产环境的主流方案，拥有最丰富的社区资源和最稳定的 API。掌握 8.x 意味着能够维护 90% 的现存项目。
  • 10.x 系列：代表 NVIDIA 对 TensorRT 架构的重大重构（Strongly Typed API），特别是对 Transformer 和 LLM 的专项优化。理解其设计思路能帮助我们预判未来的技术方向。

参考资料

All Rights Reserved.（所有权利保留。禁止未经授权的复制或再分发。）
© 2018 - 2026 七月流火
使用 Hugo 构建
主题 Stack 由 Jimmy 设计