1. 先把 Mooncake 的部署逻辑讲透再动手敲命令我头一回在生产集群里上 Mooncake是因为推理服务的首 token 延迟在高峰期抖得厉害。单机 vLLM 跑得好好的一放到几十张卡的集群里Prefill 节点算完的 KV Cache 没法高效传给 Decode 节点网络成了新瓶颈。这种场景下Mooncake 就是为以 KVCache 为中心的分离式推理架构准备的——它把 KV Cache 从 GPU 显存里抽出来做成一个跨节点、分层、可复用的分布式缓存池。简单说它要解决的是算力没吃满、显存反复搬、缓存命中率低这三件事。这套东西由几块拼图组成Transfer Engine负责底层数据传输RDMA、TCP、NVMe-oF、共享内存都能接Mooncake Store负责缓存对象的分布式管理与路由Mooncake Master是元数据大脑负责 Segment 分配和淘汰策略P2P Store则用来做模型权重和 checkpoint 的点对点分发。本文面向的是已经了解大模型推理、现在要把 Mooncake 落地的工程师——从一台开发机跑通到几十台节点组成生产集群我会把每一步的判断依据和踩过的坑都摊开说。2. 部署前必须搞明白的架构决策2.1 为什么选分离式 集中缓存而不是单机堆卡我一开始也犹豫过把模型切得更细、多卡张量并行不是更直接吗实测下来这条路在长上下文场景会撞墙。张量并行的通信量随 TP 度数上升跨机 NVLink 缺失时直接打回 PCIe 带宽而分离式架构把 Prefill 和 Decode 拆到不同节点用 Mooncake 做 KV Cache 中转Prefill 可以按算力密度配置比如 8 卡 A800Decode 按显存带宽配置两边的硬件不必一样。这样调度器可以针对缓存命中而不是请求排队做决策——这就是它所谓 KVCache-centric 的含义。代价是运维复杂度上来了你要维护 Master 的高可用、元数据服务、RDMA 网络、Segment 的容量规划。所以我的判断是单机显存够用、并发不高的小场景别上集群只有当你做到下面这些条件时才值得上单请求上下文长度常年超过 8KKV Cache 复用率有优化空间集群规模超过 16 张卡且 Prefill / Decode 负载有明确的时间差业务对 TTFT首 token 延迟和吞吐都有硬指标2.2 Transfer Engine 的传输路径选择这是部署最容易翻车的一环。Transfer Engine 抽象了多条后端路径我在不同环境里都用过传输方式适用场景单链路带宽实测参考部署复杂度RDMA (InfiniBand)大规模生产集群接近线速400Gbps 场景实测 350Gbps高需要 IB 子网管理器RoCEv2万兆/25G 以太集群视 PFC/ECN 配置调优后能到 200Gbps中高需要无损网络配置TCP单机、开发环境、小规模约 10-20Gbps低NVMe-oF冷缓存落盘、SSD 池依赖 SSD 与网卡中共享内存 (shm)单机多进程内存带宽级极低提示单机部署直接用 tcp 或 shm 就行不要折腾 RDMA否则一堆 GID、PFC、MTU 的坑能把调试时间吃掉两天。2.3 单机模式和集群模式的边界在哪我的经验是单机模式只用来验证功能与压测接口一旦要上业务就得转集群。单机模式下 Master、Store、Client 都跑在同一台机器上用 shm 或 tcp 通信整个体系本质上还是一个本地缓存池没有跨节点收益。集群模式才是 Mooncake 真正发挥的地方多个存储节点各自贡献 DRAM/SSD 作为 SegmentMaster 统一管理客户端只需一个全局地址就能读任意缓存。具体怎么切分我画了一个判断表只做功能验证、跑通 Python 示例 → 单机需要给离线批量推理提速、KV Cache 复用率高 → 单机或小集群在线服务、TTFT 敏感、节点数 4 → 集群 RDMA有冷热分层需求显存→DRAM→SSD → 集群 NVMe 池3. 单机部署从零到跑通第一个读写测试3.1 系统环境与硬件底线先说我踩过的第一个坑Mooncake 对 glibc 和编译器版本有要求太老的发行版会缺符号。我推荐组合是Ubuntu 22.04 GCC 11 CMake 3.22。如果要用 RDMA还要装libibverbs-dev、rdma-core并确保/dev/infiniband存在。硬件上单机最低配置参考CPU16 核以上编译阶段就能看出来内存≥64GB因为 Store 需要预分配大块 DRAM 做 Segment磁盘≥200GB 空闲空间SSD 优先网卡单机验证用普通网卡即可RDMA 网卡留到集群阶段注意Mooncake 的 Store 会预先mmap一大块内存如果你用容器部署务必把--shm-size调大否则启动时会 OOM。3.2 依赖安装与源码构建依赖项我按顺序列一下这样不会因为链接顺序出问题sudo apt update sudo apt install -y build-essential cmake ninja-build \ libgflags-dev libgoogle-glog-dev libgtest-dev \ libjsoncpp-dev libyaml-cpp-dev libcurl4-openssl-dev \ libssl-dev libibverbs-dev librdmacm-dev \ libnuma-dev libaio-dev拿到源码后构建我一般分两步先构建 Transfer Engine再构建 Store。原因是 Store 依赖 TE 的库如果一起 build 遇到链接错误不好定位。git clone https://github.com/kvcache-ai/Mooncake.git cd Mooncake mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease -DWITH_RDMAON -DWITH_STOREON make -j$(nproc)编译时长取决于机器16 核大约 10-15 分钟。WITH_RDMAON在没有 RDMA 网卡时也能编过只是运行期会 fallback 到 TCP。3.3 启动 Master 并跑通读写测试启动顺序很重要先起元数据服务再起 Master最后起客户端。单机验证时元数据服务我用的是 etcd因为配置简单、文档全# 1. 启动 etcd单节点即可 etcd --listen-client-urls http://0.0.0.0:2379 \ --advertise-client-urls http://0.0.0.0:2379 \ --data-dir /var/lib/etcd-mooncake # 2. 启动 Mooncake Master ./build/mooncake-store/src/mooncake_master \ --rpc_port50051 \ --eviction_high_watermark_ratio0.9 \ --default_kv_lease_ttl5000Master 起来了以后客户端这边 Python 侧接一下就通了from mooncake.store import MooncakeDistributedStore store MooncakeDistributedStore() store.setup( local_hostname127.0.0.1, metadata_serveretcd://127.0.0.1:2379, global_segment_size8 * 1024 * 1024 * 1024, # 8GB local_buffer_size512 * 1024 * 1024, # 512MB protocoltcp, device_name, ) store.put(test_key, bhello_mooncake) print(store.get(test_key))我特意留了一段日志观察put之后 Master 日志会出现ObjectAllocated记录get时如果命中的是远端 SegmentTE 层会打印TransferRequest的耗时。这套日志是排查问题的第一现场建议先用-v2打开详细日志。3.4 单机部署的三个典型坑坑一内存预分配过大导致启动慢。global_segment_size写 32G 时启动阶段 mmap 就要好几十秒而且如果物理内存不够会触发 OOM Killer。我一般按物理内存的 60% 给到 Segment。坑二local_buffer_size设太小。这个缓冲区是用于 TE 零拷贝的中转区太小会退化到多次拷贝吞吐直接砍半。512MB 起步重负载场景翻倍。坑三etcd 的 lease 泄漏。客户端异常退出后 Segment 对应的租约不一定及时清理重启客户端前先看etcdctl get --prefix mooncake/里有没有残留。这个坑在集群模式里更明显后文细讲。4. 生产环境集群部署从 3 台到 100 台4.1 网络规划RDMA 还是 RoCE以及带宽怎么算生产环境的网络方案我建议按集群规模分档3-8 节点、无无损网络条件先上 TCP带宽至少 25Gbps此时瓶颈不在网络而在 DRAM 带宽8-32 节点上 RoCEv2配置 PFC 和 ECN 做无损25G 起步32 节点以上直接上 InfiniBand HDR/NDR否则大规模下 PFC 风暴的概率会攀升带宽怎么算假设每条请求平均 KV Cache 是 1GBPrefill 和 Decode 之间 RTT 要控制在 100ms 内那么单链路至少需要 8Gbps。再乘上并发数就得到目标带宽。我给个公式所需带宽 单请求 KVCache 大小 × 并发传输数 / 可接受延迟举例1GB × 8 并发 / 0.1s 80Gbps。这个数字远超单口 25G说明要么做多链路聚合要么减少跨节点传输多做本地 Segment 命中。这是很多团队上线后才发现的事——不是有了 RDMA 就万事大吉。4.2 元数据服务与 Master 的高可用生产环境的 etcd 必须 ≥3 节点跨机架部署。配置上的关键是--heartbeat-interval和--election-timeout默认值在延迟较高的跨机架环境下容易误判我一般设成 250ms / 2500ms。Master 的高可用是另一回事Mooncake Master 目前不内置多活选举常见做法是Active-Standby 外部探测切换。Standby Master 只监听不服务通过 etcd 的租约判断 Active 是否存活探测间隔 2s失败 3 次触发切换。切换时客户端需要重连Python 侧可以自己写一个重试循环def get_client_with_retry(addr_list, max_retry5): for i in range(max_retry): try: s MooncakeDistributedStore() s.setup(local_hostname0.0.0.0, metadata_serveretcd://etcd1:2379,etcd2:2379,etcd3:2379, protocolrdma, device_namemlx5_0, master_server_addressaddr_list[i % len(addr_list)]) return s except Exception as e: print(fretry {i}: {e}) raise RuntimeError(mooncake master unavailable)注意Segment 的租约 TTL 要设得比 Master 切换时间长否则切换期间会出现缓存被误抢的混乱。我一般把default_kv_lease_ttl设成 8000msMaster 切换窗口控制在 3s 内。4.3 存储节点的分池与容量计算集群里每个存储节点就是一个 Segment 提供者。生产上我习惯按角色分池热池DRAM 为主8 节点每节点 128GB 给 Store温池NVMe SSD 为主4 节点每节点 2TB冷池HDD/远端对象存储用于归档可选容量规划的经验值是热池总容量 ≥ 单批次并发请求 KV Cache 总量 × 2。这个 2 是留给淘汰策略的冗余因为淘汰不是瞬时的水线到了还要时间落盘。Master 的淘汰参数也很关键--eviction_high_watermark_ratio0.9 # 超过 90% 触发淘汰 --eviction_ratio0.2 # 每次淘汰 20% --eviction_thread_num4 # 淘汰线程数淘汰线程数不要设太大会抢 Bandwidth也不要只设 1个否则水线一到就抖动。4.4 客户端接入与推理框架集成Mooncake 和 vLLM 的集成主要在 KV Connector 那一层。生产部署时我建议把客户端部署在和 Store 节点同机房、最好同机架的位置跨机架时延会显著拉低缓存收益。集成方式上如果你用的是 vLLM 的 disaggregated prefill 模式Mooncake 可以通过 KV Connector 直接接管缓存传输如果是自研推理框架就走 Python API 或 C 的Client接口。客户端参数里要注意local_buffer_size和global_segment_size的关系客户端本身也会把自己的一段内存注册成 Segment可以理解为客户端也在贡献缓存如果你不打算这么做就把global_segment_size设成 0只用local_buffer_size做收发缓冲。5. 监控、调优与故障排查实录5.1 必看的监控指标Mooncake 目前没有默认的 Prometheus Exporter但 Master 的日志和 metrics 端点能接一部分。我按经验列一下关键指标和对应的告警线指标含义告警阈值建议master_segment_count当前活跃 Segment 数量突降 20% 触发eviction_rate淘汰速率持续 100/s 需扩容te_transfer_latency_p99TE 传输 P99 延迟50ms 需查网络store_hit_ratio缓存命中率60% 说明缓存池不够用master_rpc_qpsMaster RPC 请求量接近单机极限时先扩 Master这些指标我一般通过日志解析推给 PrometheusMaster 侧开-v1就会输出结构化的 metrics 行用 Vector 或 Filebeat 抽字段很省事。5.2 常见故障速查表我把上线三个月遇到的真事整理成表基本上照着看能解决八成问题现象大概率原因排查方向客户端 setup 卡住etcd 不可达或 Master 未起etcdctl endpoint health 检查 Master 日志put成功但get报 KeyNotFoundSegment 租约提前过期检查default_kv_lease_ttl看是否小于客户端心跳间隔吞吐反而比直连 GPU 慢RDMA 未真正启用落回 TCPTE 日志里找using protocolMaster CPU 100%Segment 太多导致元数据膨胀合并 Segment、减少节点数或升级 Master 规格缓存持续淘汰热池容量不够 / 请求分布不均加 DRAM 节点检查路由策略是否按请求 hash5.3 调优心得与注意事项心得一先测缓存命中率再谈扩容。我见过一些部署一开始就堆了 20 台存储节点结果命中率 40%——原因是请求分布太随机KV Cache 复用率本来就低。这种时候加机器是浪费得回到业务侧看 prompt 结构。心得二RDMA 的 MTU 一定要对齐。交换机配 4096、主机配 1024 会导致大量分片实测延迟翻三倍。我部署时会先ibv_devinfo看 active_mtu再统一交换机和主机。心得三etcd 和 Master 别同机。这两个组件的资源画像差异很大混布时 etcd 的心跳抖动会传染给 Master出现 RPC 间歇性超时。哪怕只有三台机器也建议把 etcd 挪到一台独立的小规格机器上。心得四大版本升级前先做 Segment 快照。Mooncake 元数据在跨版本时不一定向前兼容生产升级前先停写、等淘汰结束用etcdctl snapshot save做一次全量备份。这个动作看似多余但有一次升级遇到 schema 变更就是靠快照 30 分钟回滚业务几乎无感。心得五客户端进程重启后记得手动清理旧 Segment。客户端侧注册的 Segment 如果没优雅退出Master 会留着它直到租约到期。批量重启时旧 Segment 会短暂占用容量导致新实例启动时被假满卡住。我的做法是脚本先抓一遍etcdctl get --prefix里本地 IP 相关的 key删掉再重启。最后分享一个我在生产里常用的小技巧给每个存储节点打一个zone标签写进 Master 的 Segment 元数据里客户端按就近优先的策略选 Segment。这一招在跨机架部署时尤其管用命中同机架缓存的 RTT 能从 300 微秒降到 80 微秒对长上下文推理的 TTFT 提升是实打实的。如果后续你还要做多级缓存显存 → DRAM → SSD可以在 Ext 里加一层 EV 策略让 SSD 池只承接明确标记为冷数据的对象避免把 SSD 当成 DRAM 用。
Mooncake部署实战：KVCache分离式推理与分布式缓存集群
1. 先把 Mooncake 的部署逻辑讲透再动手敲命令我头一回在生产集群里上 Mooncake是因为推理服务的首 token 延迟在高峰期抖得厉害。单机 vLLM 跑得好好的一放到几十张卡的集群里Prefill 节点算完的 KV Cache 没法高效传给 Decode 节点网络成了新瓶颈。这种场景下Mooncake 就是为以 KVCache 为中心的分离式推理架构准备的——它把 KV Cache 从 GPU 显存里抽出来做成一个跨节点、分层、可复用的分布式缓存池。简单说它要解决的是算力没吃满、显存反复搬、缓存命中率低这三件事。这套东西由几块拼图组成Transfer Engine负责底层数据传输RDMA、TCP、NVMe-oF、共享内存都能接Mooncake Store负责缓存对象的分布式管理与路由Mooncake Master是元数据大脑负责 Segment 分配和淘汰策略P2P Store则用来做模型权重和 checkpoint 的点对点分发。本文面向的是已经了解大模型推理、现在要把 Mooncake 落地的工程师——从一台开发机跑通到几十台节点组成生产集群我会把每一步的判断依据和踩过的坑都摊开说。2. 部署前必须搞明白的架构决策2.1 为什么选分离式 集中缓存而不是单机堆卡我一开始也犹豫过把模型切得更细、多卡张量并行不是更直接吗实测下来这条路在长上下文场景会撞墙。张量并行的通信量随 TP 度数上升跨机 NVLink 缺失时直接打回 PCIe 带宽而分离式架构把 Prefill 和 Decode 拆到不同节点用 Mooncake 做 KV Cache 中转Prefill 可以按算力密度配置比如 8 卡 A800Decode 按显存带宽配置两边的硬件不必一样。这样调度器可以针对缓存命中而不是请求排队做决策——这就是它所谓 KVCache-centric 的含义。代价是运维复杂度上来了你要维护 Master 的高可用、元数据服务、RDMA 网络、Segment 的容量规划。所以我的判断是单机显存够用、并发不高的小场景别上集群只有当你做到下面这些条件时才值得上单请求上下文长度常年超过 8KKV Cache 复用率有优化空间集群规模超过 16 张卡且 Prefill / Decode 负载有明确的时间差业务对 TTFT首 token 延迟和吞吐都有硬指标2.2 Transfer Engine 的传输路径选择这是部署最容易翻车的一环。Transfer Engine 抽象了多条后端路径我在不同环境里都用过传输方式适用场景单链路带宽实测参考部署复杂度RDMA (InfiniBand)大规模生产集群接近线速400Gbps 场景实测 350Gbps高需要 IB 子网管理器RoCEv2万兆/25G 以太集群视 PFC/ECN 配置调优后能到 200Gbps中高需要无损网络配置TCP单机、开发环境、小规模约 10-20Gbps低NVMe-oF冷缓存落盘、SSD 池依赖 SSD 与网卡中共享内存 (shm)单机多进程内存带宽级极低提示单机部署直接用 tcp 或 shm 就行不要折腾 RDMA否则一堆 GID、PFC、MTU 的坑能把调试时间吃掉两天。2.3 单机模式和集群模式的边界在哪我的经验是单机模式只用来验证功能与压测接口一旦要上业务就得转集群。单机模式下 Master、Store、Client 都跑在同一台机器上用 shm 或 tcp 通信整个体系本质上还是一个本地缓存池没有跨节点收益。集群模式才是 Mooncake 真正发挥的地方多个存储节点各自贡献 DRAM/SSD 作为 SegmentMaster 统一管理客户端只需一个全局地址就能读任意缓存。具体怎么切分我画了一个判断表只做功能验证、跑通 Python 示例 → 单机需要给离线批量推理提速、KV Cache 复用率高 → 单机或小集群在线服务、TTFT 敏感、节点数 4 → 集群 RDMA有冷热分层需求显存→DRAM→SSD → 集群 NVMe 池3. 单机部署从零到跑通第一个读写测试3.1 系统环境与硬件底线先说我踩过的第一个坑Mooncake 对 glibc 和编译器版本有要求太老的发行版会缺符号。我推荐组合是Ubuntu 22.04 GCC 11 CMake 3.22。如果要用 RDMA还要装libibverbs-dev、rdma-core并确保/dev/infiniband存在。硬件上单机最低配置参考CPU16 核以上编译阶段就能看出来内存≥64GB因为 Store 需要预分配大块 DRAM 做 Segment磁盘≥200GB 空闲空间SSD 优先网卡单机验证用普通网卡即可RDMA 网卡留到集群阶段注意Mooncake 的 Store 会预先mmap一大块内存如果你用容器部署务必把--shm-size调大否则启动时会 OOM。3.2 依赖安装与源码构建依赖项我按顺序列一下这样不会因为链接顺序出问题sudo apt update sudo apt install -y build-essential cmake ninja-build \ libgflags-dev libgoogle-glog-dev libgtest-dev \ libjsoncpp-dev libyaml-cpp-dev libcurl4-openssl-dev \ libssl-dev libibverbs-dev librdmacm-dev \ libnuma-dev libaio-dev拿到源码后构建我一般分两步先构建 Transfer Engine再构建 Store。原因是 Store 依赖 TE 的库如果一起 build 遇到链接错误不好定位。git clone https://github.com/kvcache-ai/Mooncake.git cd Mooncake mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease -DWITH_RDMAON -DWITH_STOREON make -j$(nproc)编译时长取决于机器16 核大约 10-15 分钟。WITH_RDMAON在没有 RDMA 网卡时也能编过只是运行期会 fallback 到 TCP。3.3 启动 Master 并跑通读写测试启动顺序很重要先起元数据服务再起 Master最后起客户端。单机验证时元数据服务我用的是 etcd因为配置简单、文档全# 1. 启动 etcd单节点即可 etcd --listen-client-urls http://0.0.0.0:2379 \ --advertise-client-urls http://0.0.0.0:2379 \ --data-dir /var/lib/etcd-mooncake # 2. 启动 Mooncake Master ./build/mooncake-store/src/mooncake_master \ --rpc_port50051 \ --eviction_high_watermark_ratio0.9 \ --default_kv_lease_ttl5000Master 起来了以后客户端这边 Python 侧接一下就通了from mooncake.store import MooncakeDistributedStore store MooncakeDistributedStore() store.setup( local_hostname127.0.0.1, metadata_serveretcd://127.0.0.1:2379, global_segment_size8 * 1024 * 1024 * 1024, # 8GB local_buffer_size512 * 1024 * 1024, # 512MB protocoltcp, device_name, ) store.put(test_key, bhello_mooncake) print(store.get(test_key))我特意留了一段日志观察put之后 Master 日志会出现ObjectAllocated记录get时如果命中的是远端 SegmentTE 层会打印TransferRequest的耗时。这套日志是排查问题的第一现场建议先用-v2打开详细日志。3.4 单机部署的三个典型坑坑一内存预分配过大导致启动慢。global_segment_size写 32G 时启动阶段 mmap 就要好几十秒而且如果物理内存不够会触发 OOM Killer。我一般按物理内存的 60% 给到 Segment。坑二local_buffer_size设太小。这个缓冲区是用于 TE 零拷贝的中转区太小会退化到多次拷贝吞吐直接砍半。512MB 起步重负载场景翻倍。坑三etcd 的 lease 泄漏。客户端异常退出后 Segment 对应的租约不一定及时清理重启客户端前先看etcdctl get --prefix mooncake/里有没有残留。这个坑在集群模式里更明显后文细讲。4. 生产环境集群部署从 3 台到 100 台4.1 网络规划RDMA 还是 RoCE以及带宽怎么算生产环境的网络方案我建议按集群规模分档3-8 节点、无无损网络条件先上 TCP带宽至少 25Gbps此时瓶颈不在网络而在 DRAM 带宽8-32 节点上 RoCEv2配置 PFC 和 ECN 做无损25G 起步32 节点以上直接上 InfiniBand HDR/NDR否则大规模下 PFC 风暴的概率会攀升带宽怎么算假设每条请求平均 KV Cache 是 1GBPrefill 和 Decode 之间 RTT 要控制在 100ms 内那么单链路至少需要 8Gbps。再乘上并发数就得到目标带宽。我给个公式所需带宽 单请求 KVCache 大小 × 并发传输数 / 可接受延迟举例1GB × 8 并发 / 0.1s 80Gbps。这个数字远超单口 25G说明要么做多链路聚合要么减少跨节点传输多做本地 Segment 命中。这是很多团队上线后才发现的事——不是有了 RDMA 就万事大吉。4.2 元数据服务与 Master 的高可用生产环境的 etcd 必须 ≥3 节点跨机架部署。配置上的关键是--heartbeat-interval和--election-timeout默认值在延迟较高的跨机架环境下容易误判我一般设成 250ms / 2500ms。Master 的高可用是另一回事Mooncake Master 目前不内置多活选举常见做法是Active-Standby 外部探测切换。Standby Master 只监听不服务通过 etcd 的租约判断 Active 是否存活探测间隔 2s失败 3 次触发切换。切换时客户端需要重连Python 侧可以自己写一个重试循环def get_client_with_retry(addr_list, max_retry5): for i in range(max_retry): try: s MooncakeDistributedStore() s.setup(local_hostname0.0.0.0, metadata_serveretcd://etcd1:2379,etcd2:2379,etcd3:2379, protocolrdma, device_namemlx5_0, master_server_addressaddr_list[i % len(addr_list)]) return s except Exception as e: print(fretry {i}: {e}) raise RuntimeError(mooncake master unavailable)注意Segment 的租约 TTL 要设得比 Master 切换时间长否则切换期间会出现缓存被误抢的混乱。我一般把default_kv_lease_ttl设成 8000msMaster 切换窗口控制在 3s 内。4.3 存储节点的分池与容量计算集群里每个存储节点就是一个 Segment 提供者。生产上我习惯按角色分池热池DRAM 为主8 节点每节点 128GB 给 Store温池NVMe SSD 为主4 节点每节点 2TB冷池HDD/远端对象存储用于归档可选容量规划的经验值是热池总容量 ≥ 单批次并发请求 KV Cache 总量 × 2。这个 2 是留给淘汰策略的冗余因为淘汰不是瞬时的水线到了还要时间落盘。Master 的淘汰参数也很关键--eviction_high_watermark_ratio0.9 # 超过 90% 触发淘汰 --eviction_ratio0.2 # 每次淘汰 20% --eviction_thread_num4 # 淘汰线程数淘汰线程数不要设太大会抢 Bandwidth也不要只设 1个否则水线一到就抖动。4.4 客户端接入与推理框架集成Mooncake 和 vLLM 的集成主要在 KV Connector 那一层。生产部署时我建议把客户端部署在和 Store 节点同机房、最好同机架的位置跨机架时延会显著拉低缓存收益。集成方式上如果你用的是 vLLM 的 disaggregated prefill 模式Mooncake 可以通过 KV Connector 直接接管缓存传输如果是自研推理框架就走 Python API 或 C 的Client接口。客户端参数里要注意local_buffer_size和global_segment_size的关系客户端本身也会把自己的一段内存注册成 Segment可以理解为客户端也在贡献缓存如果你不打算这么做就把global_segment_size设成 0只用local_buffer_size做收发缓冲。5. 监控、调优与故障排查实录5.1 必看的监控指标Mooncake 目前没有默认的 Prometheus Exporter但 Master 的日志和 metrics 端点能接一部分。我按经验列一下关键指标和对应的告警线指标含义告警阈值建议master_segment_count当前活跃 Segment 数量突降 20% 触发eviction_rate淘汰速率持续 100/s 需扩容te_transfer_latency_p99TE 传输 P99 延迟50ms 需查网络store_hit_ratio缓存命中率60% 说明缓存池不够用master_rpc_qpsMaster RPC 请求量接近单机极限时先扩 Master这些指标我一般通过日志解析推给 PrometheusMaster 侧开-v1就会输出结构化的 metrics 行用 Vector 或 Filebeat 抽字段很省事。5.2 常见故障速查表我把上线三个月遇到的真事整理成表基本上照着看能解决八成问题现象大概率原因排查方向客户端 setup 卡住etcd 不可达或 Master 未起etcdctl endpoint health 检查 Master 日志put成功但get报 KeyNotFoundSegment 租约提前过期检查default_kv_lease_ttl看是否小于客户端心跳间隔吞吐反而比直连 GPU 慢RDMA 未真正启用落回 TCPTE 日志里找using protocolMaster CPU 100%Segment 太多导致元数据膨胀合并 Segment、减少节点数或升级 Master 规格缓存持续淘汰热池容量不够 / 请求分布不均加 DRAM 节点检查路由策略是否按请求 hash5.3 调优心得与注意事项心得一先测缓存命中率再谈扩容。我见过一些部署一开始就堆了 20 台存储节点结果命中率 40%——原因是请求分布太随机KV Cache 复用率本来就低。这种时候加机器是浪费得回到业务侧看 prompt 结构。心得二RDMA 的 MTU 一定要对齐。交换机配 4096、主机配 1024 会导致大量分片实测延迟翻三倍。我部署时会先ibv_devinfo看 active_mtu再统一交换机和主机。心得三etcd 和 Master 别同机。这两个组件的资源画像差异很大混布时 etcd 的心跳抖动会传染给 Master出现 RPC 间歇性超时。哪怕只有三台机器也建议把 etcd 挪到一台独立的小规格机器上。心得四大版本升级前先做 Segment 快照。Mooncake 元数据在跨版本时不一定向前兼容生产升级前先停写、等淘汰结束用etcdctl snapshot save做一次全量备份。这个动作看似多余但有一次升级遇到 schema 变更就是靠快照 30 分钟回滚业务几乎无感。心得五客户端进程重启后记得手动清理旧 Segment。客户端侧注册的 Segment 如果没优雅退出Master 会留着它直到租约到期。批量重启时旧 Segment 会短暂占用容量导致新实例启动时被假满卡住。我的做法是脚本先抓一遍etcdctl get --prefix里本地 IP 相关的 key删掉再重启。最后分享一个我在生产里常用的小技巧给每个存储节点打一个zone标签写进 Master 的 Segment 元数据里客户端按就近优先的策略选 Segment。这一招在跨机架部署时尤其管用命中同机架缓存的 RTT 能从 300 微秒降到 80 微秒对长上下文推理的 TTFT 提升是实打实的。如果后续你还要做多级缓存显存 → DRAM → SSD可以在 Ext 里加一层 EV 策略让 SSD 池只承接明确标记为冷数据的对象避免把 SSD 当成 DRAM 用。
