4、环境配置与复现：搭建可复现的实验环境、固定随机种子、设置环境变量（如CUDA、OMP）确保一致性

在排查 vLLM 推理结果不一致问题时，最令人沮丧的场景莫过于：昨天还能稳定复现的异常，今天重启容器后却消失了；或者同一份代码在 A 机器上输出正常，在 B 机器上却出现偏差。这种“幽灵式”不一致，往往不是模型权重或推理逻辑本身的问题，而是实验环境未受控所致。本章聚焦于搭建一个可复现的实验环境，从随机种子、环境变量、依赖锁定三个维度，将“玄学”变为“科学”。

4.1 核心原理：不一致的三大来源

推理结果不一致的根源，可以归纳为以下三类，它们分别对应不同的控制手段：

• 随机性来源：模型加载时的权重初始化（虽然推理时通常不涉及）、采样参数中的 temperature、top_p、top_k 等随机采样逻辑，以及某些算子内部的随机 dropout（即使推理模式也可能存在）。控制手段是固定随机种子。
• 并行与调度来源：多线程/多进程下的浮点累加顺序差异、CUDA 流调度顺序、Tensor Parallel 或 Pipeline Parallel 的通信顺序。控制手段是设置线程数、流多处理器（SM）分配策略。
• 底层库与硬件来源：cuBLAS/cuDNN 的算法选择（heuristic 模式可能在不同批次大小下选择不同算法）、CPU 指令集差异（如 AVX512 vs AVX2）、GPU 驱动版本差异。控制手段是锁定库版本并设置确定性算法标志。

下图展示了从“代码输入”到“推理输出”全链路中，可能引入不一致的各个控制点：

4.2 方法流程：五步搭建可复现环境

下面给出一个经过验证的、可复现 vLLM 推理实验的完整流程。每一步都对应具体的代码或命令，建议直接复制使用。

步骤 1：锁定基础依赖版本

使用 requirements.txt 精确锁定关键库版本，避免“某个依赖悄悄升级”导致行为漂移。推荐使用 pip freeze > requirements.txt 生成当前环境的完整快照，但至少应锁定以下核心组件：

# requirements.txt 关键项示例
vllm==0.6.3.post1
torch==2.5.1
transformers==4.46.3
numpy==1.26.4
cuda-python==12.4.0

步骤 2：固定随机种子

在 Python 脚本的最开始（任何模型加载或数据操作之前）设置以下种子：

import torch
import numpy as np
import random

def set_seed(seed: int = 42):
    random.seed(seed)
    np.random.seed(seed)
    torch.manual_seed(seed)
    torch.cuda.manual_seed(seed)
    torch.cuda.manual_seed_all(seed)  # 多 GPU 时使用
    # 关闭 cuDNN 的自动调优，强制使用确定性算法
    torch.backends.cudnn.deterministic = True
    torch.backends.cudnn.benchmark = False
    torch.use_deterministic_algorithms(True)

set_seed(42)

注意：torch.use_deterministic_algorithms(True) 可能会抛出运行时错误，提示某些算子不支持确定性实现。此时需要根据错误信息，定位到具体算子，并考虑是否替换或接受该不确定性。

步骤 3：设置环境变量

环境变量影响底层库的调度行为，以下变量在 vLLM 场景中尤为关键：

在启动脚本前，通过 export 命令设置：

export CUDA_LAUNCH_BLOCKING=1
export OMP_NUM_THREADS=4
export TOKENIZERS_PARALLELISM=false
export VLLM_ATTENTION_BACKEND=FLASH_ATTENTION

步骤 4：固定推理参数

vLLM 的 SamplingParams 中，除了 temperature、top_p 等常规参数外，还需注意以下两个容易被忽略的字段：

• seed：vLLM 的采样器支持传入 seed 参数，用于固定每个请求的随机数生成器状态。建议在每次请求时显式传入。
• use_beam_search：如果使用 beam search，其内部可能引入额外的随机性（如长度惩罚的排序），建议在复现时固定 beam_width 和 length_penalty。

from vllm import SamplingParams

params = SamplingParams(
    temperature=0.0,  # 贪心解码，消除采样随机性
    top_p=1.0,
    max_tokens=256,
    seed=42,          # 显式传入 seed
)

步骤 5：记录环境指纹

在实验开始时，将环境信息输出到日志文件，便于事后比对：

import torch, platform, subprocess

print("Python:", platform.python_version())
print("PyTorch:", torch.__version__)
print("CUDA:", torch.version.cuda)
print("GPU:", torch.cuda.get_device_name(0))
print("cuDNN:", torch.backends.cudnn.version())
# 记录 GPU 驱动版本
print(subprocess.run(["nvidia-smi", "--query-gpu=driver_version", "--format=csv,noheader"], capture_output=True, text=True).stdout)

4.3 案例：一次真实的不一致排查

某团队在生产环境部署 vLLM 服务，发现同一 Prompt 在 A/B 两台 GPU 服务器上返回结果不同。A 服务器为 A100 80GB，B 服务器为 A100 40GB，驱动版本均为 535.104.05，CUDA 12.2。排查过程如下：

1. 初步对比：在 A 服务器上运行 10 次，结果完全一致；在 B 服务器上运行 10 次，结果也完全一致，但 A 与 B 之间结果不同。
2. 检查依赖：对比 pip freeze 输出，发现 B 服务器的 vllm 版本为 0.6.2，而 A 服务器为 0.6.3.post1。升级 B 服务器后，结果仍然不同。
3. 检查环境变量：发现 B 服务器未设置 OMP_NUM_THREADS，导致 OpenMP 默认使用所有逻辑核（80 线程），而 A 服务器设置为 16。将 B 服务器也设置为 16 后，结果一致。
4. 根因：OMP_NUM_THREADS 影响 torch.nn.functional.scaled_dot_product_attention 中 Flash Attention 的并行分块策略，线程数不同导致浮点累加顺序不同，最终产生微小数值差异（约 1e-6 量级），经采样放大后表现为不同 token。

这个案例说明：环境变量对结果的影响可能比模型权重版本更大。在排查不一致时，务必先对比环境指纹，再深入代码逻辑。

4.4 误区与复盘：常见陷阱

以下是实践中反复出现的误区，值得特别警惕：

• 误区一：只固定 torch 种子，忽略 numpy/random。如果代码中使用了 numpy.random 或 random 模块（例如数据预处理中的随机 mask），必须同时固定它们的种子。
• 误区二：在模型加载后才设置种子。某些模型（如 GPTQ 量化模型）在加载时会初始化量化参数，如果种子设置太晚，初始化过程已经使用了随机数。
• 误区三：盲目设置 torch.use_deterministic_algorithms(True)。该开关会强制所有算子使用确定性实现，但某些算子（如 torch.nn.functional.interpolate 的特定模式）可能不支持，导致运行时崩溃。建议先不加该开关，仅设置 cudnn.deterministic 和 benchmark=False，若仍有差异再逐步收紧。
• 误区四：忽略多进程场景。如果使用 torch.multiprocessing 或 DataLoader 的 num_workers>0，每个 worker 进程需要单独设置种子。推荐在 worker_init_fn 中调用 set_seed。
• 误区五：认为 GPU 型号相同就结果一致。即使 GPU 型号相同，不同的 PCIe 拓扑、显存频率、甚至散热导致的降频，都可能影响浮点运算结果。最稳妥的方式是固定硬件环境。