Mooncake 保姆级部署教程：面向 LLM 推理的 KV Cache 分离架构

Mooncake（kvcache-ai/Mooncake，GitHub 约 6.9k Star）是月之暗面开源的 KV Cache 中心，官方定位「a KV cache-centric LLM inference platform」。它把 KV Cache 从 GPU 节点抽出来做成分布式共享池，让多请求、多模型复用缓存，显著降本。本文基于官方 README 的 Quick Start 章节。

一、项目介绍与适用场景

Mooncake 由三部分组成：Transfer Engine（传输引擎）、Mooncake Store（KV Cache 存储）、Mooncake EP/PG（扩展点）。它是为 vLLM、SGLang 等推理框架提供的底层缓存层。

典型场景：

• 大规模 LLM 推理集群：多 GPU 节点共享 KV Cache。
• 降本：相同前缀的请求复用缓存，避免重复计算。
• 长上下文服务：KV Cache 大小直接决定并发能力。

二、核心功能逐条拆解

1. Transfer Engine：RDMA 高速传输 KV Cache。
2. Mooncake Store：分布式 KV Cache 存储。
3. EP/PG：扩展点与进程组。
4. vLLM 集成：官方提供接入指南。
5. SGLang 集成：官方提供接入指南。
6. 多硬件支持：NVIDIA、华为昇腾、AMD、寒武纪、摩尔线程等。

三、全套官方链接

四、硬件与环境前置要求

• GPU：NVIDIA CUDA（官方支持 CUDA < 13 和 >= 13）。
• 网络：推荐 RDMA/RoCE。
• 内存：32GB 起步。
• 磁盘：100GB SSD。

五、多平台部署步骤

5.1 pip 安装（官方 Quick Start）

官方 README 原文：

CUDA < 13.0：

pip install mooncake-transfer-engine

CUDA >= 13.0：

pip install mooncake-transfer-engine-cuda13

逐段解释：官方提供两个 PyPI 包，按 CUDA 版本选。包内已含 Transfer Engine、Mooncake Store、EP 和 PG。

5.2 Docker

官方提供 Docker 镜像 kvcacheai/mooncake，详见 https://hub.docker.com/r/kvcacheai/mooncake 。

5.3 源码构建

官方文档链接：https://kvcache-ai.github.io/Mooncake/getting_started/build.html 。

六、配置文件全部参数解释

主要配置项见官方 Deployment Guide：https://kvcache-ai.github.io/Mooncake/deployment/mooncake-store-deployment-guide.html 。

七、启动、后台常驻与开机自启

Mooncake Store 作为后台服务运行，详见官方部署指南。生产环境一般用 systemd 或 k8s 托管。

7.1 单机 demo

按 Quick Start 起本地进程，适合开发测试。

7.2 生产集群

按官方 Deployment Guide 起 etcd 元数据服务 + 多个 Store 节点 + Transfer Engine 节点，组成分布式 KV Cache 池。

7.3 与 vLLM 集成

vLLM 作为客户端连 Mooncake Store，把 KV Cache 写进去；不同 vLLM 实例共享缓存。

八、功能实操教程

第 1 步：按 CUDA 版本 pip 安装。nvcc --version 确认 CUDA 版本后选包。

第 2 步：按官方 Quick Start 启动本地 Transfer Engine 和 Store。单机 demo 通常用本地 TCP 模式，不需要 RDMA。

第 3 步：按 vLLM 集成指南把 Mooncake 配进 vLLM。一般是在 vLLM 启动参数里加 Mooncake 相关的 --kv-transfer-config。

第 4 步：跑两次相同前缀的请求，比如同一份系统提示词 + 不同用户问题。观察第二次命中缓存，TTFT 明显下降。

第 5 步：用官方提供的 KV Cache Size Calculator（https://kvcache.ai/tools/kv-cache-size-calculator/）估算你模型需要的缓存容量。

第 6 步：用官方提供的 KV Cache Hit Rate Simulator 模拟不同并发下的命中率。

第 7 步：多机部署时按 Deployment Guide 起 etcd 作为元数据中心，多台 Store 节点组成集群。

九、全套报错故障排查

1. 报错原文：CUDA 版本不匹配 ImportError 原因分析：装错了 pip 包（CUDA 13 装了普通包）。 解决方案：nvcc --version 查版本；CUDA < 13 用 mooncake-transfer-engine，>= 13 用 mooncake-transfer-engine-cuda13。

2. 报错原文：RDMA 初始化失败 原因分析：网卡不支持 RoCE/iWARP，或驱动没装。 解决方案：先用 TCP 模式跑通（官方文档有 fallback 配置）；生产环境配 Mellanox 网卡 + OFED 驱动。

3. 报错原文：Store 连不上 Connection refused 原因分析：元数据服务（etcd 或 Redis）未启动。 解决方案：按官方 Deployment Guide 先起 etcd，再起 Mooncake Store。

4. 报错原文：vLLM 集成后缓存不命中 原因分析：请求前缀不相同，或多租户隔离开了。 解决方案：用官方提供的 traces 工具回放测试；确认 vLLM 与 Mooncake 的 KV cache block 大小配置一致。

5. 报错原文：GPU 显存 OOM 原因分析：Mooncake 把 KV Cache 卸到 CPU/远端，但激活值还在 GPU。 解决方案：降并发或减小 --max-num-seqs。

6. 报错原文：编译源码时找不到 CUDA 头文件 原因分析：CUDA_HOME 没设。 解决方案：export CUDA_HOME=/usr/local/cuda。

十、升级、回滚与卸载

升级：pip install -U mooncake-transfer-engine；Docker 方式 docker pull kvcacheai/mooncake:latest。

回滚：pip install mooncake-transfer-engine==<旧版本号>。

卸载：pip uninstall mooncake-transfer-engine；清掉 ~/.mooncake/ 缓存目录。

十一、商用许可与合规风险提示

Mooncake 采用 Apache-2.0，商用友好。注意它是底层基础设施，生产部署需要 RDMA 网络和专业运维，不适合单机玩具。

参考链接：

• Mooncake GitHub README：https://github.com/kvcache-ai/Mooncake
• 官方文档：https://kvcache-ai.github.io/Mooncake
• Quick Start：https://kvcache-ai.github.io/Mooncake/getting_started/quick-start.html