📚 课程目录第4章环境搭建

4. 环境搭建：CUDA、cuDNN、TensorRT、TensorRT-LLM的安装与配置

4.1 核心原理：版本匹配是环境搭建的第一要务

TensorRT-LLM 并非一个独立运行的推理框架，而是构建在 CUDA、cuDNN、TensorRT 三层基础库之上的高性能推理加速组件。其底层通过 CUDA 驱动 GPU 计算，借助 cuDNN 优化卷积与矩阵运算，再经由 TensorRT 完成模型图优化与内核自动调优，最终由 TensorRT-LLM 提供面向大语言模型的 PagedAttention、KV Cache、In-flight Batching 等高级特性。因此，四者之间存在严格的版本依赖链：TensorRT-LLM 的每个发布版本都会声明其对应的 TensorRT 版本、CUDA 版本与 cuDNN 版本。若某一层版本不匹配，轻则编译失败，重则运行时出现 "undefined symbol" 或 "CUBLAS_STATUS_NOT_INITIALIZED" 等难以排查的错误。

以 TensorRT-LLM 0.10.0 版本为例，其官方要求 CUDA 12.4、cuDNN 8.9.6、TensorRT 10.1.0。若用户安装了 CUDA 12.2，虽然能完成 PyTorch 推理，但在编译 TensorRT-LLM 的 C++ 算子时就会因缺少 CUDA 12.4 的某些运行时库而失败。下图展示了四层组件之间的依赖关系与数据流方向：

4.2 方法流程：从驱动到 TensorRT-LLM 的分步安装

环境搭建遵循自底向上的顺序，每一步都需要验证通过后再进入下一步。以下是经过验证的完整安装流程：

步骤一：安装 NVIDIA 驱动与 CUDA

推荐使用 runfile 方式安装 CUDA，以便精确控制版本。首先通过 nvidia-smi 确认当前驱动版本，若驱动过旧，需先升级驱动。CUDA 安装完成后，需要配置环境变量：

# 下载 CUDA 12.4 runfile
wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda_12.4.0_550.54.14_linux.run
sudo sh cuda_12.4.0_550.54.14_linux.run --toolkit --silent --override

# 配置环境变量（写入 ~/.bashrc）
export PATH=/usr/local/cuda-12.4/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH
source ~/.bashrc

# 验证
nvcc --version   # 应显示 release 12.4
nvidia-smi       # 确认驱动与CUDA版本匹配

步骤二：安装 cuDNN

cuDNN 需要从 NVIDIA 官网下载对应 CUDA 12.4 的 deb 包或 tar 包。推荐使用 deb 包方式，便于后续卸载与升级：

# 下载 cudnn-linux-x86_64-8.9.6.50_cuda12-archive.tar.xz
tar -xvf cudnn-linux-x86_64-8.9.6.50_cuda12-archive.tar.xz
sudo cp cudnn-linux-x86_64-8.9.6.50_cuda12-archive/include/cudnn*.h /usr/local/cuda-12.4/include/
sudo cp cudnn-linux-x86_64-8.9.6.50_cuda12-archive/lib/libcudnn* /usr/local/cuda-12.4/lib64/
sudo chmod a+r /usr/local/cuda-12.4/include/cudnn*.h /usr/local/cuda-12.4/lib64/libcudnn*

# 验证
cat /usr/local/cuda-12.4/include/cudnn_version.h | grep CUDNN_MAJOR -A 2

步骤三：安装 TensorRT

TensorRT 10.1.0 提供 tar 包安装方式。解压后需要将库路径加入 LD_LIBRARY_PATH，并安装 Python 绑定：

# 下载 TensorRT-10.1.0.27.Linux.x86_64-gnu.cuda-12.4.tar.gz
tar -xzvf TensorRT-10.1.0.27.Linux.x86_64-gnu.cuda-12.4.tar.gz
export LD_LIBRARY_PATH=$PWD/TensorRT-10.1.0.27/lib:$LD_LIBRARY_PATH

# 安装 Python 绑定
pip install TensorRT-10.1.0.27/python/tensorrt-10.1.0-cp310-linux_x86_64.whl

# 验证
python -c "import tensorrt; print(tensorrt.__version__)"  # 应输出 10.1.0

步骤四：安装 TensorRT-LLM

TensorRT-LLM 提供预编译 wheel 包和源码编译两种方式。对于大多数场景，推荐直接使用官方发布的 wheel 包：

