【Mooncake】全局KV缓存池与PD分离模式的部署指南

文档覆盖单机共享 KV 缓存（MooncakeStoreConnector）+ 多机 PD 分离推理（MooncakeConnector）两套主流方案，完整说明 Mooncake 核心概念、环境依赖、配置、多卡 / 多机部署、调优、排障

一、Mooncake 简介

2.1 项目简介

Mooncake 是开源分布式 KV Cache 高速传输引擎，专为 vLLM 大模型推理设计，解决两大痛点：

相同前缀请求重复执行 Prefill，算力浪费
单 GPU 显存有限，无法承载大量并发会话 KV 缓存

核心两大连接器对接 vLLM，覆盖两种架构：

1. MooncakeStoreConnector：全局共享 KV 缓存池，vLLM 同时读写缓存
• 支持单机、多机集群所有 vLLM 实例共用一套 KV 缓存；
• 会话 KV 存入主机内存 / 远端内存池，跨机器、跨实例复用前缀；
• 适合 RAG、固定系统提示词、多租户集群

2. MooncakeConnector：PD 分离传输引擎
• 将推理拆分为 Prefill 预填充节点、Decode 解码节点；
• Prefill 生成 KV Cache 后通过 RDMA/TCP 高速传输给 Decode 节点；
• 算力错峰调度：Prefill 堆算力、Decode 堆并发，硬件利用率最大化

关键收益：
• 相同前缀请求 Prefill 耗时降低 50%~90%
• 集群整体显存占用下降 30%~70%

2.2 架构及核心组件

Transfer Engine：数据传输引擎，内置TcpTransport/RdmaTransport/UbTransport协议等
Mooncake Store Master：元数据管理服务，独立进程
Mooncake Store Client：存储客户端
Store Storage Backend：存储后端，支持BucketStorageBackend/FileStorage等
MooncakeConnector：vLLM KV Connector 适配器
Proxy Server：PD 分离请求路由网关，独立进程

如下论文中的架构图所示，

Conductor（全局调度器） = Mooncake Store Master + vLLM 调度器
Messenger = Transfer Engine
KVCache Pool（分布式缓存池）= Store Storage Backend + Mooncake Store Client
Prefill Instance = vLLM + MooncakeConnector（kv_role=kv_producer）
Decoding Instance = vLLM + MooncakeConnector（kv_role=kv_consumer）
Conductor（请求路由功能）= Proxy Server

ScreenShot_20260921144854.JPG

二、全局共享 KV 缓存池部署模式 - MooncakeStoreConnector

2.1 vllm 环境安装部署

基础依赖：

yum update && yum install -y python3-pip git libibverbs-utils  rdma-core-devel   numactl-libs  rdma-core  numactl-devel
pip install --upgrade pip

编译安装 vLLM：

