执行摘要

• 一句话：修复DFlash草稿/目标模型层数不匹配
• 推荐动作：建议合并。这是一个高信号质量的bugfix：问题发现精准（V1 vs V2行为差异分析到位）、修复方案简洁（一个字符的配对修改 + 8行输入校验）、且评审者无异议。值得借鉴的是，在核心调试信息模糊时，主动增加显式校验并附带清晰错误消息的做法，对改善开发者体验很有价值。

功能与动机

DFlash草稿模型的dflash_config.target_layer_ids配置（[1, 9, 17, 25, 33]，解析为辅助层2, 10, 18, 26, 34）需要一个至少35层的目标模型，但原测试配对的Qwen3.5-4B只有32层，导致第34层辅助隐层状态从未产生，草稿模型的fc层（期望5个拼接的辅助特征）只收到4个，出现隐晦的mat1 and mat2 shapes cannot be multiplied错误。此问题在V2下因内存profiling时调用propose()而快速失败，但V1下仅在首次解码步骤才暴露，调试困难。

实现拆解

1. 修复测试配对（tests/models/registry.py）：将DFlashDraftModel的示例目标模型从Qwen/Qwen3.5-4B更正为Qwen/Qwen3-4B，这是草稿模型实际的训练目标，具有36层（≥35层要求）。
2. 增加输入校验（vllm/model_executor/models/qwen3_dflash.py）：在combine_hidden_states()方法中，在调用self.model.fc()之前增加对输入隐层状态最后一维的尺寸校验。若尺寸与self.model.fc.input_size不匹配，抛出包含期望特征数、实际特征数以及原因说明的ValueError。
3. 变更规模极小：仅2个文件，9行新增，1行删除。

关键文件：

• vllm/model_executor/models/qwen3_dflash.py（模块 模型执行器；类别 source；类型 data-contract；符号 combine_hidden_states）: 在 combine_hidden_states 方法中增加输入特征尺寸校验，在调用 fc 层前检查隐层状态维度是否匹配，若不匹配则抛出清晰 ValueError。
• tests/models/registry.py（模块 注册表；类别 test；类型 test-coverage）: 将 DFlashDraftModel 测试的示例目标模型从 Qwen/Qwen3.5-4B（32层）更正为 Qwen/Qwen3-4B（36层），这是草稿模型实际训练的目标，解决了层数不足的问题。

关键符号：combine_hidden_states

关键源码片段

vllm/model_executor/models/qwen3_dflash.py

在 combine_hidden_states 方法中增加输入特征尺寸校验，在调用 fc 层前检查隐层状态维度是否匹配，若不匹配则抛出清晰 ValueError。

# vllm/model_executor/models/qwen3_dflash.py
​
def combine_hidden_states(
    self,
    hidden_states: torch.Tensor,
) -> torch.Tensor:
    if not self.model.use_aux_hidden_state:
        return hidden_states
    needs_squeeze = hidden_states.dim() == 1
    if needs_squeeze:
        hidden_states = hidden_states.unsqueeze(0)
​
    # 新增校验 : 检查 aux hidden 特征数量是否与 fc 层期望一致
    expected = self.model.fc.input_size
    if hidden_states.shape[-1] != expected:
        raise ValueError(
            f"DFlash drafter expects {expected} concatenated aux hidden "
            f"features but received {hidden_states.shape[-1]}. This usually "
            "means the draft model's target_layer_ids reference layers that "
            "do not exist in the target model (incompatible draft/target pair)."
        )
​
    result = self.model.fc(hidden_states)
    if needs_squeeze:
        result = result.squeeze(0)
    return result

tests/models/registry.py

将 DFlashDraftModel 测试的示例目标模型从 Qwen/Qwen3.5-4B（32层）更正为 Qwen/Qwen3-4B（36层），这是草稿模型实际训练的目标，解决了层数不足的问题。

# tests/models/registry.py — _SPECULATIVE_DECODING_EXAMPLE_MODELS
# 变更前：
# "DFlashDraftModel": _HfExamplesInfo(
# "Qwen/Qwen3.5-4B", # 错误配对，仅 32 层
# speculative_model="z-lab/Qwen3-4B-DFlash-b16", ...
# ),
# 变更后：
"DFlashDraftModel": _HfExamplesInfo(
    "Qwen/Qwen3-4B", # 修正为正确目标模型，36 层 ≥ 35 层要求
    speculative_model="z-lab/Qwen3-4B-DFlash-b16",
    use_original_num_layers=True,
    max_model_len=8192,
    max_num_seqs=32,
),

评论区精华

审核者benchislett评论：“Weird that this slipped past. Not sure why we ever paired Qwen3 dflash with Qwen3.5 target”，表达了对之前错误配对为何未被发现的不解。无其他争议讨论。

• 暂无高价值评论线程

风险与影响

• 风险：低风险。变更点清晰且范围极小：测试配对修正仅更改模型标识字符串，功能逻辑增加的是防御性校验（提前抛出清晰异常），不改变正常路径行为。校验仅在use_aux_hidden_state为True时生效，不影响其他草稿模型路径。无性能或兼容性风险。
• 影响：
  • 用户：直接受益的是使用DFlash草稿模型的用户，当草稿/目标模型不兼容时将得到清晰的错误信息而非隐晦的矩阵乘法错误。
  • 系统：无影响，不改动核心调度或推理路径。
  • 团队：减少因模型不匹配导致的调试时间，提升DFlash测试的可靠性。
  • 风险标记：无显著风险

关联脉络

• PR #48154 [ROCm] Revert Part of [ROCm] Fix pooling startup workspace lock #47912: 同属speculative decoding调试相关，但内容无直接关联