批次不变性¶

Note

Batch invariance is currently in beta. Some features are still under active development. Track progress and planned improvements at https://github.com/vllm-project/vllm-ascend/issues/5487

Note

To install the batch invariance custom operator library, set VLLM_BATCH_INVARIANT=1 before building vllm-ascend. For installation instructions, see https://github.com/vllm-project/vllm-ascend/blob/main/docs/source/installation.md#set-up-using-python

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

动机¶

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

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

硬件要求¶

Batch invariance currently requires Ascend Atlas A2 and A3 inference products NPUs. We will support Ascend 950 Products and other NPUs in the future.

软件要求¶

批次不变性需要 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 issue 跟踪器上报告。

实现细节¶

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

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

Note

The batch invariance attention operators currently do not support FULL'、'FULL_DECODE_ONLY cudagraph mode.

Note

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

未来改进¶

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

支持更多 NPU 系列
Support FULL'、'FULL_DECODE_ONLY cudagraph mode with batch invariance attention operators
扩展模型覆盖范围
性能优化
额外的测试和验证

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