kvcache-ai/Mooncake

Mooncake 是 Kimi 的服务平台，这是由 Moonshot AI 提供的领先 LLM 服务。 现在，Transfer Engine 和 Mooncake Store 均已开源！ 本仓库还托管了其技术报告和开源轨迹数据。

🔄 更新

- **2026年2月12日**：[Mooncake 加入 PyTorch 生态系统](https://pytorch.org/blog/mooncake-joins-pytorch-ecosystem/) 我们非常高兴地宣布，Mooncake 已正式加入 PyTorch 生态系统！ - **2026年1月28日**：由腾讯和 NVIDIA 与社区合作开发的分布式 KV 存储和缓存系统 [FlexKV](https://github.com/taco-project/FlexKV)，现已支持通过 Mooncake Transfer Engine 进行[分布式 KVCache 复用](https://github.com/taco-project/FlexKV/blob/main/docs/dist_reuse/README_en.md)。 - **2025年12月27日**：与 [ROLL](https://github.com/alibaba/ROLL) 合作！请点击[此处](https://arxiv.org/abs/2512.22560)查看论文。 - **2025年12月23日**：SGLang 引入了基于 Mooncake 作为传输后端的 [Encode-Prefill-Decode (EPD) Disaggregation](https://lmsys.org/blog/2026-01-12-epd/)。该集成允许将计算密集型多模态编码器（如 Vision Transformers）与语言模型节点解耦，利用 Mooncake 的 RDMA 引擎实现大型多模态 embedding 的零拷贝传输。 - **2025年12月19日**：Mooncake Transfer Engine 已[集成到 TensorRT LLM](https://github.com/NVIDIA/TensorRT-LLM/tree/main/cpp/tensorrt_llm/executor/cache_transmission/mooncake_utils) 中，用于 PD-disaggregated 推理中的 KVCache 传输。 - **2025年12月19日**：Mooncake Transfer Engine 已作为 [KV Connector](https://docs.vllm.ai/en/latest/features/mooncake_connector_usage/) 直接集成到 vLLM v1 中，用于 PD-disaggregated 设置。 - **2025年11月7日**：[RBG + SGLang HiCache + Mooncake](https://github.com/sgl-project/rbg/blob/main/keps/74-mooncake-integration/README.md)，一种开箱即用的基于角色的云原生部署解决方案，具备弹性、可扩展性和高性能。 - **2025年9月18日**：Mooncake Store 赋能 vLLM Ascend，作为[分布式 KV 缓存池后端](https://docs.vllm.ai/projects/ascend/zh-cn/main/user_guide/feature_guide/kv_pool.html)提供服务。 - **2025年9月10日**：SGLang 正式支持 Mooncake Store 作为[分层 KV 缓存存储后端](https://lmsys.org/blog/2025-09-10-sglang-hicache/)。该集成扩展了 RadixAttention，实现了跨设备、主机和远程存储层的多层 KV 缓存存储。 - **2025年9月10日**：Mooncake P2P Store 的官方高性能版本作为 [checkpoint-engine](https://github.com/MoonshotAI/checkpoint-engine/) 开源。它已成功应用于 K1.5 和 K2 生产训练中，在约 20 秒内跨数千个 GPU 更新 Kimi-K2 模型（1T 参数）。 - **2025年8月23日**：[xLLM](https://github.com/jd-opensource/xllm) 高性能推理引擎基于 Mooncake 构建了混合 KV 缓存管理，支持具有智能卸载和预取功能的全局 KV 缓存管理。 - **2025年8月18日**：vLLM-Ascend [集成了 Mooncake Transfer Engine](https://docs.vllm.ai/projects/ascend/en/latest/developer_guide/feature_guide/disaggregated_prefill.html)，用于 KV 缓存注册和 disaggregate prefill，从而在 Ascend NPU 上实现高效的分布式推理。 - **2025年7月20日**：Mooncake 支持 [Kimi K2 的部署](https://lmsys.org/blog/2025-07-20-k2-large-scale-ep/)，在 128 个 H200 GPU 上采用 PD disaggregation 和大规模专家并行，实现了 224k tokens/秒的 prefill 吞吐量和 288k tokens/秒的 decode 吞吐量。 - **2025年6月20日**：Mooncake 成为 LMDeploy 的 PD disaggregation [后端](https://kvcache-ai.github.io/Mooncake/getting_started/examples/lmdeploy-integration-v0.9.html)。 - **2025年5月9日**：NIXL 正式支持 Mooncake Transfer Engine 作为[后端插件](https://github.com/ai-dynamo/nixl/blob/main/src/plugins/mooncake/README.md)。 - **2025年5月8日**：[Mooncake x LMCache](https://kvcache-ai.github.io/Mooncake/getting_started/examples/lmcache-integration.html) 联手，开创以 KVCache 为中心的 LLM 服务系统。 - **2025年5月5日**：在 Mooncake 团队的支持下，SGLang 发布了在 96 个 H100 GPU 上通过 PD Disaggregation 部署 DeepSeek 的指南。 - **2025年4月22日**：LMCache 正式支持 Mooncake Store 作为远程连接器。 - **2025年4月10日**：SGLang 正式支持 Mooncake Transfer Engine，用于 disaggregated prefilling 和 KV 缓存传输。 - **2025年3月7日**：我们开源了基于 Transfer Engine 的分布式 KVCache —— Mooncake Store。基于 Mooncake Store 的 vLLM xPyD disaggregated prefilling & decoding 即将发布。 - **2025年2月25日**：Mooncake 在 **FAST 2025** 荣获 **最佳论文奖**！ - **2025年2月21日**：我们在 FAST'25 论文中使用的更新版轨迹数据已发布。 - **2024年12月16日**：vLLM 正式支持 Mooncake Transfer Engine，用于 disaggregated prefilling 和 KV 缓存传输。 - **2024年11月28日**：我们开源了 Mooncake 的核心组件 Transfer Engine。同时，我们提供了 Transfer Engine 的两个演示：P2P Store 和 vLLM 集成。 - **2024年7月9日**：我们将轨迹数据以JSONL 文件形式开源。 - **2024年6月27日**：我们发布了一系列中文博客，在知乎 1、2、3、4、5、6、7上进行了更多讨论。 - **2024年6月26日**：发布初始技术报告。

🎉 概述

Mooncake 采用以 KVCache 为中心的 disaggregated 架构，将 prefill 集群和 decoding 集群分离。它还利用 GPU 集群中未充分利用的 CPU、DRAM 和 SSD 资源来实现 disaggregated KVCache 池。  Mooncake 的核心是其以 KVCache 为中心的调度器，它在满足延迟相关的服务等级目标 (SLO) 的同时，平衡最大化整体有效吞吐量。与传统研究假设所有请求都会被处理不同，Mooncake 面临着高度过载场景的挑战。为了缓解这些问题，我们开发了一种基于预测的提前拒绝策略。实验表明，Mooncake 在长上下文场景中表现出色。与基线方法相比，在遵守 SLO 的前提下，Mooncake 在某些模拟场景中可将吞吐量提高多达 525%。在实际工作负载下，Mooncake 的创新架构使 Kimi 能够多处理 75% 的请求。

🧩 组件

**Mooncake 核心组件：Transfer Engine (TE)** Mooncake 的核心是 Transfer Engine (TE)，它提供了一个统一的接口，用于跨各种存储设备和网络链路进行批量数据传输。TE 支持多种协议，包括 TCP、RDMA、CXL/shared-memory 和 NVMe over Fabric (NVMe-of)，旨在为 AI 工作负载实现快速可靠的数据传输。与（分布式 PyTorch 使用的）Gloo 和传统 TCP 相比，TE 实现了显著更低的 I/O 延迟，使其成为高效数据传输的卓越解决方案。 **P2P Store 和 Mooncake Store** P2P Store 和 Mooncake Store 均基于 Transfer Engine 构建，并针对不同场景提供键/值缓存。P2P Store 专注于在集群中的节点间共享临时对象（例如 checkpoint 文件），防止单台机器的带宽饱和。另一方面，Mooncake Store 支持分布式池化 KVCache，专为 XpYd disaggregation 设计，以增强资源利用率和系统性能。 **Mooncake 与主流 LLM 推理系统的集成** Mooncake 已与多个流行的大型语言模型 (LLM) 推理系统无缝集成。通过与 vLLM 和 SGLang 团队的合作，Mooncake 现已正式支持 prefill-decode disaggregation。利用 RDMA 设备的高效通信能力，Mooncake 显著提高了 prefill-decode disaggregation 场景下的推理效率，为大规模分布式推理任务提供了强有力的技术支持。 此外，Mooncake 已成功与 SGLang 的 Hierarchical KV Caching、vLLM 的 prefill 服务以及 LMCache 集成，增强了大规模推理场景下的 KV 缓存管理能力。 **弹性专家并行支持** Mooncake 为 MoE 模型推理增加了弹性和容错支持，使推理系统能够在 GPU 故障或资源配置变更时保持响应和可恢复性。该功能包括自动故障 rank 检测，并可与 EPLB 模块配合，在推理过程中将 token 动态路由到健康的 rank。 **以 Tensor 为中心的生态系统** Mooncake 建立了一个全栈、面向 Tensor 的 AI 基础设施，其中 Tensor 作为基本的数据载体。该生态系统涵盖了从 Transfer Engine（用于加速跨异构存储 DRAM/VRAM/NVMe 的 Tensor 数据移动），到用于分布式管理 Tensor 对象（如 Checkpoints 和 KVCache）的 P2P Store 和 Mooncake Store，再到支持基于 Tensor 的弹性分布式计算的 Mooncake Backend。该架构旨在最大化大规模模型推理和训练的 Tensor 处理效率。

🔥 演示案例

### 独立使用 Transfer Engine ([指南](https://kvcache-ai.github.io/Mooncake/design/transfer-engine/index.html)) Transfer Engine 是一个高性能数据传输框架。Transfer Engine 提供了一个统一的接口来传输来自 DRAM、VRAM 或 NVMe 的数据，同时隐藏了与硬件相关的技术细节。Transfer Engine 支持多种通信协议，包括 TCP、RDMA (InfiniBand/RoCEv2/eRDMA/NVIDIA GPUDirect)、NVMe over Fabric (NVMe-of)、NVLink、HIP、CXL 和 Ascend。有关支持的协议的完整列表和配置指南，请参阅 [支持的协议文档](https://kvcache-ai.github.io/Mooncake/getting_started/supported-protocols.html)。 #### 亮点 - **高效利用多个 RDMA NIC 设备。** Transfer Engine 支持使用多个 RDMA NIC 设备来实现*传输带宽聚合*。 - **拓扑感知路径选择。** Transfer Engine 可以根据源和目的地的位置（NUMA 亲和性等）*选择最佳设备*。 - **对临时网络错误具有更强的鲁棒性。** 一旦传输失败，Transfer Engine 将自动尝试使用替代路径进行数据传送。 #### 性能 使用 40 GB 数据（相当于 LLaMA3-70B 模型中 128k tokens 生成的 KVCache 大小），Mooncake Transfer Engine 在 4×200 Gbps 和 8×400bps RoCE 网络中分别提供高达 **87 GB/s** 和 **190 GB/s** 的带宽，比 TCP 协议**快约 2.4 倍和 4.6 倍**。 ### P2P Store ([指南](https://kvcache-ai.github.io/Mooncake/design/p2p-store.html)) P2P Store 基于 Transfer Engine 构建，支持在集群中的对等节点之间共享临时对象。P2P Store 非常适合 checkpoint 传输等场景，在这些场景中，数据需要在集群内快速高效地共享。 **P2P Store 已用于 Moonshot AI 的 checkpoint 传输服务。** #### 亮点 - **去中心化架构。** P2P Store 采用纯客户端架构，全局元数据由 etcd 服务管理。 - **高效的数据分发。** 旨在提高大规模数据分发效率，P2P Store 通过允许复制的节点直接共享数据来*避免带宽饱和*问题。这减少了数据提供者（例如训练器）的 CPU/RDMA NIC 压力。 ### Mooncake Store ([指南](https://kvcache-ai.github.io/Mooncake/design/mooncake-store.html)) Mooncake Store 是一个基于 Transfer Engine 的、专门用于 LLM 推理的分布式 KVCache 存储引擎。它是以 KVCache 为中心的 disaggregated 架构的核心组件。Mooncake Store 的目标是存储推理集群中各个位置的可复用 KV 缓存。Mooncake Store 已在 [SGLang 的 Hierarchical KV Caching](https://lmsys.org/blog/2025-09-10-sglang-hicache/)、[vLLM 的 prefill 服务](https://docs.vllm.ai/en/latest/features/disagg_prefill.html) 中得到支持，现已与 [LMCache](https://kvcache-ai.github.io/Mooncake/getting_started/examples/lmcache-integration.html) 集成，以提供增强的 KVCache 管理能力。 #### 亮点 - **多副本支持**：Mooncake Store 支持为同一对象存储多个数据副本，有效缓解访问压力的热点。 - **高带宽利用率**：Mooncake Store 支持大对象的分条 (striping) 和并行 I/O 传输，充分利用多 NIC 聚合带宽进行高速数据读写。 ### SGLang 集成 ([指南](https://kvcache-ai.github.io/Mooncake/getting_started/examples/sglang-integration/hicache-integration-v1.html)) SGLang 正式支持 Mooncake Store 作为 [HiCache 存储后端](https://lmsys.org/blog/2025-09-10-sglang-hicache/)。该集成为大规模 LLM 服务场景实现了可扩展的 KV 缓存保留和高性能访问。 #### 亮点 - **分层 KV 缓存 (Hierarchical KV Caching)**：Mooncake Store 在 SGLang 的 HiCache 系统中充当外部存储后端，扩展了 RadixAttention，实现了跨设备、主机和远程存储层的多层 KV 缓存存储。 - **灵活的缓存管理**：支持多种缓存策略，包括 write-through、write-through-selective 和 write-back 模式，并具备智能预取策略以实现最佳性能。 - **全面优化**：采用先进的数据平面优化，包括用于提高 I/O 效率的页优先内存布局、用于减少内存开销的零拷贝机制、提供快速 CPU-GPU 传输的 GPU 辅助 I/O 内核，以及用于在计算执行时并发加载 KV 缓存的分层重叠 (layer-wise overlapping)。 - **弹性专家并行**：Mooncake 的集合通信后端和专家并行内核已集成到 SGLang 中，以实现容错的专家并行推理 ([sglang#11657](https://github.com/sgl-project/sglang/pull/11657))。 - **显著的性能提升**：多轮基准测试显示出相较于非 HiCache 设置的巨大性能改进。有关更多详细信息，请参阅我们的[基准测试报告](https://kvcache-ai.github.io/Mooncake/performance/sglang-hicache-benchmark-results-v1.html)。 - **社区反馈**：有效的 KV 缓存通过消除冗余且昂贵的重复计算，显著减少了 TTFT。将 SGLang HiCache 与 Mooncake 服务集成，实现了可扩展的 KV 缓存保留和高性能访问。在我们的评估中，我们在 PD-disaggregated 部署下使用从通用 QA 场景采样的内部在线请求测试了 DeepSeek-R1-671B 模型。平均而言，与完全重新计算相比，缓存命中使 TTFT 降低了 84%。 – 蚂蚁集团 ### vLLM 集成 ([指南 v0.2](https://kvcache-ai.github.io/Mooncake/getting_started/examples/vllm-integration/vllm-integration-v0.2.html)) 为了优化 LLM 推理，vLLM 社区正在努力支持 [disaggregated prefilling (PR 10502)](https://github.com/vllm-project/vllm/pull/10502)。此功能允许在不同的进程中分离 **prefill** 阶段和 **decode** 阶段。vLLM 默认使用 `nccl` 和 `gloo` 作为传输层，但目前它无法在不同机器上高效地解耦这两个阶段。 我们已经实现了 vLLM 集成，使用 Transfer Engine 作为网络层代替 `nccl` 和 `gloo`，以支持**节点间 KVCache 传输** [(PR 10884)](https://github.com/vllm-project/vllm/pull/10884)。Transfer Engine 提供了更简单的接口和更高效的 RDMA 设备利用。 我们将很快发布基于 Mooncake Store 的新 vLLM 集成，支持 xPyD prefill/decode disaggregation。 **_更新[2024年12月16日]：这是基于 vLLM 主分支的最新 vLLM 集成 ([指南 v0.2](https://kvcache-ai.github.io/Mooncake/getting_started/examples/vllm-integration/vllm-integration-v0.2.html))._** #### 性能 通过支持拓扑感知路径选择和多卡带宽聚合，使用 Transfer Engine 的 vLLM 的平均 TTFT 比传统的基于 TCP 的传输降低了高达 25%。 未来，我们将通过 GPUDirect RDMA 和零拷贝进一步改善 TTFT。 | 后端/设置 | 输出 Token 吞吐量 | 总 Token 吞吐量 | 平均 TTFT (ms) | 中位数 TTFT (ms) | P99 TTFT (ms)| |---------------------------------------------------------|---------------------------------|--------------------------------|----------------|------------------|---------------| | Transfer Engine (RDMA) | 12.06 | 2042.74 | 1056.76 | 635.00 | 4006.59 | | TCP | 12.05 | 2041.13 | 1414.05 | 766.23 | 6035.36 | - 点击[此处](https://kvcache-ai.github.io/Mooncake/performance/vllm-benchmark-results-v0.2.html)访问详细的基准测试结果。 **更多高级功能即将推出，敬请期待！**

🚀 快速开始

### 使用 Mooncake 之前 Mooncake 是为高速 RDMA 网络设计和优化的。虽然 Mooncake 支持 TCP-only 数据传输，但我们**强烈**建议用户在支持 RDMA 网络的情况下评估 Mooncake 的功能和性能。 在运行 Mooncake 的任何组件之前，需要安装以下内容： - RDMA Driver & SDK，例如 Mellanox OFED。 - Python 3.10，推荐使用虚拟环境。 - CUDA 12.1 及以上版本，包括 NVIDIA GPUDirect Storage Support，如果包是使用 `-DUSE_CUDA` 构建的（默认禁用）。*您可以从[此处](https://developer.nvidia.com/cuda-downloads)安装它们*。 ### 使用 Python 包 使用 Mooncake Transfer Engine 最简单的方法是使用 `pip`： **对于启用 CUDA 的系统：** ``` pip install mooncake-transfer-engine ``` **对于非 CUDA 系统：** ``` pip install mooncake-transfer-engine-non-cuda ``` ### 使用 Docker 镜像 Mooncake 支持基于 Docker 的部署，详见 [构建指南](https://kvcache-ai.github.io/Mooncake/getting_started/build.html)。 要生成一个从源代码编译 Mooncake、通过 `scripts/build_wheel.sh` 构建 wheel 并在容器内安装该 wheel 的镜像，请使用 `build-wheel.dockerfile`： ``` docker build -f docker/mooncake.Dockerfile \ --build-arg PYTHON_VERSION=3.10 \ --build-arg EP_TORCH_VERSIONS="2.9.1" \ -t mooncake:from-source . ``` 生成的镜像已在 `/opt/venv` 中安装了包含最新构建的 wheel 的虚拟环境。根据需要启动它并配置 GPU/RDMA 访问，例如： ``` docker run --gpus all --network host -it mooncake:from-source /bin/bash ``` ### 构建并使用二进制文件 以下是构建 Mooncake 的额外依赖项： - 构建基础工具，包括 gcc、g++ (9.4+) 和 cmake (3.16+)。 - Go 1.20+，如果您想使用 `-DWITH_P2P_STORE`、`-DUSE_ETCD`（默认启用，使用 etcd 作为元数据服务器）或 `-DSTORE_USE_ETCD`（使用 etcd 进行 store master 的故障转移）进行构建。 - CUDA 12.1 及以上版本，包括 NVIDIA GPUDirect Storage Support，如果包是使用 `-DUSE_CUDA` 构建的。*这不包含在 `dependencies.sh` 脚本中。您可以从[此处](https://developer.nvidia.com/cuda-downloads)安装它们*。 - [可选] Rust Toolchain，如果您想使用 `-DWITH_RUST_EXAMPLE` 进行构建。*这不包含在 `dependencies.sh` 脚本中。* - [可选] `hiredis`，如果您想使用 `-DUSE_REDIS` 构建以使用 Redis 而不是 etcd 作为元数据服务器。 - [可选] `curl`，如果您想使用 `-DUSE_HTTP` 构建以使用 HTTP 而不是 etcd 作为元数据服务器。 构建和安装步骤如下： 1. 从 GitHub 仓库获取源代码 git clone https://github.com/kvcache-ai/Mooncake.git cd Mooncake 2. 安装依赖项 bash dependencies.sh 3. 编译 Mooncake 和示例 mkdir build cd build cmake .. make -j sudo make install # 可选，使其准备好供 vLLM/SGLang 使用

🛣️ 即将到来的里程碑

- [x] Mooncake 首次发布并与最新版 vLLM 集成 - [ ] 跨多个服务引擎共享 KV 缓存 - [ ] 用户和开发者文档

📦 开源轨迹

``` { "timestamp": 27482, "input_length": 6955, "output_length": 52, "hash_ids": [46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 2353, 2354] } { "timestamp": 30535, "input_length": 6472, "output_length": 26, "hash_ids": [46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 2366] } ``` 以上展示了我们轨迹数据集中的两个样本。该轨迹包括请求到达的时间、输入 token 的数量、输出 token 的数量以及重映射的块哈希。为了保护客户的隐私，我们应用了几种机制来删除用户相关信息，同时保留数据集在模拟评估中的实用性。关于轨迹的更多描述（例如，高达 50% 的缓存命中率）可在技术报告的第 4 节中找到。 **_更新[2025年2月21日]：我们 FAST'25 论文中使用的更新版[轨迹](FAST25-release/traces)已发布！请参阅论文的附录（可在[此处](FAST25-release/Mooncake-FAST25.pdf)找到）以获取更多详细信息。_**

📑 引用

如果您觉得论文或轨迹有用，请引用我们的论文： ``` @article{qin2025mooncake_tos, author = {Qin Ruoyu and Li Zheming and He Weiran and Cui Jialei and Tang Heyi and Ren Feng and Ma Teng and Cai Shangming and Zhang Yineng and Zhang Mingxing and Wu Yongwei and Zheng Weimin and Xu Xinran}, title = {Mooncake: A KVCache-centric Disaggregated Architecture for LLM Serving}, year = {2025}, publisher = {Association for Computing Machinery}, address = {New York, NY, USA}, issn = {1553-3077}, url = {https://doi.org/10.1145/3773772}, doi = {10.1145/3773772}, journal = {ACM Trans. Storage}, month = {nov}, keywords = {Machine learning system, LLM serving, KVCache}, } @inproceedings{qin2025mooncake, author = {Ruoyu Qin and Zheming Li and Weiran He and Jialei Cui and Feng Ren and Mingxing Zhang and Yongwei Wu and Weimin Zheng and Xinran Xu}, title = {Mooncake: Trading More Storage for Less Computation {\textemdash} A {KVCache-centric} Architecture for Serving {LLM} Chatbot}, booktitle = {23rd USENIX Conference on File and Storage Technologies (FAST 25)}, year = {2025}, isbn = {978-1-939133-45-8}, address = {Santa Clara, CA}, pages = {155--170}, url = {https://www.usenix.org/conference/fast25/presentation/qin}, publisher = {USENIX Association}, month = {feb}, } @article{qin2024mooncake_arxiv, title = {Mooncake: A KVCache-centric Disaggregated Architecture for LLM Serving}, author = {Ruoyu Qin and Zheming Li and Weiran He and Mingxing Zhang and Yongwei Wu and Weimin Zheng and Xinran Xu}, year = {2024}, url = {https://arxiv.org/abs/2407.00079}, } ```

标签：AI基础设施, C++, DNS解析, FAST25, GPU优化, Kimi, KVCache, LLM推理, Moonshot AI, Python, Rust, TruffleHog, Vectored Exception Handling, vLLM, 内存管理, 分布式系统, 分离式架构, 响应大小分析, 大模型服务, 学术论文, 开源项目, 推理加速, 数据擦除, 无后门, 无服务器, 日志审计, 生成式AI, 索引, 网络流量审计, 请求拦截, 逆向工具, 高性能计算