# 方式一：pip 安装预编译包（推荐）
pip install tensorrt_llm==0.10.0 --extra-index-url https://pypi.nvidia.com

# 方式二：源码编译（需要较长时间）
git clone https://github.com/NVIDIA/TensorRT-LLM.git
cd TensorRT-LLM
git checkout v0.10.0
git submodule update --init --recursive
make -C docker build
# 或直接使用 Docker 镜像

# 验证安装
python -c "import tensorrt_llm; print(tensorrt_llm.__version__)"

推荐做法：使用 NVIDIA 官方提供的 nvcr.io/nvidia/tritonserver:24.05-trtllm-python-py3 Docker 镜像。该镜像已预装全部依赖，只需拉取镜像并挂载模型目录即可，可避免 90% 的版本兼容性问题。

4.3 案例场景：基于 Docker 的快速环境搭建

以下是一个实际项目中使用的 Docker 环境搭建方案，适用于需要快速验证模型转换的场景：

# 拉取预构建镜像
docker pull nvcr.io/nvidia/tritonserver:24.05-trtllm-python-py3

# 启动容器并挂载模型目录
docker run -it --gpus all \
  --shm-size=2g \
  -v /data/models:/models \
  -v /data/engines:/engines \
  nvcr.io/nvidia/tritonserver:24.05-trtllm-python-py3 \
  bash

# 容器内验证环境
python -c "import tensorrt_llm; print('TRT-LLM:', tensorrt_llm.__version__)"
python -c "import tensorrt; print('TensorRT:', tensorrt.__version__)"
python -c "import torch; print('CUDA:', torch.version.cuda)"

该镜像内部已配置好 CUDA 12.4、cuDNN 8.9.6、TensorRT 10.1.0 以及 TensorRT-LLM 0.10.0，且各组件之间的符号链接均已正确设置。使用 Docker 方案后，原本需要 2～3 小时的环境配置时间可缩短至 10 分钟以内。

4.4 常见误区与排障复盘

在实际部署中，以下问题出现频率最高，需要特别留意：

误区/错误	典型现象	根因分析	解决方案
仅安装 CUDA 12.4 但驱动过旧	nvcc 正常但运行时报 "CUDA driver version is insufficient"	CUDA Toolkit 与驱动版本不匹配	升级驱动至 ≥ 550.54.14
cuDNN 头文件与库文件版本不一致	编译时报 "cudnn.h: No such file" 或链接错误	头文件与 lib 文件来自不同版本	统一使用同一版本包覆盖安装
TensorRT Python 绑定与 C++ 库路径冲突	import tensorrt 报 "libnvinfer.so.10: cannot open"	LD_LIBRARY_PATH 未包含 TensorRT lib 目录	export LD_LIBRARY_PATH 并重新登录 shell
pip 安装 tensorrt_llm 时静默降级 TensorRT	安装后 tensorrt.__version__ 变为 8.x	pip 依赖解析将 TensorRT 降级	使用 --extra-index-url 并锁定版本
多 CUDA 版本共存时 PATH 指向错误	nvcc 显示 11.8 而非 12.4	~/.bashrc 中 PATH 顺序错误	确保 /usr/local/cuda-12.4/bin 在 PATH 最前

重要提醒：不要使用 apt install nvidia-cuda-toolkit 安装 CUDA，Ubuntu 源中的 CUDA 版本通常滞后且不完整。务必从 NVIDIA 官方仓库下载对应版本的 runfile 或 deb 包。此外，TensorRT-LLM 的 wheel 包仅支持 Python 3.10 及以上版本，使用 Python 3.8 会导致安装失败。

4.5 环境验证清单

完成安装后，建议按以下清单逐项验证，确保所有组件协同工作：

驱动层：nvidia-smi 显示 GPU 型号与驱动版本 ≥ 550.54.14
CUDA 层：nvcc --version 显示 release 12.4，且 ls /usr/local/cuda-12.4/lib64/libcudart.so.12 存在
cuDNN 层：cat /usr/local/cuda-12.4/include/cudnn_version.h | grep CUDNN_MAJOR 输出 8
TensorRT 层：python -c "import tensorrt; print(tensorrt.__version__)" 输出 10.1.0
TensorRT-LLM 层：python -c "import tensorrt_llm; print(tensorrt_llm.__version__)" 输出 0.10.0
端到端验证：运行 trtexec --onnx=/path/to/model.onnx --saveEngine=/tmp/test.engine 确认 TensorRT 能正常解析 ONNX 模型