Repository navigation
rfc: 可解释的改进——用 profile 证据和配对统计判定 PASS #454
Description
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"。这带来两个问题：- 端到端时间会整体漂移。 时钟、温度和共享负载会同时影响一次运行里的所有区域，单看一个数值无法区分真实改进和波动。在合成 A/A 仿真（两侧代码相同）中，3–20 次重复下现行规则判 PASS 的比例为 20–38%。
- 数值本身不说明原因。 解释不了的提升可能来自测量而不是代码；反过来，一个真实但小于波动的改进（例如 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，搜索继续"]
-
测量脚本可以额外输出 profile 字段。
breakdown：同一步骤内各区域的耗时。counters：工作量计数，例如 kernel launch 数、DRAM 字节数。
数据来源不限，nsys/ncu、torch profiler、msprof 或自定义计时都可以，仓库不绑定任何一种 profiler。
-
每轮可以声明机制。 用
--mechanism-file给出机制说明，以及可核对的预期：哪个区域或计数、朝哪个方向变化。- 声明在候选执行前保存，判定时使用执行前保存的这一份。
- attempt 目录里的副本带有摘要，副本被改动时按完整性错误阻断 campaign。
-
Harness 只做机械核对，不判断文字。
- 方向判断：每个区域和计数都按重复配对，方向只由配对 bootstrap 区间决定（区间整体低于或高于 1）。仓库内不设数值容差。基线为 0 的比值无定义，少于 5 对时不判断方向。
- 参照区域：声明为
unchanged的区域是一个假设。其他区域会另外给出"除以同一步骤参照区域"之后的比较；share_based_speedup用参照区域的占比推算整体加速。 - 归一化的边界：只有同一步骤内所有区域按同一比例变化时，归一化才能把这种变化抵消。参照区域本身只做原始比较，不会互相归一化来"证明"自己没变。
- 计数的作用：计数基本不随时钟和温度变化，可以说明一个小于波动的改进是否可重复。
-
两个开关在
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:
- 基线：
maina92c77cc。 - 相关 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； - 基准题包将来是否也支持机制声明。
Activity
amy-why-3459 commentedon Nov 15, 2026
谢谢这份 RFC，边界写得很清楚：新行为默认关闭，不改基准题包，也不和 #67 的规则混为一谈。我对照了当前 main（
cd8fcb452bd2c7969a7a6e2544aa1cb5f8ad5332）上的src/inferrsi/harness/project.py：assess()确实是两侧分别取中位数，然后在improvement > 0且达到min_improvement_pct时判 PASS，并固定写上statistical_significance="not_established"。这段实现与引用的基线a92c77ccaed68426c83154cff7619745f34d0058字节一致。几个希望在验收合同里再钉死的点：explained等状态的机械定义。 请写成可检查的判定：声明了多个区域/计数时，是全部满足才算explained，还是允许部分满足？区间必须整体位于 1 的哪一侧才算方向成立？少于 5 对、或某个计数基线为 0（比值无定义）时，是unverifiable还是别的状态？其中一部分声明被打脸、其余成立时，是contradicted还是拆开报告？verdict/eligible/ 选优路径保持不变，新字段只出现在报告里。两者同时打开时，请写明优先级：例如--require-explanation得到unverifiable，与--decision paired得到within_noise，最终verdict是哪一个。另外，--decision paired在“点估计未过门槛、但配对区间整体越过门槛”时怎么判，也请补一句。assess()只是按 side 把样本放进两个列表，并不要求两侧次数或对应关系一致。请说明重复次数不等、某一侧某次失败、或无法对齐成对时，配对路径是拒绝、降为unverifiable，还是退回现有的未配对中位数规则。tools/measurement_simulation.py的可复核输出，便于审查这个数字。a92c77ccaed68426c83154cff7619745f34d0058之后，main 已经合入了 Package shared technical contracts and retire root modules #453（cd8fcb452bd2c7969a7a6e2544aa1cb5f8ad5332）。project.py本身没有改，但实现 PR 需要先 rebase。三个 owner 决策我不会在这条评论里代为拍板；就技术看法而言，默认关闭是稳妥的，是否把真实设备上的 A/A + 已知改进对照作为合入前提，可以等仿真证据可审之后再由指定的 owner 决定。amy-why-3459 commentedon Nov 15, 2026
看到正文末尾已补上关联实现 PR #457，谢谢。链接是对的，设计与实现可以对照着看。
Dong1017 commentedon Nov 15, 2026
@BeatSeat — steward decision for @Dong1017 (authorized Dong-bot / InferRSI on-call delegate; comment posted as Dong1017).
Decision: accept RFC direction (with conditions) for optional, default-off profile-explained adoption on the ordinary project optimization path. Associated draft: #457 @
1b2b4593cb72ef7b956f82f000313a9910cffbd7.The three owner asks
--require-explanationand--decision paireddefault offcampaign start.Additional steward rulings
Conditions before ready-for-review / Approve
main(cd8fcb45/ Package shared technical contracts and retire root modules #453) and re-run focused harness tests on the new head.--decisionfirst;--require-explanationonly rewritesPASS) and the case where the paired interval clears the gate while the point estimate does not; add matching regression tests.Complementary knowledge work stays on #455 / #456 and is independent. This issue stays open until the accepted delivery is merged and goal acceptance is recorded separately.