指南

比較規則

將候選版本與基準版本比較示範了工作流程。本頁是比較據以做出決策的規則之參考：有哪些種類、各自提出什麼問題、差距（margin）以什麼單位量測，以及是什麼在影響判讀它們所依據的區間。

三種類型

比較規則會指定一個 kind 與一個指標。它從不接受 min 或 max：差異不是從門檻值推論出來的。

類型	提出的問題	接受的參數
superiority	候選版本是否優於基準版本？	無差距
non_inferiority	候選版本比基準版本差的程度是否不超過差距？	margin，以及可選的 direction
equivalence	候選版本是否在兩個方向上都落在基準版本的差距範圍內？	margin

差距以指標本身的單位表示。對比率而言，0.05 是五個百分點；對延遲分位數而言，5 是五毫秒。

version: 1
rules:
  - id: not-worse
    kind: non_inferiority
    metric: exact_label
    margin: 0.05
  - id: same-quality
    kind: equivalence
    metric: exact_label
    margin: 0.05
  - id: better
    kind: superiority
    metric: exact_label
  - id: not-slower
    kind: non_inferiority
    metric: latency_p50
    direction: max
    margin: 5

比較規則放在獨立的檔案中，以 --policy 傳入，因為 release.yaml 是針對單一執行做決策，而門檻規則與比較規則讀取的是不同的證據。

oloproof compare CANDIDATE_RUN_ID BASELINE_RUN_ID --policy compare.yaml

相同的規則，兩個候選版本

兩百個已標記的問題。基準版本把其中二十個標錯了。下面每個候選版本都在相同的測試套件上執行，並用上面的檔案與該基準版本比較。

一個行為與基準版本完全相同的候選版本：

Comparison sha256:7d2396c475b94028925930d4e52ae070d9a216a4558e22646169db492757c4de of run_01M3C44TVGT0X067W2H0BZ6GC9 against run_01M3C44SWMXMSQJE17SYHV87PW · 200 paired cases
exact_label: +0.0 points [-2.7, +2.7] · 200 paired · 0 missing · 0 excluded
latency_p50: -0.067 ms [-0.113, -0.001] ms · p50 of per-case differences · 200 paired · 0 missing
Decisions
  not-worse  exact_label  non-inferiority, margin 5.0 points  PASS  lower_bound_above_margin
  same-quality  exact_label  equivalence, margin ±5.0 points  PASS  interval_within_margins
  better  exact_label  superiority  INSUFFICIENT_EVIDENCE  interval_overlaps_zero
  not-slower  latency_p50  maximum increase 5 ms  PASS  lower_bound_above_margin
Gate: BLOCK (exit 3)

一個修正了那二十個錯誤的候選版本：

Comparison sha256:1e36f48662cbbc0af20217a2c69248f90b473bbf0873dc6dd222ccb1895bb33a of run_01M3C44VQ0TFFNW4FRM5Z2D12R against run_01M3C44SWMXMSQJE17SYHV87PW · 200 paired cases
exact_label: +10.0 points [+4.6, +17.9] · 200 paired · 0 missing · 0 excluded
latency_p50: -0.038 ms [-0.089, +0.009] ms · p50 of per-case differences · 200 paired · 0 missing
Decisions
  not-worse  exact_label  non-inferiority, margin 5.0 points  PASS  lower_bound_above_margin
  same-quality  exact_label  equivalence, margin ±5.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margins
  better  exact_label  superiority  PASS  difference_above_zero
  not-slower  latency_p50  maximum increase 5 ms  PASS  lower_bound_above_margin
Gate: BLOCK (exit 3)

請把兩個閘門放在一起看。兩者都被阻擋，但理由相反。第一個候選版本被確立為等價，但未被確立為更好；第二個被確立為更好，因此未被確立為等價。對同一個指標同時設下這三種類型的政策，是在問兩個互不相容的問題，其中一個永遠不會有答案。請選擇能陳述你所提出之主張的那條規則。

方向

