# PR #21764 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[HiCache & PD]Fixed detailed cache hit breakdown in PD scenarios.
- 合并时间：2026-04-02 08:44
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/21764

---

# 执行摘要

该 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）提取三级缓存计数：
   ```python
   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` 方法中，将请求对象的新字段写入缓冲区对应位置：
   ```python
   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 是这一演进中的一环，通过完善统计信息为后续性能优化提供数据支撑。