执行摘要

本PR通过引入PrefillStats数据结构替换了原有的num_cached_tokens和num_external_computed_tokens字段，解决了调度器在preemption和KV传输失败下prefill统计不准确的问题，提升了metrics报告的正确性，并简化了代码路径，为后续清理奠定基础。

功能与动机

动机源于PR #36859中讨论的Counters can only be incremented by non-negative amounts错误，该错误由num_cached_tokens和num_external_computed_tokens在preemption下的不一致设置导致。PR body进一步指出，随着#38096的合并，num_cached_tokens不再用于KV传输失败恢复，因此本PR移除了脆弱的错误处理逻辑，改用PrefillStats在请求首次调度时记录统计信息，确保metrics的清晰性和准确性。

实现拆解

关键改动按模块分解：

• metrics模块（vllm/v1/metrics/stats.py）：新增PrefillStats dataclass，包含num_prompt_tokens、num_local_cached_tokens等字段，并修改PromptTokenStats.update_from_output()以使用新结构。
• scheduler模块（vllm/v1/core/sched/scheduler.py）：在schedule()方法中首次调度prefill时设置request.prefill_stats，并通过SchedulerOutput传递。
• engine模块（vllm/v1/engine/__init__.py）：更新EngineCoreOutput，移除旧字段，添加prefill_stats可选字段。
• core模块（vllm/v1/request.py）：在Request类中新增prefill_stats字段和take_prefill_stats()方法，移除num_cached_tokens和num_external_computed_tokens。
• 测试更新：同步修改了多个测试文件，如tests/v1/metrics/test_stats.py，以验证新逻辑的正确性。

评论区精华

Review讨论中突出以下交锋：

1. 双计数争议：gemini-code-assist[bot]指出metrics计算可能存在双计数，但markmc解释这是预期行为，并引用#33289说明设计意图，结论是计划在#38709中进一步处理。
2. 设计简化：orozery质疑set_once()的必要性，认为调度器应直接负责统计，经讨论后第二个commit移除了该行为，代码更简洁。
3. 测试边界：gemini-code-assist[bot]提到测试断言在提示长度整除BLOCK_SIZE时可能不准确，markmc回应未来场景需调整，但当前暂不处理。

风险与影响

• 风险：核心调度路径变更可能引入回归，尤其是在复杂preemption场景；移除旧字段可能破坏依赖代码；测试覆盖不足可能隐藏边缘情况bug。
• 影响：用户将获得更准确的prompt tokens metrics，但需更新监控工具；系统代码更健壮，减少了错误处理复杂度；团队需适应新结构，后续PR可能继续清理。

关联脉络

本PR与多个历史PR紧密相关：

• 36859直接启发了本PR，修复了字段设置不一致问题。

• 38096为移除KV传输失败恢复逻辑提供了前提。

• 38709计划解决review中提及的metrics双计数问题，显示功能演进的连续性。

  
  整体上，这一系列变更反映了vLLM在核心调度和metrics模块上持续优化，以提升可靠性和可维护性。