附加配置¶

附加配置是 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

之后（附加配置）：

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 dump 配置。vLLM-Ascend 会将其物化为一个临时 JSON 文件，并将该文件传递给调试器。
`dump_config_path`	str	`None`	msprobe dump 的配置文件路径（兼容的旧选项）。
`enable_async_exponential`	bool	`False`	是否启用异步指数重叠。要启用异步指数，请将此配置设置为 True。
`enable_shared_expert_dp`	bool	`False`	当专家在 DP 中共享时，性能更好但内存消耗更大。目前仅支持 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 服务器上启用 Ascend 原生 CPU 绑定。设置为 `False` 以禁用。请参阅 CPU 绑定。
`enable_sleep_mode_extra_cleanup`	bool	`False`	为 RL 工作负载启用额外的睡眠模式清理，包括 HCCL 进程组释放和 ACL 图工作空间清理。默认禁用，因为唤醒可能需要恢复 HCCL 并重新捕获 ACL 图。
`SLO_limits_for_dynamic_batch`	int	`-1`	动态批次的 SLO 限制。这是一个支持动态批次特性的新调度器。
`enable_kv_nz`	bool	`False`	是否启用 KV 缓存 NZ 布局。此选项仅对使用 MLA 的模型（例如 DeepSeek）生效。
`layer_sharding`	dict	`{}`	Layer Sharding Linear 的配置选项。Layer Sharding 只能在 PD 分离的 P 节点上启用。
`enable_sparse_c8`	bool	`False`	是否在 DSA 模型（例如 DeepSeek V3.2 和 GLM5）中启用 KV 缓存 C8。目前不支持 Ascend 950 设备。
`c8_enable_reshape_optim`	bool	`False`	是否启用 StoreKVBlock 算子在 C8 特性下实现加速（这意味着需要启用 enable_sparse_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_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 多流重叠。
`short_request_first_config`	dict	`{}`	PD预填充（P）节点上ShortRequestFirst预填充调度的配置选项。与`recompute_scheduler_enable=true`配合使用。

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

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`=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	Number of chunk-time data for Online Calibration

rejection_sampler_config

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

名称	类型	默认值	描述
`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。值越大，阈值对熵越敏感——高熵令牌变得更容易接受，从而提高性能但降低精度。

short_request_first_config

PD预填充（P）节点的ShortRequestFirst预填充调度。当启用重计算调度器且调度策略为FCFS时生效。

名称	类型	默认值	描述
`enabled`	bool	`False`	是否启用ShortRequestFirst调度。
`threshold`	int	`256`	提示长度阈值（token）。`num_prompt_tokens <= threshold`的请求被视为短预填充，并优先于长预填充。
`long_max_wait_ms`	float	`0.0`	长预填充在短预填充之后等待的最大时间（毫秒），超过此时间后可提升至短预填充之前。`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
}