SGLang 里的 Unified Radix Cache：一棵树支持混合模型的前缀缓存

本文改编自 LMSYS 的 Unified Radix Cache 文章。

背景

Prefix caching 在请求共享同一段 token 前缀时复用 KV。在 full attention 下，后来的请求可以复用已缓存的前缀，只计算新增的 token。

混合模型中的三类数据各有复用规则：FULL（全注意力）需要匹配前缀上的 KV，SWA（滑动窗口注意力）需要复用边界之前的连续窗口，MAMBA 需要递归状态在该边界的快照（checkpoint）。

DeepSeek-V4 组合 FULL 和 SWA，Kimi-K3 为 KDA 递归状态组合 FULL 和 MAMBA，Inkling 三种全有。SGLang 用一棵共享树处理这些组合，各组件负责自己的复用规则。

Unified Radix Cache

设计与机制

每个 radix 节点存一段 token，并为各组件留一个槽位。FULL 和 SWA 的槽存 KV 页索引，MAMBA 的槽存该前缀末端的 checkpoint。窗口之外的 SWA 数据可以保留，也可以独立驱逐，留下称为 tombstone 的空槽。

组件负责各自数据的分裂、插入、加锁和驱逐。回收节点内的部分 SWA 数据时，先在保留边界拆开节点。MAMBA checkpoint 留在原来的前缀末端，复用它的请求通过 copy-on-write 获得私有副本，再继续更新状态。

安全复用边界

Matching 沿匹配路径走查，各组件在每个候选边界检查自己的数据。每个候选独立判断，最终选出所有组件都接受的最深边界，从那里继续计算。

HiCache 跨内存层级

HiCache 将 Unified Radix Cache 扩展到 GPU L1、主机内存 L2 和外部存储 L3，分层设计与数据搬运见 SGLang HiCache 一文。

组件与 sidecar

DeepSeek-V4 的 FULL 和 SWA 使用独立的页索引，由分配器在两者之间映射。压缩 KV、indexer buffer、compressor state 等辅助池作为 sidecar，沿用所跟随组件的索引并一起传输。其中三个跟随 FULL，两个跟随 SWA。

多轮对话基准

多轮对话不断延长可复用的前缀。在仅 L1、L1+L2、再加入 500 GiB Mooncake L3 的对照中，DeepSeek-V4-Flash 使用 L3 后的有效输入吞吐从仅 L1 时的 9.4K 提升到 145.5K tokens/s，平均 TTFT 低于 9 秒。

会话感知驱逐

应用通过 session_id 标记同一会话的请求，SGLang 据此保留会话对缓存条目的引用。调用 /close_session 撤销该会话的引用，共享前缀继续保留其他会话的引用。

驱逐时，FULL 在未加锁且符合条件的条目中，依次按有无引用、引用数和基础策略排序，通常先回收无引用的数据。这套会话保留机制用于 L1/L2，L3 由存储后端管理驱逐。

SWE-bench 结果

在 SWE-bench 测试中，同时启用 Unified Radix Cache 和会话感知驱逐，相比 HiRadixCache 加 LRU，将 DeepSeek-V4-Pro 的 TTFT 最多降低 11.0%，Qwen3.5-397B-A17B 最多降低 16.6%。

Rust 树核

SGLang 用 Rust 执行树走查、锁记账和 LRU 更新，减少 scheduler 在这些操作上的 CPU 开销。Python 负责物理 KV 分配和缓存编排，并将 Rust 返回的操作应用到各个池。

仅使用 L1 的 Rust 实验原型 #29074 在 200 轮对话测试中，相比 Python 树将 SWA、full attention 和 hybrid SSM 的 TTFT 分别降低了 38%、10% 和 5%。

后续合并的 Rust TreeCore #32710 支持 FULL、SWA、MAMBA 的组合及 HiCache。会话感知缓存继续使用 Python 树核。