kvcache-ai/Mooncake · 上手攻略

仓库：kvcache-ai/Mooncake
链接：https://github.com/kvcache-ai/Mooncake
分类：ai（llm-infra）
作者：Jay
更新：2026-07-11

🎯 是什么

Mooncake 是月之暗面（Moonshot AI）为旗下 Kimi 大模型服务开发的生产级 LLM Serving 平台，核心创新是 KVCache 中心化的 Prefill-Decode 分离架构（PD 分离），将 LLM 推理的预填充（Prefill）和解码（Decode）阶段拆分到不同集群，并通过利用 GPU 集群中闲置的 CPU DRAM 和 SSD 资源构建分布式 KVCache 池。

它是支撑 Kimi 日均处理海量请求的生产级系统，公开数据显示：在真实负载下，Mooncake 使 Kimi 吞吐量提升 75%，同时满足 SLO 要求。2025 年初已被正式开源，并陆续整合进 vLLM、SGLang、TensorRT-LLM、PyTorch 生态。

🧩 解决什么问题

LLM 推理效率低：传统架构里 Prefill 和 Decode 共用 GPU 计算资源，互相争抢导致吞吐差、延迟高
长上下文瓶颈：超长 prompt（如百万 token 级别）时，Prefill 耗时极长，Decode 阶段被拖累
GPU 显存碎片化：多用户请求的 KVCache 碎片化，显存利用率低
跨节点 KVCache 复用难：分布式推理时，不同请求的已计算 KV 无法跨实例共享，造成重复计算
多框架适配：需要统一对接 vLLM、SGLang、TensorRT-LLM 等不同推理框架的 KVCache 管理

⚡ 核心架构速览

Mooncake 的核心组件：

Mooncake Transfer Engine（C++/CUDA）：高性能 KVCache 传输引擎，支持 RDMA、TCP、P2P，零拷贝跨实例传输 KV 数据
Mooncake Store：分层分布式 KVCache 存储池（GPU HBM → CPU DRAM → NVMe SSD），LRU 策略管理缓存
Mooncake Scheduler：KVCache 中心化调度器，平衡吞吐量和 SLO 延迟，预测性早期拒绝超载请求
Mooncake Store Connector：各框架（vLLM、SGLang、LMDeploy）的 KV Connector 插件

⚡ 快速安装

Mooncake 有两个主要安装目标：Transfer Engine（Python 包）和 Mooncake Store（Docker 部署）。

Transfer Engine（Python 包，支持 CUDA）

# CUDA ≤ 12.9
pip install mooncake-transfer-engine

# CUDA 13.0 / 13.1
pip install mooncake-transfer-engine-cuda13

# 非 CUDA（如 NPU）
pip install mooncake-transfer-engine-non-cuda

# NPU（昇腾）
pip install mooncake-transfer-engine-npu

⚠️ Transfer Engine 依赖 PyTorch（torch >= 2.0），建议先装 torch 再装本包。

Mooncake Store（Docker 部署）

# 拉取官方镜像
docker pull kvcacheai/mooncake:latest

# 启动（需要 RDMA 环境才能发挥全部性能）
docker run -d --privileged \
  --net=host \
  --cap-add=ALL \
  -v /path/to/config:/etc/mooncake \
  kvcacheai/mooncake:latest

从源码编译（Transfer Engine）

git clone https://github.com/kvcache-ai/Mooncake.git
cd Mooncake
mkdir build && cd build
cmake .. -D CMAKE_BUILD_TYPE=Release
make -j$(nproc)

🔥 核心用法

⚠️ 以下为 Transfer Engine 的典型使用方式。Mooncake 作为生产级系统，完整部署涉及 PD 分离集群配置、Kubernetes 集成等，这里展示接入已有 vLLM/SGLang 的场景。

方式一：在 vLLM 中启用 Mooncake Store（推荐）

vLLM v1+ 内置 Mooncake KV Connector，启用方式（PD 分离模式）：

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --kv-connector mooncake \
  --moon-cache-config '{"kind": "Store", ...}' \
  --enforce-eager

具体参数配置参考 vLLM 官方 Mooncake Connector 文档。

方式二：在 SGLang 中启用 Mooncake Store

SGLang 支持 Mooncake 作为分层 KV 缓存后端（Device → Host → Remote）：

python -m sglang.launch_server \
  --model-path meta-llama/Llama-3.1-8B-Instruct \
  --enable-torch.compile \
  --chunked-prefill-size 4096 \
  --hf-chat-template generated

然后在 SGLang 的 HiCache 配置里指定 Mooncake Store。详见 SGLang Mooncake 集成文档。

方式三：用 Transfer Engine 做 KVCache P2P 传输（分布式训练/RL）

Kimi-K2（1T 参数）用 Mooncake Transfer Engine 实现 7x 加速（53s → 7.2s）跨 1000+ GPU 的权重更新：

