# 实验 EXP-ATTN-STRUCTURED：结构化 predictor 能否关闭大 KV 端的 RF 欠拟合

> **状态：** 已完成（profile gate PASS；global merge gate FAIL）
>
> Parent campaign：[`../frontier-simulator-gap-campaign-v0/README.md`](../frontier-simulator-gap-campaign-v0/README.md)

## Claim 与决策

- **Parent claim：** profile-v5 已补齐 chunked-prefill KV-context 测量，但当前 RF 仍在 TP1/2/4 的新网格上产生约 12%--14% self-fit MAPE，并在 TP1 真实 trace 中留下 −13% 到 −22% TTFT 偏差。
- **目的：** 检查该 residual 是否来自可工程修复的 predictor representation，而不是 profile 数据或 serving path。
- **Competing hypotheses：**
  - H1：standard prefill 模型错误混入 pure multi-request rows，且 RF 对连续 attention scaling 作阶梯平滑；使用单请求数据和结构化 `base(q)+KV×(a+bq)` 可关闭残余。
  - H2：残余主要来自未建模的 serving-path 组件；替换 predictor 不会改善 7-cell trace fidelity。
- **事前预测：**
  - H1：held-out context MAPE ≤5%，TP1 TTFT mean/p99 绝对偏差至少改善 5 pp。
  - H2：profile gate 失败，或 profile gate 通过但 trace TTFT 几乎不动。
- **判定规则：**
  - profile gate：TP1/2/4 held-out context MAPE 均 ≤5%；q/KV 单调且预测非负。
  - trace gate：两个 TP1 cell 的 TTFT mean/p99 |bias| 各改善 ≥5 pp；TP2/TP4 任一 TTFT/E2E quantile 不恶化 >5 pp。
  - profile gate 失败即停止；trace gate 失败则回退 patch，不进入 EXP-2。

## Setup

- **自变量：**
  - A：现有 RF，standard prefill 全部非 true-mixed rows。
  - B：现有 RF，但仅 `batch_size=1`。
  - C：仅 `batch_size=1` 的 structured predictor：
    - `base(q)`：KV=0 profile 的单调分段线性插值；
    - growth：非负 least-squares `KV×(a+bq)`。
- **控制变量：** attention/linear/MoE/collective profile、trace、prefix cache、scheduler、graph mode、KV blocks、MNS、全部 argv。
- **System context：** Qwen3-30B-A3B BF16；H20；Frontier `deadc4a3`；TP1/2/4；MNS16；chunk 8192；prefix caching。
- **Workload 或 trace：** 现有 7-cell 60-min production chat trace matrix；real 侧每 cell 两个 trial。
- **Baselines：** `docs/assets/frontier-fidelity/full-matrix.csv` 的 sim-v5。
- **Metrics：**
  - profile：grid fit MAPE、leave-one-context MAPE/max error、q/KV monotonicity；
  - trace：request-ID paired bias；每个 real trial 单独计算后报告 mean 与 trial interval；
  - queue validity：waiting p99，TP1 超过 1 s 的 cell 标为 diagnostic。

## 预期产物与 review

- **预期数据：** `results/predictor-ablation.{json,csv}`、`replay/<cell>/`、`results/paired-verdict.json`。
- **Figure prototype：** `figure-prototype.png`；左图为 q8k 随 KV 增长的 actual/RF/structured，右图为 7-cell TTFT bias 的事前期望。
- **人工 review：** 已按 campaign 顺序批准执行。
- **Review 意见：** 只改 standard single-request predictor；不得改 mixed predictor 或任何 profile row。

## 复现信息

- **Code：** Frontier base `deadc4a321f0baaa534c6ebd17f974123733cdc2`；实验 patch 将保存为 `frontier-structured-attn.patch` 并记录 SHA256。
- **Environment：** 本地 CPU replay；Python dependency roots 复用 `runs/frontier-collective-joint-v0/counterfactual/joint-r2/manifest.json`。
- **产物路径：** 本目录。
- **已知 deviation：** milestone 文档将 7-cell 口径称为“逐 request paired”，但旧脚本实际 pool 两个 real trial 后比较 quantile；本实验会修正分析口径，不改旧结果文件。

## 预分析事实

- 现有训练代码使用 `["kv_cache_size", "prefill_chunk_size_squared"]` 与 RF grid search。
- runtime cache 注释明确 standard model 是 per-request；多请求 prefill 在模型存在时走 `attn_prefill_mixed`。
- profile-v5 的 standard 训练集每 TP 有 29 行，其中单请求 23 行；有 4 组相同 `(KV,q²)` feature 对应多个 pure-batch 标签。
- 初步 structured candidate 的 leave-one-context MAPE：TP1 0.84%、TP2 1.61%、TP4 3.01%；max error 分别 2.04%、3.47%、5.49%。这些是实现前的临时计算，须由版本化脚本复现后才进入结果。

## 结果

- **观察事实：**
  - structured held-out-context MAPE 为 TP1/2/4=`0.84%/1.60%/3.01%`；
    当前 RF 为 `44.40%/44.20%/43.54%`。单调/非负 gate 通过。
  - TP1 两点 TTFT mean bias `−13.5/−17.7% → −6.3/−9.5%`，p99
    `−16.8/−22.1% → −8.6/−14.4%`。
  - TP2 两点 TTFT mean bias `−11.2/−14.1% → −4.5/−7.1%`，p99
    `−17.3/−19.4% → −7.7/−9.0%`。
  - TP4 三点 TTFT mean bias `+2.5/+2.9/−0.1% → +7.8/+8.4/+6.0%`；
    三点均使绝对误差恶化 `5.3--5.8 pp`，触发预设回归 gate。
  - validity 重新审计：TP1 两点 waiting p99=`1.34/1.89 s`；TP2
    ρ=.005=`1.17 s`，均标为 `GATE_FAIL_DIAGNOSTIC`。其余四点通过。
- **异常：** TP4 ρ=.005 的 TPOT p99 从 `+31.2%` 变为 `+36.6%`，
  表明该 tail 对 prefill/mixed-decode 相位敏感，不是本 patch 能关闭的稳定
  decode predictor 偏差。
- **含义：** H1 的 representation 机制得到支持，但“全局替换 RF 可直接提升
  7-cell fidelity”被反驳。TP4 原先接近零的 mean TTFT 含有 predictor
  欠拟合与其它正向 residual 的误差抵消；单独修正 attention 会揭开后者。
- **Claim update：** structured predictor 是明确的工程候选，但必须与 TP4
  residual 联合收敛后才可 merge；当前 patch 只保留为 ablation。
- **下一步：** EXP-2 先重算 structured 分支的 TP2 chunk-level residual；
  仅 residual ≥10% 才运行 GPU serving-path 三臂 profile。
