附加配置

附加配置是 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 解耦模式下有效（kv_role 为 kv_producer 或 kv_consumer）。请勿在 PD 混合模式下启用（无 kv_transfer_config，或 kv_role 为 kv_both）；启动将失败并显示明确的错误信息。
enable_cpu_binding	bool	True	在 ARM 服务器上启用昇腾原生 CPU 绑定。设置为 False 以禁用。参见 CPU 绑定。
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（例如 DeepSeekV3.2 和 GLM5）。目前 A5 设备不支持。
c8_enable_reshape_optim	bool	False	Whether to enable StoreKVBlock operator achieves acceleration under the C8 feature (this means that enable_sparse_c8 needs to be enabled). In the PD separation scenario, only the P node is enabled.
enable_mc2_hierarchy_comm	bool	False	通过 ROCE 启用分发/组合操作的节点间通信。
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	{}	拒绝采样器（块验证和熵验证）的配置选项。

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

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	在初始化阶段指定冗余专家的数量。

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	启用/禁用在线校准

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
}