# Prefill Scheduler Interaction Harness 设计与 Review

日期：2026-06-29

## 背景

case3 的 ablation 结果显示，`gpt-5.5 no-harness` 找到了一个 runtime/scheduler 方向：

```text
enable-chunked-prefill=true
max-num-batched-tokens 较低/中等
max-num-seqs 适中
block-size=16
```

而当时 harness 主要做两类动作：

- 单点打开 `enable-chunked-prefill`；
- 对 `max-num-batched-tokens` 做单调 raise。

这个 gap 不能用“把 8192/32 这组值加入 candidate grid”来修补。那会把 case3 的答案硬编码成更大的候选表，仍然是 rule-based overfitting。

## 设计原则

新增的设计不是一个 fixed value set，而是一个 normalized control dimension：

```text
prefill_quantum_ratio = max-num-batched-tokens / prompt_tokens_p95
admission_pressure    = max-num-seqs relative to trace.max_concurrency
scheduler_mode        = enable-chunked-prefill
```

因此，candidate generator 不直接说“试 8192”，而是说：

- 如果 long-tail prefill + TTFT/prefill bottleneck，且当前 `prefill_quantum_ratio` 太大，则沿 log-ratio 方向降低 prefill quantum；
- 如果 prefill quantum 远小于 prompt scale，可能是过度切碎导致 overhead，则沿 log-ratio 方向提高 prefill quantum；
- 如果 admission/queueing 是瓶颈，则只按 relative step 调整 admission pressure；
- 所有 concrete flag value 都是最后一步从 normalized target 映射到 engine flag，并按 engine granularity round。

当前实现使用几何中点作为 trust-region step：

```text
target_mbt = sqrt(current_mbt * prompt_tokens_p95)
```

这对应在 log space 走半步。它比固定乘以 0.5/1.5 更接近 scale-invariant：prompt scale 变大时，下一步 MBT 也会变大。

## 实现映射

代码入口：

- `src/aituner/harness.py::_runtime_candidate_actions`
  - 在 topology frontier settled 后调用新的 `_prefill_scheduler_candidate_actions`。
  - 仍保留 topology-before-runtime guard，runtime family 不抢未覆盖的 topology frontier。

新增逻辑：

- `_prefill_scheduler_workload_applies`
  - 只在非 decode-only、long-tail/moderate-tail prefill workload、非 high-prefix-reuse 场景激活。
- `_next_prefill_quantum_step`
  - 使用 `current_mbt / prompt_scale` 判断方向。
  - 通过几何中点做相对 step。
- `_next_admission_pressure_step`
  - 使用 `trace.max_concurrency` 作为 admission scale，不使用固定 `max-num-seqs` 表。
- `_prefill_scheduler_candidate_actions`
  - 输出 `prefill-scheduler-interaction` family。
  - `score_factors` 显式记录 current/target `prefill_quantum_ratio`，方便后续实验解释。
  - 当 scheduler dimension 还没有被 materialized config 覆盖时，加入
    `uncovered_scheduler_dimension_bonus`，让该 family 在 topology settled 后优先于
    `gpu-memory-utilization` 这类 resource micro-tuning。

## 为什么不是 rule-based hack

禁止的实现形态：

- 不允许引用 case3、具体 trace 名、模型名、机器名；
- 不允许出现 `if TP=2 and gmu=0.7 and mns=8 then MBT=8192`；
- 不允许把 case3 发现扩成 `{4096,8192,12288,16384} x {16,32,64}` 这种固定 grid；
- 不允许 bypass normalized full-config signature。

当前实现满足：

- trigger 来自 L-C-A profile、bottleneck classifier、topology frontier、tunable flags；
- proposal 是相对当前 incumbent 的 direction，不是固定答案；
- concrete value 随 prompt scale 和 current config 改变；
- validator/no-repeat 仍使用 normalized effective full-config signature；
- short prompt、decode-only、high prefix reuse 不激活该 family。

## Review 结论

### 之前实现的问题

1. `enable-chunked-prefill` 是 standalone toggle，无法表达 scheduler interaction。
2. TTFT/prefill bottleneck 下 MBT 主要单调 raise，无法发现“降低 prefill quantum 减少 HoL blocking”。
3. 旧测试断言了固定 `16384` 等值，容易把 harness 叙事拉回 heuristic table。

### 当前改动的效果

1. 引入 `prefill-scheduler-interaction` 作为新的 mechanistic family。
2. candidate 的 action id 表达方向：
   - `lower_prefill_quantum_with_chunked_prefill`
   - `raise_prefill_quantum_with_chunked_prefill`
   - `seed_chunked_prefill_quantum`
   - `adjust_admission_pressure_with_chunked_prefill`
3. 测试改为验证 normalized direction 和 scale sensitivity，而不是固定 absolute value。

### 2026-06-29 远端 review feedback

在 dash1 用 `36c301c` 启动 case3 bad-runtime 重跑后，trial-0003 的
candidate-set 已经出现 `prefill-scheduler-interaction`：

```text
action_id = seed_chunked_prefill_quantum
patch     = enable-chunked-prefill=true, max-num-batched-tokens=8192
ratio     = target prefill_quantum_ratio ~= 1.05
```

但初始 scoring 仍让 `raise_gpu_memory_utilization` 排在前面。这说明 family
接入是正确的，但排序仍偏向 resource micro-tuning。随后实现加入
`uncovered_scheduler_dimension_bonus`：当 topology frontier 已覆盖、prefill scheduler
dimension 还没有被 materialized config 测过时，优先测试 scheduler hypothesis，
避免重复旧 harness 先爬 GMU 的失败轨迹。

## 单元验证

新增/更新的测试覆盖：

- long-tail TTFT 下，过大的 `prefill_quantum_ratio` 会下降；
- prompt length scale 变大时，下一步 MBT target 也变大；
- topology frontier 已覆盖后，未覆盖的 scheduler dimension 排在 GMU 微调之前；
- short prompt workload 不激活 prefill scheduler family；
- 原有 prefill stop guard 仍不允许在有 high-value candidate 时停止；
- normalized full-config no-repeat 语义不变。

本地全量测试：

```text
PYTHONPATH=src python3 -m unittest discover -s tests
151 tests OK
```

## 还需要真机实验验证

下一步实验不应该只看 case3 是否复现，而要攻击这个 family 的边界：

1. case3 bad runtime start：
   - 目标：验证 LLM+harness / no-LLM harness 是否能从 bad runtime start 找到 chunked-prefill scheduler 方向。
2. scaled prompt case：
   - 目标：验证 proposal 不固定在同一个 MBT，而会随 `prompt_tokens_p95` 改变。
3. short/decode negative case：
   - 目标：验证该 family 不会在不适用 workload 上误触发。
4. topology frontier case：
   - 目标：验证 topology 未覆盖时 runtime scheduler 不抢跑。

核心指标：

- best request_rate_per_gpu；
- time-to-best / trial-to-target；
- candidate family sequence；
- `prefill_quantum_ratio_current -> target` 的方向是否与 bottleneck evidence 一致；
- 是否出现 repeated normalized full-config signature。