执行摘要

• 一句话：修复 V2 模型运行器中 attn 元数据 max_seq_len 传递错误
• 推荐动作：值得精读，尤其是了解如何将 DefaultModelState 中的优化模式推广到其他 ModelState 实现，以及 speculative decoding 中 draft max_seq_len 的动态管理方式。设计决策清晰，代码差异小但影响正确性。

功能与动机

PR#40654 已经为 DefaultModelState 使用了基于实际 batch 的 max_seq_len，但 MambaHybrid 和 Eagle speculative decoding 的 attention 元数据仍然使用 max_model_len。传给 FlashInfer 等后端过大的 max_seq_len 会导致 attention 计算访问超出 block table 的有效范围，可能引发非法内存访问或错误结果。

实现拆解

1. MambaHybridModelState.prepare_attn (vllm/v1/worker/gpu/model_states/mamba_hybrid.py)：引入 seq_lens_cpu_upper_bound，在非 CUDA Graph 捕获时使用该上界的前 num_reqs 个元素的最大值作为 max_seq_len；捕获时仍使用 self.max_model_len 以保证图的有效性。
2. EagleSpeculator._build_draft_attn_metadata (vllm/v1/worker/gpu/spec_decode/eagle/speculator.py)：在 __init__ 中新增成员 draft_max_seq_len（初始化为 max_model_len），在 propose 方法中根据实际 batch 的 seq_lens_cpu_upper_bound 动态计算：draft_max_seq_len = min(实际最大序列长度 + num_speculative_steps, max_model_len)。然后将 _build_draft_attn_metadata 中使用的 max_seq_len 从 self.max_model_len 改为 self.draft_max_seq_len。
3. DefaultModelState.prepare_attn 微小 cleanup (vllm/v1/worker/gpu/model_states/default.py)：去除了之前引入的冗余 int() 转换，与 mamba_hybrid 中的写法保持一致。
4. 无测试文件变更：本次改动仅涉及源码主路径，未增加直接对应的测试用例。

关键文件：

• vllm/v1/worker/gpu/model_states/mamba_hybrid.py（模块 模型状态；类别 source；类型 data-contract；符号 prepare_attn）: 核心修复之一，使 MambaHybrid 的 attention 元数据使用实际 batch max_seq_len 而非 max_model_len
• vllm/v1/worker/gpu/spec_decode/eagle/speculator.py（模块 推测解码；类别 source；类型 core-logic；符号 init, _build_draft_attn_metadata, propose）: 修复 Eagle speculator 中 draft attention 元数据使用错误的 max_seq_len，新增 draft_max_seq_len 动态计算
• vllm/v1/worker/gpu/model_states/default.py（模块 模型状态；类别 source；类型 cleanup；符号 prepare_attn）: 伴随清理，去掉冗余的 int() 调用，保持与 mamba_hybrid 的一致性

关键符号：MambaHybridModelState.prepare_attn, EagleSpeculator._build_draft_attn_metadata, EagleSpeculator.propose, DefaultModelState.prepare_attn

评论区精华

Reviewer njhill 提出了三处小改进：（1）mamba_hybrid.py 中 max_seq_len 赋值不需要 int() 包装，被接受并连带清理了 default.py 中的相同冗余；（2）speculator.py 中 draft_max_seq_len 的计算建议简化为一行，被接受；（3）建议将成员变量名 _draft_max_seq_len 改为无下划线的 draft_max_seq_len，被接受。整个 review 过程简洁高效，无重大争议。

• 移除冗余 int() 转换 (style): 移除 int()，保持代码简洁一致。
• draft_max_seq_len 命名简化 (style): 重命名成员变量为 draft_max_seq_len。
• draft_max_seq_len 计算简化 (style): 使用简化后的单行表达式。

风险与影响

• 风险：低风险。变更是对已有模式（DefaultModelState）的对称扩展，逻辑简单。MambaHybrid 的修改与非捕获路径行为一致；Eagle 部分新增的 draft_max_seq_len 动态计算在 propose 中执行，覆盖了所有调用。潜在风险在于：如果 seq_lens_cpu_upper_bound 为 None 或长度不足，可能抛出索引错误（但该字段在 V2 中应为正常填充）。
• 影响：影响范围：MambaHybrid 模型和 Eagle/MTP speculative decoding 的执行路径。这些路径在 max_model_len 远大于实际 batch 序列长度时，之前可能包含无效 attention 计算，现在只会访问有效范围，预期提升性能和正确性。无用户可见的 API 变更。
• 风险标记：缺少测试覆盖

关联脉络

• PR #40654 Use actual batch max_seq_len for attn metadata in DefaultModelState: 该 PR 是此 PR 的前置基础，引入了在 DefaultModelState 中使用实际 batch max_seq_len 的模式，此 PR 将其推广到 MambaHybrid 和 Eagle 路径。
• PR #43990 [Model Runner V2] Support zeroing freshly allocated KV blocks for hybrid + fp8 KVCache: 也涉及 MambaHybrid 的 KV cache 处理，两者共同完善混合模型的 V2 运行器支持。