# PR #22170 完整报告

- 仓库：`sgl-project/sglang`
- 标题：fix hisparse LRU policy
- 合并时间：2026-04-06 09:47
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/22170

---

# 执行摘要

本次 PR 修复了 Hisparse JIT 内核中 LRU 策略的实现错误，将 LRU 写回逻辑从缓存命中统计前移至 miss 数量计算后，确保新加载的 miss 条目能正确放置在 LRU 序列中。这是一个对核心缓存管理逻辑的关键修复，直接影响缓存淘汰顺序的正确性和系统稳定性。变更仅涉及一个文件（hisparse.cuh），但属于 JIT 内核的核心路径，建议结合历史 Hisparse 相关 PR 一起评估。

# 功能与动机

修复目标是解决 Hisparse LRU 策略的实现错误。从 review 评论可以看出，原实现中 LRU 写回逻辑依赖的 `total_misses` 计算可能不准确，需要更稳健地使用共享内存中的实际 miss 计数。PR 标题直接点明“fix hisparse LRU policy”，但 PR body 中未详细描述具体问题场景，需从代码变更推断修复动机。

# 实现拆解

仅修改 `python/sglang/jit_kernel/csrc/hisparse.cuh` 文件中的 `load_cache_to_device_buffer_kernel` 函数。关键变更如下：

1. **位置移动**：将 LRU 写回逻辑从第 281 行附近移动到第 351 行之后（`total_misses` 计算之后）。
2. **逻辑重构**：原 LRU 写回循环仅区分 evictables 和 hits，新逻辑增加 misses 处理：
   ```c++
   if (i < total_misses) {
       // Misses: just loaded from host, place right before hits
       req_lru_slots[total_evictable - total_misses + i] = s_lru_slots_out[HOT_BUFFER_SIZE - 1 - i];
   } else if (i < total_evictable) {
       // Remaining evictables: truly stale, dest at LRU front
       req_lru_slots[i - total_misses] = s_lru_slots_out[HOT_BUFFER_SIZE - 1 - i];
   } else {
       // Hits: source at forward end, dest at MRU back
       req_lru_slots[i] = s_lru_slots_out[i - total_evictable];
   }
   ```
3. **计算依赖**：LRU 写回现在依赖正确计算的 `total_misses`（`NUM_TOP_K - s_total_hits - s_newest_hit`）。

# 评论区精华

review 中只有 gemini-code-assist[bot] 的一条评论，但提出了重要技术观点：

> "The LRU write-back logic relies on `total_misses`, which is calculated at line 339 using the formula `NUM_TOP_K - s_total_hits - s_newest_hit`. This formula assumes that `s_total_hits` (which counts hit slots) is equal to the number of unique top-k tokens found in the buffer. While likely true in a well-managed cache, it is more robust to use the actual count of misses identified during the third pass, which is already available in shared memory at `s_chunk_offset[NUM_TOKEN_CHUNKS]` after the synchronization at line 337."

该评论指出当前 miss 计数计算方式存在假设风险，建议使用更稳健的实际统计值。但 PR 已合并且未看到作者回应，此建议可能被视为优化项而非阻塞问题。

# 风险与影响

**风险**：
1. 正确性风险：LRU 顺序错误可能导致缓存淘汰策略失效，影响缓存命中率和性能。
2. 测试覆盖不足：PR body 中未提供准确性测试结果，仅依赖 CI 测试，可能缺少针对 LRU 策略的专项测试。
3. review 建议未处理：关于使用实际 miss 计数的建议未被采纳，在极端情况下可能引入隐患。

**影响**：
1. 系统层面：修复核心 JIT 内核的缓存管理逻辑，提升 Hisparse 模块的稳定性和性能可预测性。
2. 用户层面：无直接 API 变更，但间接影响推理性能和缓存行为。
3. 团队层面：需要关注 Hisparse 相关测试的充分性，特别是缓存一致性测试。

# 关联脉络

与近期历史 PR 的关联：
1. **PR#22131（Hisparse Minor Fix）**：同样修改 hisparse.cuh 文件，修复内存传输和调度器请求回收逻辑，属于同一模块的连续改进。
2. **PR#22059（Hi-MambaRadixTree 修复）**：涉及缓存系统（hicache 模块）的 bugfix，与本 PR 的缓存管理修复有技术关联。

从历史 PR 看，Hisparse 模块近期有多项修复（#22131、#22170），显示团队正在持续优化 JIT 内核的稳定性和性能。本次 LRU 策略修复是这一系列改进中的重要一环，确保了缓存淘汰顺序的正确性。