3. 环境准备：硬件要求、CUDA/cuDNN/TensorRT版本兼容性、Docker镜像选择

TensorRT-LLM 的生产环境部署，第一步往往不是写代码，而是把底层环境“对齐”。很多线上事故——比如推理结果错误、显存越界、CUDA error、甚至容器启动即崩溃——根源都在环境版本不匹配。本章聚焦三个核心问题：硬件到底需要什么、CUDA/cuDNN/TensorRT 如何选版本、以及 Docker 镜像怎么选才不踩坑。

3.1 硬件要求：不只是“有张N卡就行”

TensorRT-LLM 对 GPU 架构有硬性要求。它依赖 TensorRT 的 kernel 自动调优与 Hopper/Ampere 架构特性，不支持 Maxwell、Pascal 等老架构。生产环境最低建议为 Ampere 架构（A100/A30/A10），最佳实践是 Hopper（H100/H200）或 Ada Lovelace（L40S/RTX 4090）。Blackwell（B200）需使用对应新版本镜像。

GPU 架构 代表型号 是否支持 备注
Volta V100 ❌ 不支持 缺少 FP8 与 Hopper 特性
Turing RTX 2080 Ti ⚠️ 部分支持 仅旧版 TensorRT-LLM 可用
Ampere A100 / A30 / A10 ✅ 支持 生产最低推荐
Hopper H100 / H200 ✅ 完整支持 FP8 最佳性能
Ada Lovelace L40S / RTX 4090 ✅ 完整支持 消费级可跑小模型

显存方面，除了模型权重本身，还需预留 KV Cache、激活值、CUDA context（约 300~600MB）。例如 7B FP16 模型权重约 14GB，生产部署建议至少 24GB 显存；若开启 FP8 则权重减半，但 KV Cache 可能增大。CPU 内存建议为显存的 1.5~2 倍，用于加载检查点与临时缓冲。

实操建议：使用 nvidia-smi 查看 GPU 架构与显存。若输出中 Compute Capability 低于 8.0，则 TensorRT-LLM 无法发挥完整性能，建议直接更换实例类型。

3.2 CUDA / cuDNN / TensorRT 版本兼容性矩阵

TensorRT-LLM 对 CUDA 版本非常敏感。它通过 CUDA 驱动 API 与运行时 API 访问 GPU，驱动版本必须 >= CUDA 运行时要求的最低驱动。cuDNN 用于优化卷积与注意力中的矩阵运算，TensorRT 则负责构建 engine。三者必须严格匹配，否则会出现 symbol lookup error 或 cudnn_ops_infer.so: undefined symbol。

以 TensorRT-LLM 0.10.0 为例，官方验证过的组合如下：

  • CUDA 12.2 + cuDNN 8.9.5 + TensorRT 9.2.1（主流生产组合）
  • CUDA 12.4 + cuDNN 8.9.7 + TensorRT 9.3.0（较新，支持 H200）
  • CUDA 11.8 + cuDNN 8.6.0 + TensorRT 8.6.1（旧版，仅用于 Ampere）

查看当前环境的 CUDA 版本：

nvcc --version          # 查看 CUDA 运行时版本
nvidia-smi | grep CUDA  # 查看驱动支持的最高 CUDA 版本
常见误区：很多人只装 CUDA 12.4，却忽略了 cuDNN 版本。TensorRT-LLM 在构建 engine 时会调用 cuDNN 的特定 API，若 cuDNN 版本过旧，会直接报 cudnnStatusNotInitialized。务必使用官方 Docker 镜像中锁定的 cuDNN 版本，不要自行升级。

3.3 Docker 镜像选择：直接使用 NGC 容器

手动在裸机上配置 CUDA/cuDNN/TensorRT 极易出错，且难以复现。生产环境强烈推荐使用 NVIDIA NGC 的 TensorRT-LLM Docker 镜像。这些镜像已经预装了匹配的 CUDA、cuDNN、TensorRT 以及 TensorRT-LLM 的 Python wheel，开箱即用。

镜像命名规则为：

nvcr.io/nvidia/tritonserver:<版本>-trtllm-python-<cuda版本>

例如：

nvcr.io/nvidia/tritonserver:24.05-trtllm-python-py3

拉取并启动容器：

docker pull nvcr.io/nvidia/tritonserver:24.05-trtllm-python-py3

docker run --gpus all -it --shm-size=2g --ulimit memlock=-1 \
  -v /data/models:/models \
  nvcr.io/nvidia/tritonserver:24.05-trtllm-python-py3 bash

进入容器后，验证环境：

