一、背景

在大语言模型（LLM）推理中，预填充（Prefill）阶段往往是性能瓶颈：输入序列需先转换为 KV Cache，才能进行后续解码。当多个请求共享相同前缀时，对应的 KV Cache 完全一致，存在大量重复计算。

为解决这一问题，SGLang 引入了 RadixAttention，利用空闲 GPU 内存缓存并复用前缀 KV Cache；进一步地，HiCache 将这一思路扩展至宿主机内存（Host Memory）和分布式存储层，构建三级缓存体系，在显著扩大 KV Cache 容量的同时保持较强的读取性能。

HiCache 在多轮问答（Multi-QA）和长上下文推理等 KV Cache 复用频繁的场景下具有突出优势，详细基准测试结果参见：https://www.lmsys.org/blog/2025-09-10-sglang-hicache/#benchmark。

二、系统架构

HiCache 将存储层次化组织：

缓存层级	存储介质	作用域
L1	GPU 显存	私有，每个推理实例独享
L2	宿主机内存（CPU Memory）	私有，每个推理实例独享
L3	分布式存储系统	共享，集群内所有推理实例共用

L1/L2 缓存为各推理实例私有，提供低延迟访问；L3 缓存在集群范围内共享，大幅减少跨实例的重复存储。

2.1 HiRadixTree：元数据组织结构

HiCache 在 RadixAttention 的 RadixTree 基础上提出了 HiRadixTree。

RadixTree 基本原理：树的每个节点对应 GPU 显存中一段连续 token 的 KV Cache；从根到叶的路径代表一个请求的前缀；多个请求的公共前缀可共享同一节点路径，避免冗余存储。

HiRadixTree 扩展：

• 每个节点不仅记录 token 的 KV Cache，还记录该数据的存储位置（GPU 显存、CPU 内存、L3 存储，或多层同时存在）
• 对本地数据（L1/L2）维护精确的元数据，包括具体存储地址
• 对 L3 数据不主动存储元数据，而是在访问时实时查询后端，以降低管理开销

2.2 核心工作流程

HiCache 的工作流程主要由三个关键操作构成：本地匹配（Local Match）、数据预取（Prefetch）和 数据回写（Write-back）。

当新请求到达时，HiCache 首先在本地缓存层（L1/L2）进行前缀匹配查找。若命中，则对应的 KV Cache 会直接加载至 GPU，用于后续计算；若本地未命中，则进一步查询 L3 存储，并根据命中情况触发预取操作。预取可在完成、超时或满足立即返回条件后结束，随后系统继续执行 Prefill 计算。对于本次计算中新生成的 KV Cache 数据，HiCache 会根据回写策略将其写入 L2 和/或 L3，以实现后续请求的缓存复用和跨实例共享。

本地匹配

系统从 HiRadixTree 根节点开始遍历，按 token 序列前缀匹配子节点：

• 当 page_size > 1 时，以页（page）为粒度进行匹配，优化内存访问模式
• 若匹配在节点内部中断，则自动拆分节点，为后续匹配创建精确边界
• 返回结果为请求的连续前缀，其中前段位于 L1，后段位于 L2

本地匹配仅需遍历树结构，不涉及任何实际数据拷贝，因此速度极快。

从 L3 预取数据

触发条件：本地匹配后，对于 L1/L2 均未命中的部分，系统查询 L3 元数据。若 L3 命中的缓存长度超过阈值（默认 256 tokens，可配置），则触发预取。

预取终止策略：HiCache 提供三种策略，适应不同场景需求：

策略	行为	适用场景
best_effort	GPU 可执行 Prefill 时立即终止，无等待	对延迟极敏感的场景
wait_complete	等待所有预取操作完成	对缓存命中率要求高的场景
timeout（推荐生产环境）	达到超时时间或完成时终止	平衡延迟与命中率

timeout 策略参数，超时时间计算公式如下：

timeout = min(
    prefetch_timeout_max,
    prefetch_timeout_base + prefetch_timeout_per_ki_token * num_token_to_fetch / 1024,
)

参数	默认值	说明
prefetch_timeout_base	2 秒	基础超时，覆盖调度与同步开销
prefetch_timeout_per_ki_token	0.1 秒 / 千 token	每 1024 tokens 的增量超时
prefetch_timeout_max	30 秒	超时上限，防止超长提示无限等待

数据回写

回写机制负责将频繁访问的 KV Cache 从 L1 推送至 L2 和 L3，实现更大容量的持久化存储及跨实例共享。

