ccf-mooncake/README.md

Mooncake KVCache 存储设计和性能优化赛题说明

一、赛题背景

随着大模型服务进入长上下文、多轮对话和高并发部署场景，推理系统面临两类核心瓶颈：一是 Prefill 阶段带来的高计算开销，二是 KVCache 在多实例、多请求之间难以复用造成的冗余存储和重复计算。特别是在长上下文和高并发场景下，KVCache 的生成、传输、存储、查询、淘汰和恢复会直接影响 TTFT、吞吐量、P99 延迟和整体服务成本。

Mooncake 是以 KVCache 为中心的大模型服务基础设施，采用 Prefill-Decode Disaggregation、KVCache 池化共享和高性能数据传输设计，将计算、存储和网络能力解耦。Mooncake 目前已开源 Transfer Engine、Mooncake Store、P2P Store 等核心组件，并与 vLLM、SGLang、LMDeploy、TensorRT-LLM、Dynamo、RTP 等推理系统形成生态协作。

本赛题希望参赛者围绕 Mooncake 的现有架构和社区演进需求，选择框架集成、Mooncake Store 演进、Transfer Engine 传输优化三个方向之一开展贡献。参赛作品应尽量以可合入社区的 Pull Request、可复现实验和清晰文档为目标，避免只停留在概念设计。

二、赛题目标

参赛者可从以下三个赛题方向中选择一个或多个方向完成贡献。每个方向均设置基础任务和挑战任务，鼓励队伍结合自身能力选择合适的切入点。

1. Mooncake 与主流推理框架的深度集成。
2. Mooncake Store 的吞吐性能、高可用、可扩展性和 SGLang HiCache 集成优化。
3. Mooncake Transfer Engine 在 NVLink、UB、UALink、CXL、RDMA、TCP、SHM 等传输路径上的性能优化和路径适配。

最终作品应满足以下总体目标：

• 能在 Mooncake 代码体系中运行，接口设计与现有架构保持一致。
• 能通过单元测试、集成测试或端到端 demo 证明功能有效。
• 能提供可复现的性能数据或功能验证结果。
• 能形成可阅读、可维护、可评审的开源贡献材料。

三、赛题一：Mooncake 与主流推理框架的深度集成

3.1 赛题描述

Mooncake 已经在 vLLM、SGLang 等推理系统中支持 PD 分离、KVCache 传输和分布式缓存能力。本方向鼓励参赛者将 Mooncake 的能力扩展到更多推理框架中，提升 Mooncake 在大模型推理生态中的通用性。

参赛者可以选择 TensorRT-LLM、Ollama、Dynamo、RTP、LMDeploy 或其他开源推理框架作为目标系统，完成 Mooncake Transfer Engine 或 Mooncake Store 的接入、优化和验证。

3.2 可选任务

基础任务：

• 为 TensorRT-LLM、Ollama 或其他推理框架实现 Mooncake Transfer Engine Connector 或 Mooncake Store Connector。
• 支持 PD 分离场景下的跨节点 KVCache 注册、传输、查询、读取和回收。
• 提供最小可运行示例，展示 Prefill 节点和 Decode 节点通过 Mooncake 交换 KVCache。
• 补充部署文档，说明依赖版本、启动参数、网络要求和常见问题。

进阶任务：

• 支持主流长上下文模型在 PD 分离架构下运行。
• 优化框架侧的 KVCache 命名、生命周期管理、异常恢复和资源释放。
• 在真实多节点环境中验证框架集成，展示 Mooncake 相比默认传输或无缓存方案的性能收益。
• 为上游框架提交可合入的 PR，并完成基本社区评审。

3.3 技术难点

• 不同推理框架对 KVCache layout、block/page 管理、请求<E8AFB7><E6B182><EFBFBD>命周期和调度模型的抽象差异较大。
• PD 分离场景需要同时处理跨进程、跨节点、跨设备的数据一致性和失败恢复。
• 性能评估需要区分计算收益、网络传输开销、缓存命中率和调度策略的影响。

3.4 交付要求

• 源码：提交到 GitLink 或 GitHub 仓库，包含 Mooncake 侧或目标框架侧的实现。
• 文档：包含架构设计、接口说明、部署步骤和兼容性说明。
• Demo：至少提供一个可复现的端到端示例。
• 测试：提供单元测试、集成测试或可执行验证脚本。
• 报告：包含 baseline、实验环境、测试负载、核心指标和结果分析。

四、赛题二：Mooncake Store 性能、高可用与 SGLang HiCache 优化

