执行摘要

• 一句话：为 MRV2 模型运行器添加 CUDAGraphStat 传播，提升 CUDA 图可观测性。
• 推荐动作：建议精读，本 PR 展示了如何在 MRV2 中添加可观测性指标，设计简洁且通过辅助方法保持主路径清洁。关键决策包括条件性创建和元组字段扩展，可为后续指标添加提供参考。

功能与动机

作者在 PR body 中明确目的是“Propagate CUDAGraphStat through ExecuteModelState so generation outputs expose the actual CUDA graph mode and padding counts. Exclude dummy runs from user-visible metrics.” 在关联 Issue 评论中，作者进一步确认实际使用这些指标调查性能回归，并质疑为什么默认不启用，表明了真实需求。

实现拆解

1. 新增辅助函数：在 vllm/v1/worker/gpu/cudagraph_utils.py 中定义 make_cudagraph_stats 函数，接受 BatchExecutionDescriptor 和 num_tokens 参数，返回 CUDAGraphStat 实例。此函数封装统计信息创建逻辑，提升代码可维护性。
2. 集成到模型运行器：在 vllm/v1/worker/gpu/model_runner.py 的 execute_model 方法中，当非虚拟运行且 observability_config.cudagraph_metrics 启用时，调用 make_cudagraph_stats 生成统计信息。将 cudagraph_stats 字段添加到 ExecuteModelState 元组，并在 sample_tokens 方法中提取并传递给 ModelRunnerOutput，确保统计信息流经下游。
3. 测试更新：在 tests/v1/worker/test_gpu_model_runner_v2_eplb.py 中，为模拟的 ExecuteModelState 添加 cudagraph_stats=None 字段，以匹配新的数据契约，确保测试通过。

关键文件：

• vllm/v1/worker/gpu/cudagraph_utils.py（模块 CUDA图工具；类别 source；类型 core-logic；符号 make_cudagraph_stats）: 新增 make_cudagraph_stats 辅助函数，封装 CUDAGraphStat 创建逻辑，是实现的核心入口。
• vllm/v1/worker/gpu/model_runner.py（模块 模型运行器；类别 source；类型 data-contract）: 集成 CUDAGraphStat 到执行流程，通过 ExecuteModelState 和 ModelRunnerOutput 传播统计信息，是数据契约变更的关键文件。
• tests/v1/worker/test_gpu_model_runner_v2_eplb.py（模块 EPLB测试；类别 test；类型 test-coverage）: 更新测试以覆盖 ExecuteModelState 的新字段 cudagraph_stats，确保测试兼容性。

关键符号：make_cudagraph_stats

关键源码片段

vllm/v1/worker/gpu/cudagraph_utils.py

新增 make_cudagraph_stats 辅助函数，封装 CUDAGraphStat 创建逻辑，是实现的核心入口。

# 从 cudagraph_utils.py 中提取的 make_cudagraph_stats 函数
# 该函数将批次执行描述符和实际令牌数转换为 CUDAGraphStat 对象，
# 包含未填充令牌数、填充后令牌数、填充计数和运行时模式字符串。
def make_cudagraph_stats(
    batch_desc: BatchExecutionDescriptor, num_tokens: int
) -> CUDAGraphStat:
    return CUDAGraphStat(
        num_unpadded_tokens=num_tokens,
        num_padded_tokens=batch_desc.num_tokens,
        num_paddings=batch_desc.num_tokens - num_tokens,
        runtime_mode=str(batch_desc.cg_mode),
    )

评论区精华

• 代码结构优化：Review 中 njhill 建议将统计信息创建移入 if not dummy_run 块内，并提议在 cudagraph_utils.py 中提取辅助方法 make_cudagraph_stats，以简化主流程代码。作者采纳并重构，体现了对代码清晰度的重视。

• 指标实用性讨论：在 Issue 评论中，njhill 询问作者是否真正需要这些指标，作者确认用于性能回归调查，并建议改进显示方式。结论是保留该指标但未修改默认启用行为。

• 代码结构优化：使用辅助函数简化主流程 (design): 作者采纳并重构，添加了 make_cudagraph_stats 函数。

风险与影响

• 风险：技术风险较低：指标创建仅在 cudagraph_metrics 配置启用时触发，避免性能开销；变更限于数据传播路径，不涉及核心计算逻辑。潜在风险包括：若 CUDAGraphStat 数据结构未来变更，需同步更新 make_cudagraph_stats；测试覆盖仅针对 EPLB 场景，其他模型运行器路径未测试。
• 影响：对用户的影响：提升 CUDA 图执行的可观测性，帮助调试性能问题；对系统的影响：增加少量元数据传递，无功能破坏性变更；对团队的影响：提供了指标传播的设计模式，可扩展到其他 MRV2 指标。
• 风险标记：条件性指标创建

关联脉络

• PR #54901 [Perf][Model Runner V2] Compact sampling masks on GPU instead of unpacking the full-vocab bitmask on CPU: 同为 MRV2 模型运行器的性能或可观测性改进，涉及类似的数据传播路径（如 outputs.py）。