From 591cd6d382ba6a51d8a273c684607e466e072fa7 Mon Sep 17 00:00:00 2001
From: Gahow Wang <gahow.wang@gmail.com>
Date: Tue, 12 May 2026 23:51:46 +0800
Subject: [PATCH] =?UTF-8?q?docs(eval):=20paper-quality=20evaluation=20prot?=
 =?UTF-8?q?ocol=20(M1=E2=80=93M6)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codifies the methodology fixes for every weakness called
out in AUDIT_AND_ROADMAP_ZH §3.1. Existing sweep reports
(KVCACHE_CENTRIC_PROGRESS_ZH, V2_RESULTS_ZH) violate at
least one of these; future runs must use this protocol.

Contents:
- §1.1 M1 — N≥3 + bootstrap CI; no N=1 in headline
- §1.2 M2 — paired-on-same-trial-mask; same trace /
       timeout / max_input_len / time_scale; errors
       and aborts each get their own column
- §1.3 M3 — required stratification dimensions
       (turn_id / append_len / overlap_ratio /
       inter_turn_gap / input_len)
- §1.4 M4 — minimum 2 baselines from a 6-item list,
       including at least one non-SGLang baseline
- §1.5 M5 — trace mix: Ali full + SWE-Bench +
       ShareGPT + synthetic adversarial
- §1.6 M6 — hardware tiers; single-node 4xH200 +
       dual-node NVLink/IB as minimum
- §2 report templates (main table, paired delta,
      stratified, negative-result section)
- §3 tool support: marks the two scripts that the
      follow-up commits on this branch add
- §4 SOSP/OSDI artifact requirements
- §5 pre-submission self-checklist
- §6 phased delivery plan for catching up to protocol

No code change; reading dependency for the analyzer
scripts that follow.
---
 docs/EVALUATION_PROTOCOL_ZH.md | 185 +++++++++++++++++++++++++++++++++
 1 file changed, 185 insertions(+)
 create mode 100644 docs/EVALUATION_PROTOCOL_ZH.md

diff --git a/docs/EVALUATION_PROTOCOL_ZH.md b/docs/EVALUATION_PROTOCOL_ZH.md
new file mode 100644
index 0000000..66503a6
--- /dev/null
+++ b/docs/EVALUATION_PROTOCOL_ZH.md
@@ -0,0 +1,185 @@
+# 评测协议（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 会暴露。这是论文必须经历的过程；越早做越省事。