4.1 赛题描述

Mooncake Store 是 Mooncake KVCache 池化架构的核心组件，负责 KVCache 对象的元数据管理、分布式存储、副本管理、传输调度和缓存淘汰。本方向鼓励参赛者围绕 Store 的下一代能力建设，提升 Mooncake Store 在高并发、高命中率、多租户、多副本、SSD Offload 和高可用部署下的能力。

参赛者可以选择 Mooncake Store 内核能力优化，也可以选择 SGLang HiCache + Mooncake Store 的联合优化。

4.2 可选任务

基础任务：

• 优化 Mooncake Store 的 put/get/remove/batch 接口性能，降低延迟并提升吞吐。
• 改进 SGLang HiCache 与 Mooncake Store 的交互路径，提升 prefix cache 命中后的 TTFT 收益。
• 补充 Mooncake Store benchmark、压力测试或故障恢复测试。
• 完善 Store 侧指标采集，输出 master/client/worker 关键指标。

进阶任务：

• Store V3 API 演进：在接口中引入 tensor-native 元信息，例如 model name、TP rank、layer id、dtype、shape、block size 等。
• 多副本管理：支持高频 KVCache 对象的 replica list、动态副本选择、热点复制、迁移和清理。
• Client/Worker 解耦：拆分 dummy client、real client 和 worker，使部署拓扑更加灵活。
• Prefix Query：在 Store Master 中支持 radix tree 或类似结构，提升前缀查询和多轮复用效率。
• Object Grouping：支持将多个对象作为同一 group 提交，提供 group-level 可见性和淘汰语义。
• OffsetAllocator 优化：面向多 size class 的 KVCache 对象降低内存碎片率。
• 多租户隔离：提供租户级 quota、指标、限流和故障隔离能力。
• Metadata HA：支持 K8s lease-based HA、oplog store abstraction、元数据持久化和恢复。
• SSD Offload 增强：实现 L2 到 L1 数据提升、冷热识别、LRU-like 淘汰策略和 io_uring 路径优化。
• 支持迁移或缩容场景下的热数据复制，减少 rolling upgrade 或节点退出造成的缓存损失。
• 在 SGLang HiCache 场景中实现 write-through、write-back、prefetch、layer-wise overlap、GPU-assisted I/O 等路径优化。

4.3 技术难点

• KVCache 对象体积大、生命周期复杂，既要追求吞吐，也要控制尾延迟和内存碎片。
• Store Master 的元数据一致性、副本选择和故障恢复会影响整体服务可用性。
• SGLang HiCache 的 prefix cache、GPU cache、host cache 和 remote store 之间存在复杂的层级缓存协同。
• SSD Offload 需要平衡容量、带宽、延迟、淘汰策略和数据提升时机。

4.4 交付要求

• 源码：提交 Mooncake Store 或集成框架相关 PR。
• 测试：包含功能测试、压力测试和至少一种异常场景验证。
• Benchmark：至少包含 put/get 吞吐、P50/P99 延迟、缓存命中率、内存利用率等指标。
• 文档：说明设计动机、接口变化、兼容性影响和部署方式。
• 报告：对比优化前后效果，并给出未解决问题和后续计划。

五、赛题三：Mooncake Transfer Engine 异构互联与传输性能优化

5.1 赛题描述

Mooncake Transfer Engine 是 Mooncake 的高性能数据传输核心，面向 DRAM、VRAM、NVMe、远端内存和多种网络链路提供统一数据传输接口。本方向鼓励参赛者围绕下一代传输引擎能力，优化多传输路径、传输队列、QoS、tracing 和自愈能力。

参赛者可以选择 NVLink、UB、UALink、CXL、RDMA、TCP、SHM 等任一具体传输或硬件路径开展工作。

5.2 可选任务

基础任务：

• 优化现有 RDMA、TCP、SHM 或 NVLink 路径的吞吐、延迟或稳定性。
• 为 Transfer Engine 增加 microbenchmark，覆盖不同 buffer size、并发度、设备类型和传输协议。
• 提供清晰的构建文档和运行示例。

进阶任务：

• Declarative Routing：基于硬件自动发现、NUMA、GPU 拓扑、NIC 拓扑和配置策略选择传输路径。
• QoS-aware Slice Spraying：支持跨进程优先级和分片调度，减少不同任务之间的干扰。
• TCP 高并发优化：提升无 RDMA 环境下的吞吐和尾延迟表现。

5.3 技术难点

