执行摘要

• 一句话：Voxtral Realtime 解码接入完整 CUDAGraph，吞吐提升 10%-24%
• 推荐动作：值得精读。该 PR 是理解 vLLM V1 CUDAGraph 与 attention backend 契约的极好样例：_cudagraph_support 能力声明、持久缓冲区 + 就地 copy_、禁用会绕过自定义 metadata 的快速路径，这三个手法组合起来解决了“捕获期地址固化”这一核心约束。关注重点：WhisperCausalAttentionWithBlockPoolingBuilder.build 的重写方式，以及 voxtral_realtime.py 中 mixed_mode() 断言的语义。

功能与动机

PR body 明确说明了动机与阻塞点：Currently decode steps are stuck on piecewise capture and pay the per-step launch overhead. The blocker is the whisper encoder's block-pooling attention builder: its build did a copy.deepcopy of the common attention metadata and allocated a fresh slot_mapping every step, so the tensor addresses baked in at capture time were dead by replay. 即：解码步长较短、per-step kernel launch 开销占比高，而完整 CG 一次性捕获整步可大幅削减 launch 次数；唯一障碍是 block-pooling builder 每次生成新张量，破坏捕获期的地址稳定性。

实现拆解

实现分为四步：

1. 能力声明与快速路径禁用（vllm/model_executor/models/whisper_causal.py）
   - 在 WhisperCausalAttentionWithBlockPoolingBuilder 上新增 _cudagraph_support: ClassVar[AttentionCGSupport] = AttentionCGSupport.UNIFORM_SINGLE_TOKEN_DECODE，向 CUDAGraph runner 声明该 builder 只对“纯解码、每序列单 token”的均匀批次支持完整捕获，其余场景自动回退 piecewise。
   - 新增 supports_update_block_table: bool = False：disabled 掉 runner 的 update_block_table 快捷路径，因为该路径会用原始 slot_mapping / block_table 直接拼接缓存 metadata，绕过 block pooling 的扩池逻辑，导致捕获期与重放期的 metadata 不一致。

2. 持久缓冲区 + build 重写（whisper_causal.py）
   - 新增 _maybe_init_pool_buffers：首次 build 时按输入张量的 dtype / device，结合 scheduler_config.max_num_seqs 与 max_num_batched_tokens 上限，惰性分配 _qsl_buf、_seq_buf、_slot_buf、_pool_arange 四个持久缓冲区，此后所有 capture / replay 复用同一块地址。
   - 重写 build：query_start_loc、seq_lens 缩放后通过 copy_ / mul_ 就地写入缓冲区头部切片；slot_mapping 按 block_pool_size 展开写入 _slot_buf，padding 槽位 -1 经 clamp(min=-1) 保持跳过语义；CPU 侧张量不参与捕获，直接新建缩放副本；最后用 cm.replace(...)（dataclasses.replace 语义）基于原 metadata 生成新实例并调用父类 build。

3. 模型入口断言放宽（vllm/model_executor/models/voxtral_realtime.py）
   - VoxtralRealtimeGeneration.__init__ 中的断言从 not has_full_cudagraphs() 改为 not cudagraph_mode.mixed_mode().has_full_cudagraphs()：纯 CUDAGraphMode.FULL 仍被拒绝，FULL_DECODE_ONLY 与 FULL_AND_PIECEWISE 放行，并更新报错文案提示用户改用这两种模式。

4. 测试配套（tests/models/multimodal/generation/test_voxtral_realtime.py）
   - 抽取 _build_inputs 与 _assert_expected_text 复用逻辑；新增 test_voxtral_realtime_cudagraph，以 current_platform.is_cuda() 为 skipif 条件，参数化 FULL_DECODE_ONLY 与 FULL_AND_PIECEWISE 两种模式，enforce_eager=False、cudagraph_capture_sizes=[4]，用真实音频资产端到端验证输出文本与 eager 基准一致。

关键文件：

• vllm/model_executor/models/whisper_causal.py（模块 注意力层；类别 source；类型 data-contract；符号 _maybe_init_pool_buffers, build, WhisperCausalAttentionWithBlockPoolingBuilder）: 核心改造文件：block-pooling attention builder 从 deepcopy + 新建张量改为持久缓冲区 + 就地写入，使其对 uniform single-token decode 捕获安全；同时声明 UNIFORM_SINGLE_TOKEN_DECODE 能力并禁用 update_block_table 快路径。
• vllm/model_executor/models/voxtral_realtime.py（模块 模型入口；类别 source；类型 data-contract；符号 VoxtralRealtimeGeneration.init）: 模型入口：放宽 CUDAGraph 模式断言，从禁止任何 full CG 改为仅禁止纯 FULL，放行 FULL_DECODE_ONLY 与 FULL_AND_PIECEWISE。
• tests/models/multimodal/generation/test_voxtral_realtime.py（模块 模型测试；类别 test；类型 test-coverage；符号 _build_inputs, _assert_expected_text, test_voxtral_realtime_cudagraph）: 测试配套：抽取输入构建与文本断言辅助函数，新增参数化 CUDA-only 的 cudagraph E2E 测试，覆盖 FULL_DECODE_ONLY 与 FULL_AND_PIECEWISE 两种模式。

