附加配置¶

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

迁移指南¶

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

重要提示¶

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

快速参考¶

环境变量	配置键	类型转换
`VLLM_ASCEND_BALANCE_SCHEDULING`	`scheduler_config.enable_balance_scheduling`	`"1"` → `true`, `"0"` → `false`
`VLLM_ASCEND_ENABLE_FLASHCOMM1`	`enable_flashcomm1`	`"1"` → `true`, `"0"` → `false`
`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

之后（附加配置）：

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 图模式的配置选项
`finegrained_tp_config`	dict	`{}`	模块张量并行的配置选项
`ascend_compilation_config`	dict	`{}`	Ascend 编译的配置选项
`eplb_config`	dict	`{}`	运行器特定的EPLB扩展。参见专家并行负载均衡器。
`scheduler_config`	dict	`{}`	Ascend调度器扩展的配置选项，包括均衡调度、重计算调度、DyntraLB、短请求优先和动态分块流水线并行。
`refresh`	bool	`false`	是否刷新全局 Ascend 配置内容。通常用于 rlhf 或 ut/e2e 测试用例。
`dump_config`	dict	`None`	内联的 msprobe dump 配置。vLLM-Ascend 会将其物化为一个临时 JSON 文件，并将该文件传递给调试器。
`dump_config_path`	str	`None`	msprobe dump 的配置文件路径（兼容的旧选项）。
`enable_shared_expert_dp`	bool	`False`	Replicate shared-expert weights across TP ranks and run the shared expert with data parallelism. This option is independent of `enable_flashcomm1`; it improves performance but consumes more memory.
`multistream_overlap_shared_expert`	bool	`False`	是否启用多流共享专家。此选项仅对具有共享专家的 MoE 模型生效。
`enable_cpu_binding`	bool	`True`	在 ARM 服务器上启用 Ascend 原生 CPU 绑定。设置为 `False` 以禁用。请参阅 CPU 绑定。
`enable_sleep_mode_extra_cleanup`	bool	`False`	为 RL 工作负载启用额外的睡眠模式清理，包括 HCCL 进程组释放和 ACL 图工作空间清理。默认禁用，因为唤醒可能需要恢复 HCCL 并重新捕获 ACL 图。
`pa_shape_list`	list	`[]`	page attention 算子的自定义形状列表。
`enable_kv_nz`	bool	`False`	是否启用 KV 缓存 NZ 布局。此选项仅对使用 MLA 的模型（例如 DeepSeek）生效。
`enable_sparse_sfa_c8`	bool	`False`	是否在 DSA 模型（例如 DeepSeek V3.2 和 GLM5）中启用用于稀疏闪存注意力的打包 C8 KV 缓存。此选项独立于 `enable_sparse_li_c8`。目前不支持 SFA 预填充上下文并行和 Ascend 950 DCP。
`enable_sparse_li_c8`	bool	`False`	是否在 DSA 模型中为 LightningIndexer 启用 C8 key 和 scale 缓存。此选项独立于 `enable_sparse_sfa_c8`，并且仅适用于模型量化配置中的合格 indexer 层。目前不支持 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）融合算子中，dispatch后每个rank的token容量。当负载不均衡导致某个rank接收的token数超过此限制时，多余的token会被丢弃并跳过计算，从而降低精度。不要将此值设置过大：工作区内存与此值呈线性增长。
`enable_flashcomm1`	bool	`False`	是否启用 FlashComm1 优化。在迁移期间，也可以通过 `VLLM_ASCEND_ENABLE_FLASHCOMM1` 环境变量进行配置。
`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	`{}`	拒绝采样器（块验证和熵验证）的配置选项。
`dynamic_spec_config`	dict	`{}`	动态推测解码的配置选项。参见动态推测解码。
`multistream_dsv4_dsa_overlap`	bool	`True`	是否为 DeepSeek V4 启用 dsa 多流重叠。
`enable_reduce_sample`	bool	`False`	是否启用reduce sample优化以减少张量并行场景下的通信和计算开销。启用后，logits在TP ranks间保持分区，仅通信少量top-k候选值/索引，而非执行全词表all-to-all/all-gather。注意：这是一个实验性功能。限制：(1) 不支持PD分离场景。(2) 当请求采样logprobs时必须禁用。启用reduce sample后，logprobs会在分区logits上静默计算而非全词表，导致logprob值和top-k排名不正确。(3) 不能与lmhead TP同时启用。

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

