附加配置

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

迁移指南

从 PR #9064 开始，vLLM Ascend 正在将 10 个环境变量 迁移至 --additional-config。

重要通知

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

快速参考

环境变量	配置键	类型转换
VLLM_ASCEND_BALANCE_SCHEDULING	enable_balance_scheduling	"1" → true, "0" → false
VLLM_ASCEND_ENABLE_FLASHCOMM1	enable_flashcomm1	"1" → true, "0" → false
VLLM_ASCEND_ENABLE_MATMUL_ALLREDUCE	enable_matmul_allreduce	"1" → true, "0" → false
VLLM_ASCEND_FLASHCOMM2_PARALLEL_SIZE	enable_flashcomm2_parallel_size	整数（不变）
MSMONITOR_USE_DAEMON	msmonitor_use_daemon	"1" → true, "0" → false
VLLM_ASCEND_ENABLE_MLAPO	enable_mlapo	"1" → true, "0" → false
VLLM_ASCEND_ENABLE_NZ	weight_nz_mode	整数（不变，字段名变更）
VLLM_ASCEND_ENABLE_CONTEXT_PARALLEL	enable_context_parallel	"1" → true, "0" → false
VLLM_ASCEND_ENABLE_FUSED_MC2	enable_fused_mc2	整数（不变）
VLLM_ASCEND_FUSION_OP_TRANSPOSE_KV_CACHE_BY_BLOCK	enable_transpose_kv_cache_by_block	"1" → true, "0" → false

迁移示例

迁移前（环境变量）：

export VLLM_ASCEND_ENABLE_FLASHCOMM1=1
vllm serve Qwen/Qwen3-8B

迁移后（additional-config）：

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

如何使用

无论是在线模式还是离线模式，用户都可以使用附加配置。以 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 中可用的附加配置选项：

