批次不变性¶

Note

批次不变性目前处于测试阶段。部分功能仍在积极开发中。请访问 https://github.com/vllm-project/vllm-ascend/issues/5487 跟踪进展和计划改进

Note

要安装批次不变性自定义算子库，请在构建 vllm-ascend 之前设置 VLLM_BATCH_INVARIANT=1。安装说明请参见 https://github.com/vllm-project/vllm-ascend/blob/main/docs/source/installation.md#set-up-using-python

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

动机¶

批次不变性在以下几种使用场景中至关重要：

框架调试：确定性输出使得推理框架中的问题调试更加容易，因为无论批处理如何，相同的输入总是产生相同的输出。
模型调试：通过确保不同批次配置下行为一致，帮助识别模型实现中的问题。
强化学习 (RL)：RL 训练通常需要确定性的推演以实现可复现性和稳定训练。
大规模推理系统：将 vLLM 作为组件的系统受益于确定性行为，用于测试、验证和一致性保证。

硬件要求¶

批次不变性目前需要 Ascend Atlas A2 和 A3 推理产品的 NPU。我们将在未来支持 Ascend 950 产品及其他 NPU。

软件要求¶

批次不变性需要 Atlas A2 和 A3 推理产品的自定义算子库，用户需要在构建 vllm-ascend 之前设置 VLLM_BATCH_INVARIANT=1，以便在安装过程中安装批次不变性自定义算子库。

启用批次不变性¶

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

export VLLM_BATCH_INVARIANT=1

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

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

VLLM_BATCH_INVARIANT=1 vllm serve Qwen/Qwen3-8B \
  --compilation-config '{"cudagraph_mode": "PIECEWISE"}'

然后使用 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,
    compilation_config={"cudagraph_mode": "PIECEWISE"},
)

# 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、Qwen/Qwen3-235B-A22B

其他模型也可能适用，但这些模型已明确验证。如果您在特定模型上遇到问题，请在 GitHub 问题跟踪器上报告。

实现细节¶

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

对注意力和其他操作使用确定性内核实现
确保不同批次大小下数值行为一致
禁用可能引入非确定性的某些优化

Note

批次不变性注意力算子目前不支持 FULL'、'FULL_DECODE_ONLY cudagraph 模式。

Note

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

未来改进¶

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

支持更多 NPU 系列
支持带有批次不变性注意力算子的 FULL'、'FULL_DECODE_ONLY cudagraph 模式
扩展模型覆盖范围
性能优化
更多测试和验证

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