KVCache Forge 面向 Mooncake Store 的控制路径优化、性能验证与决赛工程文档
赛题官方页 · Mooncake 上游 · 比赛交付仓库 · GitLink 镜像
本仓库是 KVCache Forge 的工程过程与决策记录仓库，用于持续维护 CCF 2026 开源创新大赛 Mooncake 赛题的技术目标、代码地图、优化日志、设计决策、实验记录、证据边界和决赛路线图。
本仓库不替代 Mooncake 源码仓库，也不存放未经筛选的过程产物。它回答五个工程问题：
- 我们正在解决什么问题，为什么它与赛题 2 直接相关？
- 每轮优化修改了什么，设计取舍是什么？
- 每轮修改如何验证，结果是否真的有效？
- 哪些结论已经得到证据支持，哪些仍是诊断性观察或计划？
- 新成员如何从文档快速定位代码、复现实验并继续开发？
源码与材料分离：Mooncake 正式代码改动在个人 Fork 中维护，初赛报告、PPT、补丁和演示材料位于比赛交付仓库；本仓库只维护工程知识与可审计记录。
更新日期：2026-08-06
| 维度 | 当前状态 | 证据等级 |
|---|---|---|
| 比赛阶段 | 已通过初赛，进入决赛优化阶段 | 已确认 |
| 初赛方案 | fragmentation_aware 已完成配置接入、测试、基准入口与提交材料 |
已验证 |
| 初赛策略收益 | 确定性碎片场景中首选可容纳率由 0/6 提升至 6/6，fallback 由 11 次降至 0 次 | 诊断性仿真 |
| 决赛本轮优化 | 在现有 FreeRatioFirst 中按采样覆盖比例门控未采样区间 fallback；不新增策略、配置、RPC 或连续区查询 |
本地研究提交 1c14ad8 |
| 决赛 E1/E3 | 65 项策略测试通过、2 个既有组合跳过；7/16 Segment 满载微基准尝试次数下降，64/128 保持原 fallback | 本地回归与诊断性微基准 |
| 决赛 E4 性能 | 健康及 7/16 Segment 压力各 5 轮 AB/BA；压力吞吐均值仅 +1.6848% 至 +2.8918%，未达到 +5% 门槛 | 单机 TCP Store，行为补丁已退出 |
| 决赛 E4 恢复 | holder 强制退出后 2.3479 秒完成 TTL 清理，容量恢复后 32 对象读写校验通过 | 单机进程级异常 |
| 上游状态 | 本轮源码不推送、不创建新 PR；下一阶段转向 profile 驱动的 Store batch/metadata 热路径 | 明确退出决定 |
| 生产性能结论 | 尚未完成多机 RDMA 与 SGLang HiCache 端到端压测 | 尚无结论 |
详细状态和风险见 PROJECT_STATUS.md。
最新每日进度汇报：2026-08-06：FreeRatioFirst 重试控制与 Store E4 退出验证。本轮完整保留早期候选的负结果、最终候选未达到服务级门槛的结果，以及成功的故障恢复验证，避免选择性报告。后续每天的工作均按“一天一文档”记录在 每日进度汇报索引 中。
官方 Mooncake 赛道包含推理框架接入、Mooncake Store 优化和 Transfer Engine 传输优化三个方向。KVCache Forge 当前聚焦赛题 2：
- 优化 Mooncake Store 吞吐性能、高可用功能和可扩展性；
- 优化 SGLang HiCache 与 Mooncake Store 的协同性能；
- 在不破坏默认行为和存储安全边界的前提下，提高混合尺寸 KVCache 对象长期运行时的分配稳定性。
初赛从“总空闲容量不能反映最大连续空闲区域”切入，完成了独立 fragmentation_aware 策略。上游维护者指出当前生产负载通常只有一至两种对象尺寸，宽混合尺寸碎片场景的代表性不足。决赛随后在现有 FreeRatioFirst 中验证请求内重复 allocator 调用：E3 局部机制成立，但 E4 Store 服务收益未达到预注册门槛。项目已经按退出规则停止该行为补丁，下一阶段先画像 batch/metadata 热路径，再决定新的最小优化。
flowchart LR
A["free_ratio_first\n按总空闲比例排序"] --> B["初赛 fragmentation_aware\n可容纳性 + 连续性固定评分"]
B --> C["决赛 Lazy Fit Guard\n按需查询 + 三态判定"]
C --> D["配对基准否决热路径快照\nfallback-only 研究原型"]
D --> E["维护者反馈与最小化\nFreeRatioFirst 重试控制"]
E --> F["Store E4\n性能门未达标，故障恢复通过"]
F --> G["退出行为补丁\n保留验证基础设施"]
G --> H["Profile 驱动\nBatch 与 metadata 热路径"]
初赛版本通过 largest_free_region >= request_size 识别可容纳候选，并使用连续性与空闲率的加权评分排序。决赛早期配对基准证明，即使使用请求级快照，只要精确连续区信息仍位于采样热路径，就会产生显著控制面回归。8 月 6 日从官方 main@bdacc80 建立最小 worktree，最终候选只在 sample 覆盖至少四分之一池时扫描未采样区间。真实 Store E4 表明局部调用减少不足以成为服务主导收益，因此该补丁停止上游化，验证方法和故障夹具被保留用于下一轮优化。
完整演进说明见 docs/technical-evolution.md。
每次优化必须形成以下闭环，不能只提交代码：
flowchart TD
I["问题与观测"] --> H["可证伪假设"]
H --> D["设计与 ADR"]
D --> C["最小代码改动"]
C --> T["单元与回归测试"]
T --> P["性能实验"]
P --> E["证据分级与结论"]
E --> L["每日工程日志"]
L --> N["下一轮问题"]
| 文档 | 用途 |
|---|---|
| PROJECT_STATUS.md | 当前代码、验证、风险与下一步状态总览 |
| ROADMAP.md | 决赛阶段路线图、优先级和阶段退出条件 |
| CHANGELOG.md | 项目级重要变更时间线 |
| docs/competition-scope.md | 赛题内容、评分映射与交付目标 |
| docs/architecture.md | Mooncake Store 分配路径与代码地图 |
| docs/technical-evolution.md | 从初赛策略到惰性 Fit Guard 的原理与取舍 |
| docs/evidence-policy.md | 评测指标、实验分层和性能声明规范 |
| docs/repository-governance.md | 各仓库、分支和发布边界 |
| docs/logs/README.md | 每日进度汇报索引，一天一文档记录优化与结果 |
| docs/decisions/README.md | 架构决策记录 ADR 索引 |
| docs/experiments/README.md | 实验记录、复现命令和结果索引 |
| docs/experiments/EXP-005-store-service-e4.md | Store 服务级 AB/BA、故障恢复与退出决定 |
| docs/experiments/EXP-006-store-batch-profile-baseline.md | 下一阶段 Batch/Metadata 基线矩阵与热点晋级门 |
| evidence/README.md | E1/E3/E4 精选原始证据、候选版本与文件职责索引 |
| evidence/2026-08-03-fallback-only/README.md | 8 月 3 日配对 CSV、原始日志、分析结果和校验值 |
| evidence/2026-08-06-free-ratio-retry-control/README.md | 8 月 6 日构建、测试、三压力 AB/BA 原始数据、统计分析和校验值 |
| tools/README.md | 配对基准、旧新二进制对照与统计分析工具 |
| CONTRIBUTING.md | 团队协作、提交和文档更新规范 |
| 仓库 | 角色 | 允许内容 |
|---|---|---|
| 本工程日志仓库 | 过程、决策、实验和路线图 | Markdown、轻量图表、模板 |
| GitHub 比赛交付仓库 | 评审可见的成果与材料 | 报告、PPT、补丁、日志、复现工具 |
| GitLink 比赛仓库 | 平台提交与镜像 | 与比赛交付版本一致的关键成果 |
| Lorry1024/Mooncake | 完整 Mooncake 源码开发 | C++/Python 源码、测试、基准 |
| kvcache-ai/Mooncake | 官方上游 | 上游主线、Issue 和贡献入口 |
[已验证]：有可复现命令、日志或 CI 结果支持。[诊断性]：用于说明趋势或定位问题，不等同于生产性能。[计划中]：尚未执行，不能写成已经完成。- 性能对比必须记录基线、硬件、软件版本、参数、样本量和统计方法。
- 不把确定性仿真外推为真实 RDMA、NVMe、SGLang HiCache 或生产吞吐收益。
- 失败结果同样记录，避免只保留正向数据形成选择性偏差。
KVCache Forge
罗荣裕（队长）· 刘神舟 · 王英颖 · 杨俊
本仓库文档采用 Apache License 2.0。Mooncake 项目及相关代码的来源与许可证声明见 THIRD_PARTY.md。