• 不同硬件平台的内存模型、DMA 能力、注册机制和同步语义差异明显。
• 多 NIC、多 GPU、多 NUMA 节点环境下，错误路径选择可能导致性能严重下降。
• 高吞吐传输与低 P99 延迟之间存在调度权衡。
• tracing 和 fault tolerance 需要尽量低开销，否则会影响传输引擎本身的性能。

5.4 交付要求

• 源码：提交 Transfer Engine transport、scheduler、queue、tracing 或硬件适配相关实现。
• Benchmark：提供 microbenchmark 和至少一个 Mooncake Store 或 PD 分离场景验证。
• 指标：包含带宽、P50/P99 延迟、CPU 占用、失败重试开销、多 NIC 聚合效果等。
• 文档：说明硬件依赖、编译选项、运行参数、拓扑要求和已知限制。

六、赛题四：Agent 与多模态推理场景下的 KVCache 分离与协同调度

6.1 赛题描述

随着 Agent 工作流（多轮推理、A2A 状态共享）和多模态大模型（Vision Encoder + LLM Prefill + Decode 三阶段流水线）的兴起，传统单一 PD 分离架构已不能满足需求。本方向鼓励参赛者将 Mooncake 的 KVCache 池化与高性能传输能力扩展到 EPD（Encoder-Prefill-Decode）三阶段分离和 Agent 状态协同场景，探索面向下一代 AI 工作负载的分布式缓存架构。

参赛者可以选择 SGLang、vLLM 或其他支持多模态推理的框架作为集成目标，围绕 Agent 状态克隆、EPD 流水线优化或 Omni 多模态管线开展工作。

6.2 可选任务

基础任务：

• 在 SGLang 或 vLLM 中实现 EPD 三阶段分离的原型：Vision Encoder 输出的 Hidden State 通过 Mooncake Transfer Engine 传输到 Prefill 节点，Prefill 产出的 KVCache 再传输到 Decode 节点。
• 实现 Agent State Cloning：当 Agent 需要 fork 出多个并行"思考"分支时，通过 Mooncake Store 实现 KVCache 状态的零拷贝克隆与跨节点共享。
• 提供基于 Qwen-VL 或类似多模态模型的端到端 demo，展示 EPD 分离相比单机部署的吞吐提升。

进阶任务：

• Omni Pipeline Worker-Level 跨阶段传输优化：在 AR → Generation → Diffusion 多阶段流水线中，利用 RDMA/SHM 实现 stage 间的低延迟数据搬运。
• Agent PD Disaggregation 调度策略：为"思考型" Agent 分配高算力 Prefill 资源，为"交互型" Agent 分配低延迟 Decode 资源，根据任务类型动态路由。
• Hidden State Prefix Caching：在多模态 omni 模型中实现 hidden state 的前缀复用，减少重复 Encoder 计算。
• 向上游框架（SGLang/vLLM）提交可合入的 PR。

6.3 技术难点

• EPD 三阶段之间的数据格式和张量布局不同，需要设计零拷贝或最小拷贝的跨阶段传输协议。
• Agent State Cloning 要求对 KVCache 的引用计数和生命周期做精细管理，避免写时冲突和内存泄漏。
• 多模态流水线各阶段计算量和延迟差异大，需要动态负载均衡以避免流水线气泡。
• Hidden State 与 KV Cache 的缓存粒度和淘汰策略不同，需要在 Store 层设计差异化的元数据管理。

6.4 交付要求

• 源码：提交 EPD 分离、Agent 状态克隆或 Omni 管线集成相关实现代码。
• 测试：提供功能验证测试和至少一个多模态模型（如 Qwen-VL）的端到端 demo。
• 指标：包含 EPD 分离前后的吞吐对比、Agent 克隆延迟、跨阶段传输带宽和 TTFT 改善数据。
• 文档：说明模型依赖、框架版本、部署拓扑、运行步骤和已知限制。

---

七、赛题五：KVCache 动态迁移与弹性自愈

7.1 赛题描述

在云原生 Spot Instance 场景和大规模集群弹性伸缩中，KVCache 状态需要在节点间无损迁移以避免请求中断；当 GPU 节点故障时，需要在秒级内恢复服务。本方向鼓励参赛者为 Mooncake 实现 KVCache 热迁移、智能弹性伸缩和快速故障恢复能力，推动 Mooncake 走向生产级高可用部署。

参赛者可以选择迁移协议设计、自动扩缩容策略或故障恢复机制中的一个或多个子方向开展工作。

7.2 可选任务

基础任务：

