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。两类都不被采纳,也都不阻塞搜索。开关打开时,campaign start 要求至少 6 次重复;round --mechanism-file 在执行前拒绝所需对数超过冻结重复次数的声明,不耗预算。
    • --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):见上文"原始与归一化方向冲突",并有回归测试复现他描述的情形。
  8. 重复次数下限(linyueqian):--require-explanation 在少于 6 次重复时任何预期都拿不到区间,所有候选都无法采纳;现在 start 直接拒绝,单轮声明所需对数超过冻结重复次数时在执行前拒绝。开关关闭时声明仍只做报告。

#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 的实现和回归测试,描述与实现一致,没有新的描述层问题。

  9. zengchuang-hw commented on Nov 17, 2026

    @zengchuang-hw
    Contributor

    独立代码侧检视(普通 Issue,不作方案已接受或已实现的结论)

    基线:main 1bbc3b0c8de14d6194d7ee7987607365b665fbfe。本次只依据隔离后的原始需求范围及当前代码检查,没有读取他人评审意见,也没有据此恢复修订方案的统计方法、状态映射、重复次数或开关优先级。因此以下是可实施接口与待验证风险,不是对修订正文逐项验收。

    1. AB/BA 执行顺序不等于配对统计。 project.py:64–75 已按测量序号交替执行 baseline/candidate;但 122–171 将两侧分别取中位数再算收益,明确输出 statistical_significance="not_established"。实现新增统计时必须保留 pair identity,而非仅对两列数组重新聚合。一个合成反例:baseline=[1,100,101]、candidate=[2,3,102] 时,中位数之比约 33.33,而逐对比值的中位数约 0.9902;两者不能混称同一指标。这不是要求采纳后一统计量,而是要求冻结所选估计量、方向、缺失配对处理及重复次数,并用此类分歧样本验证。当前 repetitions 允许 1,不能自动把所有旧配置宣称为有统计保证。

    2. 机制核对需要结构化输入,不应解释 hypothesis 自由文字。 optimization.py:298–339 目前仅要求非空 hypothesis,并在执行前留存 pending。可将机制声明的 schema/version、关注区域或 counter、预期方向及证据关联在这一路径执行前固化;round 事后补写或改变声明不能倒填成事前证据。breakdown 还需明确耗时单位、重叠区域是否可加总、工作量 counter 的定义及两侧归一化口径。工作量改变造成的耗时变化不能只按绝对 region time 当成机制成立;缺字段、非有限数和无法比较的计数应保留显式未知,不能补零。

    3. 把“证据解释状态”“候选可采纳性”“执行状态”分开接入。 optimization.py:238–283 仅接受 completed / candidate_failure / infrastructure_failure;后者会阻塞 campaign,选优另依赖 eligible 和 score。因此机制不吻合或机制证据不足若直接映射为 infrastructure_failure,可能意外终止后续搜索。实现前应给出完整映射表:质量拒绝、执行失败、测量完整但机制矛盾、机制缺证据分别如何影响 verdict / eligible / campaign state。默认关闭新增门控时必须保留现有选优及 verdict;启用“仅采纳可解释候选”时不得绕过原质量/性能条件,也不得以解释性成功覆盖执行失败。

    4. 冻结与独立 final 必须贯通。 optimization_session.py:155–187 在 start 显式构造 settings 并冻结,新增配置不能只增加 CLI 参数而漏传这里。final 使用留存 best,不是工作区,因此机制声明、候选身份与新增统计协议需要可追溯关联,并按冻结策略核对 final 的新测量,不能复用 round 的解释结论冒充独立复测。建议合成验收至少覆盖:默认关闭回归、开启但缺证据/矛盾、质量失败优先、配对缺失/顺序不一致、协议漂移、final 重测与 round 结果不一致、候选未入选时 best 不变;不需要引入题包或 Dashboard 改动来证明上述接口。

    实际验证:读了仓库 AGENTS、review-pr skill、贡献/隐私规则以及普通 campaign 调用链和相关测试源码;直接导入 project.steps 验证了 3 对测量的 AB/BA/AB 顺序,并运行了上面的纯合成统计对照。初次默认 Python 因缺少 pytest 未启动测试;随后改用现有含 pytest 的环境,在同一 main 源码上以 PYTHONPATH=src 补跑 tests/test_project_optimization.py 与 tests/test_optimization_session.py,48 项全部通过(退出码 0,另用 collect-only 确认数量)。这是既有控制链回归通过,不是新增机制功能的验收。未运行全套测试、lint、GPU/NPU 或真实 profiler 实验;没有修改代码。上述新增能力尚未由本次检视证明落地,合成数据也不证明真实优化收益。

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