agentic-pd-hybrid/docs/EVALUATION_PROTOCOL_ZH.md

评测协议（Paper-quality）

日期：2026-05-12 性质：评测协议规范，覆盖 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 §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 §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 会暴露。这是论文必须经历的过程；越早做越省事。