• 实现 KVCache Live Migration 原型：在不中断正在进行的 Decode 请求的前提下，将指定 KVCache 状态从源节点迁移至目标节点，迁移期间请求延迟增加不超过 20%。
• 实现 Store Instance 退出时的热数据迁移：当节点缩容或滚动升级时，自动将热数据搬迁至其他健康节点。
• 提供 benchmark：在 2 节点以上环境中，测量迁移带宽、迁移对在线请求 P99 延迟的影响。

进阶任务：

• LLM-Aware Autoscaler：基于全局 KVCache 压力（内存占用率）、Prefix Tree 命中率和请求队列深度，自动触发扩缩容决策，并在扩容时预热新节点的 KVCache。
• 快速 GPU 恢复：当检测到节点故障时，在 10 秒内通过从邻近节点 RDMA 拉取模型权重并利用完整 KVCache Pool 恢复服务。
• Transfer Engine 自动故障降级：RDMA 链路故障时自动回退 TCP 并重新路由，对上层完全透明。
• 提供模拟 Spot Instance 抢占场景下的端到端演示：展示从抢占通知到迁移完成到新节点接管的全流程。

7.3 技术难点

• 热迁移期间源节点仍有新写入的 KVCache 数据，需要设计增量同步或 copy-on-write 机制保证一致性。
• 迁移流量与正常推理流量共享网络带宽，需要精细的流量调度避免相互干扰。
• 自动扩缩容需要在"缓存命中率"和"资源成本"之间找到平衡，策略设计复杂。
• 秒级恢复要求极低的故障检测延迟和高效的权重分发机制，对系统端到端协同要求极高。

7.4 交付要求

• 源码：提交迁移协议、自动伸缩策略或故障恢复相关实现代码。
• 测试：提供迁移正确性验证（数据一致性校验）和故障注入测试。
• 指标：包含迁移带宽、迁移期间 P99 延迟退化比例、故障恢复时间（RTO）、扩容后缓存预热时间等。
• 文档：说明部署拓扑、故障注入方法、测试场景设计、可配置参数和已知限制。

---

八、赛题六：Mooncake PG 分布式通信与 MoE 高吞吐内核优化

8.1 赛题描述

Mooncake PG（Process Group）旨在成为面向推理场景的轻量级集合通信库，替代 NCCL 提供更灵活的容错和初始化能力；Mooncake EP（Expert Parallelism）则为 MoE 模型提供高吞吐的 All-to-All 通信内核。本方向鼓励参赛者围绕分布式通信算法、高性能 GPU kernel、容错机制和异构硬件适配开展工作，推动 Mooncake 在分布式推理通信层的能力演进。

参赛者可以选择集合通信算法实现、MoE kernel 优化、容错后端或国产硬件适配中的一个或多个子方向。

8.2 可选任务

基础任务：

• 为 Mooncake PG 实现 Ring/Tree 拓扑的 AllReduce 和 AllGather 算法，集成到 PyTorch c10d 后端，使之能在标准 torch.distributed 接口下使用。
• 为 Mooncake EP 实现针对高 batch size 场景的 MoE Dispatch/Combine 高吞吐 kernel（目标：在 8 GPU 环境下，与 DeepEP 对比吞吐不低于其 80%）。
• 建立 benchmark suite：覆盖不同 message size、不同 GPU 数量下的带宽和延迟，与 NCCL 基线对比。

进阶任务：

• Lazy Initialization 与 Split Group：实现 c10d process group 的延迟初始化，减少大规模集群启动时间（目标：1024 GPU 初始化时间 < 5s）。
• 容错后端增强：当通信组中某个 rank 失败时，支持动态重建 group 而不中断其他 rank 的通信（graceful degradation）。
• Hopper TMA Engine 优化：利用 H100 的 Tensor Memory Accelerator 实现 EP kernel 的异步数据搬运，减少 SM 占用。
• 异构硬件适配：将 Mooncake PG 适配到至少一种国产加速器平台（华为昇腾 910B 或摩尔线程），通过对应平台集合通信接口（HCCL/MCCL）完成 AllReduce 基础验证。
• Incast 流量下的 QoS 保障：在 MoE All-to-All 通信产生的 incast 流量模式下，实现优先级调度以保护延迟敏感的 Decode 流量。

8.3 技术难点