# CUDA < 13.0  
pip install mooncake-transfer-engine==0.3.10.post2  [#版本号要vllm依赖版本号一直](javascript:;) 
# CUDA >= 13.0  
pip install mooncake-transfer-engine-cuda13

安装 Mooncake：

# 方式 1：pip 快速安装
pip install mooncake-transfer-engine
# 方式 2：源码编译（解决动态库缺失）
git clone https://github.com/kvcache-ai/Mooncake.git
cd Mooncake
bash build.sh
pip install .
cd ..

2.2 全局共享 KV 缓存池部署

Mooncake全局KV缓存池的部署架构图：

                    ┌───────────────────────┐
                    │   mooncake_master     │  ← 独立进程
                    │   (RPC: 50063)        │
                    │   (HTTP: 8092)        │
                    └───────────┬───────────┘
                                │
              ┌─────────────────┼─────────────────┐
              │                 │                 │
    ┌─────────┴────────┐ ┌─────┴──────────┐ ┌─────┴──────────┐
    │  vLLM Instance A  │ │ vLLM Instance B│ │ vLLM Instance C│  ← 独立进程
    │  kv_role=kv_both  │ │ kv_role=kv_both│ │ kv_role=kv_both│
    │  ┌──────────────┐ │ │ ┌────────────┐ │ │ ┌────────────┐ │
    │  │Transfer Engine│ │ │TransferEngine│ │ │TransferEngine│ │  ← 库（嵌入）
    │  │Store Client   │ │ │Store Client  │ │ │Store Client  │ │  ← 库（嵌入）
    │  │RDMA Transport │ │ │RDMA Transport│ │ │RDMA Transport│ │  ← 库（嵌入）
    │  └──────────────┘ │ └──────────────┘ │ └──────────────┘ │
    └──────────────────┘ └────────────────┘ └────────────────┘
              │                 │                  │
              └──────── RDMA/TCP 互联 (跨节点缓存复用) ────────┘

• 单 master 节点，所有机器 vLLM 实例注册至同一 master
• 集群所有服务共享统一 KV 缓存池，A 机器生成的 KV 可被 B 机器请求复用
• kv_role=kv_both：每台 vLLM 同时读写缓存，无生产者 / 消费者拆分

集群统一配置 mooncake_config.json：
• MASTER_IP：部署 mooncake_master 的服务器内网 IP；
• protocol=rdma：多机集群推荐，无 IB 网卡改为tcp；
• local_buffer_size=4G：多卡 / 多机统一推荐值；
• global_segment_size=0：自动分配集群总共享内存

{
  "metadata_server": "http://MASTER_IP:8092/metadata",
  "master_server_address": "MASTER_IP:50063",
  "global_segment_size": 4294967296,
  "local_buffer_size": 4294967296,
  "protocol": "rdma",
  "rdma_devices": "ib0",
  "local_hostname": ""
}

步骤1：Master 节点启动 mooncake_master

mooncake_master \
  --rpc_port 50063 \
  --enable_http_metadata_server true \
  --http_metadata_server_host 0.0.0.0 \
  --http_metadata_server_port 8092 \
  --rpc_thread_num 64 

# 通过访问元数据接口，查询缓存命中情况
curl http://192.168.1.10:8092/metadata
# 返回 JSON 关键字段：
# • total_kv_requests：KV 查询总次数
# • hit_kv_requests：缓存命中次数
# • miss_kv_requests：缓存未命中

步骤 2：所有业务 GPU 节点启动 vLLM

docker run -d \
  --name vllm-openapi \
  --ipc=host \
  --network=host \
  --shm-size=4gb \
  --ulimit nofile=65535:65535 \
  --ulimit memlock=-1:-1 \
  --gpus=all \
  -v /root/xyh/models/:/home/models/ \
  -v /root/xyh/mooncake_config.json:/home/mooncake_config.json \
  -e MOONCAKE_CONFIG_PATH=/home/mooncake_config.json \
  registry.uniontech.com/uos-ai/uos-server-25-vllm-cuda-gpu:0.23.0 \
  --model /home/models/DeepSeek-R1-Distill-Qwen-1.5B \
  --served-model-name DeepSeek-R1-Distill-Qwen-1.5B \
  --max-model-len 4096 \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.8 \
  --kv-transfer-config '{
    "kv_connector":"MooncakeStoreConnector",
    "kv_role":"kv_both"
  }'

# • 单卡场景删除 --tensor-parallel-size 4；
# • 多实例多卡隔离：使用CUDA_VISIBLE_DEVICES=0,1指定显卡，更换端口

集群效果：节点1和节点2两套 vLLM 服务，相同系统提示词 KV 缓存互通，互相复用，无需重复 Prefill

三、PD 分离多机部署模式 - MooncakeConnector

Mooncake的PD分离多机的部署架构图：

Prefill 生产者节点：仅执行 Prefill，生成 KV Cache，向外传输；
Decode 消费者节点：仅执行 Decode，接收远端 KV，负责并发吞吐；
Proxy 网关：统一入口，分发请求至 Prefill，自动转发 KV 至 Decode

                          ┌───────────────────────┐
                          │   mooncake_master     │  ← 独立进程
                          │   (RPC: 50063)        │
                          │   (HTTP: 8092)        │
                          └───────────┬───────────┘
                                      │
          ┌───────────────────────────┼───────────────────────────┐
          │                           │                           │
    ┌─────┴──────────────┐    ┌───────┴────────────┐    ┌─────────┴──────────┐
    │ vLLM Prefill Node  │    │ vLLM Decode Node   │    │  Proxy Server      │  ← 独立进程
    │ kv_role=kv_producer│    │ kv_role=kv_consumer│    │  (proxy.py)        │
    │ ┌────────────────┐ │    │ ┌────────────────┐ │    │  --prefill http://..│
    │ │Transfer Engine │ │    │ │Transfer Engine │ │    │  --decode http://..│
    │ │RDMA Transport  │ │    │ │RDMA Transport  │ │    │  --port 8000       │
    │ │(无 Store Client)│ │   │ │(无 Store Client)│ │   └────────────────────┘
    │ └────────────────┘ │    │ └────────────────┘ │            │
    └─────────┬──────────┘    └─────────▲──────────┘            │
              │                         │                       │
              │    RDMA/UB 直连传输 KV   │                       │
              └─────────────────────────┘                       │
                                                                │
    业务请求 ────────────────────────────────────────────────────┘
              统一访问 8000 端口