关键符号：_maybe_init_pool_buffers, WhisperCausalAttentionWithBlockPoolingBuilder.build, VoxtralRealtimeGeneration.init, test_voxtral_realtime_cudagraph

评论区精华

该 PR 无实质技术争论（review_comments_count = 0），主要讨论集中在流程与署名：

• MatthewBonanni 人工 review：LGTM, thanks!，直接 APPROVED，说明方案在维护者视角下风险可控。
• JorgeGF24 的署名请求：coauthored-by: was not parsed correctly in commit. Could the merger include Co-authored-by: Jorge Gallego Feliciano <jorge.gallego@mistral.ai> in the squash message? 最终提交信息中确已包含该行。
• mergify[bot] 多次提示冲突：This pull request has merge conflicts that must be resolved before it can be merged. Please rebase the PR，作者通过 rebase 解决后推送 cd745ed，触发 CI #88857 后合并。

• claude[bot] 说明：fork 来源的 PR 不自动执行 Claude 审查，需维护者手动触发，因此技术审查完全依赖人工。

  • Co-authored-by 署名与 squash 信息 (other): 最终提交信息中包含该 Co-authored-by 行，署名问题解决。
  • 合并冲突与 rebase (other): 作者 rebase 后推送最终 commit cd745ed，触发 CI #88857 后合并。
  • fork PR 自动化审查禁用 (other): 人工 review 由 MatthewBonanni 完成并 APPROVED（LGTM）。

风险与影响

• 风险：
  • 共享 builder 行为变更：whisper_causal.py 的 create_whisper_attention_backend_with_block_pooling 服务所有使用 whisper 编码器的模型。build 从“每次 deepcopy 生成全新张量”改为“就地写入持久缓冲区”，若外部调用方持有旧返回 metadata 中的张量引用并期望不被改写，会观察到数据被就地更新。语义上缩放 / 展开 / clamp 结果一致，但引用语义有变化。
  • 快速路径被禁用：supports_update_block_table = False 会让非 CG 路径（eager、piecewise）也丢失该快捷路径，PR 未提供 eager / piecewise 模式的前后性能对比，存在小幅回退的可能。
  • CUDA-only 验证：测试用 skipif(not current_platform.is_cuda()) 跳过非 CUDA 平台，ROCm 等后端的行为未验证；AttentionCGSupport 声明也可能与后端能力不匹配。
  • 显存与越界：新增缓冲区按 max_num_seqs / max_num_batched_tokens 上限分配，断言防越界，但超大 max_num_batched_tokens 配置下显存占用会额外增加 max_num_batched_tokens * block_pool_size 的 slot 缓冲区。
• 影响：
  • 用户与服务：Voxtral Realtime 在纯解码批次下的吞吐提升 1.10x-1.24x（batch 4 时最高），cudaGraphLaunch 次数从约 12,272 降到约 208，显著降低 per-step launch 开销；prefill / 混合批次保持原 piecewise 行为不变。
  • 系统与代码：变更集中在 whisper block-pooling attention builder 与 Voxtral 模型入口，影响面限定在使用该 builder 的语音模型族；为后续其他 whisper 派生模型接入 FULL_DECODE_ONLY 提供了可复用的 capture-safe 模式。
  • 团队：无需新增配置项，用户只需在启动参数中选用 FULL_DECODE_ONLY 或 FULL_AND_PIECEWISE 即可受益。
  • 风险标记：共享 attention builder 行为变更, 禁用 update_block_table 快路径, 仅 CUDA 验证，ROCm 跳过, 非 CG 路径性能回退待评估

关联脉络

• PR #56808 [CI] Initialize ubatch runner in cudagraph unit test: 同为 CUDAGraph 解码路径的测试与 CI 保障，验证 cudagraph capture / replay 相关逻辑的稳定性。
• PR #56722 [PCP][DCP] Declare FlashMLASparse MTP support at CP interleave > 1: 同样是“在 attention 后端上声明能力、解除组合限制”的模式，与本 PR 的 _cudagraph_support 声明思路一致。