4. 环境准备：安装 TensorRT-LLM、配置 GPU、依赖库版本

精度损失排查的第一步，是确保你拥有一套可复现、版本可控、硬件就绪的实验环境。很多“精度异常”最终被追溯为环境不一致——例如 CUDA 版本不同导致算子选择差异、cuDNN 版本不同导致卷积算法数值抖动、TensorRT-LLM 版本不同导致层融合策略变化。本章将系统讲解 TensorRT-LLM 的安装路径、GPU 运行配置以及依赖库的版本锁定策略，为后续所有精度对比实验打下坚实基础。

4.1 核心原理：为什么环境版本会直接影响数值结果

TensorRT-LLM 的推理管线涉及多层软件栈：GPU 驱动 → CUDA 运行时 → cuBLAS/cuDNN/cuFFT → TensorRT-LLM 构建器 → 引擎执行。每一层都可能影响最终浮点计算结果：

• cuBLAS 的 GEMM 算法选择：不同算法（如 split-K、stream-K）在 FP16 下累加顺序不同，导致舍入误差累积路径不同，输出可能相差 1~2 个 ULP。
• cuDNN 的卷积/注意力实现：FlashAttention 与 Memory-Efficient Attention 在数值上并非完全一致，尤其在 head dimension 较大时。
• TensorRT-LLM 的层融合策略：QKV 融合、残差融合、激活函数融合会改变中间张量的存储精度和计算顺序，直接影响数值轨迹。
• CUDA 版本：CUDA 12.x 与 11.x 在 FP16 乘加指令的调度上存在差异，部分算子会使用不同的 PTX/SASS 指令序列。

因此，精度排查环境必须满足“三固定”原则：固定 TensorRT-LLM 版本、固定 CUDA/cuDNN 版本、固定 GPU 型号（或至少固定 GPU 架构，如 Ampere/Ada/Hopper）。任何一项漂移，都会让“精度对比”失去意义。

4.2 方法流程：TensorRT-LLM 安装与 GPU 配置

4.2.1 GPU 驱动与 CUDA 版本确认

TensorRT-LLM 官方支持 CUDA 12.x（推荐 12.4+）。首先确认驱动版本满足 CUDA 12.4 的最低要求（Linux 驱动 ≥ 535.104.05）。使用以下命令检查：

# 检查驱动与 CUDA 版本
nvidia-smi
# 输出示例：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 550.54.15    Driver Version: 550.54.15    CUDA Version: 12.4    |
# +-----------------------------------------------------------------------------+

# 检查 GPU 算力（Compute Capability）
python -c "import torch; print(torch.cuda.get_device_capability(0))"
# 例如 (8, 9) 代表 Ada Lovelace 架构，(9, 0) 代表 Hopper

如果驱动版本过低，需要先升级驱动。注意：驱动升级后必须重启系统，否则新驱动不会生效。

4.2.2 使用 Docker 安装（推荐路径）

官方 Docker 镜像已经锁定了 CUDA、cuDNN、TensorRT 的兼容版本，是精度排查最稳妥的起点。推荐使用 nvcr.io/nvidia/tensorrt-llm 镜像：

# 拉取 TensorRT-LLM 官方镜像（以 v0.13.0 为例）
docker pull nvcr.io/nvidia/tensorrt-llm:latest

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

进入容器后，验证 TensorRT-LLM 是否可用：

python -c "import tensorrt_llm; print(tensorrt_llm.__version__)"
# 输出示例：0.13.0

4.2.3 源码编译安装（需要定制时使用）

如果需要修改 TensorRT-LLM 源码或调试底层算子，则需源码编译。编译前务必确认以下依赖版本：

源码编译的关键步骤：

# 1. 克隆仓库并切换到指定 tag
git clone https://github.com/NVIDIA/TensorRT-LLM.git
cd TensorRT-LLM
git checkout v0.13.0

# 2. 初始化子模块
git submodule update --init --recursive

# 3. 创建 conda 环境（Python 3.10）
conda create -n trtllm python=3.10
conda activate trtllm

# 4. 安装 PyTorch（务必与 CUDA 12.4 匹配）
pip install torch==2.3.1 --index-url https://download.pytorch.org/whl/cu124

# 5. 编译安装 TensorRT-LLM
python setup.py install

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

4.2.4 GPU 运行配置

精度排查时，GPU 的运行状态会影响数值稳定性。建议在实验前执行以下配置：

# 锁定 GPU 时钟频率，避免动态调频导致性能波动
sudo nvidia-smi -lgc 1500,1500   # 将 GPU 时钟锁定在 1500 MHz（根据型号调整）

# 关闭 ECC（如果 GPU 支持且允许）
# 注意：关闭 ECC 会降低内存纠错能力，仅建议在短期实验中使用
sudo nvidia-smi -e 0

# 设置持久化模式，减少上下文切换开销
sudo nvidia-smi -pm 1

# 查看 GPU 利用率与温度，确保没有过热降频
watch -n 1 nvidia-smi

对于多卡环境，还需设置 NCCL 环境变量以控制通信行为：

export NCCL_DEBUG=INFO          # 打印 NCCL 初始化与通信日志
export NCCL_IB_DISABLE=1        # 如果无 InfiniBand，关闭 IB 避免超时
export NCCL_P2P_DISABLE=0       # 保持 P2P 通信（多卡精度对比时需要）

4.3 案例：一次因环境不一致导致的“假精度损失”

某团队在对比 TensorRT-LLM FP16 推理与 PyTorch FP16 推理的精度时，发现 TensorRT-LLM 输出的最大绝对误差达到 0.05，远超预期阈值 0.01。团队花费两天时间排查模型结构、量化参数，均未发现问题。

最终复盘时发现：

• PyTorch 环境运行在 CUDA 11.8 上，而 TensorRT-LLM 环境使用 CUDA 12.4。
• 两个环境中的 cuBLAS 版本不同，导致 GEMM 算法选择不同：CUDA 11.8 使用了 split-K=2 的算法，而 CUDA 12.4 使用了 stream-K 算法。
• 两种算法在 FP16 下的累加顺序不同，导致舍入误差累积路径不同，最终产生约 0.05 的数值偏差。

解决方案：将 PyTorch 环境迁移到与 TensorRT-LLM 相同的 Docker 镜像中，统一 CUDA 版本后，最大误差降至 0.002，符合预期。

4.4 误区与复盘：环境准备中的常见陷阱

以下是精度排查中反复出现的环境相关误区，务必警惕：

另一个容易被忽略的点是 TensorRT-LLM 构建引擎时的精度设置。在构建引擎时，如果设置了 --fp16 但没有显式设置 --strict_types，TensorRT 可能会在部分层自动降级为 FP32 计算，导致精度“意外地好”，但这会掩盖真实的 FP16 精度问题。因此，精度排查时建议使用 --strict_types 强制所有层保持 FP16 计算，以暴露真实的精度损失。

# 构建引擎时启用严格类型，确保所有层都使用 FP16
trtllm-build \
  --model_config ./model_config.json \
  --output_dir ./engine \
  --max_batch_size 8 \
  --max_input_len 2048 \
  --max_seq_len 4096 \
  --dtype float16 \
  --strict_types

最后，建议在环境准备完成后，运行一个数值冒烟测试：使用一个小模型（如 GPT-2 小规模版本），输入固定随机种子生成的张量，分别用 PyTorch 和 TensorRT-LLM 推理，对比输出差异。如果差异超过 1e-2（FP16 下），说明环境仍有问题，需要继续排查；如果差异在 1e-3 以内，则环境基本就绪，可以开始正式的精度对比实验。