xlite_graph_config

名称	类型	默认值	描述
`enabled`	bool	`False`	是否启用 Xlite 图模式。支持的模型、仅解码模式与全模式的区别以及示例，请参阅使用 XliteGraph。
`full_mode`	bool	`False`	是否为预填充和解码阶段均启用 Xlite。默认情况下，Xlite 仅对解码阶段启用，预填充回退到 ACLGraph 下的 runnable。当为 `True` 时，xlite 同时负责预填充和解码，不使用 ACLGraph 捕获，建议使用 `--enforce-eager`（除非配置了投机解码等）。

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_muls_add`	bool	`True`	是否启用 fuse_muls_add 优化通道。

eplb_config

接受的字段取决于模型运行器：

模型运行器V2 此处仅接受 load_collection_phase。通过 --enable-eplb 和 --eplb-config 配置上游EPLB，并在Ascend上设置 --eplb-config.use_async false。
模型运行器V1 接受除 load_collection_phase 之外的以下旧字段。MRv1在Ascend上不接受上游 --enable-eplb。

混合使用两种模式会在启动时失败，而不是静默忽略配置。

名称	类型	默认值	描述
`dynamic_eplb`	bool	`False`	仅MRv1。是否启用旧版动态EPLB。
`expert_map_path`	str	`None`	仅MRv1。加载记录的静态专家映射。
`expert_heat_collection_interval`	int	`600`	仅MRv1。用于收集专家热度的前向迭代次数。
`algorithm_execution_interval`	int	`50`	仅MRv1。允许EPLB工作线程完成其CPU任务的间隔。
`expert_map_record_path`	str	`None`	仅MRv1。将计算出的专家映射保存到指定的JSON路径。
`num_redundant_experts`	int	`0`	本表中仅MRv1。通过上游 `--eplb-config` 配置MRv2的值。
`eplb_policy_type`	int	`2`	仅MRv1。EPLB策略：`0`=Random，`1`=DefaultEplb，`2`=SwiftBalanceEplb，`3`=FlashLB。
`eplb_heat_collection_stage`	str	`"all"`	仅MRv1。选择 `"all"`、`"prefill"` 或 `"decode"` 热度收集。
`load_collection_phase`	str	`"all"`	仅MRv2。选择 `"all"`、`"prefill"` 或 `"decode"` 负载提交。任何包含prefill请求的批次整体归类为prefill。

scheduler_config

在迁移期间，旧版顶层键 enable_balance_scheduling、recompute_scheduler_enable、short_request_first_config 和 profiling_chunk_config 仍然受支持，但已弃用。如果两种格式提供了相同的字段，则以 scheduler_config 中的值为准。

名称	类型	默认值	描述
`enable_balance_scheduling`	bool	`False`	是否启用均衡调度。在迁移期间，也可以通过 `VLLM_ASCEND_BALANCE_SCHEDULING` 环境变量进行配置。
`recompute_scheduler_enable`	bool	`False`	是否启用重计算调度器。仅在PD分离的D节点上有效（`kv_role` 为 `kv_consumer`）。不要在P节点或PD混合模式下启用（没有 `kv_transfer_config`，`kv_role` 为 `kv_producer`，或 `kv_role` 为 `kv_both`）；启动将失败并显示明确的错误信息。
`profiling_chunk_config`	dict	`{}`	动态分块流水线并行的配置选项。详情请参见动态分块流水线并行。
`short_request_first_config`	dict	`{}`	在FCFS同步或异步、PD-prefill（P）或PD-mixed节点上，ShortRequestFirst预填充调度的配置选项。
`batch_job_sched_config`	dict	`{}`	批处理作业感知调度器的配置选项。详情请参见批处理作业感知调度器。
`dyntra_lb_config`	dict	`{}`	在PD分离的解码节点上，DyntraLB负载均衡的配置选项。

scheduler_config.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

scheduler_config.dyntra_lb_config

DyntraLB在数据并行等级之间均衡解码请求。它仅在data_parallel_size > 1的PD分离解码节点（kv_role="kv_consumer"）上受支持。dyntra_lb_config.enabled和recompute_scheduler_enable是独立的同级设置；同时启用两者将选择组合的DyntraLB重计算调度器。

名称	类型	默认值	描述
`enabled`	bool	`False`	启用DyntraLB并选择支持DyntraLB的调度器。
`mode`	str	`"dynamic"`	使用`"static"`或`"dynamic"`激活方式。
`start_step`	int	`250`	允许生成计划的第一个已完成引擎步骤快照。
`end_step`	int	`-1`	排他性的最终快照步骤；`-1`表示无上限。
`bubble_threshold`	float	`5.0`	修改调度所需的最小最大与平均等级负载差异。大于或等于`1`的值表示KV缓存块数；小于`1`的值表示归一化比率。
`long_req_block_threshold`	int	`700`	在动态模式下，新添加的请求超过此块数将激活均衡。默认阈值在`block_size=128`时对应约89,600个token。
`dynamic_max_step`	int	`256`	在没有新添加的长请求的情况下，经过这么多活动步骤后停止动态均衡。
`enable_diagnostics`	bool	`False`	仅用于功能验证和调试的详细日志。默认禁用，生产环境中应保持禁用。

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

dynamic_spec_config

注意：这是面向 model runner v1 的探索性功能。支持的方法包括 "dspark"（DSpark confidence head）与 "dflash"（head-free；使用草稿 logits 的 max-softmax 作为置信度代理）。你仍需配置匹配的 speculative_config（method: "dspark" 或 "dflash"）；dynamic_spec_config 仅控制每个请求实际验证多少个草稿令牌。用法与限制请参见动态推测解码。

名称	类型	默认值	描述
`method`	str	`None`	动态方法名称。支持的值：`"dspark"`、`"dflash"`。省略或设置为 `None` 可禁用。
`method_params`	dict	`{}`	特定方法的超参数。为空时，各方法回退到内置默认值。

dynamic_spec_config.method_params（当 method 为 "dspark" 或 "dflash" 时）

dspark 与 dflash 共用同一套调度超参数。区别仅在于如何估计每个令牌的接受置信度：DSpark 使用其 confidence head（sigmoid），而 DFlash（head-free）使用草稿令牌的 max(softmax(logits))。

名称	类型	默认值	描述
`initial_verify_budget_per_req`	int	`5`	首次重新计算前的每请求初始验证预算。
`budget_update_interval`	int	`16`	每 N 个解码步重新计算一次共享验证预算。
`budget_threshold`	float	`0.3`	估计平均验证预算时使用的累积存活概率阈值。
`min_verify_tokens`	int	`1`	每个请求至少验证的草稿令牌数量。

scheduler_config.short_request_first_config

ShortRequestFirst是一种用于prefill和PD-mixed路径上FCFS同步或异步调度的等待队列策略。它不支持batch-job-aware、profiling-chunk或PD分离D节点调度。有关用法、行为和调优指南，请参阅ShortRequestFirst预填充调度。

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

scheduler_config.batch_job_sched_config

名称	类型	默认值	描述
`enabled`	bool	`false`	启用批处理作业感知调度器。
`max_jobs`	int	`20`	最大跟踪作业数。`0` 表示无限制。
`reserve_margin_blocks`	int	`2`	添加到KV缓存预留中的额外块余量，作为安全缓冲区。
`reserve_max_blocks`	int	`8`	可预留的最大块数。
`low_available_tokens_threshold`	int	`4096`	用于优先处理长解码作业与短解码作业的阈值。当可用token数 > 阈值时，优先处理长解码作业；当 ≤ 阈值时，优先处理短解码作业。
`short_decode_token_threshold`	int	`32`	将作业分类为“短解码”的阈值。

示例¶

附加配置的示例如下：

{
    "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,
    },
    "dynamic_spec_config": {
        "method": "dspark",
        "method_params": {
            "initial_verify_budget_per_req": 5,
            "budget_update_interval": 50,
            "budget_threshold": 0.7,
        },
    },
    "refresh": False
}