执行摘要

• 一句话：修复非 stride 倍数时 max_num_batched_tokens 不被 CUDA graph 捕获
• 推荐动作：建议合并。这是影响实际生产性能的 bugfix，改动量小、逻辑清晰。同时建议后续考虑是否允许用户选择 padding 到下一个 stride 的策略，但当前方案足以解决问题。

功能与动机

PR 描述中说明：“When max_num_batched_tokens is not a multiple of the stride, it won't be captured. So when the model runs at max batch size, it falls back to eager mode, causing significant performance degradation.” 并附有 benchmark 对比：以 max-num-batched-tokens=700（非 stride 倍数）与 768（stride 倍数）相比，吞吐量从 5400 tok/s 下降到 16639 tok/s，性能差异达 3 倍。

实现拆解

1. 核心逻辑修改（vllm/config/vllm.py 的 _set_cudagraph_sizes 方法）：在默认捕获大小列表（步长 8/16 的序列）生成完成后，增加条件判断——若 max_num_tokens（代表 max_num_batched_tokens 经过与 max_cudagraph_capture_size 取小后的实际值）不超过 max_cudagraph_capture_size 且不在生成列表中，则将该值追加到列表末尾。后续会进行去重和排序。
2. 文档更新：在同一个方法的 docstring 中增加说明：“max_num_batched_tokens is also appended to the list if it fits within max_cudagraph_capture_size, so the max batch size is captured even when off-stride.”
3. 测试补充（tests/compile/test_config.py）：在参数化测试 test_cudagraph_sizes_post_init 中新增一个用例，参数为 cudagraph_capture_sizes=None, max_cudagraph_capture_size=2048, max_num_batched_tokens=257, expected_max_size=257，验证当 max_num_batched_tokens 为 257（非 stride 倍数）时，最终捕获大小列表中的最大值确实为 257。

关键文件：

• vllm/config/vllm.py（模块 编译配置；类别 source；类型 core-logic；符号 _set_cudagraph_sizes）: 核心配置文件，定义了 CUDA graph 捕获大小的生成逻辑。修改了 _set_cudagraph_sizes 方法，在默认列表生成后追加 max_num_tokens。
• tests/compile/test_config.py（模块 测试；类别 test；类型 test-coverage；符号 test_cudagraph_sizes_post_init）: 参数化测试 test_cudagraph_sizes_post_init 新增一个用例验证 off-stride max_num_batched_tokens 被捕获。

关键符号：_set_cudagraph_sizes, test_cudagraph_sizes_post_init

关键源码片段

vllm/config/vllm.py

核心配置文件，定义了 CUDA graph 捕获大小的生成逻辑。修改了 _set_cudagraph_sizes 方法，在默认列表生成后追加 max_num_tokens。

def _set_cudagraph_sizes(self):
    """
    vLLM defines the default candidate list of batch sizes for CUDA graph
    capture as:
    ...
    `max_num_batched_tokens` is also appended to the list if it fits
    within `max_cudagraph_capture_size`, so the max batch size is captured
    even when off-stride.
    ...
    """
    # ... ( 前面逻辑略 ) ...
    else:
        # 生成默认捕获大小列表
        if self.performance_mode == "interactivity":
            interactivity_max = min(max_cudagraph_capture_size, 32)
            cudagraph_capture_sizes = list(range(1, interactivity_max + 1))
        else:
            cudagraph_capture_sizes = [
                i for i in [1, 2, 4] if i <= max_cudagraph_capture_size
            ]
        if max_cudagraph_capture_size >= 8:
            cudagraph_capture_sizes += list(
                range(8, min(max_cudagraph_capture_size + 1, 256), 8)
            )
        if max_cudagraph_capture_size >= 256:
            cudagraph_capture_sizes += list(
                range(256, max_cudagraph_capture_size + 1, 16)
            )
        # 确保 max_num_tokens 被捕获（如果它在最大捕获范围内）
        # 这解决了当 max_num_batched_tokens 不是 stride 倍数时
        # 无法被捕获的问题
        if (
            max_num_tokens <= max_cudagraph_capture_size
            and max_num_tokens not in cudagraph_capture_sizes
        ):
            cudagraph_capture_sizes.append(max_num_tokens)
        # 去重并排序
        cudagraph_capture_sizes = sorted(set(cudagraph_capture_sizes))
    # ...

评论区精华

审核者 ZJY0516 最初对“静默变更”表示担忧，认为应该采用填充到下一个 stride 的方式而非直接追加，但后续认可了本次方案并批准了 PR，同时建议更新 docstring 以明确行为。PR 作者 wzhao18 随即将 docstring 更新，并在回复中解释了合理性。

• 静默变更 vs 填充策略 (design): 同意当前实现，并更新了 docstring 明确行为。
• 文档更新需求 (documentation): 已更新 docstring。

风险与影响

• 风险：风险极低：改动发生在默认捕获大小列表生成分支（非用户自定义列表分支），且仅当 max_num_tokens 不在列表中时追加，不会破坏现有行为。但需注意，如果 max_num_tokens 原本非常接近但小于 max_cudagraph_capture_size，多加一个捕获点会增加少量内存和捕获时间，但仅一个点，影响可忽略。无性能安全兼容性问题。
• 影响：正面影响所有使用 CUDA graph 且 max_num_batched_tokens 设置值不是 stride 倍数的用户，避免出现意外的 eager 模式回退，保证峰值吞吐量稳定。受影响范围限于 decode 阶段使用 CUDA graph 的推理场景。改动极小，无破坏性。
• 风险标记：性能关键路径, 最小改动, 边界条件修复

关联脉络

• 暂无明显关联 PR