Handleidingen

Vergelijkingsregels

Een kandidaat met een baseline vergelijken laat de workflow zien. Deze pagina is de referentie voor de regels waarmee over een vergelijking wordt beslist: welke soorten er zijn, wat elke soort vraagt, waarin een marge wordt gemeten, en wat het interval verschuift waaruit ze worden gelezen.

Drie soorten

Een vergelijkingsregel noemt een kind en een metriek. Ze neemt nooit min of max: een verschil wordt niet afgeleid uit een drempel.

Soort	Vraagt	Neemt
superiority	Is de kandidaat beter dan de baseline?	geen marge
non_inferiority	Is de kandidaat niet slechter dan de baseline met meer dan de marge?	margin, en optioneel direction
equivalence	Ligt de kandidaat binnen de marge van de baseline, in beide richtingen?	margin

Een marge is in de eigen eenheden van de metriek. Voor een percentage is 0.05 vijf procentpunten; voor een latentiekwantiel is 5 vijf milliseconden.

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

De vergelijkingsregels staan in een eigen bestand, doorgegeven met --policy, omdat release.yaml over één run beslist en een drempelregel en een vergelijkingsregel verschillend bewijs lezen.

oloproof compare CANDIDATE_RUN_ID BASELINE_RUN_ID --policy compare.yaml

Dezelfde regels tegen twee kandidaten

Tweehonderd gelabelde vragen. De baseline labelt er twintig verkeerd. Elke kandidaat hieronder werd over dezelfde suite gedraaid en met het bestand hierboven vergeleken met die baseline.

Een kandidaat die zich precies zo gedraagt als de baseline:

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)

Een kandidaat die de twintig herstelt:

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)

Lees de twee gates samen. Beide blokkeren, om tegengestelde redenen. Van de eerste kandidaat is vastgesteld dat hij equivalent is en niet dat hij beter is; van de tweede is vastgesteld dat hij beter is en daarom niet dat hij equivalent is. Een policy die alle drie de soorten voor één metriek hanteert, stelt twee onverenigbare vragen, en één daarvan blijft altijd onbeantwoord. Kies de regel die de bewering uitdrukt die je doet.

Richting

non_inferiority staat standaard op direction: min: hoger is beter, en de regel vraagt dat de kandidaat niet meer dan de marge onder de baseline zakt. direction: max is voor metrieken waarbij lager beter is, zoals latentie, tokens of kosten. De regel leest dan als een plafond op een toename, en zo drukt de terminal hem af: maximum increase 5 ms.

superiority en equivalence nemen geen richting. Equivalentie begrenst al beide kanten, en superioriteit vraagt of het verschil boven nul ligt in de eigen zin van de metriek.

Wat het interval verschuift

Een vergelijking is gepaard: het kandidaatresultaat van elke case wordt afgezet tegen zijn eigen baseline-resultaat. Twee dingen verbreden het interval dat daaruit volgt, en geen van beide is de wijziging die je aanbracht.

Cases die aan een van beide kanten ontbreken

Een case die in een van beide runs een fout gaf, ontbreekt in het paar, en wordt begrensd in plaats van weggelaten: het interval laat toe dat elke ontbrekende case beide kanten op is gegaan. Een kleinere suite, met een criterium genaamd ok: dezelfde vier onenigheden over vierendertig gepaarde cases, eerst zonder ontbrekende cases en daarna met vier extra die in beide runs een fout gaven:

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

De schatting is dezelfde, omdat die wordt berekend uit de cases die aan beide kanten zijn geobserveerd. Het interval niet, omdat vier cases die niemand zag het verschil elk met een hele case hadden kunnen verschuiven. Los de fouten op voordat je cases toevoegt: meer cases met hetzelfde foutpercentage dichten het gat niet.

Een gepaard rangschikkingsverschil, zoals ROC-AUC tussen twee modelversies, kan ontbrekende rijen niet zo begrenzen: het vergelijkt de rijen die beide kanten scoorden. Een regel daarop leest missingness_unbounded totdat ze max_missing_fraction declareert, het aandeel ontbrekende rijen dat ze accepteert als willekeurig ontbrekend.

De methode

Het standaardinterval voor een verschil in percentages is een interval voor een begrensd gemiddelde over de verschillen per case. Een policy mag in plaats daarvan de conditionele exacte methode noemen:

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

De kandidaat hierboven die tien punten beter is, leest [+4.6, +17.9] onder de standaard en dit onder de exacte methode:

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

Geen van beide is overal smaller, en daarom wordt de methode gekozen in de policy, voordat er bewijs wordt gelezen, en nooit door de engine op basis van de data. Ze geldt alleen voor verschillen in percentages.

Wanneer een regel niet kan beslissen

Een vergelijkingsregel met INSUFFICIENT_EVIDENCE kan eronder een regel dragen die zegt wat haar zou beslissen. De vergelijking van vierendertig cases zonder ontbrekende:

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)

Die schatting gaat ervan uit dat het verschil en het aandeel cases dat van mening verschilde allebei standhouden naarmate er meer cases binnenkomen. oloproof plan COMPARISON_ID drukt dezelfde regel af met de tijd die de extra cases zouden kosten.

Wanneer er paren ontbreken, wordt er geen omvang aangeboden, omdat de ontbrekende paren in het slechtste geval worden begrensd en meer cases ze niet zouden oplossen. Dezelfde vergelijking met vier ontbrekende paren drukt geen adviesregel af, en het plan zegt waarom:

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

En wanneer het verschil zelf aan de verkeerde kant van de marge ligt, zouden meer cases het alleen bevestigen, dus zegt het advies dat in plaats daarvan:

  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

Verder lezen

Een kandidaat met een baseline vergelijken behandelt de workflow en de eerste

lezing van een interval.

Geclusterde cases behandelt suites waarvan de cases niet onafhankelijk zijn,

waarover een vergelijking nog niet beslist.

Slices behandelt regels die beperkt zijn tot één deel van de suite.