Mooncake × vLLM：使用 MooncakeStoreConnector 构建分布式 KV 缓存池与 XpYd 分离式推理

人工智能大模型模型推理服务后端【免费下载链接】MooncakeMooncake is the serving platform for Kimi, a leading LLM service provided by Moonshot AI.项目地址https://gitcode.com/gh_mirrors/mo/Mooncake点击查看免费下载导读本文以 Mooncake 仓库中MooncakeStoreConnector的部署指南为核心系统讲解如何在 vLLM V1 中通过该 KV Connector 把MooncakeDistributedStore作为共享 KV 缓存池实现 CPU/SSD 缓存卸载、跨实例前缀缓存命中以及kv_both/kv_producer/kv_consumer三种角色下的单机与 XpYd 分离式部署。读完本文你将能够独立完成 master 服务、客户端配置、多节点 vLLM 实例与调度代理的完整搭建并理解每个关键参数在源码层的实际作用。背景与核心能力MooncakeStoreConnector是 vLLM V1 中的一种 KV Connector 实现它把MooncakeDistributedStoreMooncake Store作为共享的分布式 KV 缓存池向 vLLM 提供三类核心能力见 原部署指南 与合并后的 统一指南CPU/Disk 卸载CPU/Disk offloading通过 Mooncake Transfer Engine 把 KV cache 卸载到 CPU 内存或 SSD扩展有效 KV 缓存容量突破单卡显存限制。基于 block-hash 的跨实例前缀缓存hash-based prefix caching across instances多个 vLLM 实例通过共享存储池对 KV block 进行哈希去重相同前缀只需计算一次其余实例直接命中。灵活的部署形态flexible deployment既可作为单节点 KV 缓存扩展kv_both也可用于 Prefill-Decode 分离kv_producer/kv_consumer的 XpYd 场景并支持在运行时动态调整 prefill 与 decode 实例数量。如上图所示Mooncake Store 由 master 服务mooncake_master统一协调集群成员与对象放置各客户端节点贡献 DRAM可选 VRAM/SSD组成分布式缓存池控制面Put/Get/Remove走 RPC而数据面由客户端之间通过 Transfer Engine 直接传输master 不参与数据路径详见 Mooncake Store 部署与调优指南。部署前置条件在开始之前需要同时满足vLLM 已安装且使用 V1 后端MooncakeStoreConnector面向最新版 vLLMV0 后端对应的是遗留的MooncakeStoreconnector仅用于存量部署。Mooncake 已安装包括mooncake_masterStore master 服务与 Transfer Engine 运行时。安装方式可参考 快速入门pip install --upgrade pip pip install mooncake-transfer-engine也可以从源码构建先执行sudo bash dependencies.sh安装依赖再cmake .. make -j sudo make install。若遇到缺失lib*.so的问题建议先卸载 pip 包再手动编译。说明mooncake-transfer-engine包同时提供了 Mooncake Store 的 Python 绑定mooncake.store.MooncakeDistributedStorevLLM 集成正是通过该绑定把 KV cache 写入共享池。启动 Mooncake Master 服务1. 启动 mastermooncake_master --port 50063master 是集群的唯一常驻协调进程负责集群成员管理、跨客户端节点的对象存储分配以及驱逐eviction与放置placement策略的执行。默认 RPC 端口为50051可通过--port指定本文示例使用50063。启动成功后会看到类似日志Master service started on port 50063, max_threads4, ...2. 编写 Mooncake 配置文件创建 JSON 配置文件例如mooncake_config.json{ metadata_server: http://127.0.0.1:8092/metadata, master_server_address: 127.0.0.1:50063, global_segment_size: 0, local_buffer_size: 2147483648, protocol: rdma, device_name: }各字段含义如下字段示例值说明metadata_serverhttp://127.0.0.1:8092/metadataTransfer Engine 使用的元数据服务地址用于节点发现与配置下发。支持 HTTP、etcd、Redis 等后端单机快速验证时也可直接用字面量P2PHANDSHAKE去中心化握手无需独立元数据服务见 Mooncake Store Python APImaster_server_address127.0.0.1:50063Mooncake Store master 服务的 IP 与端口必须与mooncake_master --port保持一致global_segment_size0本节点向集群贡献的共享内存段大小字节。示例0表示不额外分配全局段配合local_buffer_size使用若需向集群贡献 DRAM可设为如3200 * 1024 * 1024local_buffer_size2147483648本地 Transfer Engine 缓冲区大小字节示例值 2 GiB用于数据传输的本地缓冲protocolrdma数据传输协议rdma、tcp还可扩展支持cxl、ascend等见 部署指南device_nameRDMA 网卡设备名。RDMA 场景下必填多网卡用逗号分隔如erdma_0,erdma_1TCP 场景留空。置空时配合MC_MS_AUTO_DISC可自动发现网卡3. 设置环境变量export MOONCAKE_CONFIG_PATH/path/to/mooncake_config.jsonvLLM 启动时会读取该环境变量指向的 JSON初始化 Transfer Engine 并连接 master。使用方式两种部署形态形态一单节点 KV 缓存卸载kv_both一个 vLLM 实例同时承担读写角色把显存放不下的 KV cache 卸载到 CPU/SSDMOONCAKE_CONFIG_PATHmooncake_config.json \ vllm serve meta-llama/Llama-3.1-8B-Instruct \ --kv-transfer-config {kv_connector:MooncakeStoreConnector,kv_role:kv_both}其中--kv-transfer-config是 vLLM 的 KV Connector 配置 JSONkv_connector设置为MooncakeStoreConnector选择 Store 池化连接器。kv_role实例角色取值为kv_producer生成并写入 KV、kv_consumer读取并复用 KV、kv_both对称读写适用于单机 KV 扩展。形态二XpYd Prefill-Decode 分离kv_producer/kv_consumer在分离式推理中prefill 与 decode 由不同实例组承担。为了同时利用两条路径——prefill 实例与 decode 实例之间的点对点 KV 直传MooncakeConnector走 RDMA以及共享的分布式缓存池MooncakeStoreConnector——vLLM V1 提供MultiConnector把它们编排在一起。Prefill 节点MOONCAKE_CONFIG_PATHmooncake_config.json \ VLLM_MOONCAKE_BOOTSTRAP_PORT50052 \ vllm serve meta-llama/Llama-3.1-8B-Instruct \ --port 8100 \ --kv-transfer-config { kv_connector: MultiConnector, kv_role: kv_producer, kv_connector_extra_config: { connectors: [ { kv_connector: MooncakeConnector, kv_role: kv_producer }, { kv_connector: MooncakeStoreConnector, kv_role: kv_producer } ] } }Decode 节点MOONCAKE_CONFIG_PATHmooncake_config.json \ VLLM_MOONCAKE_BOOTSTRAP_PORT50053 \ vllm serve meta-llama/Llama-3.1-8B-Instruct \ --port 8200 \ --kv-transfer-config { kv_connector: MultiConnector, kv_role: kv_consumer, kv_connector_extra_config: { connectors: [ { kv_connector: MooncakeConnector, kv_role: kv_consumer }, { kv_connector: MooncakeStoreConnector, kv_role: kv_consumer } ] } }调度代理Proxypython examples/disaggregated/mooncake_connector/mooncake_connector_proxy.py \ --prefill http://192.168.0.2:8100 50052 \ --decode http://192.168.0.3:8200代理负责把请求先转发给 prefill 节点完成预填充再把携带 KV 引用的请求转发给 decode 节点续写从而把两个阶段在集群内解耦。仓库中还提供了一个完整的轮询式round-robin代理示例 proxy_demo.py支持--prefill/--decode/--port参数并提供GET /status与POST /instances/add需ADMIN_API_KEY接口可用于运行时动态扩容 prefill/decode 组参考 统一指南 中的 Dynamic XpYd Adjustment 一节。数据并行下的哈希一致性使用数据并行DP时必须固定PYTHONHASHSEED保证各 DP rank 计算出的 block hash 一致PYTHONHASHSEED0 vllm serve ...否则相同 prompt 在不同 DP rank 上会生成不同的 block hash导致跨实例前缀缓存无法命中。这是因为前缀缓存的去重依据是 block 哈希而 Python 的字符串哈希默认带进程内随机种子固定种子后多个实例对相同文本块计算出的哈希一致才能命中共享池中的既有 KV block。关键参数与底层原理--kv-transfer-config参数族kv_connectorMooncakeStoreConnector共享池或MooncakeConnector点对点直传二者可用MultiConnector编排组合。kv_rolekv_producer/kv_consumer/kv_both。num_workersMooncakeConnector每个 prefill worker 中用于发送 KV cache 的线程池大小默认 10见 vLLM V1 分离式推理指南。环境变量环境变量默认值说明MOONCAKE_CONFIG_PATH无Mooncake 配置 JSON 的路径vLLM 启动时必读VLLM_MOONCAKE_BOOTSTRAP_PORT8998Mooncake bootstrap 服务端口仅 prefill 实例需要同一主机上每个 vLLM worker 需唯一端口TP/DP 场景按base_port dp_rank * tp_size tp_rank计算VLLM_MOONCAKE_ABORT_REQUEST_TIMEOUT480请求中止后自动释放 KV cache 的超时秒防止资源被长时间占用底层链路从连接器到 Store从源码结构看MooncakeStoreConnector的运行链路可以概括为vLLM 的 KV 生命周期事件block 写入/读取→mooncake.store.MooncakeDistributedStore的put/get/remove调用 → master RPC 控制面 Transfer Engine 数据面。其中客户端把本地 DRAM甚至 SSD注册进集群构成共享池master 只在控制面参与数据由客户端间直接传输——这正是共享池相比 Redis 后端能在长前缀场景显著降低 TTFT 的原因统一指南给出 2P2D、tp2、RDMA 下平均 TTFT 约 32% 提升的对比结论性能页 亦有 vLLM 团队评测在 agentic 多轮场景下缓存命中率从 1.7% 提升至 92.2%吞吐提升 3.8 倍P50 TTFT 降低 46 倍。如果不想通过 vLLM 连接器也可以直接用 Python API 验证 Store 本身可用from mooncake.store import MooncakeDistributedStore store MooncakeDistributedStore() store.setup( local_hostnamelocalhost, metadata_serverP2PHANDSHAKE, # 去中心化无需独立元数据服务 global_segment_size512 * 1024 * 1024, local_buffer_size128 * 1024 * 1024, protocoltcp, rdma_devices, master_server_addr127.0.0.1:50051, ) store.put(hello_key, bHello, Mooncake Store!) print(store.get(hello_key).decode()) store.close()完整的put/get/removeAPI 说明见 Mooncake Store Python API。性能验证与基准测试官方性能结论与图表见 vLLM × Mooncake Store 性能页原部署指南的 Performance 一节即指向该页。如需在本仓库复现 XpYd 基准可直接使用 benchmarks.sh默认环境变量MODELQwen/Qwen2.5-7B-Instruct、NUM_PREFILL4、NUM_DECODE4、PREFILL_PORT_BASE8100、DECODE_PORT_BASE8200、MASTER_PORT10001等可覆盖调整脚本会启动mooncake_master、若干kv_producerprefill与kv_consumerdecodevLLM 实例再启动调度代理按 1P1D → 2P1D → 2P2D → 2P4D → 4P4D 依次跑benchmark_serving.py统计ttft/tpot/itl/e2el百分位指标结果汇总为 Excel。此外stress_cluster_benchmark.py 可用来独立验证两角色prefill/decode之间的数据通路python3 mooncake-store/tests/stress_cluster_benchmark.py --role prefill python3 mooncake-store/tests/stress_cluster_benchmark.py --role decodeRDMA 场景可配合MC_MS_AUTO_DISC1 MC_MS_FILTERSmlx5_1,mlx5_2使用运行无报错即代表数据面传输成功。故障排查与注意事项连通性检查确认所有节点网络互通、防火墙放行对应端口、RDMA 网卡配置正确且mooncake_master正在运行且可达。实例异常退出若某些 vLLM 实例意外退出未正常清理连接元数据建议在下一轮测试前重启mooncake_master清理可能损坏的元数据。缺失动态库遇到lib*.so缺失时卸载 pip 包并按 快速入门 的源码构建流程重新编译安装。调试日志设置VLLM_LOGGING_LEVELDEBUG可获取详细诊断信息。DP 哈希一致性数据并行部署务必固定PYTHONHASHSEED见上文否则跨实例前缀缓存命中率会大幅下降。版本前提MooncakeStoreConnector面向 vLLM V1最新版V0 的MooncakeStore连接器仅用于存量部署新部署请直接使用 V1。延伸阅读vLLM KV Cache Storage Sharing 统一指南本页内容的权威合并版本包含 V0 遗留用法、动态 XpYd 调整与更完整的故障排查。Disaggregated Prefill-Decode with MooncakeConnector点对点 KV 直传路径的单独部署指南含 TP 配置与环境变量细节。Mooncake Store 部署与调优指南master 启动参数全表、HA 高可用、SSD 卸载、租户配额等生产级配置。Mooncake Store Python APIMooncakeDistributedStore的完整 API 与示例。vLLM × Mooncake Store 性能页官方性能评测数据与基准脚本说明。赞分享人工智能大模型模型推理服务后端【免费下载链接】MooncakeMooncake is the serving platform for Kimi, a leading LLM service provided by Moonshot AI.项目地址https://gitcode.com/gh_mirrors/mo/Mooncake点击查看免费下载相关推荐vLLM MooncakeStoreConnector 使用指南基于 Mooncake 分布式存储的 KV Cache 卸载与跨实例前缀缓存共享vLLM MooncakeStoreConnector 使用指南基于 Mooncake 分布式存储的 KV Cache 卸载与跨实例前缀缓存共享 Moonca人工智能大模型模型推理服务推理引擎本地部署vLLM 分离式 Prefill/Decode 部署实战XpYd 代理、多轮 KV 复用与 KV Cache 事件发布vLLM 分离式 Prefill/Decode 部署实战XpYd 代理、多轮 KV 复用与 KV Cache 事件发布 本文围绕 disaggregated_人工智能大模型模型推理服务推理引擎本地部署LMCache 集成 Mooncake 分布式 KV 缓存存储原理、配置与 vLLM 实战指南LMCache 集成 Mooncake 分布式 KV 缓存存储原理、配置与 vLLM 实战指南 本篇指南以 docs/source/kv_cache/stor人工智能大模型缓存抽象模型推理服务上一篇LADSPA模块与NoiseTorch-ngLinux实时麦克风降噪技术深度解析下一篇如何高效解决Buzz模型下载瓶颈3种实用方案完全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考