4. 环境搭建

TensorRT-LLM 的部署链路对底层软件栈的版本匹配极其敏感。很多“模型跑不起来”或“推理结果错误”的问题，根源并非代码逻辑，而是 CUDA、cuDNN、TensorRT 与 TensorRT-LLM 之间的版本错位。本节将梳理一条经过验证的安装路径，并给出每一步的验证方法，帮助你建立一个可复现、可诊断的基础环境。

4.1 核心原理：版本矩阵与依赖关系

在动手安装之前，必须先理解这四层软件的关系。CUDA 是底层驱动与并行计算平台，cuDNN 基于 CUDA 提供深度神经网络加速原语，TensorRT 在 cuDNN 之上做模型推理优化，而 TensorRT-LLM 则是一个依赖 TensorRT 的 Python/C++ 库，专门针对大语言模型的解码特性（如 KV Cache、Paged Attention、In-flight Batching）进行定制。

这种层层依赖的关系决定了：TensorRT-LLM 的版本决定了它支持哪个 TensorRT 版本，而 TensorRT 又决定了它需要哪个 CUDA 版本。因此，安装顺序必须自底向上，且不能随意混搭。NVIDIA 官方为 TensorRT-LLM 提供了 Docker 镜像，但生产环境中往往需要裸机安装，此时版本矩阵就是你的“地图”。

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

以下安装流程以 Ubuntu 22.04 + CUDA 12.1 + cuDNN 8.9 + TensorRT 10.0 + TensorRT-LLM 0.10 为例。请根据你实际下载的版本号替换对应命令。

步骤 1：安装 NVIDIA 驱动与 CUDA

首先确认 GPU 型号与当前驱动状态：

nvidia-smi
# 若显示 "No devices were found"，则需先安装驱动
# 推荐使用 runfile 方式安装 CUDA 12.1（内含匹配驱动）
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run --toolkit --silent --override

安装完成后，配置环境变量：

echo 'export PATH=/usr/local/cuda-12.1/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
nvcc --version   # 验证 CUDA 工具链

步骤 2：安装 cuDNN

cuDNN 需要从 NVIDIA 官网下载（需登录账号）。下载 cuDNN v8.9.5 for CUDA 12.x 的 Local Installer for Ubuntu22.04 x86_64（Debian 包）：

sudo dpkg -i cudnn-local-repo-ubuntu2204-8.9.5.29_1.0-1_amd64.deb
sudo cp /var/cudnn-local-repo-ubuntu2204-8.9.5.29/cudnn-local-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get install libcudnn8 libcudnn8-dev libcudnn8-samples

验证 cuDNN 是否安装成功：

cp -r /usr/src/cudnn_samples_v8/ $HOME/
cd $HOME/cudnn_samples_v8/mnistCUDNN
make clean && make
./mnistCUDNN   # 输出 "Test passed!" 即成功

步骤 3：安装 TensorRT

从 NVIDIA 官网下载 TensorRT 10.0 GA 的 TensorRT-10.0.1.6.Ubuntu-22.04.x86_64-gnu.cuda-12.1.tar.gz：

tar -xzvf TensorRT-10.0.1.6.Ubuntu-22.04.x86_64-gnu.cuda-12.1.tar.gz
sudo mv TensorRT-10.0.1.6 /opt/tensorrt
echo 'export LD_LIBRARY_PATH=/opt/tensorrt/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
echo 'export PATH=/opt/tensorrt/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 安装 Python 接口
pip install /opt/tensorrt/python/tensorrt-10.0.1-cp310-none-linux_x86_64.whl

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

步骤 4：安装 TensorRT-LLM

TensorRT-LLM 推荐使用源码编译或预编译 wheel。以下为源码编译方式：

git clone https://github.com/NVIDIA/TensorRT-LLM.git
cd TensorRT-LLM
git checkout v0.10.0
git submodule update --init --recursive
pip install -r requirements.txt

# 编译安装
python3 scripts/build_wheel.py -a 90   # 90 对应 A100/H100，80 对应 A30/A40
pip install ./build/tensorrt_llm-0.10.0-py3-none-any.whl

4.3 案例：一次完整的安装验证流程

以下是一个真实场景的验证脚本，用于确认整个软件栈可以协同工作。将以下内容保存为 verify_stack.py：

import ctypes
import tensorrt as trt
import torch

# 1. 检查 CUDA 可用性
assert torch.cuda.is_available(), "CUDA 不可用"
print(f"CUDA 版本: {torch.version.cuda}")
print(f"GPU 名称: {torch.cuda.get_device_name(0)}")

# 2. 检查 cuDNN 版本
cudnn = ctypes.CDLL("libcudnn.so.8")
cudnn.cudnnGetVersion.restype = ctypes.c_size_t
print(f"cuDNN 版本: {cudnn.cudnnGetVersion()}")

# 3. 检查 TensorRT 版本
print(f"TensorRT 版本: {trt.__version__}")

# 4. 简单推理测试
logger = trt.Logger(trt.Logger.WARNING)
builder = trt.Builder(logger)
network = builder.create_network()
print("TensorRT 引擎创建成功，软件栈验证通过！")

运行该脚本，预期输出如下：

CUDA 版本: 12.1
GPU 名称: NVIDIA A100-SXM4-40GB
cuDNN 版本: 8905
TensorRT 版本: 10.0.1.6
TensorRT 引擎创建成功，软件栈验证通过！

若在最后一步出现 ImportError: libcudnn.so.8: cannot open shared object file，说明 cuDNN 的库路径未正确加入 LD_LIBRARY_PATH。此时执行：

sudo ldconfig /usr/local/cuda-12.1/lib64
export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH

4.4 常见误区与复盘

复盘一个典型的失败案例：某同学在 Ubuntu 20.04 上安装了 CUDA 11.8，然后尝试编译 TensorRT-LLM 0.10（该版本要求 CUDA 12.x）。编译过程在 cmake 阶段报错，提示找不到 cuda_runtime.h 的特定版本宏。排查后发现，TensorRT-LLM 的 CMakeLists 中硬编码了 CUDA 12 的架构特性。最终解决方案是彻底卸载 CUDA 11.8，重装 12.1 后编译一次通过。

另一个高频问题是 Python 环境混乱。TensorRT-LLM 依赖 PyTorch 2.1+，且要求 CUDA 版本的 PyTorch 与系统 CUDA 一致。建议使用 conda create -n trt_llm python=3.10 创建独立环境，然后按顺序安装 PyTorch（pip install torch==2.1.0 --index-url https://download.pytorch.org/whl/cu121）、TensorRT 和 TensorRT-LLM，避免系统级 Python 环境的相互污染。