使用指南

6.10.1 环境搭建

硬件要求：

• GPU： NVIDIA A100/A800/H100/H800/H200
• 网络： InfiniBand 或支持RDMA 的以太网
• 内存： CPU DRAM >= 256GB
• 存储： NVMe SSD （可选，用于 L3 缓存）

软件依赖

#    系统依赖
  sudo apt-get update
  sudo apt-get install -y build-essential cmake git
  sudo apt-get install -y libibverbs-dev librdmacm-dev
       
  # CUDA（如果使用GPU）
  # 参考NVIDIA官方文档安装CUDA 12.1+


  # Python  依赖
  pip install torch>=2.0
  pip install vllm>=0.5.0    #    或 sglang

安装Mooncake：

#    方法1：pip安装（推荐）
  pip install mooncake-transfer-engine


  #    方法2：源码编译
  git clone https://github.com/kvcache-ai/Mooncake.git
  cd Mooncake
  mkdir build && cd build
  cmake ..
  make -j
  sudo make install

6.10.2 配置文件

mooncake.json 配置示例：

{
  "metadata_server": "etcd://192.168.1.1:2379",
  "master_server": "192.168.1.1:50001",
  "protocol": "rdma",
  "device_name": "mlx5_0",
  "gpu_memory_pool_size": 8589934592,
  "cpu_memory_pool_size": 17179869184,
  "ssd_path": "/mnt/ssd/mooncake",
  "ssd_pool_size": 1099511627776,
  "rdma_buffer_size": 1073741824,
  "max_connections": 1024
}

etcd 配置

#   单节点etcd
 etcd --listen-client-urls http://0.0.0.0:2379 \
         --advertise-client-urls http://$(hostname -i):2379


 #    集群模式（生产环境推荐）
 etcd --name node1 \
         --initial-advertise-peer-urls http://192.168.1.1:2380 \
         --listen-peer-urls http://192.168.1.1:2380 \
         --listen-client-urls http://192.168.1.1:2379,http://127.0.0.1:2379 \
         --advertise-client-urls http://192.168.1.1:2379 \
         --initial-cluster-token etcd-cluster \
         --initial-cluster node1=http://192.168.1.1:2380,node2=http://192.168.1
         --initial-cluster-state new

6.10.3 部署步骤

步骤1：启动元数据服务

#   在所有节点启动etcd
 etcd --listen-client-urls http://0.0.0.0:2379 \
         --advertise-client-urls http://$(hostname -i):2379


 #    在Master节点启动Mooncake Master
 mooncake_master --port 50001 \
                   --etcd-endpoints http://192.168.1.1:2379

步骤2：部署Prefill节点

#   节点1
 export MOONCAKE_CONFIG_PATH=./mooncake.json
 export VLLM_MOONCAKE_BOOTSTRAP_PORT=8998


 python -m vllm.entrypoints.openai.api_server \
     --model meta-llama/Llama-3.1-70B-Instruct \
     --tensor-parallel-size 4 \
     --port 8100 \
     --kv-transfer-config '{
      "kv_connector": "MooncakeConnector",
      "kv_role": "kv_producer"
     }'


 #   节点2
 export MOONCAKE_CONFIG_PATH=./mooncake.json
 export VLLM_MOONCAKE_BOOTSTRAP_PORT=8999


 python -m vllm.entrypoints.openai.api_server \
     --model meta-llama/Llama-3.1-70B-Instruct \
     --tensor-parallel-size 4 \
     --port 8101 \
     --kv-transfer-config '{
      "kv_connector": "MooncakeConnector",
      "kv_role": "kv_producer"
     }'

步骤3：部署Decode节点

#   节点3
export MOONCAKE_CONFIG_PATH=./mooncake.json


 python -m vllm.entrypoints.openai.api_server \
         --model meta-llama/Llama-3.1-70B-Instruct \
         --tensor-parallel-size 4 \
         --port 8200 \
         --kv-transfer-config '{
          "kv_connector": "MooncakeConnector",
          "kv_role": "kv_consumer"
         }'


 #       节点4
 export MOONCAKE_CONFIG_PATH=./mooncake.json


 python -m vllm.entrypoints.openai.api_server \
         --model meta-llama/Llama-3.1-70B-Instruct \
         --tensor-parallel-size 4 \
         --port 8201 \
         --kv-transfer-config '{
          "kv_connector": "MooncakeConnector",
          "kv_role": "kv_consumer"
         }'

步骤4：启动Proxy

python examples/online_serving/disaggregated_serving/mooncake_connector/main.py \
--prefill http://192.168.1.10:8100 http://192.168.1.11:8101 \
--decode http://192.168.1.12:8200 http://192.168.1.13:8201 \
--port 8000

步骤5：测试

#   发送测试请求
curl http://localhost:8000/v1/completions \
     -H "Content-Type: application/json" \
     -d '{
      "model": "meta-llama/Llama-3.1-70B-Instruct",
      "prompt": "Once upon a time",
      "max_tokens": 100
     }'

6.10.4 常见问题

Q1：Transfer Engine初始化失败

Error: Mooncake Transfer Engine initialization failed

解决方案：

• 检查RDMA设备是否正确配置： ibstat
• 检查etcd服务是否正常运行
• 检查防火墙是否放行了RDMA端口

Q2：KV Cache传输失败

Error: batch_transfer_sync_write returned non-zero

解决方案：

• 检查网络连通性： ping
• 检查 RDMA 连接：ib_write_bw 测试带宽
• 检查内存注册是否成功

Q3：内存不足

Error: Failed to allocate GPU memory

解决方案：

• 减小 gpu_memory_pool_size
• 减小 --gpu-memory-utilization 参数
• 使用更小的模型或更大的GPU

Q4：性能不达预期

排查步骤： 1. 检查 RDMA带宽： ib_read_bw 2. 检查 GPU利用率：nvidia-smi 3. 检查Prefill/Decode比例是否合理 4. 检查Prefix Caching命中率

Q5：如何调优 Prefill/Decode比例建议：

• 根据负载特征调整
• 输入密集型负载： Prefill节点更多
• 输出密集型负载：Decode节点更多
• 典型比例：Prefill:Decode = 1:1 到 1:3

Q6：如何监控 Mooncake 集群状态监控指标：

• Transfer Engine 传输带宽和延迟
• KVCache命中率
• Prefill/Decode节点负载
• etcd集群健康状态

监控工具：

#   查看RDMA带宽
 ib_read_bw -d mlx5_0

 #    查看GPU利用率
 nvidia-smi dmon -s u

 #    查看Mooncake Master状态
 curl http://localhost:50001/metrics

 #    查看etcd集群健康
 etcdctl endpoint health

Q7：如何处理节点故障 故障恢复策略：

1. Transfer Engine自动重连 2. Conductor重新调度请求到健康节点 3. KV Cache从副本恢复

配置故障转移：

{
  "failover_enabled": true,
  "failover_timeout_ms": 5000,
  "retry_attempts": 3,
  "health_check_interval_ms": 1000
}