执行摘要

• 一句话：修复 UBatch CUDA graph 缓存键仅用前两个微批次求和的问题
• 推荐动作：值得合入：精准的一行修复，有明确的 issue 复现和测试脚本验证。推荐所有使用 ubatch > 2 且开启 FULL CUDA graph 的场景升级此修复。

功能与动机

Issue #43145 报告：当 ubatch_size > 2 且 FULL CUDA graph capture 启用时，_capture_ubatches() 将捕获的 graph 存储在仅前两个微批次的 token 总数下，而 call() 使用所有微批次的 token 总数作为缓存键，导致已捕获的 graph 永远不会被命中，每次调用都会重新捕获，造成性能退化。

实现拆解

1. 修改缓存键计算（vllm/v1/worker/gpu_ubatch_wrapper.py，第 255 行）：将 num_tokens = ubatch_metadata[0].num_tokens + ubatch_metadata[1].num_tokens 改为 num_tokens = sum(m.num_tokens for m in ubatch_metadata)，使存储键与查找键一致。
2. 更新注释（第 270 行、第 335 行）：将 self.ready_barrier.wait() # Wait for both threads to be ready 改为 # Wait for all ubatch threads to be ready，避免混淆。

关键文件：

• vllm/v1/worker/gpu_ubatch_wrapper.py（模块 CUDA Graph；类别 source；类型 core-logic；符号 _capture_ubatches, _run_ubatches）: 唯一变更文件，包含缓存键计算的核心逻辑修复和注释更新。

关键符号：_capture_ubatches, _run_ubatches

评论区精华

本 PR 仅有一个来自 gemini-code-assist[bot] 的自动化评论，无实质争议。评审者 njhill 直接批准。pr 作者 liulanze 在合并前评论确认两个 CI 失败与本次修改无关（一个为 Buildkite 缓存问题，一个为端口冲突抖动）。

• CI 失败与本次修改无关 (other): 评审者未提出异议，PR 被合并。

风险与影响

• 风险：风险极低：改动仅修改一行计算逻辑和两行注释，逻辑等价于将硬编码的前两个求和改为通用求和。但需要确保所有调用路径中 ubatch_metadata 不为空且顺序与预期一致。若 ubatch_metadata 长度可能为 0 或 1，则 sum() 仍可正确工作（空列表和为 0），而原代码在 ubatch_size=1 时会索引到 ubatch_metadata[1] 导致 IndexError。所以修改变更实际上是修复了一个潜在的隐患。
• 影响：直接影响：当 ubatch_size > 2 时，CUDA graph 缓存不再每次错过，避免额外的重新捕获开销，恢复预期性能。对于 ubatch_size <= 2 的场景行为不变。调整范围仅限于 UBatchWrapper._capture_ubatches() 方法，不涉及其它模块。
• 风险标记：暂无

关联脉络

• 暂无明显关联 PR