执行摘要
- 一句话：为 Qwen3.5 纯文本包装类补齐 DFLASH 钩子，修复启动崩溃
- 推荐动作：值得快速阅读（约 10 行改动），不适合精读。对维护 DSPARK/DFLASH 与 Qwen3.5 适配的工程师尤其有用：它展示了“包装类必须透传 aux-hidden capture 契约”这一模式。建议后续补充一个单元测试，断言 wrapper 存在
set_dflash_layers_to_capture 且将调用委托给 body 类，防止同类契约回归。
功能与动机
PR body 指出：使用 text-only Qwen3.5 检查点（Qwen3_5ForCausalLM / Qwen3_5MoeForCausalLM，来自 qwen3_5_text.py）启动 DFLASH 推测解码时，会在 attention-backend 初始化阶段失败，报错 ValueError: Model Qwen3_5MoeForCausalLM implements neither set_dspark_layers_to_capture nor set_dflash_layers_to_capture, one of which is required for DFLASH/DSPARK.。被包装的 body 类（qwen3_5.Qwen3_5ForCausalLM）已实现捕获逻辑，wrapper 的 forward 也已解包 aux hidden states，唯一缺失的是包装类上的委托 setter，导致 configure_aux_hidden_state_capture 的 hasattr 分发找不到钩子。
实现拆解
- 变更入口：核心改动位于
python/sglang/srt/models/qwen3_5_text.py 的 Qwen3.5 纯文本包装类，在 set_embed_and_head 与 forward 之间新增 set_dflash_layers_to_capture 方法（+10 行）。该方法是 DFLASH 初始化时 configure_aux_hidden_state_capture 通过 hasattr 查找的钩子，缺失直接导致启动期 ValueError。
- 核心逻辑与设计对齐：方法完整镜像
LlamaForCausalLM.set_dflash_layers_to_capture 的三个语义：PP 非末段 rank 直接 return（只有末段生成 logits 与 aux hidden states）；layers_to_capture is None 时抛出显式错误（DFLASH 要求显式层 id）；通过后置 capture_aux_hidden_states = True 并委托给 self.model.set_dflash_layers_to_capture。body 类此前已实现在目标层打上 _is_layer_to_capture 标记并在 forward 返回 (hidden_states, aux_hidden_states) 元组，wrapper 的 forward 也已有解包逻辑，因此本次只补齐缺失的委托 setter，不改任何既有执行路径。
- 配套验证与测试缺口：PR 未附带自动化测试，作者说明已在生产部署中验证：DFLASH 在 text-only Qwen3.5-MoE 检查点上可正常启动并服务；非 DFLASH 启动与
ForConditionalGeneration 类无行为变化。该契约类缺口后续若再被重构，仍可能因缺少单元测试而回归。
关键文件：
python/sglang/srt/models/qwen3_5_text.py（模块 模型层；类别 source；类型 data-contract；符号 set_dflash_layers_to_capture）: 唯一的变更文件，为 Qwen3.5 纯文本包装类补上 DFLASH aux-hidden capture 委托方法，解锁 Qwen3.5 纯文本检查点的 DFLASH 启动。
关键符号：set_dflash_layers_to_capture
关键源码片段
python/sglang/srt/models/qwen3_5_text.py
唯一的变更文件，为 Qwen3.5 纯文本包装类补上 DFLASH aux-hidden capture 委托方法，解锁 Qwen3.5 纯文本检查点的 DFLASH 启动。
# 纯文本包装类补齐 DFLASH 接口契约：body 类（qwen3_5.Qwen3_5ForCausalLM）
# 已实现捕获逻辑，wrapper 此前缺少委托 setter，导致
# configure_aux_hidden_state_capture 的 hasattr 分发找不到钩子，
# DFLASH 启动期直接抛 ValueError。
def set_dflash_layers_to_capture(self, layers_to_capture: list[int]):
# 与 LlamaForCausalLM 语义保持一致：PP 流水线只有最后一个 rank
# 需要生成 logits 与 aux hidden states，非末段直接返回。
if not self.pp_group.is_last_rank:
return
# DFLASH 要求显式层 id 用于 aux hidden 捕获，None 属配置错误。
if layers_to_capture is None:
raise ValueError(
"DFLASH requires explicit layer ids for aux hidden capture."
)
# 打开捕获开关后委托给 body 类：body 在对应层打上
# _is_layer_to_capture 标记，并在 forward 返回
# (hidden_states, aux_hidden_states) 元组，由 wrapper 的 forward 解包。
self.capture_aux_hidden_states = True
self.model.set_dflash_layers_to_capture(layers_to_capture)
评论区精华
Review 全程聚焦代码整洁：b8zhong 对新增方法头部的解释性注释提出 “Delete comment”，作者 gilfordting 回复 “removed”，并在提交 449ae2aa（removed comment）中删除该注释。随后 b8zhong 与合并者 hnyls2002 先后 APPROVED。未出现正确性、性能或设计权衡方面的争议，说明改动语义（PP 末段守卫、显式层 id 校验、委托 body）在评审中没有分歧。
- 删除新增方法中的解释性注释 (style): 注释已删除，reviewer 与合并者先后 APPROVED，无设计分歧。
风险与影响
- 风险：
- 回归风险（低）：新增方法不触碰既有逻辑，非 DFLASH 启动路径完全不变；唯一新增点是 DFLASH 初始化时的 hasattr 分发，此前该场景直接崩溃，现在变为可用。
- 契约漂移风险（中）：方法硬依赖 body 类实现
set_dflash_layers_to_capture。若未来 body 类重构移除该方法或改动签名，wrapper 会在 DFLASH 启动时抛 AttributeError，且没有单测兜底。
- 测试缺口（中）：PR 未新增自动化测试，验证依赖生产部署的人工确认；这类“wrapper 镜像 body 接口”的模式在同类模型中已多次出现接口不同步问题。
- 行为一致性：PP 非末段直接返回与
LlamaForCausalLM 一致，但该方法刻意跳过非末段 rank 的校验，若各 rank 配置不一致，可能部分 rank 静默不启用捕获（实际多 rank 统一调用 configure，风险较低）。
- 影响：
- 用户侧：解锁 DFLASH 推测解码 + Qwen3.5 纯文本检查点（如 Qwen3.5-MoE RTN-v1）组合，从“启动即失败”变为正常推理；对使用 DSPARK/DFLASH 相关功能的部署有直接正向影响。
- 系统侧：仅在启动初始化多一次委托调用，无运行时性能开销，无 KV cache 或调度行为变化。
- 团队侧：为后续接入其他模型的 wrapper 类提供“必须镜像 body 接口”的参考范式；同时暴露测试覆盖缺口，值得在 Qwen3.5 推测解码测试矩阵中补充该场景。
- 风险标记：缺少测试覆盖, 接口契约强依赖 body 类
关联脉络
- PR #34844 [Spec] Support MegaMoE for DSpark under dp attention: 同一 DSPARK/DFLASH 功能线上的另一适配，二者分别扩展捕获链路的不同环节，说明该功能线正在持续扩充模型覆盖。
- PR #34560 [Fix] Fix Qwen3.5 MTP startup with HiCache: 同为 Qwen3.5 推测解码（MTP）启动路径的契约修复，说明 Qwen3.5 系列在推测解码集成期间接口同步问题多发。
- PR #34816 [Perf] Publish the WAR read-done event at DSPARK verify: DSPARK 调度优化，体现 DFLASH/DSPARK 在 SGLang 中是持续演进的功能主线，与本 PR 同属 speculative-decoding 生态。
参与讨论