# 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 上复现。

## 2026-07-13 系统重审：收紧主张和后续 gate

本轮查阅 [vLLM Dynamic SD 限制](https://docs.vllm.ai/en/latest/features/speculative_decoding/dynamic_speculative_decoding/)
与 [DSpark](https://arxiv.org/abs/2607.05147) 后，原先“dynamic K 会使 collective
diverge，因此做 ragged verifier”这一表述太宽，不能作为实现前提：

- DSpark 已公开主张按请求动态 verification length、跨请求 token flatten 与 ragged
  physical execution；这些本身不再构成新颖性。
- dash0 当前实际 import 的 vLLM wheel 与本地 checkout 不同。实验中的运行日志称
  `v0.11.1`，而 wheel metadata 为 `0.13.0rc2.dev2111+gb44b43f43.d20260309`；后续任何
  hook 必须对这个 live source 做 provenance pin，不能把本地 v0.24 API 当作证据。
- 这个 live runtime 已原生使用 per-request `list[list[int]]` draft token IDs，并将真实
  长度送入 scheduler/metadata；EP all-to-all 也具有 variable-split data path。因此
  **per-request horizon 不等于 collective divergence**。必须先观测到不同 DP replica
  的 collective call count、phase 或 branch trace 的真实不一致。

修订后的唯一可能研究命题是更窄的：

> 对共享一个 EP collective domain 的独立 DP scheduler，如何将异构 verification plan
> 编译为可证明 liveness 的 canonical execution trace，同时在同一逻辑 plan 下回收
> global physical-max padding 的关键路径成本。

它有四个顺序严格的停止门槛：

1. **P0 / 真实 premise**：以预先给定的 `k_i ∈ {0,1,2,3}` replay 表截断已生成的
   EAGLE candidates，在每个 DP/TP rank 记录 target、EAGLE 和 EP phase signature。若
   没有 trace mismatch、强制 global padding 或 liveness 问题，就停止把 plan header 当作
   研究贡献。
2. **P1 / 机会量**：即使存在 mismatch，也必须证明 rank-local oracle 相对 best static
   或 globally synchronized K 有至少 10% 的 SLO-goodput headroom；全局同步若恢复 90%
   以上 gap，则只值得做 upstream patch。
3. **P2 / 因果物理对照**：同一个 `k_i` replay plan 必须对比
   `PaddedSync-semantic`（物理 `N × (1 + max k_i)` rows）与 `CompactSync`
   （物理 `Σ_i(1+k_i)` rows）。static K=3 不是 PaddedSync，因为二者 logical algorithm
   不同。若实际 target/EP work 与关键路径未减少，停止。
4. **P3 / 正确性与部署**：所有 TP peers 的 plan digest 相同、所有 EP ranks 观察到同一
   header vector、每 epoch 的 target/EAGLE/MoE signature 一致；greedy output token-exact，
   并通过 empty-rank、`{0,3}` 交替、长时间 stress。只有随后在两个 session-coherent
   workload 上重现 SLO-goodput 才能讨论论文。

若 P0--P3 任一项失败，合理结论是停止 CollectiveSpec，而不是继续调 controller、K 或
queue policy。若全部通过，最小原型的边界也只应是 verifier-side compaction：当前
EAGLE 仍按 Kmax 产生 candidate，短 `k_i` 不会自动消除 draft-side work，不能把 verifier
节省误报为完整 draft+verify speedup。

### Trace 数据可用性与 window-closure fallback

本轮发现 `prepare_trace_windows.py` 依赖的 2026-03-27 原始格式化 trace span 在 dash0
已不存在，不能把它的 streaming full-session root 当作已经复验。现有的完整 600 秒
materialized window 仍含 prompt、`chat_id` 与 `parent_chat_id`，因此新增的 fallback 仅将
窗口内图的 connected component 作为选择原子：保留 384/384 条窗口内 parent edge，且把
同一个窗口外 parent 的 sibling 归为同一 component。该窗口有 15,479 requests、15,095
components；414 条 non-root edge 中 30 条（7.25%）父节点落在窗口外。

这只能称为 **window-session-closed**，不等于 full-session coherent：任何结果都必须报告
这 30 条 boundary-parent residual，且不能据此声称跨窗口 KV reuse。若原始 span 恢复，必须
重新从完整 source resolve root 与重新采样，不能沿用 fallback 的 score/threshold。

## 2026-07-13 P0 v2：header/liveness premise 的实际结果

### 先报异常

两个 cell 都在 probe/result 已落盘、64 个请求都已完成后出现 teardown 异常。heterogeneous
cell 有 `free(): corrupted unsorted chunks` 与共享资源泄漏；control 还出现 SIGTERM/SIG11
和 TCPStore broken pipe。这些不是运行期 request/collective failure，但也意味着本实验**不
证明干净退出或部署鲁棒性**。本节只使用完成前的 request、worker phase 与 DP metadata
作为 P0 evidence；不报告任何 TPOT/QPS 比较。

### 设计、判定与修正后的观测范围

在 dash0 的 Qwen3-235B-A22B FP8 + EAGLE3、TP=4/DP=2/EP=8、DeepEP 配置上，P0 将 EAGLE
已生成的 Kmax=3 candidates 按预先给定的 request-static 表截断为 `k_i ∈ {0,1,2,3}`。它只
改变 verifier 可见 candidate，不消除 EAGLE 的 Kmax drafter 工作。

原始 worker hook 还会记录 vLLM 的 profile/DP dummy run；空 `SchedulerOutput` 仍可能有
physical rows。因此真实 target batch 的判据固定为：

```text
event == batch_execution_plan
AND request_count > 0
AND total_scheduled_rows > 0
```

最初 summary 将 676/640 条 dummy/profile record 混入 target phase，错误地把 control 的
145/146 internal-call 差异解释为 rank mismatch。修正后的汇总只比较 target event，并将
真实 DP pair 识别为 `[0,4]`、`[1,5]`、`[2,6]`、`[3,7]`；同一 logical DP replica 内的 TP
group 则为 `[0,1,2,3]` 与 `[4,5,6,7]`。

### 结果

远端可复核 artifact：
`/home/admin/cpfs/wjh/collectivespec-pilot/20260713T054328Z/p0_phase_v2_20260713T0944Z`
（run source `bb698b5`；`summary.json`、`summary.md`、`driver_result.json` 和原始
`p0_logs/*.jsonl` 均在该目录）。

| cell | completion | 实际 candidate K | target worker records | target plan / DP coordination |
|---|---:|---|---:|---|
| control K=3 | 64/64，usage 均为 64 | `{3}` | 488；DP0 每 TP peer 65，DP1 每 peer 57 | 每个 logical DP replica 内序列完全一致；四个真实 DP pair 的 57 个 shared target epoch 的 scalar coordination signature 一致 |
| heterogeneous | 64/64，usage 均为 64 | `{0,1,2,3}` | 528；8 个 peer 各 66 | 两个 logical DP replica 内序列完全一致；四个真实 DP pair 的 66/66 shared target epoch signature 一致 |

heterogeneous 的 `candidate_truncate` 直方图为 `{0: 1408, 1: 670, 2: 672, 3: 398}`，而截断前
全部为 K=3（共 3,148 个 candidate）。所以它不是只改变 log 的“伪异构”实验。两 cell 的
target record 都满足：

```text
num_tokens_per_rank[dp_rank] == total_scheduled_rows
physical_batch_rows == rows_across_dp[dp_rank]
rows_across_dp[i] >= num_tokens_per_rank[i]
len(rows_across_dp) == len(num_tokens_per_rank) == 2
```

这说明两个独立 scheduler 的 logical plan 可以不同，但 live runtime 已用 scalar DP metadata
协调共同 physical shape，并让共享 EP domain 的真实请求完成；没有观察到运行期 deadlock 或
collective error。它反驳的是“异构 verifier-side K 必须新增 canonical header 才能先保证
liveness”的必要性，而不是一般性的形式化证明。

### 留下的物理现象，以及为什么它仍不足以继续造系统

heterogeneous 的 66 个 shared target epoch 中有 62 个的 raw DP token counts 不相等；现有
runtime 将 `rows_across_dp` 同步为共同 shape。按每个 DP replica 的一个 TP anchor 计，
target-only raw logical rows 为 6,276；逐 epoch 保留当前 TP/CUDA-graph local alignment 后为
6,536；最终 physical rows 为 7,024。因此可单独归因给跨 DP global-max padding 的只有
488 rows（6.95% physical rows）。此前用 7,024-6,276 得到的 748（10.65%）还混入了 260
行本地 alignment，不能当作 compact 对照可回收的 DP work。control 的 row totals 也不与
heterogeneous 直接比较，因为 logical plan 和 scheduler trajectory 不同。

这只能看作 **P2 的 row-count upper bound**，绝不能把 control 与 heterogeneous 相减当作
速度收益：两者 logical plan、scheduler trajectory 都不同。更关键的是 EAGLE drafter 仍完成
Kmax 工作；即使理想 compact verifier 回收全部 6.95% 的 DP-only target rows，端到端
SLO-goodput 增益也只会更小。

因此决策为：

1. **停止**把 canonical plan header / deadlock avoidance 当作 CollectiveSpec 的研究主线；
   P0 已在目标部署上否定其必要前提。
2. **停止**把“dynamic verification length + flattened ragged execution”本身当贡献；DSpark
   已覆盖该组合，且它也指出固定长度 drafter 的前置工作不会因 verifier 截断自动消失。
3. 仅保留一个很窄的、默认 no-go 的机会：同一 logical plan 下的 compact-vs-padded physical
   execution。只有先以 P1 证明相对 best-static/global-sync 至少 10% E2E SLO-goodput，再以
   P2 的因果对照证明关键路径 rows/bytes 真正下降，并完成 DSpark topology gap 审计，才值得
   再投入实现。当前 P0 不满足这些条件。

P0 未验证 greedy token-exact 输出、真实 DeepEP dispatch ordinal/split digest、取消/empty-rank
stress，或其他模型/后端/更大 K 的泛化；这些都不能从本结果外推。

### P0 data sanity

- **teardown red flag 已单列**：control/heterogeneous 都在 completion 后发生 allocator/资源
  清理异常；因此没有使用延迟、吞吐或 clean-shutdown 指标作结论。
- n=2 cells，8 worker/cell，64 usage-verified completions/cell；completion count 的
  min=max=64，distinct=1。
- target worker record count：control=488、heterogeneous=528（min=488，max=528，distinct=2）；
  dummy/profile records 分别为 676/640，已排除。
- heterogeneous K：min=0，max=3，distinct=4；control K distinct=1。所有计数、rows 和
  padding 非负；JSON parse errors=0。
- heterogeneous 的 66 target epochs：两个 DP rank 的 raw row values 共 n=132，min=1、
  max=77、distinct=35；physical rows n=66，min=4、max=80、distinct=14；分解
  `6,276 <= 6,536 <= 7,024` 与 `7,024 - 6,536 = 488` 均成立。
- 修正后的不变量均为 true：probe integrity、8 workers observed、每个 DP replica 内 target
  phase/sequence 一致、target DP metadata 合法、DP coordination record 存在、四个真实 DP pair
  的 shared scalar coordination signature 一致。
