从零理解 SGLang、HiCache、Mamba 与 LMCache:为什么 8768 的状态不能存到 8704
从一次 64/256 token 对齐冲突出发,解释混合模型的状态缓存、SGLang 调度器、HiCache 与 LMCache 的边界,以及为什么修复必须发生在调度阶段。
从一次 64/256 token 对齐冲突出发,解释混合模型的状态缓存、SGLang 调度器、HiCache 与 LMCache 的边界,以及为什么修复必须发生在调度阶段。
本文对应 SGLang PR #50706,代码快照固定在 2026-11-16 的 PR head
6e4771a。文章讨论的是一个跨越调度器、Radix Cache 和外部存储的正确性约束,而不是某个后端的性能调优。
一个请求已经处理到第 8768 个 token。系统随后准备把状态写进一个以 256 token 为块的外部缓存,于是生成了 key 8704。
只差 64,看起来似乎无伤大雅。
但对 Mamba 来说,这等价于把“读完第 8768 页后的脑中摘要”贴上“只读到第 8704 页”的标签。下次从 8704 继续读时,模型会提前知道后面 64 个 token。这个缓存不是稍微不精确,而是语义上错误。
收到 prompt 后,模型先一次性读入已有文本,这叫 prefill;随后一次生成一个新 token,这叫 decode。如果每次 decode 都从头重算 prompt,成本会非常高,所以系统会缓存“已经读过的历史”。
Transformer 的注意力层通常为历史中的每个 token 保存 Key/Value。可以把它想成一排带编号的档案:前 8704 个 token 对应前 8704 份档案,边界天然可切。
Mamba 更像一位边读边更新笔记的人。读到第 8704 个 token 的状态记作 h8704;继续读 64 个 token 后得到 h8768:
一般情况下,h8768 不能反推出 h8704。如果中间状态没有保存,后端无法把 8768 的状态“裁掉 64 个 token”。
现代 hybrid model 会同时包含 Attention 层和 Mamba 层。要复用一个前缀,不仅 KV 要对,Mamba 的递归状态也必须对应完全相同的 token 深度。
下面这张图是理解问题的地图。把鼠标或手指放到每个节点上,可以看到它拥有的信息。
这里要区分两个经常被混用的概念:
所以,不是每一种 HiCache 配置都使用 LMCache;但当 HiCache 连接 LMCache 时,两侧必须对“一个可存储前缀结束在哪里”达成一致。
这次回归用例很具体:
8192 + 617 = 8809旧逻辑从已命中的前缀开始,按 64 向下取整:
因此 forward 保留了 h8768。但 LMCache 为 8809 生成的最后一个完整 chunk key 是:
于是系统手里只有 内容属于 8768 的状态,外部存储却只接受 名字为 8704 的 chunk。
64-token gap:它不是可以忽略的 padding,而是 h8704 与 h8768 的语义差异。
LMCache 原来的防线会检测长度不一致并跳过 store。这避免了静默写入错误状态,但也意味着本来应该进入外部缓存的前缀没有被保存。下一次请求无法从 LMCache 命中,HiCache 的这条路径失去了作用。
下面是一个简化模型。拖动参数,观察“旧 checkpoint”“外部 key”和“修复后的 checkpoint”。真实代码还会检查 checkpoint 是否位于当前可达前缀之后,但核心约束就是这里展示的共同边界。
修复采用的是一个很小、但边界清晰的 capability contract:
BasePrefixCache.external_store_alignment() 默认返回 1。没有外部约束的缓存行为不变。UnifiedRadixCache 返回连接器的 chunk_size,例如 256。本例中:
然后从请求的绝对 token 位置 8809 向下选择共同边界:
forward 因此直接产出 h8704。Radix Cache、HiCache 和 LMCache 看到的是同一个深度,store 可以安全完成。
因为 checkpoint 是计算的产物,不是 store 时可以随便切割的字节数组。
Scheduler 在 forward 之前同时知道:
一旦 forward 结束且只保留了 h8768,下面的存储层已经没有 h8704。因此,把修复全部塞进 lmcache_unified_radix_cache.py 会面临四个不成立的选择:
静默数据错误。后续请求从 8704 恢复,却拿到包含未来 64 token 信息的状态。
破坏它按固定 chunk 建立的寻址与复用合同,也不能保证其他 tensor 与元数据拥有相同边界。
正确状态需要 forward 过程中的中间演化;此时通常已经丢失。重放还会把缓存写入变成昂贵的额外推理。
对 hybrid model 不是可恢复的完整前缀。命中一个无法继续执行的缓存条目没有意义。
把约束从 LMCache 上报给 Scheduler,并不等于“让通用调度器依赖 LMCache”。Scheduler 只看到一个整数 capability:external_store_alignment();默认值为 1,其他后端无需知道 LMCache 的存在。
这与内存分配器向上报告 alignment、网络设备报告 MTU 是同一种设计:消费者声明约束,生产者在生产时满足约束。
可以用三个问题判断 ownership:
| 问题 | 谁知道答案? |
|---|---|
| 外部后端接受什么 chunk 边界? | LMCache connector |
| 当前模型能在哪些位置捕获 Mamba checkpoint? | SGLang model/scheduler path |
| forward 最终应该产出哪个状态? | Scheduler,在计算开始之前 |
LMCache 负责诚实地报告自己的对齐要求;SGLang 负责不要生产一个无法沿当前缓存路径持久化的 checkpoint。任意一侧单独行动都无法完成这个合同。
更一般地说,这不是某个产品名的问题,而是 recurrent-state checkpoint producer 与 external chunked-store consumer 的跨层不变量。未来换成另一种外部后端,只要它也有大于 1 的固定粒度,同样需要把能力传到 checkpoint 的生产点。
PR 的改动集中在五处:
chunk_size;lcm 合并对齐约束,并在存在外部约束时使用绝对边界;8192 + 617 → 8704。关键点是:它没有把 LMCache 类型判断硬编码进 Scheduler,也没有改变所有缓存的默认行为。只有后端明确报告外部对齐时,新约束才生效。
PR 的 Buildkite #6665 端到端验证还覆盖了一个 hybrid model 场景:两次请求输出一致,第二次能够从 LMCache retrieve。这里的“命中”不是单纯检查 store API 被调用,而是验证存下来的状态真的能被下一次推理使用。
如果你想沿着代码继续读,可以按这个顺序:
schedule_batch.py:计算 checkpoint 对齐base_prefix_cache.py:通用 capability 默认值lmcache_unified_radix_cache.py:LMCache 报告 chunk_sizetest_mamba_checkpoint_depth.py:回归场景这就是为什么 schedule_batch.py 的改动不是把 LMCache 细节泄漏到调度器,而是在正确的 ownership 边界上补齐一个此前缺失的跨层合同。