名称	类型	默认值	描述
xlite_graph_config	dict	{}	Xlite 图模式的配置选项
weight_prefetch_config	dict	{}	权重预取的配置选项
finegrained_tp_config	dict	{}	模块级张量并行的配置选项
ascend_compilation_config	dict	{}	昇腾编译选项配置
eplb_config	dict	{}	EPLB 的配置选项
refresh	bool	false	是否刷新全局昇腾配置内容。通常用于 RLHF 训练或 UT/E2E 测试用例。
dump_config	dict	None	内联 msprobe dump 配置。vLLM-Ascend 会将其物化为临时 JSON 文件，并将该文件传递给调试器。
dump_config_path	str	None	msprobe dump 的配置文件路径（兼容旧版选项）。
enable_async_exponential	bool	False	是否启用异步指数重叠。设置为 True 以启用异步指数。
enable_shared_expert_dp	bool	False	在数据并行中共享专家模型可提供更好的性能，但会消耗更多显存。目前仅支持 DeepSeek 系列模型。
multistream_overlap_shared_expert	bool	False	是否启用多流共享专家。此选项仅对包含共享专家的 MoE 模型生效。
multistream_overlap_gate	bool	False	是否启用多流门控重叠。此选项仅对包含共享专家的 MoE 模型生效。
recompute_scheduler_enable	bool	False	是否启用重计算调度器。仅在 PD 分离 D 节点上有效（kv_role 为 kv_consumer）。不要在 P 节点或 PD 混合模式下启用（无 kv_transfer_config、kv_role 为 kv_producer，或 kv_role 为 kv_both）；启动将失败并显示明确的错误信息。
enable_cpu_binding	bool	True	在 ARM 服务器上启用昇腾原生 CPU 绑定。设置为 False 以禁用。参见 CPU 绑定。
enable_sleep_mode_extra_cleanup	bool	False	为 RL 工作负载启用额外的睡眠模式清理，包括 HCCL 进程组释放和 ACL 图工作空间清理。默认禁用，因为唤醒可能需要恢复 HCCL 并重新捕获 ACL 图。
SLO_limits_for_dynamic_batch	int	-1	动态批处理的服务级别目标限制。这是支持动态批处理功能的新调度器。
enable_npugraph_ex	bool	False	是否启用 npugraph_ex 图模式。
pa_shape_list	list	[]	页面注意力算子的自定义形状列表。
enable_kv_nz	bool	False	是否启用 KV 缓存 NZ 布局。此选项仅对使用 MLA 的模型（如 DeepSeek）生效。
layer_sharding	dict	{}	层分片线性的配置选项。层分片只能在 PD 解耦的 P 节点中启用。
enable_sparse_c8	bool	False	是否在 DSA 模型中启用 KV 缓存 C8（例如 DeepSeek V3.2 和 GLM5）。目前 Ascend 950 设备不支持。
c8_enable_reshape_optim	bool	False	是否启用 StoreKVBlock 算子在 C8 特性下实现加速（这意味着需要启用 enable_sparse_c8）。在 PD 分离场景中，仅 P 节点启用。
enable_mc2_hierarchy_comm	bool	False	通过 ROCE 启用分发/组合操作的节点间通信。
enable_prefill_mc2	bool	False	Whether to reserve mc2_token_capacity for prefill batches. When enabled, max_num_batched_tokens is used to calculate the mc2_token_capacity instead of the decode-only capacity. In this scenario, the recommended maximum value of max_num_batched_tokens is tp_size * 512. This is a temporary switch; once MC2 operators are complete for all scenarios, this switch will be removed and MC2 will be enabled by default.
mega_moe_max_tokens	int	65536	Per-rank token capacity after dispatch in the mega moe (dispatch_ffn_combine) fused operator. When load imbalance causes a rank to receive more tokens than this limit, the excess tokens are dropped and skipped from computation, degrading accuracy. Do not set this too large: workspace memory scales linearly with this value.
profiling_chunk_config	dict	{}	动态分块流水线并行的配置选项。详情请参见动态分块流水线并行。
enable_balance_scheduling	bool	False	是否启用均衡调度。也可以通过 VLLM_ASCEND_BALANCE_SCHEDULING 环境变量在迁移期间配置。
enable_flashcomm1	bool	False	是否启用 FlashComm1 优化。也可以通过 VLLM_ASCEND_ENABLE_FLASHCOMM1 环境变量在迁移期间配置。
enable_matmul_allreduce	bool	False	是否启用矩阵乘法全规约优化。也可以通过 VLLM_ASCEND_ENABLE_MATMUL_ALLREDUCE 环境变量在迁移期间配置。
flashcomm2_parallel_size	int	0	FlashComm2 并行大小。也可以通过 VLLM_ASCEND_FLASHCOMM2_PARALLEL_SIZE 环境变量在迁移期间配置。
msmonitor_use_daemon	bool	False	是否对 msmonitor 使用守护进程模式。也可以通过 MSMONITOR_USE_DAEMON 环境变量在迁移期间配置。
enable_mlapo	bool	True	是否启用 MLAPO（模型逐层自适应并行优化）。也可以通过 VLLM_ASCEND_ENABLE_MLAPO 环境变量在迁移期间配置。
weight_nz_mode	int	1	权重 NZ 模式。也可以通过 VLLM_ASCEND_ENABLE_NZ 环境变量在迁移期间配置。
enable_context_parallel	bool	False	是否启用上下文并行。也可以通过 VLLM_ASCEND_ENABLE_CONTEXT_PARALLEL 环境变量在迁移期间配置。
enable_fused_mc2	int	0	融合 MC2 配置。也可以通过 VLLM_ASCEND_ENABLE_FUSED_MC2 环境变量在迁移期间配置。
enable_transpose_kv_cache_by_block	bool	True	是否启用按块转置 KV 缓存。也可以通过 VLLM_ASCEND_FUSION_OP_TRANSPOSE_KV_CACHE_BY_BLOCK 环境变量在迁移期间配置。
enable_dsa_cp	bool	False	是否为 DeepSeek V3.2、DeepSeek V4 及其他相同架构的模型启用 dsa_cp。此功能依赖于 FLASHCOMM1。启用此功能前请确保已启用 FLASHCOMM1。
rejection_sampler_config	dict	{}	拒绝采样器（块验证和熵验证）的配置选项。
multistream_dsv4_dsa_overlap	bool	True	是否为 DeepSeek V4 启用 dsa 多流重叠。

每个配置选项的详细说明如下：

xlite_graph_config

名称	类型	默认值	描述
enabled	bool	False	是否启用 Xlite 图模式。目前仅支持 Llama、Qwen 全量系列模型以及 Qwen3-VL。
full_mode	bool	False	是否在预填充和解码阶段同时启用 Xlite。默认情况下，Xlite 仅在解码阶段启用。

weight_prefetch_config

