批次不变性

批次不变性#

备注

批次不变性功能目前处于测试阶段。部分功能仍在积极开发中。请通过 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 问题跟踪器上报告。

实现细节#

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

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

备注

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

未来改进#

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

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

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