执行摘要

本次PR修复了稀疏注意力索引器（sparse_attn_indexer.py）中两处张量形状不匹配问题，这些问题在使用推测解码（MTP/EAGLE）和填充解码批次时会导致RuntimeError，影响DeepSeek-V3.2等模型的运行。修复通过对齐序列长度参数和缓冲区切片逻辑，确保了形状一致性，提升了系统在边缘场景下的稳定性。PR已合并，风险可控。

功能与动机

问题背景：在运行DeepSeek-V3.2-NVFP4模型时，当同时启用推测解码（MTP）和填充解码批次（requires_padding=True）时，会出现RuntimeError，错误信息如Target sizes: [104, 2048]. Tensor sizes: [98, 2048]。

根本原因：之前的重构在切片decode_metadata.seq_lens时，遗漏了两个下游消费者：

1. persistent_topk内核仍使用未切片的序列长度，导致输出行数不匹配。
2. topk_indices_buffer写回时使用num_decode_tokens（填充前总令牌数），而非解包后的实际行数。

触发条件：仅当三个条件同时满足时才会触发：推测解码激活（next_n > 1）、requires_padding=True（短预填充块混入解码批次）、填充批次大小与原始解码令牌数不同。

实现拆解

修改仅涉及一个文件vllm/model_executor/layers/sparse_attn_indexer.py，包含两处关键改动：

其中seq_lens是已正确切片为batch_size的序列长度张量。

评论区精华

review中仅有一条实质性评论来自gemini-code-assist[bot]，它指出：

"The change to use seq_lens instead of decode_metadata.seq_lens is correct for ensuring the kernel processes the expected number of rows. However, there is a potential data corruption issue when requires_padding is True. The topk_indices tensor is a view into the shared topk_indices_buffer with a size of num_padded_tokens. If num_padded_tokens exceeds the actual number of decode tokens (num_decode_tokens), this view overlaps with the prefill results..."

核心交锋：虽然形状修复正确，但bot警告了当填充启用时，视图可能覆盖共享缓冲区中的预填充结果，存在数据损坏风险。然而，维护者WoosukKwon直接批准了合并，表明团队认为当前修复足以解决报告的RuntimeError，重叠风险可能已在其他逻辑中处理或被视为低优先级。

风险与影响

技术风险：

1. 数据损坏风险：如bot所述，当requires_padding=True时，topk_indices视图可能覆盖topk_indices_buffer中的预填充结果。但鉴于PR已针对特定错误场景测试通过，实际影响可能有限。
2. 回归风险：低，变更仅调整形状对齐，不改变算法逻辑。
3. 兼容性：无影响，修复后行为更符合预期。

影响范围：

• 用户影响：修复了使用稀疏注意力和推测解码的用户在特定条件下的崩溃问题，提升体验。
• 系统影响：增强了对边缘批次处理场景的鲁棒性，特别是短预填充块与解码混合时。
• 团队影响：揭示了稀疏注意力与推测解码集成时的形状处理陷阱，为类似bug提供参考。

关联脉络

从近期历史PR看，稀疏注意力和推测解码是vLLM持续优化的重点领域：

• PR 39225：修复了ROCm稀疏注意力索引器在推测解码下的越界读取问题，与本PR同属稀疏注意力索引器的bugfix，但针对不同平台（ROCm vs 通用）。
• PR 39253：修复了GLM工具解析器在推测解码下的参数格式错误，展示了MTP集成中的常见问题模式。

演进趋势：推测解码（MTP/EAGLE）作为性能优化特性，在与稀疏注意力、工具解析等模块集成时，容易因形状、填充等边缘条件引发bug。本PR是这一趋势下的又一个正确性修复，强调了在复杂推理场景下张量形状一致性的重要性。