docs(eval): paper-quality evaluation protocol (M1–M6)
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.
This commit is contained in:
185
docs/EVALUATION_PROTOCOL_ZH.md
Normal file
185
docs/EVALUATION_PROTOCOL_ZH.md
Normal file
@@ -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 会暴露。这是论文必须经历的过程；越早做越省事。
|
||||
Reference in New Issue
Block a user