执行摘要

• 一句话：修复DFlash前瞻槽位分配以解决崩溃
• 推荐动作：此PR虽然改动量小，但涉及投机解码与调度器交互的关键逻辑，值得精读。特别是effective_lookahead_tokens的条件演进和DFlash特殊需求的论证，可作为类似bug修复的参考。

功能与动机

DFlash运行时因前瞻槽位未正确分配而崩溃。DFlash需要额外前瞻槽位，因为其使用填充式解码，有一个查询用于最后采样令牌再加上每个草稿令牌的查询。原限制逻辑在P/D分离下覆盖了前瞻槽位，导致DFlash槽位不足。

实现拆解

1. 在Scheduler.__init__中检测DFlash配置：新增加if speculative_config.use_dflash(): self.num_lookahead_tokens = self.num_spec_tokens + 1，确保DFlash获得足够的前瞻槽位。
2. 在Scheduler.schedule中调整effective_lookahead_tokens的计算：原逻辑在num_computed_tokens==0时强制设为0，这错误地影响了DFlash的槽位。现改为仅当load_kv_async and self.use_eagle时限制，因为只有Eagle在P/D分离预填充阶段需要避免块数量不匹配。
3. 这些修改协同工作：第一步为DFlash分配正确槽位，第二步避免对DFlash误限，从而修复崩溃。

关键文件：

• vllm/v1/core/sched/scheduler.py（模块 调度器；类别 source；类型 core-logic；符号 init, schedule）: 核心调度器，修复DFlash前瞻槽位分配和P/D分离场景下的限制逻辑

关键符号：init, schedule

关键源码片段

vllm/v1/core/sched/scheduler.py

核心调度器，修复DFlash前瞻槽位分配和P/D分离场景下的限制逻辑

# Scheduler.__init__ 中前瞻槽位配置部分
speculative_config = vllm_config.speculative_config
self.use_eagle = False
self.num_spec_tokens = self.num_lookahead_tokens = 0
if speculative_config:
    self.num_spec_tokens = speculative_config.num_speculative_tokens
    if speculative_config.use_eagle():
        self.use_eagle = True
        self.num_lookahead_tokens = self.num_spec_tokens
    if speculative_config.uses_draft_model():
        self.num_lookahead_tokens = self.num_spec_tokens
    if speculative_config.use_dflash():
        # DFlash 使用 infill-style 解码，需要一个额外的查询槽位
        # 用于最后采样的 token，再加上每个草稿 token 的查询
        self.num_lookahead_tokens = self.num_spec_tokens + 1

# Scheduler.schedule 中有效前瞻槽位计算部分
# 原逻辑：if request.num_computed_tokens == 0 then 0，限制了所有投机解码
# 新逻辑：仅对 Eagle 在 P/D 分离预填充阶段限制，避免块数量不匹配
limit_lookahead_tokens = load_kv_async and self.use_eagle
effective_lookahead_tokens = (
    0 if limit_lookahead_tokens else self.num_lookahead_tokens
)

评论区精华

NickLucche指出原问题根源在于P/D分离时配置不对称导致块数量不匹配，提议使用load_kv_async作为更明确的门控。经讨论，最终方案确定为load_kv_async and self.use_eagle，避免对非Eagle的DFlash产生错误限制。hclsys确认num_spec_tokens+1正确且隔离安全。shreyas269提醒GPU model runner中effective_drafter_max_model_len可能也需要更新，但被列为后续跟踪。

• 前瞻槽位限制条件的修改 (design): 使用load_kv_async and self.use_eagle作为限制条件

风险与影响

• 风险：风险较低。变更范围仅限单个文件的7行代码，且逻辑简单。但需注意：1）DFlash槽位增加可能略微增加内存占用，但仅在使用DFlash时生效；2）限制条件改为load_kv_async and self.use_eagle可能影响Eagle在非P/D分离时的行为，但load_kv_async仅在connector存在且首次预填充时成立，因此安全；3）其他非Eagle投机解码方法（如draft model）不再受此限制，这可能是原意修复的一部分。未涉及测试变更，但新增逻辑通过配置隔离。
• 影响：对使用DFlash的用户而言是重要的bugfix，使DFlash功能可用。对不使用DFlash的用户无影响。系统层面，修复了P/D分离场景下投机解码的槽位不匹配问题，提升了兼容性。
• 风险标记：仅修改单文件, 依赖DFlash配置, 影响P/D分离兼容性

关联脉络

• PR #22317 Override lookahead slots in prefill scheduling: 本PR修复了#22317引入的问题，该PR在调度预填充时覆盖了前瞻槽位，导致DFlash槽位不足。