执行摘要

• 一句话：修复 EAGLE v2 非 CUDA Graph 路径验证元数据初始化顺序
• 推荐动作：值得精读。该 PR 虽然改动很小（两个文件共 7 行净增），但针对的是一个关键初始化和时序问题，并且清楚说明了背后设计原则：元数据必须在实际 forward 使用的 batch 形状确定之后才初始化。建议阅读时结合 model_runner.forward_idle 中第 3104-3108 行（PR 提及的类似模式）一起理解，可以加深对 sglang 中 CUDA Graph 和非 CUDA Graph 路径差异管理的认识。

功能与动机

在非 CUDA Graph 路径（如 --disable-cuda-graph）下，EAGLE v2 验证阶段会产生形状不匹配的崩溃（crash），影响 DeepSeek-V4 等依赖精确形状的注意力后端。PR body 明确指出：'Metadata reflected pre-pad shapes while the actual forward consumed post-pad input_ids / out_cache_loc; backends that bake those shapes into metadata (DSv4 indexer's c4/c128 write targets + symbolic-shape TVM kernel) crashed on shape mismatch'。

实现拆解

1. python/sglang/srt/speculative/eagle_info_v2.py：在 prepare_for_v2_verify 方法中，移除非 CUDA Graph 分支中提前调用 init_forward_metadata 的代码（第 310-313 行，原 else 分支）。现在该分支完全跳过 init_forward_metadata，让它在后续的 forward_extend 中自然执行（此时 batch 已被 prepare_mlp_sync_batch 正确填充）。

2. python/sglang/srt/speculative/eagle_worker_v2.py：在 verify 方法中，将 forward_batch_generation 调用的 skip_attn_backend_init 参数从硬编码的 True 改为 can_run_cuda_graph。这样，CUDA Graph 路径（已由 replay_prepare 完成初始化）继续跳过；而非 CUDA Graph 路径则允许 forward_extend 内部自动调用 init_forward_metadata，确保元数据与填充后的形状一致。

关键文件：

• python/sglang/srt/speculative/eagle_info_v2.py（模块 推测解码；类别 source；类型 core-logic；符号 prepare_for_v2_verify）: 在 prepare_for_v2_verify 中移除了非 CUDA Graph 路径下的提前 init_forward_metadata 调用，修复了元数据形状不匹配的根源。
• python/sglang/srt/speculative/eagle_worker_v2.py（模块 推测解码；类别 source；类型 core-logic；符号 verify）: 将 skip_attn_backend_init 从硬编码 True 改为 can_run_cuda_graph，确保非 CUDA Graph 路径不会跳过元数据初始化，与 eagle_info_v2.py 的改动配合完成修复。

关键符号：prepare_for_v2_verify, verify

关键源码片段

python/sglang/srt/speculative/eagle_info_v2.py

在 prepare_for_v2_verify 中移除了非 CUDA Graph 路径下的提前 init_forward_metadata 调用，修复了元数据形状不匹配的根源。

# python/sglang/srt/speculative/eagle_info_v2.py (modified)
# 在 prepare_for_v2_verify 方法中，原 else 分支提前 init 被移除
        can_run_cuda_graph = bool(
            target_worker.model_runner.graph_runner
            and target_worker.model_runner.graph_runner.can_run(verify_forward_batch)
        )
        if can_run_cuda_graph:
            target_worker.model_runner.graph_runner.replay_prepare(verify_forward_batch)
        # 非 CUDA Graph 路径：将 init 延迟到 forward_extend
        # 此时 batch 已被 prepare_mlp_sync_batch 正确填充（pad），
        # 避免因预填充形状导致 DeepSeek-V4 索引器 /TVM kernel 形状不匹配
        return verify_forward_batch, can_run_cuda_graph

python/sglang/srt/speculative/eagle_worker_v2.py

将 skip_attn_backend_init 从硬编码 True 改为 can_run_cuda_graph，确保非 CUDA Graph 路径不会跳过元数据初始化，与 eagle_info_v2.py 的改动配合完成修复。

# python/sglang/srt/speculative/eagle_worker_v2.py (modified)
# 在 verify 方法中，调用 forward_batch_generation 时根据 CUDA Graph 可用性控制 skip
        # Run target verify batch in the main compute stream (GPU compute).
        # 只有 CUDA Graph 路径（已执行 replay_prepare）才跳过 init；
        # 非 CUDA Graph 路径需要 forward_extend 内部的 init（在 pad 之后）。
        forward_batch_output = self.target_worker.forward_batch_generation(
            batch=None,
            forward_batch=verify_forward_batch,
            is_verify=True,
            skip_attn_backend_init=can_run_cuda_graph, # 原为 True
        )

评论区精华

无 review 评论记录，但 PR body 和 commit 注释清晰地解释了 bug 原理和修复思路。讨论主要集中在 CI 测试结果上：基础测试中有部分失败，作者通过 /rerun-test 命令重新运行了相关的 4 个测试（test_disaggregation_dsv4.py、test_deepseek_v4_flash_fp4_b200.py、test_deepseek_v4_flash_fp4_h200.py、test_deepseek_v4_flash_fp8_h200.py），最终 4-gpu-b200 通过，8-gpu-h200 有 2 个失败（疑似环境问题）。

• CI 测试失败 (testing): 4-gpu-b200 测试通过，8-gpu-h200 有 2 个失败（可能为环境问题）。

风险与影响

• 风险：风险较低。变更仅涉及非 CUDA Graph 路径，CUDA Graph 路径（默认路径）行为完全不变。非 CUDA Graph 路径的改动是延迟了 init_forward_metadata 调用，属于典型的重排初始化顺序，逻辑上等价。潜在风险是如果其他后端依赖于 prepare_for_v2_verify 中提前初始化的元数据（例如某些自定义后端可能在 prepare 阶段读取 metadata），但当前代码逻辑表明没有这样的依赖。此外，性能上可能有一点微小开销（init 从 plan_stream 移到 forward_extend），但正如 PR 所说这是 minor cost。
• 影响：直接影响：修复了使用 --disable-cuda-graph 运行 DeepSeek-V4 等需要精确元数据的模型时的崩溃问题。影响范围限定于非 CUDA Graph 路径下的 EAGLE v2 验证阶段，对其他功能（如采样、grammar）无影响。用户层面，该修复确保了禁用 CUDA Graph 时的正确性，提高系统鲁棒性。团队层面，该 PR 展示了如何正确处理 CUDA Graph 与非 CUDA Graph 路径的差异，为后续类似问题提供了参考。
• 风险标记：非默认路径, 缺少测试覆盖, 核心路径变更

关联脉络

• PR #26239 [dsv4] fix multi-step draft on non-cuda-graph path: 同一个作者针对相似问题（DSv4 非 CUDA Graph 路径）的修复，涉及相同的文件 eagle_worker_v2.py 和 eagle_utils.py，构成连续修复工作。
• PR #26047 Add --disable-attn-tp-gather opt-out for model-managed SP: 涉及 --disable-cuda-graph 等 opt-out 配置的引入，与本 PR 的非 CUDA Graph 路径上下文相关。