4、环境搭建：CUDA、cuDNN、TensorRT安装与版本匹配、开发环境配置

TensorRT 的序列化与反序列化过程高度依赖底层 CUDA 运行时版本与 cuDNN 库的 ABI 兼容性。许多“模型无法加载”“引擎反序列化失败”的报错，根源并非代码逻辑错误，而是环境组件版本错位。因此，在动手编写任何 TensorRT 代码之前，必须先建立一套严格匹配的软件栈。

4.1 核心原理：版本匹配的“三角约束”

TensorRT 引擎文件（.engine / .plan）在序列化时会将当前 CUDA 运行时版本、cuDNN 版本、TensorRT 版本以及 GPU 架构（SM 版本）以元数据形式写入文件头。反序列化时，TensorRT 会逐项校验这些元数据与当前加载环境是否一致。任何一项不匹配，都会触发 std::runtime_error 或返回 nullptr。

版本匹配遵循“三角约束”关系：

CUDA 驱动版本 ≥ CUDA 运行时版本：驱动向下兼容，但运行时库版本不能高于驱动支持的版本。
TensorRT 版本与 CUDA 版本有官方对应表：例如 TensorRT 8.6 对应 CUDA 11.8 和 12.0，TensorRT 10.0 对应 CUDA 12.3。
cuDNN 版本需在 TensorRT 官方验证列表中：cuDNN 的 API 向后兼容，但 TensorRT 在编译时链接了特定版本的 cuDNN 符号，若缺失或版本过旧会直接加载失败。

关键认知：TensorRT 引擎的序列化格式并不保证跨版本兼容。用 TensorRT 8.5 生成的引擎，无法在 TensorRT 8.6 或 10.0 环境中反序列化。这是设计使然，目的是避免底层 kernel 优化因版本差异产生数值偏差或崩溃。

4.2 安装方法流程：从驱动到 TensorRT 的完整链路

推荐使用 deb 包（Debian/Ubuntu）或 tar 包方式安装，避免使用 pip 安装 TensorRT 时可能出现的 CUDA 依赖缺失问题。以下以 Ubuntu 22.04 + CUDA 12.3 + TensorRT 10.0 为例。

步骤 1：安装 NVIDIA 驱动

# 查看推荐驱动版本
ubuntu-drivers devices
# 安装推荐驱动（例如 545 或 550）
sudo apt install nvidia-driver-550
# 重启后验证
nvidia-smi

步骤 2：安装 CUDA Toolkit（运行时 + 开发库）

# 使用 runfile 或 deb 网络安装，推荐 deb 方式
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install cuda-12-3

# 设置环境变量
echo 'export PATH=/usr/local/cuda-12.3/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.3/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
nvcc --version

步骤 3：安装 cuDNN（需登录 NVIDIA 开发者账号下载）

# 下载 cuDNN 9.1 for CUDA 12.x deb 包
sudo dpkg -i cudnn-local-repo-ubuntu2204-9.1.0_1.0-1_amd64.deb
sudo cp /var/cudnn-local-repo-ubuntu2204-9.1.0/cudnn-*-keyring.gpg /usr/share/keyrings/
sudo apt update
sudo apt install libcudnn9-dev-cuda-12

# 验证
cat /usr/include/x86_64-linux-gnu/cudnn_version.h | grep CUDNN_MAJOR

步骤 4：安装 TensorRT

# 下载 TensorRT 10.0 GA tar 包
tar -xzvf TensorRT-10.0.1.6.Ubuntu-22.04.x86_64-gnu.cuda-12.3.tar.gz
cd TensorRT-10.0.1.6

# 添加环境变量
echo 'export LD_LIBRARY_PATH=$PWD/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
echo 'export PATH=$PWD/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 验证安装
trtexec --version

4.3 案例：版本不匹配导致的序列化异常

某团队在开发机上使用 TensorRT 8.6 + CUDA 11.8 生成引擎文件，部署到生产服务器时，服务器安装的是 CUDA 12.2 + TensorRT 10.0。反序列化时出现以下错误：

[E] Error Code 1: Serialization (incompatible engine)
[E] Engine was built with a different version of TensorRT than the one being used.
[E] Built version: 8600, Current version: 10000

该错误明确指出了版本不匹配。解决方案有两种：

重新生成引擎：在生产服务器上使用 TensorRT 10.0 重新序列化模型（推荐，能利用新版本优化）。
降级环境：将生产服务器环境回退到与开发机一致的 CUDA 11.8 + TensorRT 8.6（不推荐，损失性能提升）。

最佳实践：在 CI/CD 流水线中，将 TensorRT 引擎生成与部署环境统一为同一 Docker 镜像。使用 nvidia/cuda:12.3-cudnn9-devel-ubuntu22.04 作为基础镜像，再叠加 TensorRT 10.0，确保构建与运行环境完全一致。

4.4 开发环境配置清单

组件	版本要求	验证命令	常见问题
NVIDIA 驱动	≥ 550.54.14	`nvidia-smi`	驱动过旧导致 CUDA 初始化失败
CUDA Toolkit	12.3（与 TensorRT 10.0 匹配）	`nvcc --version`	nvcc 与驱动版本不匹配
cuDNN	9.1.0	`cat /usr/include/cudnn_version.h`	libcudnn.so 缺失或版本过旧
TensorRT	10.0.1.6	`trtexec --version`	libnvinfer.so 找不到
Python 绑定（可选）	tensorrt==10.0.1	`python -c "import tensorrt; print(tensorrt.__version__)"`	pip 安装的版本与 CUDA 不匹配

4.5 常见误区与复盘

误区 1：盲目使用最新版本。TensorRT 10.x 移除了对 CUDA 11.x 的支持，如果项目依赖旧版 CUDA 算子库，升级 TensorRT 会导致编译失败。务必先查阅官方 TensorRT Support Matrix，确认版本对应关系。

误区 2：忽略 GPU 架构（SM 版本）。TensorRT 引擎针对特定 SM 架构优化。在 Ampere（SM_86）上生成的引擎，无法在 Turing（SM_75）上运行。使用 trtexec --device=0 --buildOnly 时，务必确认目标 GPU 架构。

复盘建议：每次环境变更后，执行一次完整的“生成→序列化→反序列化→推理”冒烟测试。将 nvidia-smi、nvcc --version、trtexec --version 的输出保存为环境快照文件，与引擎文件一同归档，便于后续问题回溯。

完成上述安装与配置后，建议使用 trtexec 工具对 ONNX 模型做一次快速转换测试，验证环境链路是否通畅。若转换成功并生成引擎文件，说明 CUDA、cuDNN、TensorRT 三者版本匹配，可以进入后续的序列化代码开发阶段。