附加配置¶

附加配置是 vLLM 提供的一种机制，允许插件自行控制内部行为。VLLM Ascend 使用该机制使项目更加灵活。

迁移指南¶

从 PR #9064 开始，vLLM Ascend 正在将受支持的环境变量迁移到 --additional-config。

重要通知¶

• 当前支持：过渡期内同时支持环境变量和 --additional-config
• 建议：新部署使用 --additional-config，并迁移现有配置
• 未来计划：环境变量将在未来版本中移除；仅支持 --additional-config

快速参考¶

如何使用¶

在线模式或离线模式下，用户都可以使用附加配置。以 Qwen3 为例：

在线模式：

vllm serve Qwen/Qwen3-8B --additional-config='{"config_key":"config_value"}'

离线模式：

from vllm import LLM

LLM(model="Qwen/Qwen3-8B", additional_config={"config_key":"config_value"})

配置选项¶

下表列出了 vLLM Ascend 中可用的附加配置选项：

各配置选项的详细信息如下：

[!WARNING] 在 HDK 0.26.0 或更早版本中，c8_enable_reshape_optim 可能与使用 AICPU 算子的池化模型发生冲突。将 c8_enable_reshape_optim 设置为 false 以禁用该优化并避免冲突。有关详细信息，请参见 issue #15896。

xlite_graph_config

finegrained_tp_config

ascend_compilation_config

eplb_config

接受的字段取决于模型运行器：

• Model Runner V2 此处仅接受 load_collection_phase。通过 --enable-eplb 和 --eplb-config 配置上游 EPLB。Ascend 使用 上游默认策略和异步 Gloo 移动。
• Model Runner V1 接受以下旧字段，但不接受 load_collection_phase。 MRv1 在 Ascend 上不接受上游 --enable-eplb。

混合两种模式会在启动时失败，而不是静默忽略配置。

scheduler_config

旧版顶层 enable_balance_scheduling、recompute_scheduler_enable、short_request_first_config 和 profiling_chunk_config 键在迁移期间仍受支持，但已弃用。如果两种格式都提供了相同字段，则以 scheduler_config 中的值为准。

scheduler_config.profiling_chunk_config

scheduler_config.dyntra_lb_config

DyntraLB 在数据并行 rank 之间均衡解码请求。它仅在具有 data_parallel_size > 1 的 PD 分离解码节点（kv_role="kv_consumer"）上受支持。 dyntra_lb_config.enabled 和 recompute_scheduler_enable 是独立的同级 设置；同时启用两者会选择组合的 DyntraLB 重计算调度器。

rejection_sampler_config

注意：块验证和熵验证都能提升投机解码性能（更高的接受率、更低的延迟），但会降低采样精度。更大的 posterior_alpha 会使调整更激进——它会进一步降低高熵 token 的接受阈值，从而提高吞吐量但降低输出质量。用户应根据其具体模型权重和应用场景调整这些参数，以在性能和精度之间找到合适的平衡。

dynamic_spec_config

注意：这是针对 model runner v1 的探索性功能。支持的方法为 "dspark"（DSpark 置信度头）和 "dflash"（无头；使用草稿 logits 上的 max-softmax 作为置信度代理）。仍然需要匹配的 speculative_config（method: "dspark" 或 "dflash"）；dynamic_spec_config 仅控制每个请求验证多少个草稿 token。用法和限制参见 动态投机解码。

dynamic_spec_config.method_params（当 method 为 "dspark" 或 "dflash" 时）

dspark 和 dflash 共享相同的调度超参数。区别仅在于如何估计每个 token 的接受置信度：DSpark 使用其置信度头（sigmoid），而 DFlash（无头）使用草稿 token 的 max(softmax(logits))。

scheduler_config.short_request_first_config

ShortRequestFirst 是用于 prefill 和 PD 混合路径上 FCFS 同步或异步调度的等待队列策略。它不支持批作业感知、profiling-chunk 或 PD 分离 D 节点调度。用法、行为和调优指南参见 ShortRequestFirst Prefill 调度。

