环境搭建：安装NVIDIA驱动、CUDA、cuDNN、TensorRT、TensorRT-LLM，配置Docker容器

TensorRT-LLM 的编译与推理高度依赖底层 GPU 计算栈。很多初学者在模型编译阶段遇到“段错误”“符号找不到”或“版本不匹配”等问题，根源往往不是代码写错，而是宿主机的驱动、CUDA 运行时、TensorRT 库与 TensorRT-LLM 的预期版本不一致。本节将梳理从 NVIDIA 驱动到 Docker 容器的完整安装链路，并给出经过验证的版本组合与配置方法。

2.1 核心原理：软件栈的层次关系与版本耦合

TensorRT-LLM 并非独立运行的软件，它构建在多层基础库之上。理解各层之间的依赖关系，是避免环境问题的第一步。下图展示了从硬件到应用层的完整调用链：

从上图可以看出，驱动是唯一直接与硬件交互的组件，而 CUDA、TensorRT、TensorRT-LLM 均运行在用户态。Docker 容器共享宿主机的驱动与内核模块，因此容器内只需安装 CUDA 工具包、cuDNN、TensorRT 及 TensorRT-LLM，无需重复安装驱动。

2.2 方法流程：分步安装与验证

步骤一：安装 NVIDIA 驱动

推荐使用 nvidia-driver-535 或更高版本。在 Ubuntu 22.04 上执行：

# 添加 NVIDIA 官方驱动源
sudo add-apt-repository ppa:graphics-drivers/ppa
sudo apt update

# 安装驱动（535 或更高版本）
sudo apt install -y nvidia-driver-535

# 重启后验证
nvidia-smi
# 应显示 GPU 型号、驱动版本、CUDA 版本（如 12.2）

步骤二：安装 CUDA 工具包

TensorRT-LLM 0.10+ 要求 CUDA ≥ 12.2。推荐使用 runfile 方式安装，避免污染系统包管理器：

# 下载 CUDA 12.2（或 12.4）
wget https://developer.download.nvidia.com/compute/cuda/12.2.0/local_installers/cuda_12.2.0_535.54.03_linux.run

# 执行安装（仅安装工具包，不安装驱动）
sudo sh cuda_12.2.0_535.54.03_linux.run --toolkit --silent --override

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

# 验证
nvcc --version  # 应显示 release 12.2

步骤三：安装 cuDNN 与 TensorRT

cuDNN 和 TensorRT 需要从 NVIDIA 官网下载（需注册账号）。下载后使用 dpkg 安装：

# 安装 cuDNN 8.9+（以 .deb 包为例）
sudo dpkg -i cudnn-local-repo-ubuntu2204-8.9.7.29_1.0-1_amd64.deb
sudo cp /var/cudnn-local-repo-ubuntu2204-8.9.7.29/cudnn-local-*-keyring.gpg /usr/share/keyrings/
sudo apt update
sudo apt install -y libcudnn8 libcudnn8-dev

# 安装 TensorRT 10.3+
sudo dpkg -i nv-tensorrt-local-repo-ubuntu2204-10.3.0_1.0-1_amd64.deb
sudo cp /var/nv-tensorrt-local-repo-ubuntu2204-10.3.0/nv-tensorrt-local-*-keyring.gpg /usr/share/keyrings/
sudo apt update
sudo apt install -y tensorrt

# 验证 TensorRT
python3 -c "import tensorrt as trt; print(trt.__version__)"  # 应输出 10.3.0

步骤四：配置 Docker 容器

使用 NVIDIA Container Toolkit 让容器访问 GPU：

# 安装 NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt update
sudo apt install -y nvidia-container-toolkit

# 重启 Docker
sudo systemctl restart docker

# 拉取 TensorRT-LLM 官方镜像（推荐）
docker pull nvcr.io/nvidia/tensorrt-llm:latest

# 启动容器并挂载代码目录
docker run --gpus all -it --rm \
  -v /path/to/your/code:/workspace \
  nvcr.io/nvidia/tensorrt-llm:latest

2.3 案例：从零搭建可运行的编译环境

以下是一个经过验证的完整环境配置清单，适用于 Ubuntu 22.04 + A100/H100 服务器：

进入容器后，建议先运行一个简单的 TensorRT-LLM 示例验证环境：

# 在容器内执行
cd /workspace
python3 -c "
from tensorrt_llm import LLM
import tensorrt as trt
print('TensorRT-LLM 版本:', LLM.__version__)
print('TensorRT 版本:', trt.__version__)
print('环境验证通过！')
"

2.4 误区与复盘：常见环境问题排查

• 误区一：驱动版本过旧。TensorRT-LLM 的某些内核需要驱动 ≥ 535 才能使用新的 CUDA 特性。若 nvidia-smi 显示驱动低于 525，请先升级驱动。
• 误区二：CUDA 版本不匹配。TensorRT-LLM 编译时依赖 CUDA 12.x 的头文件。若使用 CUDA 11.x，会出现 cuda_runtime.h 找不到或 __CUDA_ARCH_LIST__ 未定义等错误。
• 误区三：在容器内重复安装驱动。容器共享宿主机内核，安装驱动会报错或导致容器无法启动。正确做法是宿主机装驱动，容器内只装 CUDA 工具包和库。
• 误区四：忽略 cuDNN 版本。TensorRT-LLM 的卷积和注意力实现依赖 cuDNN 8.9+。若 cuDNN 版本过低，运行时会报 cudnnStatusNotInitialized 错误。
• 误区五：使用 pip 安装 TensorRT-LLM 但未安装 TensorRT。TensorRT-LLM 的 Python wheel 包不会自动安装 TensorRT，需要手动安装匹配版本的 TensorRT 库。

# 宿主机检查
nvidia-smi | grep "Driver Version"
# 容器内检查
python3 -c "import tensorrt_llm, tensorrt, torch; print('TRT-LLM:', tensorrt_llm.__version__); print('TRT:', tensorrt.__version__); print('PyTorch:', torch.__version__)"