Skip to content

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

Open

Description

@BeatSeat

Current state: 方向已接受(附条件,见 steward 决定):作为可选能力、两个开关默认关闭、#457 作为一个 PR 评审。实现在 #457,已按评审修订(见下文"评审后的修订");尚未合入,也未在 GPU/NPU 上实测。
Decision needed: 无新的 owner 决策。下文"评审后的修订"第 3、6 条按仓库对 FAIL 的定义,把"证据不足"统一记为 INCONCLUSIVE(配对区间跨过门槛、预期变化未检出),只有反证记 FAIL。
Next action: 评审 #457 新 head;通过 hosted CI 和仓库要求的独立批准后合入,再由 goal-acceptance owner 单独记录验收。

Goal and acceptance

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

    1. 端到端时间会整体漂移。 时钟、温度和共享负载会同时影响一次运行里的所有区域,单看一个数值无法区分真实改进和波动。在合成 A/A 仿真(两侧代码相同、门槛 1%)中,3–20 次重复下现行规则判 PASS 的比例为 20–38%;门槛为 0% 时约为 50%(tools/measurement_simulation.py,设定见 harness: explain gains with profile evidence and paired statistics #457)。
    2. 数值本身不说明原因。 解释不了的提升可能来自测量而不是代码;反过来,一个真实但小于波动的改进(例如 DRAM 字节数减少 12%),只看端到端时间也证明不了。

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

  • Completion criteria: 三个 owner 决策已给出(见上);harness: explain gains with profile evidence and paired statistics #457 满足 steward 条件(rebase、两开关优先级与"区间过门槛而点估计未过"的文档和回归测试、默认关闭时只报告),通过 hosted CI,获得仓库要求的独立批准后合入。

设计

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

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

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

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

    • 声明在候选执行前保存,判定时使用执行前保存的这一份。
    • attempt 目录里的副本带有摘要,副本被改动时按完整性错误阻断 campaign。
  3. Harness 只做机械核对,不判断文字。

    • 方向判断:每个区域和计数都按重复配对,方向只由配对比值中位数的精确次序统计量区间(符号检验反演)决定(区间整体低于或高于 1)。仓库内不设数值容差。基线为 0 的比值无定义。
    • 多重比较:声明 k 条预期时,所有区间使用 Bonferroni 置信度 1 − 5%/k,任一条因噪声误判的概率合计不超过 5%。所需对数:k = 1 为 6 对,k = 2–3 为 7 对,k = 4–6 为 8 对;不足时为 unverifiable。
    • "不变"的含义:区间包含 1 只说明没有检出变化,不是"没变"的证据。声明 unchanged 的项只会是"未被推翻"或"被推翻",永远不会被"确认不变"。
    • 原始与归一化方向冲突:某区域原始比较和"除以参照区域"后的比较给出明确相反的方向时(例如原始增加、相对参照却下降),记为 raw_normalized_conflict,该条核对为 unverifiable。机制声明无法表达"只预期相对变化",所以两个方向都不采信。
    • 参照区域:声明为 unchanged 的区域是一个假设。其他区域会另外给出"除以同一步骤参照区域"之后的比较;share_based_speedup 用参照区域的占比推算整体加速。
    • 归一化的边界:只有同一步骤内所有区域按同一比例变化时,归一化才能把这种变化抵消。参照区域本身只做原始比较,不会互相归一化来"证明"自己没变。
    • 计数的作用:计数基本不随时钟和温度变化,可以说明一个小于波动的改进是否可重复。
  4. 两个开关在 campaign start 时冻结,默认都关闭:

    • --require-explanation:只采纳 explained 的候选。只有 contradicted(反证)记 FAIL;unsupported、unverifiable、not_declared 是证据不足,记 INCONCLUSIVE。两类都不被采纳,也都不阻塞搜索。
    • --decision paired:用配对区间判定,至少 6 次重复。区间整体高于门槛为 PASS;整体低于门槛为 FAIL;跨过门槛为 INCONCLUSIVE(within_noise),不被采纳,也不阻塞后续轮次。只看区间,不看点估计:点估计未过门槛而区间整体高于门槛时判 PASS,两者不一致时记录 agrees_with_point_gate: false。
    • 两者同时打开时的优先级:先由 --decision 得到性能结论;--require-explanation 只作用于性能结论为 PASS 的轮次,把它降为 FAIL 或 INCONCLUSIVE,不会提升或改写非 PASS 的结论。
    • 两者都关闭时,原有的 verdict、eligible 和选优逻辑完全不变,新字段只做报告(report_only: true);--decision paired 时记录 report_only: false。

配对统计使用精确的次序统计量区间:取逐对加速比排序后的第 j 小与第 j 大,j 是使 P(Bin(n, 1/2) ≤ j−1) ≤ 2.5% 的最大秩。各对独立且来自连续分布时,下界高于真实中位数的概率不超过 2.5%,与对数无关;因此真实中位加速比恰好等于门槛时(门槛 0% 即 A/A),判 PASS 的概率不超过 2.5%。5 对时最极端的一对也有 1/32 ≈ 3.1% 的单侧误差,所以最少 6 对。

配对思路与 #67 中 owner 批准过的"配对比值"一致,但区间方法不同(精确次序统计量区间而非固定 seed bootstrap),配对单位(repetition 而非 input cluster)和比值方向(speedup 而非 candidate/baseline)也不同。因此这不构成对 #67 规则的迁移或认可。"区间跨过门槛记 INCONCLUSIVE"与仓库内 qwen38 验证器的处理一致。

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 通道或仓库级数值门槛。
  • 已知局限:
    • 区间的精确性依赖"各次重复独立、比值来自连续分布";同一对内共同的设备争用无法消除,计数等离散值出现并列时区间偏保守。
    • 参照归一化只能抵消同比例的变化。
    • 计数在缓存驻留、共享负载或数据相关分支下也可能变化。
    • 候选以调用者权限运行,Harness 的哈希检查是漂移检测,不是可信沙箱。
    • 所有统计结论都来自 CPU 合成仿真。

Ownership and authorization

  • Proposed by / actual requester: BeatSeat
  • Status: Accepted with conditions(steward 决定,2026-11-15)
  • Accountable parent (Issue-level owner, if assigned): Dong1017
  • Slice implementer(s) / acting contributor (if assigned): BeatSeat(关联 PR)
  • Goal-acceptance owner: Dong1017
  • Accepted decision or scoped delegation: steward 决定:可选能力;两个开关默认关闭;harness: explain gains with profile evidence and paired statistics #457 作为一个 PR 评审;硬件 A/A + 已知改进对照不是合入前提,作为可选后续证据。合入批准不包含在内。

Inputs and deliverables

Completion and closure

评审后的修订

  1. 两开关优先级与"区间过门槛、点估计未过"(amy-why-3459、cursor[bot]、steward 条件 2):已写入上文与 docs/optimization-workflow-unification.md,并补回归测试。
  2. 配对区间的单侧误差(linyueqian):bootstrap 的中位数下界在小样本时就是某个次序统计量,5/7/13 对时单侧误差为 3.1%/6.25%/4.6%,高于名义 2.5%。改为精确次序统计量区间,任何对数下都不超过 2.5%,最少 6 对。
  3. 区间跨过门槛的判定(linyueqian):docs/contributing.md 把 FAIL 定义为"证据表明门槛没达到",跨过门槛只说明没能证明过门槛,因此改为 INCONCLUSIVE(within_noise);区间整体低于门槛仍为 FAIL。搜索不受阻塞,这一点与原设计相同。
  4. "不变"与多重比较(linyueqian):见上文"多重比较"和"不变的含义"。
  5. report_only(linyueqian):--decision paired 时记录为 false。
  6. unsupported 记 INCONCLUSIVE(david6666666):预期变化未检出时区间仍可能包含预期的变化,这是证据不足,不是反证;与第 3 条同一原则,只有 contradicted 记 FAIL。
  7. 原始与归一化方向冲突(david6666666):见上文"原始与归一化方向冲突",并有回归测试复现他描述的情形。

#457

Activity

  1. amy-why-3459 commented on Nov 15, 2026

    @amy-why-3459
    Collaborator

    谢谢这份 RFC,边界写得很清楚:新行为默认关闭,不改基准题包,也不和 #67 的规则混为一谈。我对照了当前 main(cd8fcb452bd2c7969a7a6e2544aa1cb5f8ad5332)上的 src/inferrsi/harness/project.py:assess() 确实是两侧分别取中位数,然后在 improvement > 0 且达到 min_improvement_pct 时判 PASS,并固定写上 statistical_significance="not_established"。这段实现与引用的基线 a92c77ccaed68426c83154cff7619745f34d0058 字节一致。几个希望在验收合同里再钉死的点:

    1. 关联实现 PR。 正文还没有给出 PR 编号,我这边也还没看到对应的 Harness PR。请在开出来之后把链接补到这里,便于对照设计评审。
    2. explained 等状态的机械定义。 请写成可检查的判定:声明了多个区域/计数时,是全部满足才算 explained,还是允许部分满足?区间必须整体位于 1 的哪一侧才算方向成立?少于 5 对、或某个计数基线为 0(比值无定义)时,是 unverifiable 还是别的状态?其中一部分声明被打脸、其余成立时,是 contradicted 还是拆开报告?
    3. 两个开关的组合。 同意默认都保持关闭。两者都关闭时,希望有回归测试证明原有 verdict / eligible / 选优路径保持不变,新字段只出现在报告里。两者同时打开时,请写明优先级:例如 --require-explanation 得到 unverifiable,与 --decision paired 得到 within_noise,最终 verdict 是哪一个。另外,--decision paired 在“点估计未过门槛、但配对区间整体越过门槛”时怎么判,也请补一句。
    4. 配对单位。 现在的 assess() 只是按 side 把样本放进两个列表,并不要求两侧次数或对应关系一致。请说明重复次数不等、某一侧某次失败、或无法对齐成对时,配对路径是拒绝、降为 unverifiable,还是退回现有的未配对中位数规则。
    5. A/A 仿真证据。 “3–20 次重复下现行规则误判 PASS 的比例为 20–38%”是很关键的动机,但 issue 里还没有仿真设定(分布、门槛、seed、重复次数和脚本路径)。请在关联 PR 里附上 tools/measurement_simulation.py 的可复核输出,便于审查这个数字。
    6. 合入基线。 引用的 a92c77ccaed68426c83154cff7619745f34d0058 之后,main 已经合入了 Package shared technical contracts and retire root modules #453(cd8fcb452bd2c7969a7a6e2544aa1cb5f8ad5332)。project.py 本身没有改,但实现 PR 需要先 rebase。三个 owner 决策我不会在这条评论里代为拍板;就技术看法而言,默认关闭是稳妥的,是否把真实设备上的 A/A + 已知改进对照作为合入前提,可以等仿真证据可审之后再由指定的 owner 决定。
  2. amy-why-3459 commented on Nov 15, 2026

    @amy-why-3459
    Collaborator

    看到正文末尾已补上关联实现 PR #457,谢谢。链接是对的,设计与实现可以对照着看。

  3. Dong1017 commented on Nov 15, 2026

    @Dong1017
    Collaborator

    @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

    # Ask Decision
    1 Accept “improvement should be explainable by profile evidence” as an optional ordinary-project gate Accept as optional capability. Not a default repository rule.
    2 Keep --require-explanation and --decision paired default off Yes — both remain off unless the caller freezes them at campaign start.
    3 Review #457 as one PR vs split by commit Keep as one PR for design coherence. Address review blockers on that head (or follow-up commits on the same PR); do not require a forced split unless a later review finds an unreviewable coupling.

    Additional steward rulings

    • Goal-acceptance owner / accountable parent: Dong1017.
    • Hardware A/A + known-gain device confirmation: not a merge prerequisite while both switches default off. Track as optional follow-up evidence, not a gate for landing the opt-in machinery.
    • Merge / Approve of harness: explain gains with profile evidence and paired statistics #457: not granted by this comment. Formal PR review on the current draft is DO NOT PASS until the blockers below are fixed.

    Conditions before ready-for-review / Approve

    1. Rebase onto current main (cd8fcb45 / Package shared technical contracts and retire root modules #453) and re-run focused harness tests on the new head.
    2. Document dual-switch priority (--decision first; --require-explanation only rewrites PASS) and the case where the paired interval clears the gate while the point estimate does not; add matching regression tests.
    3. Keep defaults off; preserve report-only behavior when both switches are off.

    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.

  4. added
    area:harnessHarness module: profile, A/B loop, quality gates, evidence reports
    kind:rfcProposal / design discussion; scope review before build
    on Nov 16, 2026
  5. amy-why-3459 commented on Nov 16, 2026

    @amy-why-3459
    Collaborator

    看到正文已按 steward 决定 更新为「附条件接受」,并把 goal-acceptance owner 记为 Dong1017,与该决定一致。本条只针对描述里新增或改动的部分。

    关于「评审后的修订」第 3 条:同意把配对区间跨过门槛记为 INCONCLUSIVE(within_noise),而不是 FAIL。docs/contributing.md 把 FAIL 定义为完整证据表明门槛未达到;区间跨过门槛只说明没能证明过门槛,尚未构成「门槛没达到」的证据,区间整体低于门槛仍应是 FAIL。正文已把这种用法写清楚,也与 #457 当前 head 的实现一致。

    第 1、2、4、5 条(两开关优先级、精确次序统计量区间与最少 6 对、Bonferroni 与「不变」只作未被推翻/被推翻、report_only)在描述里已经写明,我也在 #457 新 head 上对照了实现和测试,没有新的描述层问题。硬件 A/A 作为可选后续、Dashboard 只读投影作为后续协调,都不构成新的 owner 决策。

  6. david6666666 commented on Nov 16, 2026

    @david6666666
    Collaborator

    Could --require-explanation make the same evidence distinction as the paired performance gate? When a predicted increase is unsupported because the profile interval includes 1, the interval may still contain the predicted change. That is different from contradicted. I'd keep the candidate ineligible either way, but report INCONCLUSIVE when evidence is insufficient and reserve FAIL for evidence against the prediction (or explicitly label a separate adoption-policy failure).

  7. BeatSeat commented on Nov 16, 2026

    @BeatSeat
    Author

    @david6666666 Agreed; this is the same evidence principle as the paired gate. Implemented in #457 6a3c1236: under --require-explanation, only contradicted (evidence against the prediction) is FAIL. unsupported (the predicted change is not shown, and the interval may still contain it), unverifiable and not_declared are INCONCLUSIVE with reason explanation_<status>. Either way the candidate is not adopted and the search continues. The RFC body above, docs/optimization-workflow-unification.md and the regression cases in tests/test_project_explanation.py are updated accordingly. Your raw/normalized reversal point is answered on the PR thread.

  8. amy-why-3459 commented on Nov 16, 2026

    @amy-why-3459
    Collaborator

    看到正文这次针对 david6666666 的两点做了实质更新:「评审后的修订」新增第 6、7 条,并把流程图和 --require-explanation 的判定一并改掉了。本条只针对这些新增或改动的部分。

    第 6 条把 unsupported(以及 unverifiable / not_declared)从 FAIL 改记为 INCONCLUSIVE,只把 contradicted 留作 FAIL。这与仓库对 FAIL「证据表明门槛/预期未达到」的定义、以及配对区间跨门槛记 INCONCLUSIVE 的第 3 条原则一致;候选仍不被采纳、也不阻塞搜索。第 7 条把 raw 与 normalized 明确反向记为 raw_normalized_conflict / unverifiable,同时保留「raw 无明确变化、normalized 检出变化」的归一化路径,这个区分是清楚的。我对照了 #457 当前 head 6a3c123691b0ba6937084837c62a888b9735f59b 的实现和回归测试,描述与实现一致,没有新的描述层问题。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:harnessHarness module: profile, A/B loop, quality gates, evidence reportskind:rfcProposal / design discussion; scope review before build

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions