3. 环境搭建：GPU驱动、CUDA、cuDNN、TensorRT-LLM安装与验证

TensorRT-LLM 的部署环境并非简单的“装个包”就能完成，它是一条从硬件到软件、从驱动到推理引擎的完整依赖链。任何一个环节的版本错位，都会在运行时以极其晦涩的错误（如 symbol lookup error 或 CUDA driver version is insufficient）暴露出来。本节将按照依赖顺序，梳理从 GPU 驱动到 TensorRT-LLM 验证的完整搭建路径，并给出可复用的检查方法。

3.1 核心原理：依赖链与版本匹配逻辑

TensorRT-LLM 的底层调用关系可以概括为：GPU 硬件 → 内核驱动 → CUDA 运行时 → cuDNN/TensorRT → TensorRT-LLM Python 层。每一层只与相邻层通信，但版本兼容性却需要跨层对齐。

  • GPU 驱动：负责与硬件直接交互，其版本决定了系统支持的最高 CUDA 版本。驱动是“天花板”，CUDA 版本不能高于驱动支持的最高版本。
  • CUDA：包含运行时库（libcudart）和开发工具。TensorRT-LLM 编译时需要 CUDA 工具链，运行时需要 CUDA 驱动库（libcuda，由驱动提供）。
  • cuDNN：深度神经网络加速库，TensorRT-LLM 中的卷积、归一化等算子会调用它。cuDNN 版本必须与 CUDA 版本严格对应。
  • TensorRT-LLM：基于 TensorRT 构建，但 TensorRT-LLM 的 pip 包通常已捆绑或自动依赖特定版本的 TensorRT，无需单独安装。
关键认知：驱动与 CUDA 的关系是“向下兼容”。例如，Driver 535.104 支持 CUDA 12.2，但如果你安装了 CUDA 12.4 的运行时，系统会报错。因此，先定驱动，再定 CUDA，最后定 cuDNN 和 TensorRT-LLM 是唯一正确的顺序。
TensorRT-LLM 环境依赖链与版本验证路径 ① GPU 驱动 nvidia-smi 显示版本 | 决定 CUDA 上限（如 535.104 → CUDA 12.2） 验证: nvidia-smi ② CUDA 工具包 nvcc --version | 需 ≤ 驱动支持的最高版本 | 包含 nvcc 编译器 验证: nvcc -V ③ cuDNN libcudnn.so 版本 | 必须与 CUDA 版本匹配（如 8.9.x for CUDA 12.x） 验证: dpkg -l | grep cudnn ④ TensorRT-LLM pip 安装 | 自动依赖 TensorRT 8.6+ | 需 Python 3.8-3.11 验证: python -c "import tensorrt_llm" 推荐版本组合（示例） Driver: 535.104+ CUDA: 12.2 cuDNN: 8.9.2 TensorRT-LLM: 0.7.x Python: 3.10 ⚠ 版本不匹配时： • 驱动低于 CUDA 需求 → "CUDA driver too old" • cuDNN 与 CUDA 不匹配 → "libcudnn.so: undefined symbol"

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

步骤 1：确认 GPU 驱动与硬件

执行 nvidia-smi，确认驱动版本和 GPU 型号。若驱动过旧，需先升级驱动。推荐使用 NVIDIA 官方 runfile 或发行版仓库安装，避免使用系统自带的旧版驱动。

# 检查驱动与 GPU
nvidia-smi
# 输出示例：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 535.104.05   Driver Version: 535.104.05   CUDA Version: 12.2     |
# +-----------------------------------------------------------------------------+
# | GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
# |   0  NVIDIA A100-PCIE-40GB    On  | 00000000:3B:00.0 Off |                 0 |
# +-----------------------------------------------------------------------------+
注意：如果 nvidia-smi 显示 CUDA Version: N/A，说明驱动未正确加载或驱动版本过旧。此时不要继续安装 CUDA，先解决驱动问题。

步骤 2：安装 CUDA 工具包

根据驱动支持的 CUDA 版本，从 NVIDIA 官网下载对应版本的 runfile 或 deb 包。安装后设置环境变量。

# 以 CUDA 12.2 为例（runfile 方式）
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

# 添加环境变量到 ~/.bashrc
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 -V

步骤 3：安装 cuDNN

cuDNN 需要注册 NVIDIA 开发者账号才能下载。下载与 CUDA 版本匹配的 cuDNN 包，解压后复制到 CUDA 目录。

# 以 cuDNN 8.9.2 for CUDA 12.x 为例
tar -xzvf cudnn-linux-x86_64-8.9.2.26_cuda12-archive.tar.xz
sudo cp cudnn-linux-x86_64-8.9.2.26_cuda12-archive/include/cudnn*.h /usr/local/cuda-12.2/include/
sudo cp cudnn-linux-x86_64-8.9.2.26_cuda12-archive/lib/libcudnn* /usr/local/cuda-12.2/lib64/
sudo chmod a+r /usr/local/cuda-12.2/include/cudnn*.h /usr/local/cuda-12.2/lib64/libcudnn*

# 验证
dpkg -l | grep cudnn  # 或检查库文件
ls /usr/local/cuda-12.2/lib64/libcudnn.so*

步骤 4：安装 TensorRT-LLM

TensorRT-LLM 提供 pip 包，但强烈建议使用 官方 Docker 镜像 或 预编译 wheel，避免源码编译带来的复杂依赖问题。

# 方式一：使用官方 Docker（推荐）
docker pull nvcr.io/nvidia/tensorrt-llm:latest
docker run --gpus all -it --rm nvcr.io/nvidia/tensorrt-llm:latest

# 方式二：pip 安装（需预先安装 CUDA 和 cuDNN）
pip install tensorrt-llm

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

3.3 案例：一次完整的安装验证过程

以下是一个实际部署场景的完整验证流程，假设目标机器为 A100 GPU，操作系统为 Ubuntu 22.04。

检查项 命令 预期结果 失败排查方向
GPU 驱动 nvidia-smi 显示 A100，驱动 ≥ 535 重新安装驱动，检查 PCIe 插槽
CUDA 编译器 nvcc -V release 12.2 检查 PATH 是否指向正确 CUDA
cuDNN 库 ls /usr/local/cuda/lib64/libcudnn.so 文件存在且链接正确 重新复制 cuDNN 库文件
TensorRT-LLM python -c "import tensorrt_llm" 无报错，打印版本号 检查 Python 版本、依赖冲突
GPU 计算能力 python -c "import torch; print(torch.cuda.get_device_capability())" (8, 0) 表示 A100 确认 PyTorch 与 CUDA 匹配

3.4 误区与复盘：常见安装陷阱

误区 1：盲目安装最新版 CUDA
最新版 CUDA 往往要求更高版本的驱动。如果驱动停留在 535，安装 CUDA 12.4 会导致运行时错误。正确做法是先查驱动支持的最高 CUDA 版本（nvidia-smi 右上角会显示），再选择匹配的 CUDA。
误区 2：忽略 cuDNN 的符号链接
复制 cuDNN 文件后，需要确保 libcudnn.so 指向具体的版本文件。如果缺少符号链接，TensorRT-LLM 加载时会报 libcudnn.so.8: cannot open shared object file。修复方法： 
sudo ldconfig
# 或手动创建软链接
sudo ln -sf /usr/local/cuda/lib64/libcudnn.so.8 /usr/local/cuda/lib64/libcudnn.so
误区 3：使用系统 Python 环境
系统自带的 Python 3.8 或 3.12 可能与 TensorRT-LLM 不兼容。TensorRT-LLM 官方支持 Python 3.8-3.11。建议使用 conda 创建独立环境： 
conda create -n trt-llm python=3.10
conda activate trt-llm
pip install tensorrt-llm

复盘总结：环境搭建的失败案例中，80% 以上源于版本不匹配而非操作错误。建议在安装前先记录驱动版本，然后反向推导 CUDA、cuDNN 的兼容版本。安装完成后，务必执行一次完整的验证命令链（nvidia-smi → nvcc -V → import tensorrt_llm），确保每一层都正确链接。最后，推荐将环境固化为 Docker 镜像，以便在多台机器上快速复现，也为后续多租户隔离部署打下基础。

← 上一章 📖 返回目录 下一章 →