rfc: 可解释的改进——用 profile 证据和配对统计判定 PASS #454

Current state: 提案。实现已完成并附在关联 PR 中；所有新行为默认关闭；尚未合入，也未在 GPU/NPU 上实测。
Decision needed: 请 owner 决定三件事：(1) 是否接受"改进必须能被 profile 证据解释"作为普通项目优化的可选判定；(2) 两个开关的默认值是否保持关闭；(3) 关联 PR 是作为一个整体评审，还是按其中的提交拆分。
Next action: owner 评审设计与关联 PR；接受后按评审意见修改并合入。

Goal and acceptance

• Problem / desired outcome:
  src/inferrsi/harness/project.py 的 assess() 现在分别取两侧样本的中位数，点估计过门槛就判 PASS，同时标注 statistical_significance="not_established"。这带来两个问题：

  1. 端到端时间会整体漂移。 时钟、温度和共享负载会同时影响一次运行里的所有区域，单看一个数值无法区分真实改进和波动。在合成 A/A 仿真（两侧代码相同）中，3–20 次重复下现行规则判 PASS 的比例为 20–38%。
  2. 数值本身不说明原因。 解释不了的提升可能来自测量而不是代码；反过来，一个真实但小于波动的改进（例如 DRAM 字节数减少 12%），只看端到端时间也证明不了。

  目标：让 Harness 能核对"这次改进的机制是否被 profile 数据证实"，并且在需要时只采纳能被解释的候选。

• Completion criteria: owner 对上述三个决策给出结论；关联 PR 通过 hosted CI，获得仓库要求的独立批准后合入。

设计

flowchart LR
    A["round 声明假设 + 机制<br/>（区域/计数与预期方向）"] --> B["测量脚本输出<br/>metric + breakdown + counters"]
    B --> C["Harness 机械核对<br/>配对区间 / 参照归一化 / 工作量计数"]
    C --> D{"explanation"}
    D -->|explained| E["可采纳"]
    D -->|unsupported / contradicted| F["FAIL，搜索继续"]
    D -->|unverifiable / not_declared| G["INCONCLUSIVE，搜索继续"]

1. 测量脚本可以额外输出 profile 字段。

   • breakdown：同一步骤内各区域的耗时。
   • counters：工作量计数，例如 kernel launch 数、DRAM 字节数。

   数据来源不限，nsys/ncu、torch profiler、msprof 或自定义计时都可以，仓库不绑定任何一种 profiler。

2. 每轮可以声明机制。 用 --mechanism-file 给出机制说明，以及可核对的预期：哪个区域或计数、朝哪个方向变化。

   • 声明在候选执行前保存，判定时使用执行前保存的这一份。
   • attempt 目录里的副本带有摘要，副本被改动时按完整性错误阻断 campaign。

3. Harness 只做机械核对，不判断文字。

   • 方向判断：每个区域和计数都按重复配对，方向只由配对 bootstrap 区间决定（区间整体低于或高于 1）。仓库内不设数值容差。基线为 0 的比值无定义，少于 5 对时不判断方向。
   • 参照区域：声明为 unchanged 的区域是一个假设。其他区域会另外给出"除以同一步骤参照区域"之后的比较；share_based_speedup 用参照区域的占比推算整体加速。
   • 归一化的边界：只有同一步骤内所有区域按同一比例变化时，归一化才能把这种变化抵消。参照区域本身只做原始比较，不会互相归一化来"证明"自己没变。
   • 计数的作用：计数基本不随时钟和温度变化，可以说明一个小于波动的改进是否可重复。

4. 两个开关在 campaign start 时冻结，默认都关闭：

   • --require-explanation：只采纳 explained 的候选。
   • --decision paired：用配对区间判定。区间跨过门槛时判 FAIL（within_noise），不阻塞后续轮次。
   • 两者都关闭时，原有的 verdict、eligible 和选优逻辑完全不变，新字段只做报告。

方法借鉴了 #67 中 owner 批准过的"配对比值 + 固定 seed bootstrap"思路，但有三处不同：重采样单位（repetition 而非 input cluster）、比值方向（speedup 而非 candidate/baseline）、区间尾部（双侧而非单侧上界）。因此这不构成对 #67 规则的迁移或认可。

Scope and constraints

• In scope: 普通项目路径（campaign start/round/final），具体包括 harness/measurement.py、project.py、控制器与 CLI 参数、中文文档、测试，以及合成消融脚本。
• Out of scope:
  • 修改默认判定；
  • 基准题包（benchmarks session 会拒绝 --mechanism-file）；
  • Dashboard 展示；
  • 与具体 profiler 绑定的采集脚本；
  • GPU/NPU 实测；
  • 新的 CI 通道或仓库级数值门槛。
• 已知局限：
  • 区间是名义 95%，覆盖率没有经过一般校准。合成仿真中 3 对时覆盖率约为 75%，所以少于 5 对时不报告区间。
  • 参照归一化只能抵消同比例的变化。
  • 计数在缓存驻留、共享负载或数据相关分支下也可能变化。
  • 候选以调用者权限运行，Harness 的哈希检查是漂移检测，不是可信沙箱。
  • 所有统计结论都来自 CPU 合成仿真。

Ownership and authorization

• Proposed by / actual requester: BeatSeat
• Status: Proposed
• Accountable parent (Issue-level owner, if assigned): TBD
• Slice implementer(s) / acting contributor (if assigned): BeatSeat（关联 PR）
• Goal-acceptance owner: TBD
• Accepted decision or scoped delegation: Not yet granted

Inputs and deliverables

• Relevant sources, revisions or linked issues:
  • 基线：main a92c77cc。
  • 相关 issue：task: 让 RSI 按预期收益与试验成本选择下一轮优化 #419（要求有重复的对照实验）、task: measure whether InferRSI helps Claude Code and Codex optimize inference tasks #248（Agent 收益评估）、feat: share RSI optimization management across project and benchmark tasks #338（知识库开 1.48× / 关 1.92×，每个条件只跑了一次）、[RFC] RSI 投机验证：覆盖推理引擎优化与 Agent/Skill 自我改进 #363、acceptance: Qwen3.8 FP8 vs vLLM 0.32.0 — ≥25% TTFT or TPOT gain, ≤5% regression #67、task: source audit follow-up — 34 findings, proposed remedies and acceptance checks #43、acceptance: Qwen3-TTS 0.6B C1 RTF optimization on RTX 4090 #75、discussion: what trace evidence should InferRSI persist beyond per-run artifacts? #333。
  • 另有一个独立的知识 PR（GPU 测量有效性与 profiler 归因指南），与本提案互补，两者不互相依赖。
• Expected artifacts: 关联 PR（配对统计、profile 解释与开关、两轮评审加固），以及合成消融脚本 tools/measurement_simulation.py。

Completion and closure

• Who accepts completion and may close: goal-acceptance owner。
• Remaining uncertainty / next decision:
  • 是否需要先在真实设备上做一次"A/A + 已知改进"的对照，作为合入前提或后续工作；
  • Dashboard 是否展示 explanation；
  • 基准题包将来是否也支持机制声明。

#457