Add reproducible CollectiveSpec opportunity screen

docs/collectivespec-pilot-design-20260713.md

@@ -0,0 +1,157 @@
+# CollectiveSpec：先做机会判定的实验设计
+
+## 结论先行
+
+当前不应先实现一个“按请求动态 K、再做一次 DP collective 同步”的原型。该路径的
+工程修复很薄，而且相邻公开工作已经覆盖了 request-level dynamic speculation 与
+ragged verification 的大量空间。CollectiveSpec 只有在
+一个更强、可证伪的事实成立时才值得继续：**在 wide-EP MoE、DP>1 的生产负载中，
+不同 DP rank / request 所需的投机深度确实不同，并且全局 static K 明显浪费了 SLO
+可行 goodput。**
+
+本文件把第一轮实验定义为一个机会判定（opportunity gate），不是最终性能主张。
+
+## 固定条件
+
+- Host: `dash0`, 8x NVIDIA H20。
+- Model: Qwen3-235B-A22B FP8；draft: EAGLE3。
+- Deployment: TP=4, DP=2, EP=8，`VLLM_MOE_USE_DEEPEP=1`。
+- Trace: `thinking_w20260327_1000`，600 秒 decode-only 窗口。
+- SLO: TPOT <= 40 ms，pass rate >= 0.95。
+- 同一 engine revision、同一模型/trace 路径、同一环境变量；实验串行执行，避免 GPU
+  互相干扰。
+
+这里的 resolved topology 来自远端实际 StudySpec，而不是仓库 README 中可能已过期的
+配置描述。
+
+## 假设与可证伪指标
+
+### G0：static-K 是否有足够可利用的空间？
+
+- H0：在该固定拓扑和负载下，NoSpec/K=1/2/3 的 SLO-goodput 差异很小；最佳固定 K 已经
+  足够好。此时停止 CollectiveSpec。
+- H1：不同 static K 的可行前沿存在实质差异，且最优 K 对负载区间敏感。只有 H1 才
+  说明 dynamic policy 可能有直接性能价值。
+
+主要指标：每个 K 在相同 SLO 下可达到的最大 `sampling_u`，以及对应请求率、TPOT
+pass rate、p50/p95 TPOT、成功/失败原因。`sampling_u` 是现有 replay 使用的一致 trace
+抽样旋钮，因此只能作为此 trace 的 SLO-goodput proxy，不能直接外推为线上 QPS。
+
+本 trace 的 output-length 分布很重尾；replayer 的 drain deadline 可能在长输出尚未完成
+时终止 probe。故每个结果必须同时报告 completion-success count 和 deadline failure；不能
+只因 TPOT pass rate 达标就把截断 request 当作“无成本”。本轮的原始 static screen 仍沿用
+现有 SLO 以便和项目 baseline 可比，但它不能替代完整 completion 的确认实验。
+
+判定门槛（预注册）：
+
+1. 在 K=1/2/3 之间，最优 K 相对次优 K 的最大可行 `sampling_u` 小于 5%，或
+   置信区间/重复实验重叠很大：
+   **停止**。
+2. 最优 speculative K 比次优 speculative K 至少高 10%，且在两个独立重复中方向一致：
+   进入 G1。NoSpec 仅作为“是否值得用 draft model”的部署对照，不能替代这条判据。
+3. 如果 K=3 不受当前 engine 支持、任一配置启动失败，记录为兼容性结果，不把它误作
+   性能差。
+
+## 第一阶段：static-K screening
+
+配置为 `{NoSpec, K=1, K=2, K=3}`。NoSpec 会删除 `--speculative-config`，而不是传
+非法的 `num_speculative_tokens=0`。它释放 draft model 相关资源，因此不等于
+same-stack 的 logical K=0；后者在 EAGLE 类实现中仍可能需要一次 draft forward 来保持
+KV 同步。当前 dash0 binary 的 MLA indexer 明确限制 `num_speculative_tokens <= 3`，
+故这已穷尽该 binary 的合法 static horizon。原计划每个配置：
+
+- 搜索范围 `sampling_u in [0.005, 0.020]`；
+- 最多 3 次 probe、tolerance=0.003；
+- 每个 probe 使用完整 600 秒 trace replay（不会使用 `max_requests_per_probe` 的
+  截断模式）；
+- 启动顺序 `2,1,3,0`，降低冷启动或时间漂移与 K 单调对应的风险；
+- 每个 K 都使用独立 Store、不可变派生 StudySpec、完整 stdout/stderr log。
+
+这是一轮筛选而非 final frontier。它一旦显示值得继续，才对 top-2 K 做交叉顺序的完整
+搜索与至少两次重复。
+
+### 2026-07-13 数据质量修正：controlled screen
+
+原始 trace 第一个 K=2 probe 暴露了一个不应隐藏的 measurement red flag：worker 的
+drain deadline 按 selected set 的 p99 output length 计算，而该 set 含一个 36,034-token
+completion。该 request 因 deadline 被裁掉；尽管 TPOT-only pass rate 仍可达标，censoring
+会随 `sampling_u` 改变 selected set，不能用于比较 static-K frontier。
+
+因此原始 run 只保留为诊断 artifact，停止后改跑一个明确标为 **controlled** 的 screen：
+保持相同 arrival、prompt、sampling seed 和 topology，但把每个 request 的
+`min_tokens=max_tokens=4096`。4096 接近原始 output mean 3,924.6，且使 p99 deadline 覆盖
+每个 request 的完整 completion。它回答的是“在相同输入/到达条件下，static K 是否留下
+可利用空间”，不是 production trace 的最终 goodput 结论。最终论文实验必须同时有：
+
+1. 该受控 curve（机制和可重复性）；
+2. 原始长度 trace 的完整-completion 版本（不能使用 p99 censoring）；
+3. 至少一个 held-out window。
+
+### 2026-07-13 数据质量修正 #2：fresh-engine fixed grid
+
+受控 screen 的第一条 K=2、`u=0.0125` probe 本身通过了完整性检查（152/152 success、
+usage 返回的 completion token 均精确为 4096、无 early stop）。但随后发现原二分搜索会
+在同一 engine 内连续执行多个 probe；第二、三 probe 继承前一 probe 的 prefix/KV cache，
+也继承全局 RNG 的已消耗状态。不同 K 的二分分支/中止路径不同，因此不能把该搜索输出的
+`best_sampling_u` 差异直接归因于 K。该 run 在第二 probe 中主动停止，**不作为 G0 结果**。
+
+替代协议是每个 `(offered-load, K)` 只运行一次、每次均启动一个 fresh engine。两个固定
+负载由原始 immutable trace 的统一 `sampling_u` 阈值物化：`u=0.0125`（152 requests,
+0.2533 req/s）和 `u=0.0200`（263 requests, 0.4383 req/s）。物化后的 request 仍保留原
+prompt、arrival 和 sampling provenance，但强制 `temperature=0`、显式 engine `seed=0`，
+并用统一的 4096 completion override。每个 K 只有一个 probe，所以 accelerator KV/prefix
+cache 为空且 RNG 从相同 seed 开始；每次都从 `probe_details.jsonl` 验证：
+
+1. `early_stopped=false`；
+2. outcome count = selected count，且每个 request success；
+3. TTFT/TPOT 均非空；
+4. completion token 的 source 为 usage，且实际/预期均为 4096；
+5. result 无 partial-probe failure，且只包含一个 primary probe。
+
+运行顺序在两个负载间反向（ABBA），避免 K 与时间漂移完全共线。这个 grid 仍然只回答
+static-K 是否存在足够大的机会；它不估计 production sampling goodput，也不证明 rank-local
+K 的上界。当前 vLLM deployment 的 `reasoning_parser=''`；其 SSE 实现将生成文本放在
+`delta.content`，所以本协议中的 token-time 定义覆盖当前 `<think>` 输出。若以后启用
+reasoning parser，客户端必须同时记录 `reasoning_content` 后才可复用此指标。
+
+## G1：只有在 G0 通过后才做的直接验证
+
+目标不是“不同请求有不同 K”这种已经很常见的说法，而是验证下面的系统命题：
+
+> 在 DP+EP MoE 下，局部独立的 K 决策会让 collective 序列分歧；把它们编译为
+> rank-agreement 的 ragged execution plan，可保留异质请求的计算节省，同时不改变
+> collective order。
+
+当前 dash0 vLLM 已经有一个很好的切入点：每个 DP step 会 all-reduce 一段 metadata，
+并把各 rank 的 total token count padding 到最大值；CUDA graph mode 也会取跨 rank 的
+共同模式。这说明论文的最小机制不应另造一个 scheduler，而应把现有 scalar
+`(num_tokens, num_reqs, graph_mode)` agreement 扩展为 canonical speculative-plan header。
+关键增量是让 header 描述真实 active frontiers，并保证后续 verifier/EP split vector 的
+collective ordinal 相同；若最后仍 padding 到 global max，就没有可主张的性能机制。
+
+需要实现/测量：
+
+1. **oracle trace replayer**：利用 G0 的 per-K service curve，为每个到达时刻选择
+   SLO-feasible K，比较 best-static K 与 oracle 的 upper bound。若 oracle gain <10%，
+   停止，避免把噪声当论文方向。
+2. **collective trace**：按 DP rank 记录每个 decode step 的 collective 序列、token
+   shape、active-sequence mask、MoE all-to-all bytes 和 rank idle time。验证“local K
+   不同”是否真的导致 sequence divergence，而不是仅是一个 API 限制。
+3. **CollectiveSpec prototype**：固定 collective order，用全局 agreement header 和
+   ragged/padded verification plan；对比 `best static K`、global-max-K、oracle 和当前
+   upstream dynamic-spec baseline（包括 DSpark/FASER 能实现的部分）。
+4. **ablation**：去掉 agreement、去掉 ragged packing、去掉 queue/SLO policy；报告
+   goodput、p50/p95/p99 TPOT、acceptance、MoE communication bytes、GPU SM/HBM util、
+   rank skew。
+
+## 主要风险
+
+- 最新 upstream 动态投机对 DP>1 的处理可能本身只需一个 global-K broadcast；那是
+  feature patch，不构成研究贡献。
+- 当前 dash0 runtime 已验证 DP=2 + static EAGLE 可以工作；尚未在这个 binary 上证明
+  “local dynamic K 会 deadlock”。因此研究动机必须写成固定 EAGLE horizon 的执行限制，
+  不能把未运行的 dynamic-K 路径当作既成故障。
+- FASER/DSpark 等相邻工作会把“dynamic K + ragged verify”作为强 baseline；必须在
+  做任何大实现前进行逐项复现/排除。
+- trace 的 `sampling_u` 是 proxy；最终结论必须在固定 arrival trace、真实请求长度和
+  至少一个不同 workload 上复现。