Mooncake项目vLLM解耦式服务与KVCache传输技术详解

最新推荐文章于 2025-06-17 19:41:51 发布

明会泽Irene

最新推荐文章于 2025-06-17 19:41:51 发布

阅读量395

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00974/article/details/148578583

Mooncake项目vLLM解耦式服务与KVCache传输技术详解

Mooncake 项目地址: https://gitcode.com/gh_mirrors/mo/Mooncake

引言

在大模型推理服务领域，如何高效处理长文本序列一直是个技术难点。Mooncake项目通过创新的KVCache传输机制，实现了vLLM推理服务的预填充(prefill)和解码(decoding)阶段解耦，为这一难题提供了优雅的解决方案。本文将深入解析这一技术的实现原理和使用方法。

技术背景

传统的大模型推理服务通常将预填充和解码阶段耦合在同一个进程中，这导致资源利用率不高且缺乏弹性。Mooncake项目通过以下创新点解决了这些问题：

解耦架构：将计算密集型的预填充阶段和内存密集型的解码阶段分离
KVCache传输：通过MooncakeStore实现键值缓存的跨节点传输
弹性扩展：支持动态调整预填充组和解码组的实例数量

核心组件

Mooncake传输引擎

Mooncake传输引擎是整个架构的核心，负责：

管理KVCache的存储和传输
协调预填充实例和解码实例之间的通信
提供元数据服务

vLLM适配层

适配层实现了vLLM与MooncakeStore的无缝集成，主要功能包括：

将预填充阶段生成的KVCache导出到MooncakeStore
解码阶段从MooncakeStore导入KVCache
处理传输过程中的异常情况

安装指南

系统要求

Python 3.8+
CUDA 11.8+
RDMA或TCP网络环境

安装步骤

安装Mooncake传输引擎：

pip3 install mooncake-transfer-engine

编译安装vLLM：

git clone vllm官方仓库
cd vllm
pip3 install -e .

注意：对于vLLM v0.8.4及以下版本，必须从源码编译安装。

配置详解

Mooncake服务需要配置文件来定义运行参数，以下是关键配置项说明：

RDMA配置示例

{
    "local_hostname": "192.168.0.137",
    "metadata_server": "etcd://192.168.0.137:2379",
    "protocol": "rdma",
    "device_name": "erdma_0",
    "master_server_address": "192.168.0.137:50001"
}

TCP配置示例

{
    "local_hostname": "192.168.0.137",
    "metadata_server": "etcd://192.168.0.137:2379",
    "protocol": "tcp",
    "device_name": "",
    "master_server_address": "192.168.0.137:50001"
}

配置项说明

local_hostname：节点IP地址
metadata_server：支持etcd、redis或http三种后端
protocol：数据传输协议，可选rdma或tcp
device_name：RDMA设备名称（仅RDMA协议需要）
master_server_address：MooncakeStore主守护进程地址

服务部署

启动顺序

启动etcd服务器：

etcd --listen-client-urls http://0.0.0.0:2379 --advertise-client-urls http://localhost:2379

启动mooncake_master：

mooncake_master --port 50001

启动vLLM实例：

预填充实例示例：

MOONCAKE_CONFIG_PATH=./mooncake.json VLLM_USE_V1=0 python3 -m vllm.entrypoints.openai.api_server \
--model Qwen/Qwen2.5-7B-Instruct-GPTQ-Int4 \
--port 8100 \
--max-model-len 10000 \
--gpu-memory-utilization 0.8 \
--kv-transfer-config '{"kv_connector":"MooncakeStoreConnector","kv_role":"kv_producer"}'

解码实例示例：

MOONCAKE_CONFIG_PATH=./mooncake.json VLLM_USE_V1=0 python3 -m vllm.entrypoints.openai.api_server \
--model Qwen/Qwen2.5-7B-Instruct-GPTQ-Int4 \
--port 8200 \
--max-model-len 10000 \
--gpu-memory-utilization 0.8 \
--kv-transfer-config '{"kv_connector":"MooncakeStoreConnector","kv_role":"kv_consumer"}'

启动中间服务器：

python3 disagg_proxy_demo.py \
--model Qwen/Qwen2.5-7B-Instruct-GPTQ-Int4 \
--prefill localhost:8100 localhost:8101 \
--decode localhost:8200 localhost:8201 \
--port 8000

动态扩展

Mooncake支持运行时动态调整实例组：

设置管理密钥：

export ADMIN_API_KEY="xxxxxxxx"

添加预填充实例：

curl -X POST "http://localhost:8000/instances/add" \
-H "Content-Type: application/json" \
-H "X-API-Key: $ADMIN_API_KEY" \
-d '{"type": "prefill", "instance": "localhost:8102"}'

添加解码实例：

curl -X POST "http://localhost:8000/instances/add" \
-H "Content-Type: application/json" \
-H "X-API-Key: $ADMIN_API_KEY" \
-d '{"type": "decode", "instance": "localhost:8202"}'

查询服务状态：

curl localhost:8000/status | jq

测试验证

发送OpenAI兼容请求测试服务：

curl -s http://localhost:8000/v1/completions \
-H "Content-Type: application/json" \
-d '{
  "model": "Qwen/Qwen2.5-7B-Instruct-GPTQ-Int4",
  "prompt": "San Francisco is a",
  "max_tokens": 1000
}'