scheduler_config.batch_job_sched_config

rl_config

rl_config 是一键 RL 模式开关。当 enabled 为 true 时，它会在每次初始化时刷新全局 Ascend 配置，强制设置 AscendConfig.weight_nz_mode=0，设置 VLLM_SERVER_DEV_MODE=1，并移除 PYTORCH_NPU_ALLOC_CONF 中的 expandable_segments 条目，同时记录一条信息日志。这些固定的 RL 行为不能作为 rl_config 子字段进行配置。当 enabled 为 false 时，所有其他子字段均被忽略。

当启用 RL 模式时，其固定的 NZ 设置优先于顶层 weight_nz_mode 配置。当 rl_config.enable_batch_invariant 为 false 时，VLLM_BATCH_INVARIANT=1 仍保持启用。

部署模式

• 同设备模式（睡眠/唤醒 + IPC 权重传输）：推理引擎和训练器共享同一张 NPU 卡。使用 enable_sleep_mode=True，并可选使用 sleep_mode_extra_cleanup=True 以获取额外内存。
• 跨设备模式（暂停/恢复 + HCCL 权重传输）：推理引擎和训练器使用不同的 NPU 卡。使用 --weight-transfer-config '{"backend": "nccl"}'。

示例（在线，同设备）：

vllm serve DeepSeek-V4 \
    --enable-sleep-mode \
    --enable-return-routed-experts \
    --weight-transfer-config '{"backend": "ipc"}' \
    --additional-config '{"rl_config": {"enabled": true, "enable_training_consistency": true, "enable_batch_invariant": true, "sleep_mode_extra_cleanup": true}}'

示例（在线，跨设备）：

vllm serve DeepSeek-V4 \
    --weight-transfer-config '{"backend": "nccl"}' \
    --additional-config '{"rl_config": {"enabled": true}}'

示例（离线）：

from vllm import LLM

llm = LLM(
    model="DeepSeek-V4",
    enable_sleep_mode=True,  # same-device mode only
    additional_config={
        "rl_config": {
            "enabled": True,
            "enable_training_consistency": True,
            "enable_batch_invariant": True,
        },
    },
)

迁移指南

示例¶

附加配置示例如下：

{
    "finegrained_tp_config": {
        "lmhead_tensor_parallel_size": 8,
        "oproj_tensor_parallel_size": 8,
        "embedding_tensor_parallel_size": 8,
        "mlp_tensor_parallel_size": 8,
    },
    "enable_kv_nz": False,
    "multistream_overlap_shared_expert": True,
    "rejection_sampler_config": {
        "enable_block_verify": True,
        "enable_entropy_verify": True,
        "posterior_threshold": 0.95,
        "posterior_alpha": 0.4,
    },
    "dynamic_spec_config": {
        "method": "dspark",
        "method_params": {
            "initial_verify_budget_per_req": 5,
            "budget_update_interval": 50,
            "budget_threshold": 0.7,
        },
    },
    "refresh": False
}

KV 流水线并行（KVPP）¶

在 --additional-config 中设置 enable_kvpp: true，可将持久化 MLA KV-cache 层分布在同一 DP 副本和 PP 阶段内的 TP 以及（配合 Model Runner V2）PCP rank 上。组大小为 TP x PCP：TP4 + PCP2 使用八个 rank；TP1 + PCP2 也会启用 KVPP。DP 副本和 PP 阶段使用独立的组。

PCP 需要 VLLM_USE_V2_MODEL_RUNNER=1。KVPP 仍要求 eager 执行和非混合 MLA，并且不支持 DCP 或 KV 传输连接器。PCP 在缓存写入前收集 prefill KV；层广播在注意力之前恢复先前前向的缓存内容。广播决策使用全局调度批，而不是 PCP 本地段偏移。