from mooncake_transfer_engine import RemoteBuffer

# 在分布式训练节点间建立 KV 传输通道
buffer = RemoteBuffer(
    src_rank=0,
    dst_rank=1,
    transport="rdma",   # 或 "tcp"
    numa_aware=True,
)

# 零拷贝发送 KVCache 数据
buffer.send_kvcache(kv_tensor, peer_rank=1)

实际生产使用建议参考 Mooncake GitHub examples。

PyTorch 集成

Mooncake 已加入 PyTorch 生态，通过 PyTorch Elastic/NCCL 插件接入：

import torch
import mooncake_torch

# 使用 Mooncake 的分布式 KVCache
mooncake_store = mooncake_torch.KVStore(
    backend="mooncake",
    transport="rdma",
)

📊 生态集成全景

Mooncake 已深度整合进主流 LLM 推理框架：

框架	集成方式	支持版本
vLLM v1+	内置 Mooncake KV Connector（PD 分离）	v1.0+
SGLang	HiCache 多层 KV 缓存后端 + Encoder Global Cache	2025.09+
TensorRT-LLM	Transfer Engine 作为 PD 分离后端	最新版
LMDeploy	PD 分离后端	v0.9+
vLLM-Ascend	NPU 上的 KVCache transfer	2025.08+
PyTorch	PyTorch Ecosystem 成员，Elastic 插件	PyTorch 2.5+
FlexKV（Tencent/NVIDIA）	分布式 KVCache reuse via Transfer Engine	—
TorchSpec	投机解码训练 hidden states 管理	—

💡 典型适用场景

Kimi 级别 LLM 服务：月之暗面生产验证，75% 吞吐量提升是真实数据
长上下文推理：百万 token 级别的 RAG 或文档分析，PD 分离让 Prefill 不阻塞 Decode
分布式 RL 训练：用 Transfer Engine 做跨 GPU 的 KVCache 或权重高速传输（Kimi-K2 验证 7x 加速）
多框架统一缓存：同时跑 vLLM 和 SGLang 时，Mooncake Store 作为统一 KVCache 层避免重复计算
昇腾 NPU 推理：Moonshot 同时支持了华为昇腾 NPU，通过 mooncake-transfer-engine-npu 包

⚠️ 坑与注意

RDMA 环境是性能关键：Mooncake 的核心性能优势依赖 RDMA（如 InfiniBand），没有 RDMA 的环境下性能提升有限
PD 分离复杂度高：完整 PD 分离架构需要两套集群（Prefill 和 Decode），运维复杂度比单体架构高
各框架版本要求：vLLM 需要 v1.0+，SGLang 需要 2025.09+ 版本才完整支持
CUDA 版本区分：需要根据 GPU 的 CUDA 版本选择正确的 pip 包（≤12.9 / 13.0-13.1 / non-CUDA）
生产部署门槛：Mooncake Store 的 Docker 部署需要 privileged 模式和高性能网络，生产环境建议参考官方 K8s 部署指南
中文资料少：目前主要资料是英文论文（FAST '25）和 GitHub，完整中文部署文档较少

🔄 与同类对比

方案	定位	特色	不足
Mooncake	生产级 LLM Serving 平台	PD 分离 + KVCache 池 + 多框架整合，Kimi 背书	完整部署复杂，依赖 RDMA
vLLM 内置 PD	vLLM 原生 PD 分离	开源可用	生态不如 Mooncake 完整
SGLang	高效 LLM 推理框架	RadixAttention + HiCache 优秀	非完整 Serving 平台
TensorRT-LLM	NVIDIA GPU 优化推理	性能极致	NVIDIA only，封闭
LMDeploy	量化推理	支持 AWQ、GPTQ 量化	生态整合弱

一句话推荐：Mooncake 是目前唯一一个在生产环境验证过的、跨框架整合的 KVCache 中心化 Serving 方案，如果你在跑长上下文 LLM 推理或需要跨实例 KV 缓存复用，它值得深入研究。

🏁 推荐结论

Mooncake 是 Kimi 背后的生产级 LLM Serving 平台，技术创新在于 KVCache 中心化调度和 PD 分离架构，已得到 vLLM、SGLang、TensorRT-LLM 等主流框架的官方支持。

对于AI 基础设施工程师和LLM 应用开发者，Mooncake 的价值体现在： - 直接用：vLLM/SGLang 用户加一个参数就能启用 Mooncake KVCache - 理解原理：读它的架构论文（FAST '25）能学到 PD 分离的核心设计思路 - 二次开发：Transfer Engine 是纯 C++/CUDA 的，可以嵌入自己的推理框架

最大的门槛是 RDMA 依赖和 PD 分离的运维复杂度——如果你不需要 Kimi 级别的规模，可能先用 vLLM 原生功能更实际。