3、环境搭建：GPU服务器配置、CUDA/cuDNN/TensorRT-LLM安装、Docker容器化部署

3.1 环境搭建的核心原则：版本匹配是生命线

TensorRT-LLM 的低延迟性能高度依赖 GPU 硬件特性（如 FP8、Tensor Core）与软件栈的深度协同。环境搭建的核心并非“装最新”，而是“装匹配”。一个典型的失败案例是：开发者安装了 CUDA 12.4，但 TensorRT-LLM 的预编译 Wheel 包基于 CUDA 12.2 构建，导致运行时出现 libcudart.so.12.2 缺失错误。因此，动手前必须锁定三组版本关系：GPU 驱动版本 → CUDA 运行时版本 → TensorRT-LLM 版本。驱动版本需向下兼容 CUDA 运行时，而 TensorRT-LLM 的官方 Release 页面会明确标注其依赖的 CUDA、cuDNN 和 TensorRT 版本。

推荐基线（以 TensorRT-LLM 0.10.0 为例）：
  • GPU：NVIDIA A100/A800（80GB）或 H100/H800，显存建议 ≥ 40GB（用于 7B~13B 模型 FP16 推理）
  • 驱动：≥ 535.104.05（支持 CUDA 12.2）
  • CUDA：12.2（不要使用 12.3+，除非自行源码编译）
  • cuDNN：8.9.5（对应 CUDA 12.x）
  • TensorRT：9.2.0（TensorRT-LLM 内置依赖，无需单独安装）
  • 操作系统：Ubuntu 22.04 LTS（内核 ≥ 5.15）
TensorRT-LLM 环境依赖匹配关系 GPU 硬件 A100 / H100 / L40S NVIDIA 驱动 ≥ 535.104.05 CUDA 12.2 nvcc + 运行时 TensorRT-LLM 0.10.0 (Wheel) Docker 容器边界 TensorRT-LLM Python Runtime CUDA 12.2 cudart + cublas cuDNN 8.9.5 深度卷积加速 TensorRT 9.2 引擎执行层 驱动调用 API 映射 运行时依赖 关键检查点 驱动版本 ≥ CUDA 要求 CUDA 必须为 12.2 cuDNN 版本精确匹配 容器内无需装驱动 nvidia-smi 验证穿透 ldd 检查 .so 链接 版本不匹配 → 段错误或 CUDA error: no kernel image

3.2 方法流程：从裸机到容器化部署

环境搭建遵循“宿主机最小化 + 容器内完整化”的策略。宿主机仅需安装 GPU 驱动和容器运行时（如 Docker + NVIDIA Container Toolkit），而 CUDA、cuDNN、TensorRT-LLM 全部封装进镜像，保证可移植性与可复现性。具体步骤如下：

  1. 宿主机驱动安装：通过 nvidia-smi 确认驱动可用。若未安装，使用 sudo apt install nvidia-driver-535 或从 NVIDIA 官网下载 runfile 安装，安装后重启并验证。
  2. 安装 Docker Engine：配置官方 apt 源后安装 docker-ce docker-ce-cli containerd.io，并将当前用户加入 docker 组。
  3. 安装 NVIDIA Container Toolkit：该工具让容器能访问 GPU 设备。安装后需重启 Docker 服务。
  4. 拉取 TensorRT-LLM 官方镜像：NVIDIA 提供预构建镜像，包含完整依赖链，推荐直接使用。
  5. 启动容器并挂载模型目录：使用 --gpus all 参数启用 GPU 访问，通过 -v 挂载预训练模型权重与输出目录。
# 宿主机验证驱动
nvidia-smi
# 输出应显示 GPU 型号与驱动版本，如 Driver Version: 535.104.05

# 安装 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-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

# 拉取并启动 TensorRT-LLM 容器
docker run --gpus all -it --shm-size=16g \
  -v /data/models:/models \
  -v /data/engines:/engines \
  -p 8000:8000 \
  nvcr.io/nvidia/tensorrt-llm:24.05-py3
关键参数说明：
  • --shm-size=16g：TensorRT-LLM 的 KV Cache 与多进程通信依赖共享内存，默认 64MB 会导致 OOM。
  • -p 8000:8000：暴露推理服务端口，供客户端调用。
  • --gpus all：将全部 GPU 传入容器；若需指定，使用 --gpus '"device=0,1"'。

3.3 案例：基于 Docker 的 TensorRT-LLM 快速验证

以下演示一个完整的“容器内验证”流程，确保环境可用。假设已拉取镜像并进入容器，执行以下命令验证 TensorRT-LLM 是否正常工作：

# 进入容器后检查 CUDA 运行时
python3 -c "import torch; print('CUDA available:', torch.cuda.is_available())"
# 期望输出: CUDA available: True

# 检查 TensorRT-LLM 版本
python3 -c "import tensorrt_llm; print('TensorRT-LLM version:', tensorrt_llm.__version__)"

# 运行官方示例（GPT-2 125M 模型）
cd /app/tensorrt_llm/examples/gpt
python3 build.py --model_dir=gpt2 --output_dir=/engines/gpt2 \
  --dtype=float16 --use_gpt_attention_plugin=float16

# 推理测试
python3 run.py --engine_dir=/engines/gpt2 --max_output_len=50 \
  --input_text="The future of AI is"

若上述命令成功输出生成的文本，说明环境搭建完成。实际生产环境中，建议将模型构建（Engine Build）与推理服务分离：构建阶段使用 GPU 资源密集的容器，推理阶段使用轻量化运行时容器，两者共享同一引擎文件目录。

验证项 命令 预期结果
GPU 穿透 nvidia-smi 显示 GPU 型号与显存
CUDA 可用 python3 -c "import torch; print(torch.cuda.is_available())" True
TensorRT-LLM 导入 python3 -c "import tensorrt_llm" 无报错
引擎构建 python3 build.py ... 生成 .engine 文件
推理输出 python3 run.py ... 返回连贯文本

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

环境搭建阶段最容易踩坑，以下总结高频问题与解决路径：

误区一：盲目升级 CUDA 版本
现象：安装 CUDA 12.4 后，TensorRT-LLM 报 undefined symbol: cublasLtMatmulDescSetAttribute。
原因：预编译 Wheel 链接的是 CUDA 12.2 的 cuBLAS 库，版本不匹配导致符号缺失。
解决：严格使用官方要求的 CUDA 12.2，或从源码编译 TensorRT-LLM 以适配更高版本。
误区二：容器内重复安装驱动
现象：容器启动时提示 could not select device driver "" with capabilities: [[gpu]]。
原因：宿主机未安装 NVIDIA Container Toolkit，或容器内误装驱动导致冲突。
解决：宿主机执行 sudo nvidia-ctk runtime configure 后重启 Docker；容器内绝不安装驱动。
误区三：忽略共享内存限制
现象：推理时出现 RuntimeError: CUDA out of memory，但 nvidia-smi 显示显存充足。
原因：KV Cache 分配在共享内存中，默认 /dev/shm 仅 64MB。
解决：启动容器时添加 --shm-size=16g 或更大值。

复盘建议：在项目初期，建议编写一个 check_env.sh 脚本，自动检测驱动版本、CUDA 版本、容器 GPU 穿透状态，并输出诊断报告。将脚本纳入 CI/CD 流程，确保每次环境重建后的一致性。同时，将 Dockerfile 与依赖清单（requirements.txt）纳入版本控制，避免“在我机器上能跑”的尴尬。

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