名称	类型	默认值	描述
enabled	bool	False	是否启用权重预取。
prefetch_ratio	dict	{"attn": {"qkv": 1.0, "o": 1.0}, "moe": {"gate_up": 0.8}, "mlp": { "gate_up": 1.0, "down": 1.0}}	各项权重的预取比例。

finegrained_tp_config

名称	类型	默认值	描述
lmhead_tensor_parallel_size	int	0	lm_head 的自定义张量并行大小。
oproj_tensor_parallel_size	int	0	o_proj 的自定义张量并行大小。
embedding_tensor_parallel_size	int	0	embedding 层的自定义张量并行大小。
mlp_tensor_parallel_size	int	0	MLP 层的自定义张量并行大小。

ascend_compilation_config

名称	类型	默认值	描述
enable_npugraph_ex	bool	True	是否启用 npugraph_ex 后端。
enable_static_kernel	bool	False	是否启用静态内核。适用于形状变化极小且有时间为静态内核编译预留时间的场景。
fuse_norm_quant	bool	True	是否启用 fuse_norm_quant 优化通道。
fuse_qknorm_rope	bool	True	是否启用 fuse_qknorm_rope 优化通道。如果环境中没有安装 Triton，请将其设置为 False。
fuse_allreduce_rms	bool	False	是否启用 fuse_allreduce_rms 优化通道。由于与 SP 存在冲突，默认设置为 False。
fuse_muls_add	bool	True	是否启用 fuse_muls_add 优化通道。

eplb_config

名称	类型	默认值	描述
dynamic_eplb	bool	False	是否启用动态专家并行负载均衡 (EPLB)。
expert_map_path	str	None	为 MoE 模型使用专家负载均衡时，需要传入专家映射表的路径。
expert_heat_collection_interval	int	400	EPLB 开始前的正向迭代次数。
algorithm_execution_interval	int	30	EPLB 工作线程完成 CPU 任务所需的正向迭代次数。
expert_map_record_path	str	None	将专家负载计算结果保存到指定目录下的新专家表中。
num_redundant_experts	int	0	在初始化阶段指定冗余专家的数量。
eplb_policy_type	int	1	EPLB 均衡策略：0=随机，1=默认值Eplb（开源算法），2=SwiftBalanceEplb（针对低带宽优化），3=FlashLB（基于滑动窗口的统计方法）。
eplb_heat_collection_stage	str	"all"	收集 EPLB 热度的阶段："prefill" 仅在预填充阶段收集，"decode" 仅在解码阶段收集，"all" 在两个阶段均收集。在 PD 共置场景中，预填充和解码请求可能产生不同的专家工作负载。选择性地在某个阶段收集热度可以更有效地减少专家不均衡。

profiling_chunk_config

名称	类型	默认值	描述
enabled	bool	False	是否启用动态分块流水线并行。需要 pipeline-parallel-size > 1。
smooth_factor	float	1.0	平滑因子 (0 < x ≤ 1.0)。值越大越信任动态预测；0.0 表示禁用动态调整。
min_chunk	int	4096	动态计算的最小分块大小。应小于 max-num-batched-tokens。
need_timing	bool	True	启用/禁用在线校准
max_fit_chunk	int	30	在线校准的分块时间数据数量

rejection_sampler_config

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

名称	类型	默认值	描述
enable_block_verify	bool	False	是否启用块验证模式。块验证使用累积概率乘积将草稿 token 作为一个整体进行评估，可以提高接受率。
enable_entropy_verify	bool	False	是否启用熵验证模式。熵验证根据目标分布的熵调整接受阈值——高熵（不确定）token 获得更低的阈值（更容易接受），而低熵（确定）token 获得更严格的阈值。
posterior_threshold	float	0.95	熵调整后接受阈值的上限。必须在 (0, 1] 范围内。有效阈值为 min(exp(-entropy * posterior_alpha), posterior_threshold)。
posterior_alpha	float	0.4	阈值计算中熵的缩放因子。必须 >= 0。值越大，阈值对熵越敏感——高熵 token 更容易被接受，从而提高性能但降低精度。

示例

附加配置的一个示例如下：

{
    "weight_prefetch_config": {
        "enabled": True,
        "prefetch_ratio": {
            "attn": {
                "qkv": 1.0,
                "o": 1.0,
            },
            "moe": {
                "gate_up": 0.8
            },
            "mlp": {
                "gate_up": 1.0,
                "down": 1.0
            }
        },
    },
    "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,
    },
    "refresh": False
}