回写策略：

策略	行为	适用场景
write_through	每次访问立即写入下一层	带宽充足，追求最强缓存效果
write_through_selective	访问频次超过阈值后才写入	仅备份热数据，减少 I/O 开销
write_back	数据从上层被驱逐时才写入下层	存储容量有限，需最大化内存利用率

从 L2 向 L3 回写时，仅传输 L3 中尚不存在的数据，避免重复写入。L3 中的 KV Cache 可供集群内所有 SGLang 实例共享（取决于后端实现），在相同内存预算下显著提升缓存命中率。

2.3 优化技术

多 Rank 同步

在张量并行（TP）等多 GPU 并行场景中，HiCache 通过 all_reduce 操作确保各 rank 状态一致：

• 预取阶段：使用 all_reduce(op=min) 确保所有 rank 获得相同的 L3 命中数量，防止各 rank 对预取阈值的判断出现分歧
• 预取完成后：再次执行 all_reduce(op=min)，确保各 rank 对成功获取的 KV Cache 前缀长度达成一致
  

说明：由于 GPU 的 KV Cache 计算通常按层逐层执行，因此 GPU 内部采用layer_first布局。对于page_first布局的数据，在加载至 GPU 时需要按照“每层一个 Token”的粒度进行拆分传输；而 page_first_direct 通过层内聚合机制，在一定程度上缓解了这一问题，进一步优化了数据传输效率。

数据传输优化

零拷贝传输（Zero-Copy）

预取（Prefetch）和回写（Write-back）过程涉及大量数据搬移。HiCache 支持在 L2 向 L3 传输时直接传递内存地址和数据大小信息，避免冗余的数据拷贝，从而显著提升传输效率并降低额外的内存开销。

面向批次的数据组织（Batch-Oriented）

HiCache 的 L3 层以页（Page）为基本粒度存储和传输 KV Cache 数据，并支持以下几种内存布局方案：

布局方式	说明
layer_first	按层（Layer）组织 KV Cache 数据，与 GPU 计算内核天然兼容，为默认布局。
page_first	同一 Page 的所有 KV Cache 数据连续存放，优化 I/O 效率，并支持零拷贝传输至 L3。
page_first_direct	在 page_first 基础上，进一步将同一 Page 内同一层的所有 Token 聚合，使 L2 到 GPU 的传输可按 Page-Layer 级别批量执行，从而减少传输次数。

说明：由于 GPU 的 KV Cache 计算通常按层逐层执行，因此 GPU 内部采用 layer_first 布局。对于 page_first 布局的数据，在加载至 GPU 时需要按照“每层一个 Token”的粒度进行拆分传输；而 page_first_direct 通过层内聚合机制，在一定程度上缓解了这一问题，进一步优化了数据传输效率。

CPU 到 GPU 传输优化

HiCache 针对 CPU 到 GPU 的 KV Cache 传输过程进行了多项优化，以降低传输延迟并提升整体执行效率。

优化技术	说明
计算与传输重叠（Computation-Transfer Overlap）	在 Prefill 阶段，加载第 N+1 层 KV Cache 与计算第 N 层并发执行，从而有效隐藏数据传输延迟，提高流水线利用率。
GPU 辅助 I/O 内核（GPU-assisted I/O Kernel）	在 cudaMemcpyAsync 基础上实现专为 KV Cache 传输优化的 GPU I/O 内核，相较于基线方案，传输速度最高可提升 3 倍。

MLA 模型回写优化

在张量并行（Tensor Parallel, TP）场景下，不同注意力机制的 KV Cache 分布方式不同，因此 HiCache 采用了差异化的回写优化策略。

模型类型	多 TP 下每个 Rank 持有的数据	优化策略
MHA（Multi-Head Attention，多头注意力）	每个 Token 的 KV 数据的 1 / tp_size	各 Rank 独立执行回写
MLA（Multi-Layer Attention，多层注意力）	每个 Token 的完整且相同的 KV 数据	仅由一个 Rank 执行回写，避免跨 Rank 冗余存储

说明：在 MHA 场景中，不同 Rank 持有 KV Cache 的不同分片，因此需要独立回写；而在 MLA 场景下，各 Rank 持有的是完整且相同的数据，若全部回写会造成冗余存储，因此 HiCache 仅选择单个 Rank 执行回写，以降低存储开销并提升效率。

2.4 与 PD 分离部署模式的集成