• 集合通信算法需要在不同拓扑下自适应选择最优策略，NUMA/PCIe/NVLink 层级对性能影响显著。
• MoE kernel 面临 token 分发不均匀导致的负载不平衡问题，需要处理动态路由带来的内存访问不规则性。
• 容错重建要求在不阻塞健康 rank 的前提下完成 group 拓扑变更，一致性协议设计复杂。
• 国产硬件的 RDMA 实现和内存注册机制与 NVIDIA 生态存在差异，需要深入适配底层驱动接口。
• TMA 优化需要精细控制异步拷贝与计算的 overlap，对 GPU 微架构理解要求较高。

8.4 交付要求

• 源码：提交集合通信算法、MoE kernel、容错后端或硬件适配相关实现代码。
• 测试：提供正确性验证（与 NCCL 结果对比）、容错场景测试和性能回归测试。
• 指标：包含不同规模下的带宽/延迟数据、与 NCCL/DeepEP 的对比、初始化时间、故障恢复时间等。
• 文档：说明硬件依赖、PyTorch 版本要求、编译选项、拓扑配置和已知限制。

九、统一技术要求

9.1 代码要求

• 代码应遵循 Mooncake 现有代码风格和目录组织。
• 新增公共接口应保持向后兼容；如需破坏兼容性，必须说明迁移方式。
• 新增功能应包含必要的错误处理、日志和资源释放逻辑。
• 不建议引入重量级依赖；确需引入时，应说明依赖来源、许可证和构建影响。
• 鼓励以小而清晰的 PR 形式提交，便于社区 review。

9.2 测试要求

• 基础功能必须提供可执行验证方式。
• 涉及核心模块的改动应补充单元测试或集成测试。
• 涉及性能优化的改动必须提供 baseline 和优化后结果。
• 涉及高可用、故障恢复或迁移的改动，应提供故障注入或模拟验证。

9.3 文档要求

参赛队伍应至少提交以下文档：

• README.md：作品概述、运行方式、依赖环境和结果摘要。
• DESIGN.md：设计方案、接口说明、数据流和关键权衡。
• EVALUATION.md：实验环境、测试方法、baseline、指标和结果分析。

十、评分标准

评分项	权重	说明
功能完整性	30%	是否实现所选任务目标，是否能端到端运行，是否覆盖关键异常路径。
性能与可扩展性	25%	是否相对 baseline 有明确收益，是否给出可复现实验，是否覆盖吞吐、延迟、P99、命中率、资源利用率等核心指标。
代码质量与可维护性	20%	代码结构是否清晰，是否符合 Mooncake 风格，接口是否合理，测试是否充分，是否便于合入社区。
文档与可复现性	15%	文档是否完整，环境是否可复现，实验数据是否可信，部署步骤是否清晰。
创新性与社区价值	10%	是否解决 Mooncake 生态中的关键问题，是否具有通用性，是否形成可持续维护的社区贡献。

加分项：

• PR 被 Mooncake 或相关上游社区合入。
• 在真实多节点或指定传输路径环境中完成验证。
• 对社区讨论中的关键需求给出完整实现闭环。
• 提供高质量 benchmark、文档、可视化指标或故障分析工具。
• 形成可复用 transport plugin 或 benchmark 工具。

扣分项：

• 仅有设计文档，没有运行代码或验证<EFBFBD><EFBFBD><EFBFBD>果。
• 代码无法复现，依赖环境不清晰。
• 性能数据缺少 baseline 或实验条件说明。
• 大量修改无关代码，难以 review 或合入。
• 引入许可证风险或不兼容依赖。

八、作品提交要求

参赛作品建议以 Pull Request 或可公开访问的代码仓库形式提交，包含以下内容：

1. 作品说明文档：说明选择的赛题方向、完成任务、核心贡献和使用方式。
2. 源码链接：提交 GitLink 或 GitHub 仓库地址，建议关联对应 PR。
3. 运行说明：包含环境依赖、构建命令、启动命令、测试命令。
4. 实验报告：包含实验环境、硬件配置、软件版本、baseline、指标和结果分析。
5. 演示材料：可选，包含 demo 视频、截图、日志、监控面板或 benchmark 输出。
6. 社区贡献说明：列出关联 PR、讨论链接和未完成事项。

九、参赛建议

为提高作品完成度，建议参赛队伍按以下路径推进：

1. 选择一个明确任务，不要同时展开过多模块。
2. 阅读 Mooncake 相关设计文档、讨论记录和现有 tests，确认接口边界。
3. 先完成最小可运行原型，再逐步加入性能优化和异常处理。
4. 尽早提交 draft PR，争取社区 maintainer 的方向反馈。
5. 保留完整实验记录，避免最后阶段无法复现实验结果。
6. 文档和测试与代码同步推进，降低评审理解成本。