尧图网页设计 
1. 为什么 Mooncake 的 KVCache 分层值得单独拆一次如果你正在用 vLLM 跑长上下文推理大概率遇到过两个现象一是首 token 延迟TTFT忽高忽低二是多机部署时预填充和解码两个阶段抢带宽。Mooncake 这套以 KVCache 为中心的分解架构核心思路就是把预填充Prefill和解码Decode拆到不同集群再把 GPU 集群里闲置的 CPU、DRAM、SSD 利用起来做分层缓存同时用 Transfer Engine 替代默认的 NCCL/Gloo 做节点间 KVCache 传输。它适合谁适合已经在单机 vLLM 上跑通、准备往多机 P/D 分离演进或者想先把 KVCache 命中率和 RDMA 链路摸清楚的团队。Mooncake 的 Transfer Engine 支持 TCP、RDMAInfiniBand/RoCEv2/eRDMA/GPUDirect以及 NVMe over Fabric能聚合多张 RDMA 网卡带宽还能按 NUMA 亲和性做拓扑感知路径选择。实测数据里带 Transfer Engine 的 vLLM 平均 TTFT 比纯 TCP 低约 25%长上下文场景吞吐提升更明显。但真正落地时卡人的往往不是算法而是配置RDMA 设备名写错、KVCache 分层目录权限不对、vLLM 的 kv-transfer-config 参数和 Mooncake 的 config.toml 对不上。这篇就把这些配置骨架摊开配合 TaoToken 统一 Key/API 通道的接入位置让你能直接复制、逐段验证。2. TaoToken 在 Mooncake 链路里的接入位置Mooncake 本身是推理侧的缓存与传输框架它不负责模型 API 的鉴权与路由。实际部署里你通常需要一个统一的 Key/API 通道来管理模型调用、coding-plan 和 console 里的密钥分发。TaoToken 在这里扮演的是「统一入口」角色模型对话、API Keys、接入文档、Coding Plan 都在同一套体系下。接入位置很明确vLLM 作为推理后端暴露 OpenAI 兼容接口TaoToken 的 API 通道指向这个后端前端应用只认 TaoToken 的 Key。这样 KVCache 分层和 RDMA 传输在 vLLM 内部完成鉴权和路由在 TaoToken 层完成两边解耦。你需要先拿到 Key。访问 API Keys 页面生成然后对照接入文档确认 base_url 和模型名。如果你要长期跑编码或 Agent 任务Coding Plan 里有更细的配额说明想先验证模型连通性直接用模型对话页面发一条请求即可。注意TaoToken 的 API 地址是 https://taotoken.net/api不要加多余路径。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content里面有 console 和文档的 deep link。3. 可复制的 config.toml 与 settings.json 配置骨架Mooncake 的 Transfer Engine 配置分两块一块是 Mooncake 侧的 config.toml定义 RDMA 设备、元数据服务和传输协议另一块是 vLLM 侧的 settings.json或启动参数定义 kv-transfer-config 和 P/D 分离角色。先看 Mooncake 的 config.toml。这个文件通常放在 Mooncake 源码的 build 目录或你指定的配置路径下# config.toml - Mooncake Transfer Engine 配置骨架 [metadata] # 元数据服务支持 etcd / redis / http server_type etcd server_address 127.0.0.1:2379 # 如果不用 etcd可换成 redis # server_type redis # server_address 127.0.0.1:6379 [transfer_engine] # 传输协议tcp / rdma protocol rdma # RDMA 设备列表按 NUMA 亲和性排列 # 用 ibv_devinfo 或 rdma link 查看实际设备名 device_names [mlx5_0, mlx5_1] # 是否启用 GPUDirect RDMA use_gpu_direct true # 是否启用多网卡带宽聚合 enable_multi_nic true # 拓扑感知路径选择 topology_aware true # 传输超时毫秒 timeout_ms 5000 # 重试次数 retry_count 3 [kvcache] # KVCache 分层目录 cache_dir /mnt/nvme/mooncake_kvcache # 内存缓存大小GB dram_cache_gb 64 # SSD 缓存大小GB ssd_cache_gb 512 # 缓存淘汰策略lru / lfu eviction_policy lru # 块大小token 数 block_size 16 [p2p_store] # P2P Store 元数据服务 metadata_server etcd metadata_address 127.0.0.1:2379 # 是否启用去中心化分发 decentralized true再看 vLLM 侧的 settings.json。vLLM 从 2024 年 12 月起正式支持 Mooncake 传输引擎做分解预填充和 KV 缓存传输启动时需要指定 kv-transfer-config{ kv_transfer_config: { kv_connector: MooncakeConnector, kv_role: kv_producer, kv_connector_extra_config: { mooncake_config_path: /etc/mooncake/config.toml, transfer_engine_protocol: rdma, device_names: [mlx5_0, mlx5_1], use_gpu_direct: true, enable_multi_nic: true } }, prefill_decode_disaggregation: { enabled: true, role: prefill, peer_host: 10.0.0.2, peer_port: 8000 }, cache_config: { block_size: 16, gpu_memory_utilization: 0.9, swap_space: 32 } }如果你跑的是解码节点把kv_role改成kv_consumerrole改成decodepeer_host指向预填充节点。两个节点都要能访问同一个 etcd 或 redis 元数据服务。注意device_names必须和ibv_devinfo输出一致。我见过有人把mlx5_0写成mlx5_bond0结果 Transfer Engine 初始化直接报no available device。4. 验证 KVCache 命中与 RDMA 连通性配置写完不算完得验证两件事KVCache 有没有真的命中RDMA 链路通不通。先验证 RDMA 连通性。在预填充节点和解码节点分别执行# 查看 RDMA 设备状态 ibv_devinfo -v | grep -E hca_id|state|rate # 用 perftest 测带宽和延迟 # 服务端解码节点 ib_send_bw -d mlx5_0 -a -F # 客户端预填充节点 ib_send_bw -d mlx5_0 -a -F 10.0.0.2如果ib_send_bw能跑出接近网卡标称带宽的结果说明 RDMA 链路正常。Mooncake 的 Transfer Engine 支持多网卡聚合你可以用-d mlx5_0,mlx5_1同时指定两张卡观察带宽是否叠加。再验证 KVCache 命中。Mooncake 的 trace 是 jsonl 格式每条记录包含timestamp、input_length、output_length和hash_ids。你可以在 vLLM 启动后发一批长上下文请求然后检查缓存目录# 查看 KVCache 目录增长 du -sh /mnt/nvme/mooncake_kvcache # 统计缓存块数量 find /mnt/nvme/mooncake_kvcache -type f | wc -l # 查看 vLLM 日志中的缓存命中信息 grep -i kv cache hit /var/log/vllm/server.log如果du -sh在请求后明显增长且日志里出现kv cache hit rate相关行说明分层缓存生效。Mooncake 论文里提到最高 50% 的缓存命中率实际取决于你的请求重复度和 block_size 设置。最后用 TaoToken 的模型对话页面发一条请求确认整条链路从 API 入口到 vLLM 后端都通curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer YOUR_TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: your-model-name, messages: [{role: user, content: 用一句话解释 KVCache 分层}], max_tokens: 64 }返回正常 completion 就说明 TaoToken 通道和 vLLM 后端已经串起来了。5. 本篇常见错排查报错一Transfer engine init failed: no available device原因通常是device_names写错或者 RDMA 驱动没加载。先跑ibv_devinfo确认设备名再检查lsmod | grep mlx5看驱动是否加载。如果是 RoCEv2 环境还要确认rdma link里端口状态是 ACTIVE。报错二KVCache block size mismatchvLLM 的block_size和 Mooncake config.toml 里的block_size必须一致。默认都是 16但如果你在 vLLM 侧改过cache_config.block_sizeMooncake 侧也要同步改。两边不一致时KVCache 传输会直接失败。报错三etcd connection refused元数据服务没起来或者地址写错。Mooncake 支持 etcd、redis、http 三种元数据服务server_type和server_address要匹配。如果你用 redis记得装 hiredis 并用-DUSE_REDIS重新编译。报错四TaoToken 返回 401Key 没带对或者 base_url 写成了https://taotoken.net/api/v1以外的路径。确认请求头是Authorization: Bearer YOUR_KEYbase_url 是https://taotoken.net/api。如果还是 401去 API Keys 页面重新生成一个。报错五TTFT 没有下降RDMA 链路通了但 TTFT 没改善通常是use_gpu_direct没开或者topology_aware没生效。检查 config.toml 里这两项是否为 true然后确认 GPU 和 RDMA 网卡在同一 NUMA 节点上。nvidia-smi topo -m可以看到 GPU 和网卡的拓扑关系。6. 把配置落到可运行的一步Mooncake 的 KVCache 分层和 RDMA 传输本质上是在 vLLM 的 P/D 分离基础上加了两层优化一层是缓存分层把 DRAM、SSD 拉进来做 KVCache 池化另一层是传输优化用 Transfer Engine 替代 NCCL/Gloo 做节点间数据搬迁。配置骨架的核心就是 config.toml 里的device_names、protocol、cache_dir以及 vLLM settings.json 里的kv_connector和kv_role。TaoToken 在这里不碰推理内部逻辑只做统一 Key/API 通道。你先把 vLLM 和 Mooncake 跑通再用 TaoToken 的 API 通道包一层前端就不用关心后端是单机还是 P/D 分离。如果后面要长期跑编码或 Agent 任务Coding Plan 里有配额和模型路由的说明想先验证模型连通性模型对话页面发一条就行。接入文档里有完整的 base_url 和参数对照console 里可以管理所有 Key。 Mooncake LLM 服务拆解：KVCache 与 RDMA 在 vLLM 中的配置骨架
1. 为什么 Mooncake 的 KVCache 分层值得单独拆一次如果你正在用 vLLM 跑长上下文推理大概率遇到过两个现象一是首 token 延迟TTFT忽高忽低二是多机部署时预填充和解码两个阶段抢带宽。Mooncake 这套以 KVCache 为中心的分解架构核心思路就是把预填充Prefill和解码Decode拆到不同集群再把 GPU 集群里闲置的 CPU、DRAM、SSD 利用起来做分层缓存同时用 Transfer Engine 替代默认的 NCCL/Gloo 做节点间 KVCache 传输。它适合谁适合已经在单机 vLLM 上跑通、准备往多机 P/D 分离演进或者想先把 KVCache 命中率和 RDMA 链路摸清楚的团队。Mooncake 的 Transfer Engine 支持 TCP、RDMAInfiniBand/RoCEv2/eRDMA/GPUDirect以及 NVMe over Fabric能聚合多张 RDMA 网卡带宽还能按 NUMA 亲和性做拓扑感知路径选择。实测数据里带 Transfer Engine 的 vLLM 平均 TTFT 比纯 TCP 低约 25%长上下文场景吞吐提升更明显。但真正落地时卡人的往往不是算法而是配置RDMA 设备名写错、KVCache 分层目录权限不对、vLLM 的 kv-transfer-config 参数和 Mooncake 的 config.toml 对不上。这篇就把这些配置骨架摊开配合 TaoToken 统一 Key/API 通道的接入位置让你能直接复制、逐段验证。2. TaoToken 在 Mooncake 链路里的接入位置Mooncake 本身是推理侧的缓存与传输框架它不负责模型 API 的鉴权与路由。实际部署里你通常需要一个统一的 Key/API 通道来管理模型调用、coding-plan 和 console 里的密钥分发。TaoToken 在这里扮演的是「统一入口」角色模型对话、API Keys、接入文档、Coding Plan 都在同一套体系下。接入位置很明确vLLM 作为推理后端暴露 OpenAI 兼容接口TaoToken 的 API 通道指向这个后端前端应用只认 TaoToken 的 Key。这样 KVCache 分层和 RDMA 传输在 vLLM 内部完成鉴权和路由在 TaoToken 层完成两边解耦。你需要先拿到 Key。访问 API Keys 页面生成然后对照接入文档确认 base_url 和模型名。如果你要长期跑编码或 Agent 任务Coding Plan 里有更细的配额说明想先验证模型连通性直接用模型对话页面发一条请求即可。注意TaoToken 的 API 地址是 https://taotoken.net/api不要加多余路径。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content里面有 console 和文档的 deep link。3. 可复制的 config.toml 与 settings.json 配置骨架Mooncake 的 Transfer Engine 配置分两块一块是 Mooncake 侧的 config.toml定义 RDMA 设备、元数据服务和传输协议另一块是 vLLM 侧的 settings.json或启动参数定义 kv-transfer-config 和 P/D 分离角色。先看 Mooncake 的 config.toml。这个文件通常放在 Mooncake 源码的 build 目录或你指定的配置路径下# config.toml - Mooncake Transfer Engine 配置骨架 [metadata] # 元数据服务支持 etcd / redis / http server_type etcd server_address 127.0.0.1:2379 # 如果不用 etcd可换成 redis # server_type redis # server_address 127.0.0.1:6379 [transfer_engine] # 传输协议tcp / rdma protocol rdma # RDMA 设备列表按 NUMA 亲和性排列 # 用 ibv_devinfo 或 rdma link 查看实际设备名 device_names [mlx5_0, mlx5_1] # 是否启用 GPUDirect RDMA use_gpu_direct true # 是否启用多网卡带宽聚合 enable_multi_nic true # 拓扑感知路径选择 topology_aware true # 传输超时毫秒 timeout_ms 5000 # 重试次数 retry_count 3 [kvcache] # KVCache 分层目录 cache_dir /mnt/nvme/mooncake_kvcache # 内存缓存大小GB dram_cache_gb 64 # SSD 缓存大小GB ssd_cache_gb 512 # 缓存淘汰策略lru / lfu eviction_policy lru # 块大小token 数 block_size 16 [p2p_store] # P2P Store 元数据服务 metadata_server etcd metadata_address 127.0.0.1:2379 # 是否启用去中心化分发 decentralized true再看 vLLM 侧的 settings.json。vLLM 从 2024 年 12 月起正式支持 Mooncake 传输引擎做分解预填充和 KV 缓存传输启动时需要指定 kv-transfer-config{ kv_transfer_config: { kv_connector: MooncakeConnector, kv_role: kv_producer, kv_connector_extra_config: { mooncake_config_path: /etc/mooncake/config.toml, transfer_engine_protocol: rdma, device_names: [mlx5_0, mlx5_1], use_gpu_direct: true, enable_multi_nic: true } }, prefill_decode_disaggregation: { enabled: true, role: prefill, peer_host: 10.0.0.2, peer_port: 8000 }, cache_config: { block_size: 16, gpu_memory_utilization: 0.9, swap_space: 32 } }如果你跑的是解码节点把kv_role改成kv_consumerrole改成decodepeer_host指向预填充节点。两个节点都要能访问同一个 etcd 或 redis 元数据服务。注意device_names必须和ibv_devinfo输出一致。我见过有人把mlx5_0写成mlx5_bond0结果 Transfer Engine 初始化直接报no available device。4. 验证 KVCache 命中与 RDMA 连通性配置写完不算完得验证两件事KVCache 有没有真的命中RDMA 链路通不通。先验证 RDMA 连通性。在预填充节点和解码节点分别执行# 查看 RDMA 设备状态 ibv_devinfo -v | grep -E hca_id|state|rate # 用 perftest 测带宽和延迟 # 服务端解码节点 ib_send_bw -d mlx5_0 -a -F # 客户端预填充节点 ib_send_bw -d mlx5_0 -a -F 10.0.0.2如果ib_send_bw能跑出接近网卡标称带宽的结果说明 RDMA 链路正常。Mooncake 的 Transfer Engine 支持多网卡聚合你可以用-d mlx5_0,mlx5_1同时指定两张卡观察带宽是否叠加。再验证 KVCache 命中。Mooncake 的 trace 是 jsonl 格式每条记录包含timestamp、input_length、output_length和hash_ids。你可以在 vLLM 启动后发一批长上下文请求然后检查缓存目录# 查看 KVCache 目录增长 du -sh /mnt/nvme/mooncake_kvcache # 统计缓存块数量 find /mnt/nvme/mooncake_kvcache -type f | wc -l # 查看 vLLM 日志中的缓存命中信息 grep -i kv cache hit /var/log/vllm/server.log如果du -sh在请求后明显增长且日志里出现kv cache hit rate相关行说明分层缓存生效。Mooncake 论文里提到最高 50% 的缓存命中率实际取决于你的请求重复度和 block_size 设置。最后用 TaoToken 的模型对话页面发一条请求确认整条链路从 API 入口到 vLLM 后端都通curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer YOUR_TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: your-model-name, messages: [{role: user, content: 用一句话解释 KVCache 分层}], max_tokens: 64 }返回正常 completion 就说明 TaoToken 通道和 vLLM 后端已经串起来了。5. 本篇常见错排查报错一Transfer engine init failed: no available device原因通常是device_names写错或者 RDMA 驱动没加载。先跑ibv_devinfo确认设备名再检查lsmod | grep mlx5看驱动是否加载。如果是 RoCEv2 环境还要确认rdma link里端口状态是 ACTIVE。报错二KVCache block size mismatchvLLM 的block_size和 Mooncake config.toml 里的block_size必须一致。默认都是 16但如果你在 vLLM 侧改过cache_config.block_sizeMooncake 侧也要同步改。两边不一致时KVCache 传输会直接失败。报错三etcd connection refused元数据服务没起来或者地址写错。Mooncake 支持 etcd、redis、http 三种元数据服务server_type和server_address要匹配。如果你用 redis记得装 hiredis 并用-DUSE_REDIS重新编译。报错四TaoToken 返回 401Key 没带对或者 base_url 写成了https://taotoken.net/api/v1以外的路径。确认请求头是Authorization: Bearer YOUR_KEYbase_url 是https://taotoken.net/api。如果还是 401去 API Keys 页面重新生成一个。报错五TTFT 没有下降RDMA 链路通了但 TTFT 没改善通常是use_gpu_direct没开或者topology_aware没生效。检查 config.toml 里这两项是否为 true然后确认 GPU 和 RDMA 网卡在同一 NUMA 节点上。nvidia-smi topo -m可以看到 GPU 和网卡的拓扑关系。6. 把配置落到可运行的一步Mooncake 的 KVCache 分层和 RDMA 传输本质上是在 vLLM 的 P/D 分离基础上加了两层优化一层是缓存分层把 DRAM、SSD 拉进来做 KVCache 池化另一层是传输优化用 Transfer Engine 替代 NCCL/Gloo 做节点间数据搬迁。配置骨架的核心就是 config.toml 里的device_names、protocol、cache_dir以及 vLLM settings.json 里的kv_connector和kv_role。TaoToken 在这里不碰推理内部逻辑只做统一 Key/API 通道。你先把 vLLM 和 Mooncake 跑通再用 TaoToken 的 API 通道包一层前端就不用关心后端是单机还是 P/D 分离。如果后面要长期跑编码或 Agent 任务Coding Plan 里有配额和模型路由的说明想先验证模型连通性模型对话页面发一条就行。接入文档里有完整的 base_url 和参数对照console 里可以管理所有 Key。