步骤1：Prefill 生产者节点（kv_producer）

export MOONCAKE_CONFIG_PATH=/data/mooncake_pd.json  [#根据实际情况修改json文件路径](javascript:;) export VLLM_MOONCAKE_BOOTSTRAP_PORT=8998
vllm serve Qwen/Qwen2.5-72B-Instruct \
    --port 8100 \
    --tensor-parallel-size 4 \
    --max-model-len 65536 \
    --gpu-memory-utilization 0.8 \
    --kv-transfer-config '{"kv_connector":"MooncakeConnector","kv_role":"kv_producer"}'

步骤2：Decode 消费者节点（kv_consumer）

export MOONCAKE_CONFIG_PATH=/data/mooncake_pd.json [#根据实际情况修改json文件路径](javascript:;)   
vllm serve Qwen/Qwen2.5-72B-Instruct \
    --port 8200 \
    --tensor-parallel-size 4 \ 
   --max-model-len 65536 \
    --gpu-memory-utilization 0.8 \
    --kv-transfer-config '{"kv_connector":"MooncakeConnector","kv_role":"kv_consumer"}'

启动统一 Proxy 网关（任意节点）

python vllm/examples/online_serving/disaggregated_serving/mooncake_connector_proxy.py \
  --prefill http://192.168.1.10:8100 \
  --decode http://192.168.1.11:8200 \
  --port 8000
# 业务统一访问 8000 端口，无感知 PD 拆分

四、性能调优和常见故障

4.1 性能调优参数

Mooncake 环境变量相关

# KV闲置自动回收300秒
export VLLM_MOONCAKE_ABORT_REQUEST_TIMEOUT=300
# 开启CPU内存缓存
export MOONCAKE_DISABLE_CPU_CACHE=0

vLLM 缓存优化参数相关

--enable-prefix-caching
--num-gpu-blocks-override 20000

RDMA 网络优化相关

# 关闭防火墙，开放50063/8092/业务端口
systemctl stop firewalld
# 校验RDMA网卡
ibv_devinfo

4.2 常见故障问题

缓存命中率为 0
• 所有节点必须统一 export PYTHONHASHSEED=0
• 模型权重、max-model-len、量化方式完全一致

RDMA 连接失败
• 检查网卡驱动、ibverbs、RoCE 配置，关闭防火墙
• device_name 填写正确网卡名（ibstat查看）

mooncake_master 崩溃 / 元数据错乱
• vLLM 进程异常退出后，重启 mooncake_master 清空缓存

显存 OOM
• 调小 local_buffer_size，开启 KV 缓存卸载（Store 模式自动支持 CPU 内存兜底）

端口占用
• 修改 VLLM_MOONCAKE_BOOTSTRAP_PORT、mooncake_master --port

©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成，浏览时请结合常识与多方信息审慎甄别。
平台声明：文章内容（如有图片或视频亦包括在内）由作者上传并发布，文章内容仅代表作者本人观点，简书系信息发布平台，仅提供信息存储服务。

【Mooncake】全局KV缓存池与PD分离模式的部署指南

【Mooncake】全局KV缓存池与PD分离模式的部署指南

一、Mooncake 简介

2.1 项目简介

2.2 架构及核心组件

二、全局共享 KV 缓存池部署模式 - MooncakeStoreConnector

2.1 vllm 环境安装部署

2.2 全局共享 KV 缓存池部署

三、PD 分离多机部署模式 - MooncakeConnector

四、性能调优和常见故障

4.1 性能调优参数

4.2 常见故障问题

相关阅读更多精彩内容

友情链接更多精彩内容