SGLang 通过 Mooncake TransferEngine 支持 PD（Prefill-Decode）分离部署模式。在该架构下，Prefill 节点负责输入预填充计算，Decode 节点负责后续解码生成，HiCache 可以在两个阶段协同工作：

• Prefill 节点启用 HiCache：用于优化预填充阶段的 KV Cache 管理和访问性能，降低缓存加载开销。
• Decode 节点启用 HiCache：解码阶段生成的 KV Cache 数据同样可回写至 L3，实现缓存复用与统一管理。
• 双节点协同启用：HiCache 可同时部署在 Prefill 和 Decode 节点，在 PD 分离架构下形成完整的多级 KV Cache 生命周期管理机制。

说明：在 PD 分离部署模式下，HiCache 不仅可以优化预填充阶段的缓存访问，还可以将解码阶段生成的 KV Cache 回写至 L3，为后续请求提供缓存复用能力。

2.5 L3 存储后端

HiCache 通过抽象基类 HiCacheStorage (ABC) 封装 L3 层的读写和查询操作，提供统一、简洁的接口，从而支持多种底层存储后端。

后端	简介	特点
Mooncake	面向 LLM 推理的高性能缓存系统	基于 RDMA 和多网卡，支持零拷贝高速传输
DeepSeek 3FS（HF3FS）	Kubernetes 原生分布式存储	基于 Operator 部署，适合云原生环境
NIXL	统一存储插件访问 API	兼容 3FS、GPU Direct Storage（GDS）、Amazon S3 等多种后端
AIBrix KVCache	生产级 KV Cache Offloading 框架	支持高效内存分层和低开销跨引擎复用
HiCacheFile	基于文件的简单存储实现	主要用于演示和调试场景

说明：通过 HiCacheStorage 抽象层，HiCache 可在不同存储系统之间灵活切换，而无需修改上层缓存管理逻辑。

除 HiCache 外，SGLang 还支持 LMCache 作为企业级 LLM 推理场景下的高效 KV Cache 分层方案。LMCache 与 HiCache 属于并列的缓存系统实现，可通过以下参数启用：

--enable-lmcache

https://github.com/sgl-project/sglang/tree/main/python/sglang/srt/mem_cache/storage/lmcache

三、关键配置参数

HiCache 提供了一组配置参数，用于控制层次化缓存的启用方式、容量管理、预取与回写策略、数据传输优化以及存储后端选择。

基础参数

参数	说明
--enable-hierarchical-cache	启用 HiCache 功能（必选）
--hicache-ratio RATIO	Host KV Cache 内存池与设备内存池的比值，要求 RATIO > 1
--hicache-size SIZE	Host KV Cache 内存池大小（GB），每个 Rank 独立分配。配置后将覆盖 hicache-ratio
--page-size PAGE_SIZE	每页包含的 Token 数，影响缓存粒度与 I/O 效率

调优建议：HiCache 容量越大，缓存命中率通常越高，但边际收益会逐渐递减。当热数据已基本覆盖后，继续扩大缓存容量的收益有限，因此需要结合实际负载特征进行权衡。

预取与回写参数

参数	可选值	说明
--hicache-storage-prefetch-policy	best_effort / wait_complete / timeout	预取终止策略，生产环境推荐 timeout
--hicache-write-policy	write_through / write_through_selective / write_back	KV Cache 数据回写策略

I/O 与内存布局参数

参数	可选值	说明
--hicache-io-backend	direct / kernel	CPU-GPU 数据传输后端，推荐使用 kernel
--hicache-mem-layout	layer_first / page_first / page_first_direct	Host 内存池的数据布局方式

存储后端参数

参数	说明
--hicache-storage-backend	选择 L3 存储后端，支持 file / mooncake / hf3fs / nixl / aibrix / dynamic
--enable-lmcache	使用 LMCache 作为替代的层次化缓存方案
--hicache-storage-backend-extra-config	传入后端额外配置，支持 JSON 字符串或配置文件

后端额外配置示例（JSON 字符串）

--hicache-storage-backend-extra-config \
'{"prefetch_threshold":512,"prefetch_timeout_base":0.5,"prefetch_timeout_per_ki_token":0.25}'

后端额外配置示例（配置文件）

--hicache-storage-backend-extra-config "@config.toml"

说明：
当配置项较多或较复杂时（例如 NIXL 后端），推荐使用配置文件方式进行管理，以提高可维护性和配置清晰度。