non_inferiority 預設為 direction: min：越高越好，規則要求候選版本低於基準版本的程度不超過差距。direction: max 用於越低越好的指標，例如延遲、token 或成本。此時規則會被解讀為增加量的上限，終端機也是這樣印出的：maximum increase 5 ms。

superiority 與 equivalence 不接受方向。等價已經限制了兩側，而優越性問的是差異在指標本身的意義上是否高於零。

什麼會影響區間

比較是成對的：每個案例的候選結果都與它自己的基準結果相對照。有兩件事會讓由此得出的區間變寬，而兩者都不是你所做的變更。

任一側缺失的案例

在任一次執行中出錯的案例會從配對中缺失，而它會被納入區間界限，而不是被丟棄：區間允許每個缺失案例都可能朝任一方向發展。以一個較小的測試套件為例，其準則名為 ok：同樣是三十四個配對案例中的四個不一致，先是沒有缺失案例，然後再加上四個在兩次執行中都出錯的案例：

ok: +11.8 points [-7.2, +34.3] · 34 paired · 0 missing · 0 excluded

ok: +11.8 points [-24.8, +44.7] · 34 paired · 4 missing · 0 excluded

估計值相同，因為它是從兩側都觀察到的案例計算出來的。區間則不同，因為沒有人看到的四個案例，每一個都可能讓差異移動整整一個案例。請先修正錯誤再增加案例：在相同的錯誤率下，更多案例並不能縮小這個缺口。

成對的排序差異，例如兩個模型版本之間的 ROC-AUC，無法用這種方式限制缺失的列：它比較的是兩側都評分過的列。針對它的規則會顯示 missingness_unbounded，直到它宣告 max_missing_fraction，也就是它接受為隨機缺失的缺失列比例。

方法

比率差異的預設區間是針對每個案例差異的有界平均數區間。政策可以改為指定條件精確法：

version: 1
difference_method: conditional_exact_paired_difference@1
rules:
  - {id: not-worse, metric: exact_label, kind: non_inferiority, margin: 0.05}

上面那個好了十個百分點的候選版本，在預設方法下顯示為 [+4.6, +17.9]，在精確法下則顯示為：

exact_label: +10.0 points [+3.5, +15.8] · 200 paired · 0 missing · 0 excluded

兩者都不是一致地更窄，這就是為什麼方法是在政策中、在讀取任何證據之前選定，而絕不是由引擎根據資料選擇。它只適用於比率差異。

當規則無法做出決定時

INSUFFICIENT_EVIDENCE 的比較規則下方可能會附上一行，說明什麼可以讓它做出決定。沒有任何缺失的三十四案例比較：

Decisions
  not-worse  ok  non-inferiority, margin 5.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margin
    about 5 more paired cases would decide it, if the difference holds (39 in total at 12% discordance)
Gate: BLOCK (exit 3)

該估計假設差異與不一致案例的比例在更多案例到來時都維持不變。oloproof plan COMPARISON_ID 會印出同樣的一行，並附上額外案例所需的時間。

當有配對缺失時，不會提供任何樣本量，因為缺失的配對是以最壞情況納入界限的，更多案例也無法解決它們。同一個比較在有四個缺失配對時不會印出建議行，而計畫會說明原因：

oloproof plan COMPARISON_ID

Comparison sha256:22c1aa4fddc4e96ca77e0509ac9835c2a377ed237ca80556bbf1a54a172239bd: no sample size can be computed for a rule that did not decide.
  not-worse: 4 missing pairs are bounded at their worst, and the advice does not size under missingness; resolve them and compare again

而當差異本身落在差距錯誤的一側時，更多案例只會確認這一點，因此建議會改為這樣說：

  overall  ok  non-inferiority, margin 5.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margin
    no sample size would make this PASS: the difference itself (-5.0 points) is outside the margin, so more cases would move it toward FAIL

下一步

將候選版本與基準版本比較說明工作流程，以及初次如何判讀區間。
叢集案例說明案例之間並非獨立的測試套件，這類比較目前尚無法做出決策。
切片說明限定於測試套件某一部分的規則。