# 评测协议（Paper-quality）

**日期**：2026-05-12
**性质**：评测协议规范，覆盖 [AUDIT_AND_ROADMAP_ZH.md](AUDIT_AND_ROADMAP_ZH.md) §3.1 M1–M6 全部薄弱点
**对象**：跑实验的合作者；写 paper 的人；artifact reviewer

---

## 0. 总原则

> 论文里每一个数字都必须能回答两个问题：
> 1. **抽样误差有多大？**（bootstrap CI、N、std）
> 2. **公平吗？**（同 trial、同 trace、同 token cap、同 timeout、paired）

当前 sweep 报告（`KVCACHE_CENTRIC_PROGRESS_ZH.md` / `V2_RESULTS_ZH.md`）都不满足上述任一条。本文给出合规模板。

---

## 1. 评测维度（M1–M6 一对一解决）

### 1.1 M1 — 统计显著性

| 决策 | 规则 |
|---|---|
| `N` 每个 config 最小 run 数 | **3**（headline 数字）/ **5**（ablation 终值） |
| 报告统计量 | `mean ± std`，**附 2.5/97.5 bootstrap CI** |
| 多 run 聚合 | 把每 run 的 per-request latency append 后整体做 bootstrap；不要先 per-run 求 mean 再 average mean |
| 差异显著性 | paired bootstrap p-value（≥ 5000 samples） |
| `N=1` 仅允许 | smoke / sanity check，**不进 headline 表** |

### 1.2 M2 — 公平 paired 比较

| 决策 | 规则 |
|---|---|
| trace fixity | 用同一个 `samples-*.jsonl` 文件；replay 用 `--use-trace-as-sample` 锁定 |
| timeout | 所有 mechanism 同 `--request-timeout-s`；不允许某一组用 600s 而另一组 300s |
| token cap | 同 `--max-input-len`（取所有 baseline 的最小值并显式 truncate） |
| 错误 / abort | **不**只算成功请求；abort 与 timeout 各自单列 `error_count`，按全集（含错误）报指标，或 paired-on-same-trial-mask |
| 时间窗 | `time_scale` 一致；不允许同 sweep 内换 |
| Worker 数 / GPU 类型 | 一致；topology 差异必须标注 |

**反例**：当前 `E1 vs E2` 表（[E1_E2_RESULTS_ZH.md](E1_E2_RESULTS_ZH.md) §4）显式声明 "not a fair head-to-head"——E2 80% 失败，successful-only 算 latency 与 E1 全集对比。**这种表不能直接进 paper**。

### 1.3 M3 — Trace 分层

| 维度 | 分桶建议 |
|---|---|
| `turn_id` | `{1, 2-5, 6-20, 21+}` |
| `append_len` | `{≤128, 128-1K, 1K-8K, >8K}` |
| `overlap_ratio` | `{≤0.3, 0.3-0.7, >0.7}` |
| `inter_turn_gap_s` | `{≤5, 5-30, 30-300, >300}` |
| `input_len` | `{≤8K, 8K-64K, >64K}` |

**报告要求**：headline 数字之外，至少给一张"按 turn_id × append_len"的 heatmap，让 reviewer 看到收益来自哪个 slice。

**反例**：当前 Real Ali 实验仅在 KVC-fit slice（high overlap + small append + 100% direct-eligible）上报 -46% p50。这是上限，不是平均。必须同时给出 full Ali 上的 paired 表。

### 1.4 M4 — Baseline 矩阵

至少以下 baseline 中跑 **2 个**：

| Baseline | 类别 | 库 |
|---|---|---|
| vLLM + automatic prefix caching | 同 model 单 worker prefix cache | vLLM main |
| SGLang DP cache-aware（4×TP1） | 当前主要 baseline | 本仓 vendored SGLang |
| SGLang PD-disaggregation（kv-aware） | naive 但 cache-aware 拓扑 | 本仓 |
| DistServe | P/D 分离 baseline | DistServe upstream |
| SplitWise | P/D split + adaptive routing | open-source impl |
| Mooncake-Master scheduler | 同代设计 | mooncake-master |

**额外推荐**：跑一个 "oracle" baseline——assume `Σ.resident[d]` 完美已知 + admission 永不失败，作为 KVC 的上限对照。

### 1.5 M5 — Trace 组合

| Trace | 用途 |
|---|---|
| Ali coding agent (full) | 主结果；含 single-turn dilution |
| Ali KVC-fit slice | KVC 上限演示 |
| SWE-Bench 50 sess | 已有；多轮高 overlap workload |
| ShareGPT | 对比 chat workload（短 turn，低 overlap）。**用来证明 KVC 不会在不合适 workload 上劣化** |
| Inferact | tool-use heavy 的 agent workload |
| Mooncake trace | 单 turn LLM serving 的 baseline trace |
| Synthetic adversarial | 自构：burst 100 个新 session 同时 seed，验证 mooncake death 与 reset-on-success 的 robustness |

**最低组合**：Ali full + SWE-Bench + ShareGPT + Synthetic adversarial。

