Mooncake 源码解读
快照：
main分支，commit056f67a5947bc6fb3216ff39d5758086cac0e1ba，核对日期 2026-09-24。正文中的路径、行号与行为描述均以该快照为准（GitHub 永久链接）。
Mooncake 是 Kimi（月之暗面）背后的 LLM 推理服务平台，也是一篇 FAST'25 最佳论文的系统实现。它的核心主张是：以 KVCache 为中心做分离式架构——把 Prefill 与 Decode 集群分开，再用集群里闲置的 CPU、DRAM 和 SSD 搭一个分布式 KVCache 池。
本系列沿两条端到端主线读源码：
- 数据面：一次 RDMA 传输如何在 Transfer Engine 里从
batchTransfer走到多网卡聚合与自动重试； - 缓存面：一次
Put/Get如何在 Mooncake Store 里经过 Master 元数据、副本放置、传输与分层存储。
目录
- 定位与总体架构——KVCache 中心化的分离式架构，三大组件如何分工
- 仓库地图与模块边界——17 个顶层目录各自的职责与依赖方向
- Transfer Engine：拓扑、元数据与段模型——段描述符、拓扑发现与元数据服务
- Transfer Engine：一次传输的完整路径——从批次提交到多 NIC 聚合与重试
- Store 客户端读写黄金路径——Put/Get 两阶段协议与数据面交接
- Master 服务：元数据、放置与复制——副本分配器与放置策略
- 存储后端、淘汰与生命周期——分层存储、Offload 与淘汰策略
- Python 绑定与推理引擎集成——vLLM / SGLang 如何挂上 Mooncake
- 部署形态、可观测性与 HA——从 wheel 内嵌二进制到 Master 热备
- 附录 A：推荐阅读路径
- 附录 B：核心符号速查
- 附录 C：术语表