批次不变性¶

注意

批次不变性目前处于测试阶段 (beta)。部分功能仍在积极开发中。请通过 Issue #27433 跟踪进展及计划的改进。

本文档展示了如何在 vLLM 中启用批次不变性。批次不变性确保模型的输出是确定性的，且与批次大小或批次中请求的顺序无关。

动机¶

批次不变性对于以下几种应用场景至关重要：

框架调试：确定性输出使得调试推理框架中的问题变得更容易，因为相同的输入无论如何分批，始终会产生相同的输出。
模型调试：通过确保不同批次配置下的行为一致，有助于识别模型实现中的问题。
强化学习 (RL)：RL 训练通常需要确定性的采样 (rollouts) 以保证可重现性和训练稳定性。
大规模推理系统：将 vLLM 作为组件的系统可以受益于这种确定性行为，从而获得测试、验证和一致性的保障。

硬件要求¶

批次不变性目前需要计算能力 9.0 或更高的 NVIDIA GPU：

H 系列：H100, H200
B 系列：B100, B200

启用批次不变性¶

可以通过将环境变量 VLLM_BATCH_INVARIANT 设置为 1 来启用批次不变性。

export VLLM_BATCH_INVARIANT=1

在线推理 (服务器模式)¶

要启动启用了批次不变性的 vLLM 服务器：

VLLM_BATCH_INVARIANT=1 vllm serve meta-llama/Llama-3.1-8B-Instruct

然后使用 OpenAI 兼容的客户端：

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="https://:8000/v1",
)

# These requests will produce deterministic outputs
# regardless of batch size or order
response = client.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    prompt="The future of AI is",
    max_tokens=100,
    temperature=0.7,
    seed=42,
)

print(response.choices[0].text)

离线推理¶

对于启用批次不变性的离线批处理推理：

import os
os.environ["VLLM_BATCH_INVARIANT"] = "1"

from vllm import LLM, SamplingParams

prompts = [
    "The future of AI is",
    "Machine learning enables",
    "Deep learning models can",
]

sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.95,
    max_tokens=100,
    seed=42,
)

llm = LLM(
    model="meta-llama/Llama-3.1-8B-Instruct",
    tensor_parallel_size=1,
)

# Outputs will be deterministic regardless of batch size
outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}")
    print(f"Generated: {generated_text!r}\n")

已测试模型¶

批次不变性已在以下模型上进行了测试和验证：

DeepSeek 系列：deepseek-ai/DeepSeek-V3, deepseek-ai/DeepSeek-V3-0324, deepseek-ai/DeepSeek-R1, deepseek-ai/DeepSeek-V3.1
Qwen3 (密集型)：Qwen/Qwen3-1.7B, Qwen/Qwen3-8B
Qwen3 (MoE)：Qwen/Qwen3-30B-A3B, Qwen/Qwen3-Next-80B-A3B-Instruct
Qwen2.5：Qwen/Qwen2.5-0.5B-Instruct, Qwen/Qwen2.5-1.5B-Instruct, Qwen/Qwen2.5-3B-Instruct, Qwen/Qwen2.5-7B-Instruct, Qwen/Qwen2.5-14B-Instruct, Qwen/Qwen2.5-32B-Instruct
Llama 3：meta-llama/Llama-3.1-8B-Instruct, meta-llama/Llama-3.2-1B-Instruct
GPT-OSS：openai/gpt-oss-20b, openai/gpt-oss-120b
Mistral：mistralai/Mistral-7B-v0.3

其他模型可能也能工作，但上述模型已获得明确验证。如果您在使用特定模型时遇到问题，请在 GitHub 问题跟踪器上进行报告。

实现细节¶

当启用批次不变性时，vLLM 会：

使用确定性的内核实现进行注意力机制及其他运算
确保在不同批次大小下数值行为的一致性
禁用某些可能引入非确定性的优化（例如张量并行模式下的自定义 all-reduce 操作）

注意

与默认的非确定性模式相比，启用批次不变性可能会影响性能。这种权衡是有意为之，旨在确保可重现性。

未来改进¶

批次不变性功能正在积极开发中。计划中的改进包括：

支持更多 GPU 架构
扩大模型覆盖范围
性能优化
额外的测试和验证

欲了解最新状态并贡献想法，请查看跟踪问题。