### 1.6 M6 — 硬件覆盖

| Tier | 用途 |
|---|---|
| 单节点 ≤ 8 GPU | 当前所有结果 |
| 双节点 NVLink + IB | 验证跨节点 D→P sync 与 mooncake 行为 |
| 4 节点 cluster（≥ 16 GPU） | scaling 数字、cluster scheduler 假设 |
| 异构（H100 + L40S） | topology-aware routing |

**最低组合**：单节点 4×H200 + 双节点 NVLink + IB。剩下两个 tier 可放 future work。

---

## 2. 报告模板

### 2.1 主结果表（Table 1）

```
| Config | N | mean ± std | p50 [CI] | p90 [CI] | p99 [CI] | err% | timeout% |
|--------|---|------------|----------|----------|----------|------|----------|
```

加注：trace name、time_scale、`max_input_len`、`request_timeout_s`、所有共用参数。

### 2.2 Paired delta 表

```
| Pair | N pairs | mean delta [CI] | p50 delta [CI] | wins / losses | p-value |
```

`N pairs` = 两边都 successful 的 trial 数。`wins` = `latency_kvc < latency_baseline` 的 trial 数。

### 2.3 分层表（Table 2）

每个分层维度（§1.3）独立一张。

### 2.4 Negative-result 章节（强制）

paper 必须有专章列出：

- KVC 在 ShareGPT 上比 baseline 慢的具体数字。
- KVC 在 trace 哪些 percentile / slice 不胜。
- 失败的 sweep（mooncake death、E3 crash）的诊断链路。

→ 论文 reviewer 看见诚实的 negative result 会显著提高印象分。当前的 [V2_DEEP_ANALYSIS_ZH.md](V2_DEEP_ANALYSIS_ZH.md) §4 雏形可以扩成这一章。

---

## 3. 工具支持（本仓需要的脚本）

| 脚本 | 状态 | 说明 |
|---|---|---|
| `scripts/analysis/recompute_summary.py` | ✅ 已有 | 修复 abort 污染的 latency；本协议主要数据入口 |
| `scripts/analysis/stratified.py` | ⏳ 本分支新增 | 按 §1.3 维度切桶 + 输出表 |
| `scripts/analysis/paired_compare.py` | ⏳ 本分支新增 | paired bootstrap，输出 §2.2 表 |
| `scripts/analysis/plot_*` | ✅ 已有 | TTFT PDF、GPU 利用率、cache efficiency |

→ 本分支的 stratified + paired 脚本 land 后，跑实验的合作者可以一条命令出表。

---

## 4. Artifact 要求（SOSP/OSDI AE）

| 项目 | 标准 |
|---|---|
| Dockerfile | 单一 `Dockerfile.artifact`，4×A100/H100 即可启 |
| 一键脚本 | `bash artifact/reproduce_main_table.sh`，1 小时内出 Table 1 |
| 数据集 | 提供 `outputs/sample-*.jsonl` 子集（可 ~5GB 内）；full Ali 走 instruction |
| 复现度 | bootstrap CI 与原文重叠即算复现，不要求 bit-exact |
| 文档 | `artifact/README.md`，列出每张表 / 图对应的命令 |

→ 本路线图 §M1 修复后再准备 artifact。

---

## 5. 自检清单（提 paper draft 前用）

- [ ] 每张表 N ≥ 3，含 mean±std 与 95% CI。
- [ ] 没有 "successful only" 字样；所有错误已列入 `err%`。
- [ ] 所有 baseline 用同 `max_input_len` / 同 `request_timeout_s` / 同 `time_scale`。
- [ ] 至少 3 个 trace + 1 个 synthetic adversarial。
- [ ] 至少 1 个 non-SGLang baseline。
- [ ] 有 negative-result 章节。
- [ ] 有 KVC 在 single-turn workload 上的 dilution 数据。
- [ ] 形式化部分：Algorithm 1/2/3 + Theorem 1/2，以及 D→P sync 完成后的 Theorem 4。
- [ ] 失败模式 forensic：mooncake death、E3 crash、cold-D 都进 §Limitations 或 §Discussion。

---

## 6. 路线图衔接

- [ ] Phase A — 实现本分支 `scripts/analysis/stratified.py` + `scripts/analysis/paired_compare.py`（无 GPU 可做）。
- [ ] Phase B — 把现有 `kvc-real-ali-iter-v1` 的 600-req/15min 数据用新工具重出一份分层表 / paired 表，存入 `outputs/`（GPU 不需重跑）。
- [ ] Phase C — 跑 ShareGPT + Synthetic adversarial baseline（GPU 需 ~12h）。
- [ ] Phase D — 选 1 个非 SGLang baseline（推荐 vLLM + prefix caching）补齐 M4（GPU 需 ~24h）。

---

**核心句**：当前结果"看起来已经赢"，但按本协议重报后，赢的 magnitude 会缩小、赢的 slice 会窄化、负面 slice 会暴露。这是论文必须经历的过程；越早做越省事。