博客

1 特性介绍 ​

Mooncake 采用以 KVCache 为中心的解耦架构，将Prefill集群和Decode集群分离，并利用集群中未充分利用的 CPU、DRAM 和 SSD 资源来实现 KVCache 的解耦缓存。Mooncake Store热点缓存特性的核心思想是在Mooncake Client缓存远端被频繁访问的KVCache数据切片。特性价值如下：

• 能够显著减少热点数据的跨节点网络传输开销，优化get和批量get操作的性能。
• 改善AI推理场景下的TTFT（Time To First Token）和Total Token Throughput指标。
• 通过环境变量LOCAL_HOT_CACHE_SIZE进行配置，支持按16MB为单位动态分配内存块，实现高效的热数据本地缓存管理。

1.1 应用场景 ​

• 多客户端+主节点架构：推荐用于多Mooncake Client的分布式部署场景。当Master Service因随机分配数据切片到不同存储节点而造成频繁跨节点网络传输时，该特性能够有效减少网络开销。
• 高频访问场景：适用于存在热点数据的KVCache访问场景，当部分数据被频繁访问时，本地缓存能够显著提升访问效率。

注：在单机独立客户端场景下，由于所有数据都在本地存储，无需启用客户端热缓存功能，为避免额外内存开销应禁用该特性。

1.2 能力范围 ​

• 支持用户根据自身业务场景灵活配置Mooncake Store热点缓存大小，降低get/batchGet操作延迟。
• 支持推理引擎（vLLM、SGLang等）无感集成，兼容Mooncake的get/batchGet接口。

2 实现原理 ​

核心处理流程：

1. 初始化阶段：当创建Client时，根据环境变量配置项LOCAL_HOT_CACHE_SIZE初始化Mooncake Store热点缓存。默认值为0，表示禁用该特性。如果配置值大于16MB，则分配相应的内存用于存储热数据。
2. 元数据查询：当get/batchGet请求到达时，首先向Master Service查询目标KVCache的存储位置信息（replica descriptor），获取每个数据切片所在的存储节点和地址信息。
3. 缓存查询：遍历所有数据切片，使用{request_key}_{slice_index}作为键查询该Mooncake Client的Mooncake Store热点缓存。如果缓存命中，更新replica descriptor：

• 将存储节点替换为本地节点。
• 将存储地址替换为缓存中该切片的数据地址。
• 提交给TransferSubmitter后，会自动选择LOCAL_MEMCPY传输策略优化传输。

4. 传输提交：将读取请求提交给TransferSubmitter。如果目标地址是本地节点（包括Mooncake Store热点缓存命中的情况），Transfer Engine会自动选择LOCAL_MEMCPY传输策略，避免网络传输开销。
5. 缓存更新：等待所有传输请求返回后，通过异步任务处理器（LocalHotCacheHandler）将远程传输的切片更新到Mooncake Store热点缓存。缓存更新采用LRU策略，当缓存空间不足时自动驱逐最久未访问的数据块。

3 安装部署 ​

本特性提供两种安装方式：使用镜像安装和手动安装。详情可参见：

https://docs.openfuyao.cn/zh/docs/v26.03/user_guide/mooncake_store_hotspot_cache_optimization.html#安装

4 未来展望 ​

Mooncake Store热点缓存特性未来将会在如下方面进行规划，满足不同业务场景需求。

1. 开放缓存块大小自定义配置，取消 16MB 固定尺寸限制，适配更多业务场景。
2. 后续会继续优化异步缓存调度流程，减少一次内存拷贝，在高并发场景下提升整体吞吐。
3. 同步适配 Mooncake 上游 V3 新架构，get/batchGet 请求优先读取本地客户端元数据。

注：本特性已正式合入上游社区主干（https://github.com/kvcache-ai/Mooncake/pull/1226），并且已包含上述前两项未来规划内容。

5 资源参考 ​

openFuyao v26.03版本软件包下载地址：https://www.openFuyao.cn/zh/download/