批次不变性

批次不变性#

备注

批次不变性目前处于测试阶段。部分功能仍在积极开发中。请通过 vllm-project/vllm-ascend#5487 跟踪进展和计划中的改进。

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

动机#

批次不变性在以下几个用例中至关重要：

  • 框架调试：确定性的输出使得推理框架中的问题更容易调试，因为相同的输入无论批次如何，都会产生相同的输出。

  • 模型调试：通过确保不同批次配置下的行为一致性，帮助识别模型实现中的问题。

  • 强化学习（RL）：RL 训练通常需要确定性的推演以确保可复现性和稳定的训练。

  • 大规模推理系统：将 vLLM 作为组件的系统受益于确定性的行为，便于测试、验证和一致性保证。

硬件要求#

批次不变性目前需要 Ascend Atlas A2 推理产品 NPU，因为目前只有 Atlas A2 推理产品支持带有 HCCL 通信的批次不变性。未来我们将支持其他 NPU。

软件要求#

批次不变性需要 Atlas A2 推理产品的自定义算子库。我们将在未来版本中发布该自定义算子库。

启用批次不变性#

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

export VLLM_BATCH_INVARIANT=1

在线推理（服务器模式）#

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

VLLM_BATCH_INVARIANT=1 vllm serve Qwen/Qwen3-8B

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

from openai import OpenAI

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

# These requests will produce deterministic outputs
# regardless of batch size or order
response = client.completions.create(
    model="Qwen/Qwen3-8B",
    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,
    max_tokens=100,
    seed=42,
)

llm = LLM(
    model="Qwen/Qwen3-8B",
    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")

已测试的模型#

批次不变性已在以下模型上完成测试和验证：

  • Qwen3（稠密模型）：Qwen/Qwen3-1.7B、Qwen/Qwen3-8B

  • Qwen3（MoE）：Qwen/Qwen3-30B-A3B

其他模型也可能适用，但以上是经过明确验证的模型。如果在特定模型上遇到问题，请在 GitHub issue 跟踪器 上报告。

实现细节#

启用批次不变性后，vLLM 会：

  1. 对注意力和其他操作使用确定性的内核实现

  2. 确保不同批次大小下的数值行为一致

  3. 禁用某些可能引入非确定性的优化

备注

与默认的非确定性模式相比，启用批次不变性可能会影响性能。这种权衡是为了保证可复现性。

未来改进#

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

  • 支持更多 NPU 系列

  • 扩展模型覆盖范围

  • 性能优化

  • 额外的测试和验证

有关最新状态和贡献想法，请参见跟踪 issue。