附加配置

附加配置#

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

Migration Guide#

Starting from PR #9064, vLLM Ascend is migrating 10 environment variables to --additional-config.

Important Notice#

Current Support: Both environment variables and --additional-config are supported during the transition period
Recommendation: Use --additional-config for new deployments and migrate existing configurations
Future Plan: Environment variables will be removed in a future release; only --additional-config will be supported

Quick Reference#

Environment Variable	Config Key	Type Conversion
`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`	Integer (unchanged)
`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`	Integer (unchanged, field name changed)
`VLLM_ASCEND_ENABLE_CONTEXT_PARALLEL`	`enable_context_parallel`	`"1"` → `true`, `"0"` → `false`
`VLLM_ASCEND_ENABLE_FUSED_MC2`	`enable_fused_mc2`	Integer (unchanged)
`VLLM_ASCEND_FUSION_OP_TRANSPOSE_KV_CACHE_BY_BLOCK`	`enable_transpose_kv_cache_by_block`	`"1"` → `true`, `"0"` → `false`

Example Migration#

Before (environment variable):

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

After (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 设备不支持。
`enable_mc2_hierarchy_comm`	bool	`False`	通过 ROCE 启用分发/组合操作的节点间通信。
`profiling_chunk_config`	dict	`{}`	动态分块流水线并行的配置选项。详情请参见动态分块流水线并行。
`enable_balance_scheduling`	bool	`False`	Whether to enable balance scheduling. Can also be configured via `VLLM_ASCEND_BALANCE_SCHEDULING` environment variable (deprecated).
`enable_flashcomm1`	bool	`False`	Whether to enable FlashComm1 optimization. Can also be configured via `VLLM_ASCEND_ENABLE_FLASHCOMM1` environment variable (deprecated).
`enable_matmul_allreduce`	bool	`False`	Whether to enable matmul allreduce optimization. Can also be configured via `VLLM_ASCEND_ENABLE_MATMUL_ALLREDUCE` environment variable (deprecated).
`flashcomm2_parallel_size`	int	`0`	FlashComm2 parallel size. Can also be configured via `VLLM_ASCEND_FLASHCOMM2_PARALLEL_SIZE` environment variable (deprecated).
`msmonitor_use_daemon`	bool	`False`	Whether to use daemon mode for msmonitor. Can also be configured via `MSMONITOR_USE_DAEMON` environment variable (deprecated).
`enable_mlapo`	bool	`True`	Whether to enable MLAPO (Model Layer-wise Adaptive Parallel Optimization). Can also be configured via `VLLM_ASCEND_ENABLE_MLAPO` environment variable (deprecated).
`weight_nz_mode`	int	`1`	Weight NZ mode. Can also be configured via `VLLM_ASCEND_ENABLE_NZ` environment variable (deprecated).
`enable_context_parallel`	bool	`False`	Whether to enable context parallelism. Can also be configured via `VLLM_ASCEND_ENABLE_CONTEXT_PARALLEL` environment variable (deprecated).
`enable_fused_mc2`	int	`0`	Fused MC2 configuration. Can also be configured via `VLLM_ASCEND_ENABLE_FUSED_MC2` environment variable (deprecated).
`enable_transpose_kv_cache_by_block`	bool	`True`	Whether to enable transpose KV cache by block. Can also be configured via `VLLM_ASCEND_FUSION_OP_TRANSPOSE_KV_CACHE_BY_BLOCK` environment variable (deprecated).
`enable_dsa_cp`	bool	`False`	Whether to enable dsa_cp for DeepSeek V3.2, DeepSeek V4, and other models with the same architecture. This feature depends on FLASHCOMM1. Please ensure that FLASHCOMM1 is enabled before enabling this feature.

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

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

示例#

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

{
    "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,
    "refresh": False
}