附加配置

附加配置是 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_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	{}	Ascend 编译的配置选项
eplb_config	dict	{}	eplb 的配置选项
refresh	bool	false	是否刷新全局 Ascend 配置内容。通常用于 rlhf 或 ut/e2e 测试用例。
dump_config	dict	None	内联的 msprobe 转储配置。vLLM-Ascend 会将其物化为临时 JSON 文件，并将该文件传递给调试器。
dump_config_path	str	None	msprobe 转储的配置文件路径（兼容旧版选项）。
enable_async_exponential	bool	False	是否启用异步指数重叠。要启用异步指数，请将此配置设置为 True。
enable_shared_expert_dp	bool	False	当专家在 DP 中共享时，性能更优但内存消耗更大。
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 服务器上启用 Ascend 原生 CPU 绑定。设置为 False 以禁用。请参阅 CPU 绑定。
enable_sleep_mode_extra_cleanup	bool	False	为 RL 工作负载启用额外的睡眠模式清理，包括 HCCL 进程组释放和 ACL 图工作空间清理。默认禁用，因为唤醒时可能需要恢复 HCCL 并重新捕获 ACL 图。
SLO_limits_for_dynamic_batch	int	-1	动态批处理的 SLO 限制。这是支持动态批处理功能的新调度器
pa_shape_list	list	[]	页面注意力算子的自定义形状列表。
enable_kv_nz	bool	False	是否启用KV缓存NZ布局。此选项仅对使用MLA的模型（如DeepSeek）生效。
layer_sharding	dict	{}	Layer Sharding Linear的配置选项。Layer Sharding只能在PD分离架构的P节点上启用。
enable_sparse_sfa_c8	bool	False	是否在DSA模型（如DeepSeek V3.2和GLM5）中为稀疏Flash Attention启用打包的C8 KV缓存。此选项独立于enable_sparse_li_c8。不支持SFA预填充上下文并行和Ascend 950 DCP。
enable_sparse_li_c8	bool	False	是否在DSA模型中为LightningIndexer启用C8键和缩放缓存。此选项独立于enable_sparse_sfa_c8，仅适用于模型量化配置中符合条件的索引器层。不支持SFA预填充上下文并行和Ascend 950 DCP。
c8_enable_reshape_optim	bool	False	是否使用StoreKVBlock算子加速LightningIndexer C8缓存写入。必须同时启用enable_sparse_li_c8。在PD分离场景中，仅P节点启用。
enable_mc2_hierarchy_comm	bool	False	通过RoCE启用dispatch/combine操作的节点间通信。
enable_prefill_mc2	bool	False	是否为预填充批次预留mc2_token_capacity。启用后，将使用max_num_batched_tokens而非仅解码容量来计算mc2_token_capacity。在此场景下，max_num_batched_tokens的推荐最大值为tp_size * 512。此为临时开关；一旦MC2算子在所有场景中完善，此开关将被移除，MC2将默认启用。
mega_moe_max_tokens	int	65536	mega moe（dispatch_ffn_combine）融合算子中每个rank在分发后的token容量。当负载不均衡导致某个rank接收的token超过此限制时，超出的token将被丢弃并跳过计算，从而降低精度。请勿设置过大：工作区内存与此值呈线性增长。
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	是否启用matmul allreduce优化。迁移期间也可通过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_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多流重叠。
enable_reduce_sample	bool	False	是否启用减少采样优化以降低张量并行场景下的通信和计算开销。启用后，logits 将保持在 TP 各 rank 间分区，仅通信少量 top-k 候选值/索引，而不再执行全词汇表的 all-to-all/all-gather。注意：这是一个实验性功能。限制：(1)不支持 PD 分离场景。(2)当请求采样 logprobs 时必须禁用。启用减少采样后，logprobs 会在分区 logits 上静默计算，而非全词汇表，从而产生错误的 logprob 值和 top-k 排名。(3)不能与 lmhead TP 同时启用。

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

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	2	EPLB 均衡策略：0=随机，1=DefaultEplb（开源算法），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 值越大，调整越激进——它会进一步降低高熵令牌的接受阈值，从而提高吞吐量但降低输出质量。用户应根据具体的模型权重和应用场景调整这些参数，以找到性能和精度之间的最佳平衡。

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

示例

附加配置的示例如下：

{
    "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
}