执行摘要

该PR修复了参数解耦（PD）场景下HiCache缓存命中细粒度统计信息无法正确传递的问题。通过扩展解码传输、元数据缓冲区和重构调度器输出处理器，新增cached_tokens_device、cached_tokens_host、cached_tokens_storage三个字段，确保设备、主机、存储三级缓存的统计在分布式和非分布式场景下都能完整展示。这是一个低风险但重要的可观测性修复，不影响核心推理逻辑。

功能与动机

修复动机源于历史PR #17648（具体内容未提供），推测先前存在PD场景下缓存统计不完整的问题。作者在review讨论中进一步解释："storage type是字符串，在PD实例间传输难以定义，暂时不支持该字段"，且"集群通常只选择单一存储后端——固定值，无需在PD实例间传输"。因此，本次修复聚焦于确保数值型缓存统计（设备、主机、存储命中数）在PD场景下的正确传递，放弃字符串类型的storage_backend字段以简化实现。

实现拆解

实现涉及三个关键文件，按数据流顺序拆解：

1. 解码传输层（python/sglang/srt/disaggregation/decode.py）：

   • 在_commit_transfer_to_req函数中，从cached_tokens数组（索引1-3）提取三级缓存计数：
     

     decode_req.req.cached_tokens_device = cached_tokens[1].item()
     decode_req.req.cached_tokens_host = cached_tokens[2].item()
     decode_req.req.cached_tokens_storage = cached_tokens[3].item()
     

2. 元数据缓冲区（python/sglang/srt/disaggregation/utils.py）：

   • 在MetadataBuffers.set_buf方法中，将请求对象的新字段写入缓冲区对应位置：
     

     self.cached_tokens[req.metadata_buffer_index][1] = req.cached_tokens_device
     self.cached_tokens[req.metadata_buffer_index][2] = req.cached_tokens_host
     self.cached_tokens[req.metadata_buffer_index][3] = req.cached_tokens_storage
     

3. 调度器输出处理（python/sglang/srt/managers/scheduler_output_processor_mixin.py）：

   • 重构_get_cached_tokens_details方法，简化逻辑：
     • 移除对enable_hierarchical_cache的强依赖
     • 根据字段存在性动态返回统计字典
     • 保留storage_backend字段的兼容性（非PD场景）

评论区精华

review讨论中几个有价值的交锋：

• 代码风格争议：gemini-code-assist[bot]指出magic number索引（1,2,3）应替换为命名常量：

  "Using magic numbers (1, 2, 3) for accessing elements of cached_tokens can make the code harder to read and maintain."
  作者未在本次PR中采纳，但该建议为后续优化留下空间。

• 设计权衡：vladnosiv建议删除已不再使用的_get_storage_backend_type辅助函数，作者回应：

  "Oh, in that case, let's keep it for now; that way, the information can still be passed along properly even when PD isn't open."
  这体现了向后兼容性的谨慎考虑。

• 术语优化：ShangmingCai提议"is_breakdown"可能比现有术语更准确，但未强制修改，显示团队对命名细节的关注。

风险与影响

风险点：

1. 魔法数字索引增加未来维护成本，特别是当缓存层级扩展时。
2. 上下文未提供测试变更，需确保PD场景下新增字段的端到端测试覆盖。
3. 重构后的_get_cached_tokens_details方法需验证所有缓存场景（HiCache启用/禁用、PD/非PD）的逻辑正确性。

影响分析：

• 对用户透明，仅影响内部监控数据准确性。
• 提升分布式场景下缓存性能分析的能力，便于优化三级缓存策略。
• 代码变更范围小（16行新增，8行删除），回归风险低。

关联脉络

从近期历史PR可见相关脉络：

• PR #21884：同样涉及HiCache模块的修改（移除TTL硬钉），显示团队持续优化缓存管理。
• PR #19890：同属参数解耦（PD）场景的优化，引入GPU暂存缓冲区提升传输吞吐量，与本PR共同完善PD场景下的性能可观测性。
• PR #21705：同样修改调度器相关逻辑（修复暂停模式内存泄漏），反映调度器模块的持续迭代。

整体来看，sglang项目在参数解耦和缓存管理两个方向持续投入，本PR是这一演进中的一环，通过完善统计信息为后续性能优化提供数据支撑。