python3 -c "import tensorrt_llm; print(tensorrt_llm.__version__)"
python3 -c "import torch; print(torch.cuda.get_device_name(0))"
选择策略：若使用 Triton 推理服务器，选择 tritonserver 标签；若仅需 TensorRT-LLM 的 Python API 做离线 engine 构建，可选择 tensorrt_llm 标签。两者底层一致，区别在于是否预装 Triton 后端。

3.4 案例：从裸机迁移到 Docker 的完整流程

某团队原先在裸机上部署 TensorRT-LLM，遇到以下问题：

  1. CUDA 驱动为 535.104，但 CUDA 12.2 需要 ≥ 535.54，勉强可用；
  2. cuDNN 被系统包管理器升级到 9.0，导致 TensorRT 9.2 无法加载；
  3. 多卡环境 NCCL 版本不匹配，AllReduce 报错。

迁移到 Docker 后，流程简化为：

# 宿主机只需安装 NVIDIA 驱动（≥ 535.104）
# 1. 拉取镜像
docker pull nvcr.io/nvidia/tritonserver:24.05-trtllm-python-py3

# 2. 启动容器并挂载模型目录
docker run -d --gpus all --ipc=host \
  -v /data/llama2-7b:/models/llama2-7b \
  -p 8000:8000 \
  nvcr.io/nvidia/tritonserver:24.05-trtllm-python-py3 \
  tritonserver --model-repository=/models

# 3. 验证推理
curl -X POST http://localhost:8000/v2/models/llama2-7b/generate \
  -d '{"text_input": "Hello, world!", "max_tokens": 64}'

整个迁移过程约 30 分钟，且后续环境完全可复现，不再出现“在我机器上能跑”的问题。

3.5 误区与复盘：版本对齐的隐性陷阱

误区一：只看 CUDA 版本，忽略驱动。 CUDA 12.2 要求驱动 ≥ 535.54，若宿主机驱动为 525，容器内 CUDA 无法正常工作。检查方法：nvidia-smi 右上角显示的 CUDA Version 是驱动支持的最高版本，必须 ≥ 容器内 CUDA 版本。

误区二：使用 pip 安装 tensorrt-llm 覆盖 NGC 镜像内的版本。 NGC 镜像内的 TensorRT-LLM 是经过完整测试的版本，pip 安装的 nightly build 可能引入不兼容的依赖。若必须更新，请先备份原镜像：

docker commit <容器名> trtllm-backup:latest

误区三：忽略共享内存设置。 TensorRT-LLM 的 KV Cache 与多进程通信依赖共享内存，默认 64MB 往往不够。启动容器时务必添加 --shm-size=2g 或 --ipc=host，否则会出现 Bus error 或 Cannot allocate memory。

误区四：在容器内运行 nvidia-smi 看到驱动版本与宿主机不一致就惊慌。 容器内 nvidia-smi 显示的是宿主机驱动版本，这是正常的。容器内不应安装驱动，只需安装 CUDA 工具包与运行时库。

复盘清单：每次部署前，按以下顺序检查——① GPU 架构是否 ≥ Ampere；② 宿主机驱动是否满足容器 CUDA 要求；③ 是否使用 NGC 官方镜像；④ 容器是否设置 --gpus all 与 --shm-size；⑤ 进入容器后执行 python3 -c "import tensorrt_llm" 验证。
TensorRT-LLM 生产环境版本兼容性总览 GPU 硬件层 • 架构 ≥ Ampere (CC 8.0) • 显存 ≥ 模型权重×1.5 • 推荐 Hopper / Ada • 多卡需 NVLink / PCIe NVIDIA 驱动 • 版本 ≥ CUDA 要求 • nvidia-smi 验证 • 容器内不装驱动 • 535.104+ 推荐 NGC Docker 容器 • tritonserver:24.05 • -trtllm-python-py3 • 预装 CUDA/cuDNN/TRT • --shm-size=2g 驱动 容器 容器内软件版本矩阵（必须严格匹配） CUDA 12.2 nvcc --version cuDNN 8.9.5 cudnn.h 版本 TensorRT 9.2.1 trtexec --version TRT-LLM 0.10.0 部署前验证命令 nvidia-smi # 驱动 ≥ 535.54 nvcc --version # CUDA 12.2 python3 -c "import tensorrt_llm" docker run --gpus all --shm-size=2g nvcr.io/nvidia/tritonserver:24.05 -trtllm-python-py3

上图总结了生产环境部署的完整链路：硬件层决定性能上限，驱动层是容器运行的前提，NGC 容器内锁定了 CUDA/cuDNN/TensorRT 的匹配版本。任何一层的版本漂移，都可能导致推理异常。建议将镜像 tag 记录在项目的 requirements.txt 或 Dockerfile 中，确保团队所有成员使用完全一致的环境。

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