Een praktische gids voor AI-ontwikkelaars die de vraag "hoe weet je dat het werkt?" krijgen over een model of een LLM-functie en daar geen bewijs voor kunnen leveren. U bouwt in ongeveer 400 regels Python het bewijsmateriaal dat zo'n bewijs vervangt: een evaluatieharness met slice-metrics en een pass/fail-contract, property-based en metamorfe tests, kalibratie en conformal prediction, outputcontracten en een regressie-eval voor een LLM-stap, driftcontroles, een CI-gate en exacte formele verificatie van een klein neuraal netwerk. Elk blok hieronder is daadwerkelijk uitgevoerd, en de getoonde output is echt.
Deze technote hoort bij onze blogpost Provable correctness fails in AI: what evidence to build instead, die de zakelijke en regelgevende kant behandelt. Feiten zijn bijgewerkt tot 16 november 2026.
Voor wie dit is, wat u bouwt, vereisten
Voor wie dit is: ML- en AI-engineers, data scientists die modellen in productie brengen en platformengineers die de pipelines eromheen beheren. U kent Python en pytest; achtergrond in formele methoden is niet nodig.
Wat u bouwt: een klein project, evidence/, rond een classifier voor leningaflossing die is getraind op synthetische data met een bekende ground truth, plus een stap voor factuurextractie die een LLM vertegenwoordigt. Elk bestand levert één soort bewijs; gate.sh draait ze allemaal en laat de build falen als er één faalt.
Vereisten: Python 3.10 of hoger (wij gebruikten 3.12), ongeveer 300 MB schijfruimte voor de libraries, een willekeurige laptop-CPU. Er zijn geen GPU en geen API-sleutel nodig. We hebben getest met NumPy 2.5.5, SciPy 1.18.1, scikit-learn 1.9.1, Hypothesis 6.170.15, Pydantic 2.14.3, MAPIE 1.6.0 en pytest 9.2.0.
Stap 0: inrichten
mkdir evidence && cd evidence
python3 -m venv .venv && . .venv/bin/activate
pip install numpy scipy scikit-learn hypothesis pydantic pytest mapie
export OMP_NUM_THREADS=1 # see "Pitfalls": per-row predictions get ~100x slower without it on a busy machine
Stap 1: data met een bekende ground truth
Echte data is beter voor echte beslissingen, maar om de technieken te leren wilt u een dataset waarvan u het juiste antwoord kent. Hier hangt aflossing af van inkomen (omhoog), schuldratio (omlaag), dienstjaren (omhoog) en regio, waarbij de kleinste regio iets slechter af is. Elke test hieronder heeft daardoor een correcte uitkomst.
"""Synthetic loan data with a known ground truth, so every test has a right answer."""
import numpy as np
FEATURES = ["income_k", "debt_ratio", "years_employed", "region"]
REGIONS = ["north", "south", "east", "west"]
def make_loans(n: int, seed: int = 0, income_shift: float = 0.0):
rng = np.random.default_rng(seed)
income = rng.lognormal(mean=10.4 + income_shift, sigma=0.5, size=n) # GBP a year
debt_ratio = rng.beta(2, 5, size=n)
years = rng.integers(0, 30, size=n)
region = rng.choice(4, size=n, p=[0.4, 0.3, 0.2, 0.1])
logit = (1.5 * (np.log(income) - 10.4) - 4.0 * (debt_ratio - 0.3)
+ 0.05 * (years - 8) - 0.3 * (region == 3))
y = (rng.random(n) < 1 / (1 + np.exp(-logit))).astype(int) # 1 = repaid
X = np.column_stack([income / 1000, debt_ratio, years, region]).astype(float)
return X, y
Stap 2: het model trainen, met twee ingebouwde regels
HistGradientBoostingClassifier van scikit-learn accepteert monotonic_cst, dat de score dwingt in één richting te bewegen als een feature stijgt [1]. We trainen één model met de constraints en één zonder, zodat we kunnen zien wat de tests vangen.
"""Train the model under test. monotonic_cst encodes two business rules by construction."""
import joblib
from sklearn.ensemble import HistGradientBoostingClassifier
from data import make_loans
def train(constrained: bool = True, seed: int = 0):
X, y = make_loans(20_000, seed=seed)
clf = HistGradientBoostingClassifier(
max_iter=300, learning_rate=0.05, random_state=seed,
categorical_features=[3],
# +1: more income never lowers the score; -1: more debt never raises it
monotonic_cst=[1, -1, 0, 0] if constrained else None,
)
return clf.fit(X, y)
if __name__ == "__main__":
joblib.dump(train(constrained=True), "model.joblib")
joblib.dump(train(constrained=False), "model_unconstrained.joblib")
print("saved model.joblib and model_unconstrained.joblib")
Stap 3: een evaluatieharness met een contract
Het contract komt het dichtst bij een specificatie: drempelwaarden die vóór de training met de business zijn afgesproken. De harness rapporteert de held-out ROC AUC (hoe goed de score aflossers boven wanbetalers rangschikt), de Brier-score en de expected calibration error (ECE, het gemiddelde verschil tussen voorspelde kans en waargenomen frequentie), en daarna hetzelfde per regio met bootstrap-betrouwbaarheidsintervallen van 95%. De gate kijkt naar de ondergrens van het interval van elke slice, zodat een kleine slice niet op geluk kan slagen, en eindigt bij falen met een exitcode ongelijk aan nul, wat hem bruikbaar maakt in CI.
"""Held-out and per-slice evaluation with bootstrap confidence intervals and a pass/fail contract."""
import json
import sys
import joblib
import numpy as np
from sklearn.metrics import roc_auc_score, brier_score_loss
from data import make_loans, REGIONS
CONTRACT = { # agreed with the business before training
"auc_min": 0.70, # overall held-out ROC AUC
"slice_auc_lower_ci_min": 0.62, # worst slice, lower end of the 95% CI
"ece_max": 0.03, # expected calibration error
"min_slice_n": 300, # below this a slice is reported, not gated
}
def ece(y, p, bins=10):
"""Expected calibration error: weighted gap between confidence and frequency."""
edges = np.linspace(0, 1, bins + 1)
idx = np.clip(np.digitize(p, edges) - 1, 0, bins - 1)
return sum(abs(p[idx == b].mean() - y[idx == b].mean()) * (idx == b).mean()
for b in range(bins) if (idx == b).any())
def bootstrap_auc(y, p, n_boot=1000, seed=0):
rng = np.random.default_rng(seed)
stats = []
for _ in range(n_boot):
i = rng.integers(0, len(y), len(y))
if y[i].min() != y[i].max():
stats.append(roc_auc_score(y[i], p[i]))
return np.percentile(stats, [2.5, 97.5])
def evaluate(model_path="model.joblib", seed=1):
model = joblib.load(model_path)
X, y = make_loans(10_000, seed=seed) # held-out: a seed never used in training
p = model.predict_proba(X)[:, 1]
report = {"n": len(y), "auc": roc_auc_score(y, p),
"brier": brier_score_loss(y, p), "ece": ece(y, p), "slices": {}}
for code, name in enumerate(REGIONS):
m = X[:, 3] == code
lo, hi = bootstrap_auc(y[m], p[m])
report["slices"][name] = {"n": int(m.sum()), "auc": roc_auc_score(y[m], p[m]),
"auc_ci": [lo, hi]}
failures = []
if report["auc"] < CONTRACT["auc_min"]:
failures.append(f"auc {report['auc']:.3f} < {CONTRACT['auc_min']}")
if report["ece"] > CONTRACT["ece_max"]:
failures.append(f"ece {report['ece']:.3f} > {CONTRACT['ece_max']}")
for name, s in report["slices"].items():
if s["n"] >= CONTRACT["min_slice_n"] and s["auc_ci"][0] < CONTRACT["slice_auc_lower_ci_min"]:
failures.append(f"slice {name}: AUC lower CI {s['auc_ci'][0]:.3f}")
report["failures"] = failures
return report
if __name__ == "__main__":
r = evaluate(*sys.argv[1:2])
print(f"held-out n={r['n']} AUC={r['auc']:.3f} Brier={r['brier']:.3f} ECE={r['ece']:.3f}")
for name, s in r["slices"].items():
print(f" {name:<6} n={s['n']:>5} AUC={s['auc']:.3f} 95% CI [{s['auc_ci'][0]:.3f}, {s['auc_ci'][1]:.3f}]")
json.dump(r, open("eval_report.json", "w"), indent=2, default=float)
print("PASS" if not r["failures"] else "FAIL: " + "; ".join(r["failures"]))
sys.exit(1 if r["failures"] else 0)
$ python eval_harness.py
held-out n=10000 AUC=0.747 Brier=0.200 ECE=0.014
north n= 3989 AUC=0.749 95% CI [0.735, 0.764]
south n= 2920 AUC=0.759 95% CI [0.740, 0.778]
east n= 2065 AUC=0.735 95% CI [0.714, 0.756]
west n= 1026 AUC=0.723 95% CI [0.694, 0.753]
PASS
$ python eval_harness.py model_unconstrained.joblib
held-out n=10000 AUC=0.747 Brier=0.200 ECE=0.012
...
PASS
Let op de breedtes: de slice west, met 1.026 gevallen, heeft een interval dat bijna twee keer zo breed is als dat van north. Beide modellen slagen. Op deze cijfers alleen zou u niet tussen ze kunnen kiezen, en dat is underspecification in het klein: één pipeline, veel modellen met dezelfde held-out score [2].
Stap 4: property-based en metamorfe tests
Een property-based test formuleert een regel en laat een library de inputs genereren. Hypothesis genereert honderden gevallen, en als er één faalt, verkleint het dat tot het eenvoudigste falende voorbeeld [3]. Een metamorfe test is een eigenschap die twee runs met elkaar verbindt: u weet niet wat de juiste score voor een aanvrager is, maar u weet wel dat extra inkomen die niet mag verlagen. Dit idee komt uit het testen van software, waar het werd ontwikkeld voor programma's zonder betrouwbaar test-orakel [4]; CheckList paste hetzelfde idee toe op NLP-modellen als invariantie- en richtingstests [5].
"""Property-based and metamorphic tests: rules that must hold for every input, not just the test set."""
import os
import joblib
import numpy as np
from hypothesis import given, settings, strategies as st
MODEL = joblib.load(os.environ.get("MODEL", "model.joblib"))
applicant = st.tuples(
st.floats(5, 500), # income_k
st.floats(0, 1), # debt_ratio
st.integers(0, 45), # years_employed
st.integers(0, 3), # region code
)
def proba(rows):
return MODEL.predict_proba(np.asarray(rows, dtype=float))[:, 1]
@settings(max_examples=300, deadline=None)
@given(applicant)
def test_output_is_a_probability(a):
p = proba([a])
assert p.shape == (1,) and 0.0 <= p[0] <= 1.0
@settings(max_examples=300, deadline=None)
@given(applicant, st.floats(0.1, 200))
def test_more_income_never_lowers_score(a, extra): # metamorphic relation
richer = (a[0] + extra, *a[1:])
assert proba([richer])[0] >= proba([a])[0] - 1e-9
@settings(max_examples=300, deadline=None)
@given(applicant, st.floats(0.01, 0.5))
def test_more_debt_never_raises_score(a, extra):
worse = (a[0], min(1.0, a[1] + extra), *a[2:])
assert proba([worse])[0] <= proba([a])[0] + 1e-9
@settings(max_examples=100, deadline=None)
@given(st.lists(applicant, min_size=2, max_size=20), st.randoms())
def test_batch_order_does_not_change_answers(rows, rnd): # invariance
perm = list(range(len(rows)))
rnd.shuffle(perm)
p = proba(rows)
assert np.allclose(proba([rows[i] for i in perm]), p[perm])
$ python -m pytest -q test_properties.py
.... [100%]
4 passed in 4.51s
$ MODEL=model_unconstrained.joblib python -m pytest -q test_properties.py
.FF. [100%]
E assert np.float64(0.8262130572178492) >= (np.float64(0.8346077610546677) - 1e-09)
E Failing test case: test_more_income_never_lowers_score(
E a=(33.0, 0.0, 7, 0),
E extra=1.0,
E )
...
FAILED test_properties.py::test_more_income_never_lowers_score - assert np.fl...
FAILED test_properties.py::test_more_debt_never_raises_score - assert np.floa...
2 failed, 2 passed in 6.91s
Het model zonder constraints, met dezelfde AUC, geeft een aanvrager die £33k verdient een score van 0.835 en dezelfde aanvrager met £34k een score van 0.826. Hypothesis vond dit en verkleinde het tot ronde getallen. Uw falende voorbeeld kan afwijken, omdat de generatie willekeurig is; Hypothesis slaat fouten op in zijn lokale database en speelt ze bij de volgende run als eerste opnieuw af. De oplossing was hier om de regel in het model in te bouwen; waar dat niet kan, meldt de test het nog steeds en blokkeert de gate de release.
Stap 5: kalibratie en conformal prediction
Een score van 0.8 zou moeten betekenen dat ongeveer 80% van zulke aanvragers aflost. Moderne neurale netwerken zijn vaak te zelfverzekerd [6]; onze trees waren al goed gekalibreerd (ECE 0.014). Als de uwe dat niet zijn, past CalibratedClassifierCV van scikit-learn een correctie toe op held-out data.
Conformal prediction gaat verder: het zet de scores van elk model om in voorspellingsverzamelingen die het echte label bevatten met een gekozen kans, hier 90%, onder de enige aanname dat nieuwe data uitwisselbaar is met de kalibratiedata (grofweg: uit dezelfde populatie getrokken) [7]. In NumPy kost het drie stappen.
"""Split conformal prediction in plain numpy: prediction sets with a coverage guarantee."""
import joblib
import numpy as np
from data import make_loans
model = joblib.load("model.joblib")
alpha = 0.10 # target: true label in the set 90% of the time
X_cal, y_cal = make_loans(2_000, seed=2) # calibration data, unseen in training
X_test, y_test = make_loans(10_000, seed=3)
# 1. Non-conformity score: 1 - probability the model gave to the true class
p_cal = model.predict_proba(X_cal)
scores = 1 - p_cal[np.arange(len(y_cal)), y_cal]
# 2. Finite-sample-corrected quantile of the calibration scores
n = len(scores)
qhat = np.quantile(scores, np.ceil((n + 1) * (1 - alpha)) / n, method="higher")
# 3. Prediction set: every class whose score is within qhat
p_test = model.predict_proba(X_test)
sets = (1 - p_test) <= qhat # boolean matrix, shape (n_test, 2)
covered = sets[np.arange(len(y_test)), y_test].mean()
size = sets.sum(axis=1)
print(f"qhat={qhat:.3f} empirical coverage={covered:.3f} (target {1 - alpha:.2f})")
print(f"singleton sets={np.mean(size == 1):.1%} both classes={np.mean(size == 2):.1%} empty={np.mean(size == 0):.1%}")
# The guarantee is an average over calibration draws, so check it over many draws
cov = []
for s in range(100, 150):
Xc, yc = make_loans(2_000, seed=s)
sc = 1 - model.predict_proba(Xc)[np.arange(len(yc)), yc]
q = np.quantile(sc, np.ceil((len(sc) + 1) * (1 - alpha)) / len(sc), method="higher")
cov.append(((1 - p_test) <= q)[np.arange(len(y_test)), y_test].mean())
print(f"over 50 calibration draws: mean coverage={np.mean(cov):.3f} min={np.min(cov):.3f} max={np.max(cov):.3f}")
$ python conformal.py
qhat=0.689 empirical coverage=0.897 (target 0.90)
singleton sets=49.7% both classes=50.3% empty=0.0%
over 50 calibration draws: mean coverage=0.899 min=0.885 max=0.913
Twee lessen. Ten eerste geldt de garantie gemiddeld over kalibratietrekkingen, niet voor elke afzonderlijke trekking: individuele trekkingen varieerden van 0.885 tot 0.913, en het gemiddelde was 0.899 op een vaste testset die zelf ook ruis toevoegt. Ten tweede, en nuttiger voor de business: de helft van de aanvragers krijgt de verzameling {repay, default}; het model kan bij 90% betrouwbaarheid niet beslissen. Dat is uw wachtrij voor menselijke beoordeling, en de omvang ervan is een kostenpost die u nu kunt benoemen.
MAPIE verpakt dezelfde methode, met meer conformiteitsscores en ondersteuning voor regressie. Versie 1 veranderde de API; dit is de 1.x-vorm [8]:
"""The same thing with MAPIE 1.x (prefit model, LAC score)."""
import joblib
import numpy as np
from mapie.classification import SplitConformalClassifier
from data import make_loans
X_cal, y_cal = make_loans(2_000, seed=2)
X_test, y_test = make_loans(10_000, seed=3)
mapie = SplitConformalClassifier(estimator=joblib.load("model.joblib"),
confidence_level=0.90, prefit=True)
mapie.conformalize(X_cal, y_cal)
_, sets = mapie.predict_set(X_test) # sets: (n, n_classes, n_confidence_levels)
sets = sets[:, :, 0]
print(f"MAPIE coverage={sets[np.arange(len(y_test)), y_test].mean():.3f} "
f"mean set size={sets.sum(axis=1).mean():.2f}")
MAPIE coverage=0.897 mean set size=1.50
Dezelfde dekking, dezelfde gemiddelde verzamelingsgrootte (half singletons, half paren): de NumPy-versie en de library komen overeen.
Stap 6: outputcontracten en regressie-evals voor een LLM-stap
De output van een LLM is tekst; uw systeem heeft data nodig. Behandel elk antwoord als onvertrouwde input. Pydantic valideert de structuur (types, toegestane waarden, verplichte velden) en laat u deterministische bedrijfscontroles toevoegen zoals "netto plus btw is totaal" [9].
"""An output contract for an LLM step: schema, deterministic business checks, and a regression eval."""
import json
from datetime import date
from typing import Literal
from pydantic import BaseModel, Field, ValidationError, field_validator, model_validator
class InvoiceExtraction(BaseModel):
supplier: str = Field(min_length=2, max_length=120)
invoice_date: date
currency: Literal["GBP", "EUR", "USD"]
net: float = Field(ge=0)
vat: float = Field(ge=0)
total: float = Field(gt=0)
@field_validator("invoice_date")
@classmethod
def not_in_future(cls, v: date) -> date:
if v > date.today():
raise ValueError("invoice date is in the future")
return v
@model_validator(mode="after")
def totals_add_up(self):
if abs(self.net + self.vat - self.total) > 0.01:
raise ValueError(f"net + vat = {self.net + self.vat:.2f} but total = {self.total:.2f}")
return self
def check(raw: str) -> tuple[bool, str]:
"""Never trust the model's text: parse, validate, and say exactly what failed."""
try:
InvoiceExtraction.model_validate_json(raw)
return True, "ok"
except ValidationError as e:
return False, "; ".join(f"{'.'.join(map(str, err['loc'])) or 'model'}: {err['msg']}"
for err in e.errors())
# Three outputs an LLM really might produce for the same invoice
outputs = {
"good": '{"supplier":"Acme Ltd","invoice_date":"2026-10-31","currency":"GBP","net":100.0,"vat":20.0,"total":120.0}',
"bad_maths": '{"supplier":"Acme Ltd","invoice_date":"2026-10-31","currency":"GBP","net":100.0,"vat":20.0,"total":102.0}',
"bad_shape": '{"supplier":"Acme Ltd","invoice_date":"31/10/2026","currency":"£","net":"100","vat":20.0}',
}
if __name__ == "__main__":
for name, raw in outputs.items():
ok, why = check(raw)
print(f"{name:<10} {'PASS' if ok else 'FAIL'} {why}")
$ python llm_contract.py
good PASS ok
bad_maths FAIL model: Value error, net + vat = 120.00 but total = 102.00
bad_shape FAIL invoice_date: Input should be a valid date or datetime, invalid character in year; currency: Input should be 'GBP', 'EUR' or 'USD'; total: Field required
Let op wat niet werd gemarkeerd: "net":"100", een string, werd geaccepteerd en geconverteerd, omdat de standaard lax mode van Pydantic numerieke strings omzet. Wilt u dat het model exacte types produceert, stel dan model_config = ConfigDict(strict=True) in. Routeer fouten vervolgens: probeer het één keer opnieuw met de foutmelding in de prompt en stuur herhaalde fouten naar een mens.
Validatie bewijst vorm, geen waarheid. Voor waarheid hebt u een golden set nodig: echte gevallen met antwoorden die door een mens zijn gecontroleerd, per veld gescoord en vergeleken met de release in productie voordat een wijziging van prompt of model live gaat.
"""Regression eval for an LLM step: golden cases, field-level scoring, compared against the last release."""
import json
import sys
from llm_contract import InvoiceExtraction, check
GOLDEN = [ # expected fields per case, written and reviewed by a person
{"id": "inv-001", "expect": {"supplier": "Acme Ltd", "total": 120.0, "currency": "GBP"}},
{"id": "inv-002", "expect": {"supplier": "Brightwater plc", "total": 54.0, "currency": "GBP"}},
{"id": "inv-003", "expect": {"supplier": "Nordlicht GmbH", "total": 238.0, "currency": "EUR"}},
{"id": "inv-004", "expect": {"supplier": "Kestrel Ltd", "total": 960.0, "currency": "GBP"}},
]
def extract(case_id: str, outputs: dict) -> str:
"""Replace with your model call (temperature 0, pinned model version, logged prompt)."""
return outputs[case_id]
def run(outputs: dict) -> dict:
valid = fields_ok = fields_total = 0
for case in GOLDEN:
raw = extract(case["id"], outputs)
ok, _ = check(raw)
valid += ok
got = InvoiceExtraction.model_validate_json(raw).model_dump() if ok else {}
for k, v in case["expect"].items():
fields_total += 1
fields_ok += got.get(k) == v
return {"schema_valid": valid / len(GOLDEN), "field_accuracy": fields_ok / fields_total}
if __name__ == "__main__":
baseline = json.load(open("baseline.json")) # scores of the release in production
candidate = run(json.load(open(sys.argv[1]))) # recorded outputs of the new prompt/model
print("baseline ", {k: round(v, 3) for k, v in baseline.items()})
print("candidate", {k: round(v, 3) for k, v in candidate.items()})
bad = [k for k in candidate if candidate[k] < baseline[k] - 0.02]
print("PASS" if not bad else f"FAIL: regression in {bad}")
sys.exit(1 if bad else 0)
$ python regression_eval.py outputs_v2.json
baseline {'schema_valid': 1.0, 'field_accuracy': 1.0}
candidate {'schema_valid': 0.75, 'field_accuracy': 0.667}
FAIL: regression in ['schema_valid', 'field_accuracy']
Hier bevatten outputs_v1.json en outputs_v2.json opgenomen antwoorden voor vier facturen (in v2 is één valuta fout en klopt één totaal niet), zodat het voorbeeld zonder API-sleutel draait. In uw project roept extract() het model aan met temperatuur 0 en een vastgepinde modelversie, en slaat u de ruwe antwoorden samen met de score op, zodat een fout later kan worden onderzocht. Vier gevallen is een demonstratie; een bruikbare golden set heeft er een paar honderd, gekozen om uw slices en uw eerdere incidenten te dekken.
Stap 7: driftmonitoring
Elke garantie hierboven gaat ervan uit dat productiedata lijkt op uw evaluatiedata. Controleer of dat nog zo is. De population stability index (PSI) meet hoe ver een verdeling over vaste bins is verschoven; de two-sample Kolmogorov-Smirnov-test (KS) vraagt of twee steekproeven uit dezelfde verdeling kunnen komen.
"""Drift checks on inputs and scores: population stability index and the two-sample KS test."""
import joblib
import numpy as np
from scipy.stats import ks_2samp
from data import make_loans, FEATURES
def psi(expected, actual, bins=10):
"""Population stability index over quantile bins of the reference data."""
edges = np.unique(np.quantile(expected, np.linspace(0, 1, bins + 1)))
edges[0], edges[-1] = -np.inf, np.inf
e = np.histogram(expected, edges)[0] / len(expected)
a = np.histogram(actual, edges)[0] / len(actual)
e, a = np.clip(e, 1e-6, None), np.clip(a, 1e-6, None)
return float(np.sum((a - e) * np.log(a / e)))
model = joblib.load("model.joblib")
X_ref, _ = make_loans(10_000, seed=1) # what the model was validated on
for label, shift in [("same population", 0.0), ("incomes 20% higher", np.log(1.2))]:
X_live, _ = make_loans(5_000, seed=7, income_shift=shift) # a week of production traffic
print(label)
for j, name in enumerate(FEATURES[:3]):
ks = ks_2samp(X_ref[:, j], X_live[:, j])
print(f" {name:<15} PSI={psi(X_ref[:, j], X_live[:, j]):.3f} KS p={ks.pvalue:.3g}")
s_ref, s_live = model.predict_proba(X_ref)[:, 1], model.predict_proba(X_live)[:, 1]
print(f" {'score':<15} PSI={psi(s_ref, s_live):.3f} mean {s_ref.mean():.3f} -> {s_live.mean():.3f}")
$ python drift.py
same population
income_k PSI=0.002 KS p=0.484
debt_ratio PSI=0.001 KS p=0.33
years_employed PSI=0.005 KS p=0.0319
score PSI=0.003 mean 0.572 -> 0.573
incomes 20% higher
income_k PSI=0.126 KS p=6.14e-59
debt_ratio PSI=0.001 KS p=0.33
years_employed PSI=0.005 KS p=0.0319
score PSI=0.066 mean 0.572 -> 0.627
Het verschoven inkomen wordt door beide maten opgepikt, en de scoreverdeling beweegt mee. Maar kijk naar years_employed op dezelfde populatie: KS geeft p = 0.03, "significant" op het gebruikelijke niveau van 5%, terwijl er niets mis is. Draai elke dag genoeg tests en sommige gaan bij toeval af; bij grote steekproeven worden ook kleine onschuldige verschuivingen significant. Alert op effectgroottes zoals PSI (een gangbare vuistregel in credit scoring beschouwt onder 0.1 als stabiel en boven 0.25 als een grote verschuiving; stem die af op uw eigen historie) en vooral op uitkomsten zodra labels binnenkomen.
Stap 8: formele verificatie van een klein netwerk
Voor een klein ReLU-netwerk kunt u uitspraken bewijzen zoals "voor elke aanvrager met een inkomen van £50k tot £200k, een schuldratio van hoogstens 0.25 en een willekeurig arbeidsverleden zegt het netwerk dat aflossing waarschijnlijk is". Twee methoden, beide in minder dan 100 regels:
- Interval bound propagation duwt de inputbox door elke laag. De methode is sound (als ze zegt dat de eigenschap geldt, dan geldt die ook) maar incompleet (ze kan falen bij het bewijzen van een ware eigenschap, omdat de grenzen ruim zijn).
- Mixed-integer linear programming codeert elke ReLU exact met één binaire variabele en vraagt een solver om het echte minimum van de output over de box. De methode is compleet, maar het probleem is in het algemeen NP-compleet [10], dus ze schaalt alleen naar kleine netwerken.
milpvan SciPy gebruikt de HiGHS-solver [11].
"""Formal verification of a small ReLU network: interval bounds (fast, sound, incomplete)
and an exact mixed-integer program (complete) with scipy.optimize.milp."""
import sys
import numpy as np
from scipy.optimize import milp, LinearConstraint, Bounds
from sklearn.neural_network import MLPClassifier
from sklearn.preprocessing import StandardScaler
from data import make_loans
X, y = make_loans(20_000, seed=0)
X = X[:, :3] # income_k, debt_ratio, years_employed
scaler = StandardScaler().fit(X)
net = MLPClassifier(hidden_layer_sizes=(8, 8), activation="relu", max_iter=500,
random_state=0).fit(scaler.transform(X), y)
layers = list(zip(net.coefs_, net.intercepts_)) # last layer gives the logit
def to_scaled(lo, hi):
return (np.array(lo) - scaler.mean_) / scaler.scale_, (np.array(hi) - scaler.mean_) / scaler.scale_
def interval_bounds(lo, hi):
"""Push a box through the network; returns pre-activation bounds per layer."""
bounds = []
for k, (W, b) in enumerate(layers):
Wp, Wn = np.clip(W, 0, None), np.clip(W, None, 0)
l, u = lo @ Wp + hi @ Wn + b, hi @ Wp + lo @ Wn + b
bounds.append((l, u))
lo, hi = np.maximum(l, 0), np.maximum(u, 0)
return bounds
def min_logit_milp(lo, hi):
"""Exact minimum of the logit over the box. Each unstable ReLU a = max(z, 0) becomes
linear constraints plus one binary d (d=1: active), using the interval bounds l <= z <= u."""
pre = interval_bounds(lo, hi)
n_in = len(lo)
sizes = [W.shape[1] for W, _ in layers]
# variable layout: x | (z, a, d) per hidden layer | logit
idx, off = {}, n_in
for k, n in enumerate(sizes[:-1]):
idx[k] = (off, off + n, off + 2 * n); off += 3 * n
out = off; nv = off + 1
rows, lb, ub = [], [], []
def add(coef, l, u):
r = np.zeros(nv)
for i, c in coef: r[i] += c
rows.append(r); lb.append(l); ub.append(u)
prev = list(range(n_in))
for k, (W, b) in enumerate(layers):
if k == len(layers) - 1: # logit = W a + b
add([(prev[i], W[i, 0]) for i in range(len(prev))] + [(out, -1)], -b[0], -b[0])
break
z0, a0, d0 = idx[k]
l, u = pre[k]
for j in range(W.shape[1]):
add([(prev[i], W[i, j]) for i in range(len(prev))] + [(z0 + j, -1)], -b[j], -b[j])
add([(a0 + j, 1), (z0 + j, -1)], 0, np.inf) # a >= z
add([(a0 + j, 1), (d0 + j, -max(u[j], 0))], -np.inf, 0) # a <= u d
add([(a0 + j, 1), (z0 + j, -1), (d0 + j, -min(l[j], 0))], -np.inf, -min(l[j], 0)) # a <= z - l(1-d)
prev = list(range(a0, a0 + W.shape[1]))
vlo, vhi, integ = np.full(nv, -np.inf), np.full(nv, np.inf), np.zeros(nv)
vlo[:n_in], vhi[:n_in] = lo, hi
for k in idx:
z0, a0, d0 = idx[k]; n = sizes[k]
vlo[a0:a0 + n] = 0; vlo[d0:d0 + n] = 0; vhi[d0:d0 + n] = 1; integ[d0:d0 + n] = 1
c = np.zeros(nv); c[out] = 1 # minimise the logit
res = milp(c, constraints=LinearConstraint(np.array(rows), lb, ub),
integrality=integ, bounds=Bounds(vlo, vhi))
assert res.success, res.message # never report a bound from a failed solve
return res.fun, res.x[:n_in] * scaler.scale_ + scaler.mean_
# Property: every applicant in the box must be scored "likely to repay" (logit > 0).
# required=True boxes are policy; the last one is exploratory, to find where the policy stops holding.
PROPERTIES = [
("income 80-200k, debt <= 0.15, 5-30 yrs", [80, 0.0, 5], [200, 0.15, 30], True),
("income 50-200k, debt <= 0.25, 0-30 yrs", [50, 0.0, 0], [200, 0.25, 30], True),
("income 40-200k, debt <= 0.30, 0-30 yrs", [40, 0.0, 0], [200, 0.30, 30], False),
]
failed = False
for name, box_lo, box_hi, required in PROPERTIES:
lo, hi = to_scaled(box_lo, box_hi)
ibp_lower = interval_bounds(lo, hi)[-1][0][0]
exact, worst = min_logit_milp(lo, hi)
verdict = "VERIFIED" if exact > 0 else "COUNTEREXAMPLE"
if ibp_lower > 0:
verdict += " (intervals alone were enough)"
print(f"{name}\n interval lower bound={ibp_lower:+.3f} exact min logit={exact:+.3f} {verdict}")
if exact <= 0:
print(f" worst case: income {worst[0]:.1f}k, debt {worst[1]:.3f}, {worst[2]:.1f} yrs")
failed |= required
# cross-check the verifier: no random sample may beat the exact minimum
S = np.random.default_rng(0).uniform(box_lo, box_hi, (100_000, 3))
h = scaler.transform(S)
for W, b in layers[:-1]:
h = np.maximum(h @ W + b, 0)
print(f" lowest logit in 100,000 random samples={(h @ layers[-1][0] + layers[-1][1]).min():+.3f}")
sys.exit(1 if failed else 0) # a required property failed
$ python verify_tiny_net.py
income 80-200k, debt <= 0.15, 5-30 yrs
interval lower bound=+0.254 exact min logit=+1.942 VERIFIED (intervals alone were enough)
lowest logit in 100,000 random samples=+1.960
income 50-200k, debt <= 0.25, 0-30 yrs
interval lower bound=-1.573 exact min logit=+0.589 VERIFIED
lowest logit in 100,000 random samples=+0.626
income 40-200k, debt <= 0.30, 0-30 yrs
interval lower bound=-2.774 exact min logit=-0.273 COUNTEREXAMPLE
worst case: income 40.0k, debt 0.300, 0.0 yrs
lowest logit in 100,000 random samples=-0.231
Lees de drie rijen. De eerste eigenschap wordt alleen met intervallen al bewezen. De tweede is waar, maar intervallen konden dat niet aantonen; de exacte solver wel. De derde is onwaar, en de solver geeft de slechtste aanvrager terug, een concreet tegenvoorbeeld om met de business te bespreken. Willekeurige steekproeven kwamen elke keer dicht bij het echte minimum maar bereikten het nooit, en daarom is steekproeven een plausibiliteitscontrole en geen bewijs.
De grenzen: dit netwerk heeft 16 verborgen neuronen. Gebruik voor grotere netwerken een speciale verifier: α,β-CROWN, dat van 2021 tot en met 2025 elk jaar VNN-COMP won en meldt te schalen naar convolutionele netwerken met miljoenen parameters bij lokale eigenschappen, of Marabou [12][13]. Geen van beide bewijst iets over de antwoorden van een groot taalmodel. En een bewijs geldt voor één modelversie en één inputbox: draai het opnieuw bij elke hertraining, in de gate.
Stap 9: de release-gate in CI
Bewijs dat niet wordt afgedwongen, vervalt. gate.sh draait alles hierboven en stopt bij de eerste fout:
#!/usr/bin/env bash
# Release gate: every check must pass before a model or prompt change can ship.
set -euo pipefail
export OMP_NUM_THREADS=1 # stop OpenMP oversubscription in per-row tests
python model.py
python eval_harness.py model.joblib # held-out + slice contract
python -m pytest -q test_properties.py # properties and metamorphic relations
python conformal.py # coverage report (informational)
python regression_eval.py outputs_v1.json # LLM step: no regression against production
python verify_tiny_net.py # formal check: required boxes must verify
echo "ALL GATES PASSED"
Een minimale GitHub Actions-workflow die het bij elke pull request draait (getoond voor de vorm; wij draaiden gate.sh lokaal, niet in Actions):
name: model-gate
on: [pull_request]
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-python@v7
with: { python-version: "3.12" }
- run: pip install numpy scipy scikit-learn hypothesis pydantic pytest mapie
- run: ./gate.sh
- uses: actions/upload-artifact@v7
if: always()
with: { name: evidence, path: eval_report.json }
In productie draaien
- Pin alles vast. Pin libraryversies in een lockfile en leg de hash van het modelartefact, de datasnapshot en de git-commit vast in
eval_report.json. Een rapport dat u niet aan een modelversie kunt koppelen, is geen bewijs. - Containers. Draai de gate in hetzelfde image dat u uitrolt, zodat de tests dezelfde builds van NumPy en scikit-learn zien als productie. Dit alles draait op CPU; de property-tests en de verifier waren op een laptop in enkele seconden klaar.
- Threads. Stel
OMP_NUM_THREADSbewust in, zowel in CI als bij serving. Op onze gedeelde buildmachine duurde één voorspelling van één rij 150 ms met standaard threading en 1,3 ms met één thread. - Monitoring. Plan
drift.pyin tegen een dagelijkse steekproef van gelogde inputs en scores, exporteer PSI per feature als metrics naar uw bestaande monitoringstack en alert via de normale on-call-route. Koppel uitkomsten aan voorspellingen zodra labels binnenkomen en draai de evaluatieharness er opnieuw op. - Verder gaan. De ML Test Score van Google noemt 28 tests en monitoringcontroles voor productierijpheid en is een goede audit van wat u hebt gemist [17]; Sculley et al. leggen uit waarom de datapipelines en lijmcode rond een model dezelfde zorg nodig hebben als het model zelf [16].
- Bewaar het dossier. Sla de output van elke gate-run op bij de release. Wanneer een auditor of klant vraagt hoe u wist dat het model geschikt was voor gebruik, is dit het antwoord.
Valkuilen en debuggen
- Hypothesis-tests zijn erg traag. Thread-oversubscription in OpenMP; stel
OMP_NUM_THREADS=1in. Stel ookdeadline=Nonein, omdat modelaanroepen een variabele latency hebben. - Een property-test faalt op een minuscuul verschil. Floating-point-ruis; vergelijk met een tolerantie (wij gebruiken 1e-9) en bepaal welk verschil voor de business telt.
- Conformal coverage ligt onder het doel. Bij één enkele kalibratietrekking kan dat; controleer het gemiddelde over trekkingen. Ligt het ver eronder, dan is uw kalibratiedata niet uitwisselbaar met productie, vaak door een trend in de tijd: kalibreer op recente data.
- De MILP is traag of faalt. Maak de inputgrenzen strakker, want ruime grenzen leveren zwakke coderingen op, en controleer
res.success. Boven een paar honderd neuronen stapt u over op een speciale verifier. - De LLM-regressie-eval wisselt van uitkomst. Zet de temperatuur op 0, pin de modelversie vast en draai, als de output nog steeds varieert, elk geval meerdere keren en gate op het slagingspercentage.
Het bewijsmateriaal zelf evalueren
Test uw tests. Plant een bekende fout en bevestig dat de gate die vangt: het model zonder constraints is precies dat voor de property-tests, outputs_v2.json is er een voor de LLM-eval, en de verschoven inkomens zijn er een voor drift. Bewaar deze geplante fouten in de repository en draai ze in CI als tests waarvan wordt verwacht dat ze falen, zodat een kapotte controle niet ongemerkt kan slagen.
Alternatieven
| Behoefte | Wat wij gebruikten | Alternatieven | Wanneer overstappen |
|---|---|---|---|
| Evaluatieharness | Kale scikit-learn en NumPy | MLflow evaluation, de eval-functies van uw experiment-tracker | Veel modellen en teams; u hebt een UI en historie nodig |
| Property-tests | Hypothesis | CheckList (gedragstests voor NLP) | Tekstmodellen waarbij perturbaties taalkundig zijn |
| Onzekerheid | Split conformal in NumPy, MAPIE | CalibratedClassifierCV alleen voor kalibratie | U hebt gekalibreerde scores nodig, geen verzamelingen |
| LLM-output | Pydantic plus een golden set | Structured-output-modi van providers, LLM-evalframeworks | Veel prompts; u wilt dashboards en scoring met LLM-as-judge |
| Drift | PSI en KS in SciPy | Evidently en vergelijkbare monitoringlibraries | Veel features; u wilt rapporten en dashboards |
| Verificatie | Intervalgrenzen en SciPy MILP | α,β-CROWN, Marabou | Netwerken groter dan een paar honderd neuronen |
Veelgestelde vragen
Is dit genoeg voor de EU AI Act? Het levert het soort bewijs waar de artikelen 9 en 15 om vragen (testen tegen vooraf gedefinieerde metrics en probabilistische drempels, verklaarde nauwkeurigheid, robuustheid), maar compliance vereist ook risicobeheer, datagovernance, documentatie en processen voor menselijk toezicht [14]. Na de Digital Omnibus gelden de verplichtingen voor zelfstandige hoog-risicosystemen uit bijlage III vanaf 2 december 2027 [15].
Heb ik dit allemaal nodig voor elk model? Nee. Schaal het naar het risico: een interne zoekranker heeft misschien stappen 3, 6 en 7 nodig; een kredietbeslissing heeft ze allemaal nodig, plus onafhankelijke validatie.
Kan ik een LLM formeel verifiëren? De antwoorden niet. U kunt de deterministische code eromheen verifiëren, het outputformaat beperken en kleine classifiers verifiëren die ernaast staan, zoals een router of een guard-model.
Waarom synthetische data? Zodat elke test een bekend juist antwoord heeft. Vervang het door uw eigen data en behoud de structuur; de drempels in het contract zullen veranderen.
Wilt u hulp bij het opzetten van evaluatieharnesses, release-gates en monitoring rond uw eigen modellen, bekijk dan onze dienst MLOps setup.
Referenties
- scikit-learn user guide: histogram-based gradient boosting, monotonic constraints
- D'Amour et al., "Underspecification presents challenges for credibility in modern machine learning", arXiv 2011.03395 (JMLR, 2022)
- Documentatie van Hypothesis
- Chen et al., "Metamorphic testing: a review of challenges and opportunities", ACM Computing Surveys, 2018
- Ribeiro et al., "Beyond accuracy: behavioral testing of NLP models with CheckList", ACL 2020
- Guo et al., "On calibration of modern neural networks", ICML 2017
- Angelopoulos en Bates, "A gentle introduction to conformal prediction and distribution-free uncertainty quantification", arXiv 2107.07511
- Documentatie van MAPIE
- Documentatie van Pydantic: validators
- Katz et al., "Reluplex: an efficient SMT solver for verifying deep neural networks", CAV 2017
- Documentatie van SciPy: scipy.optimize.milp
- α,β-CROWN-verifier voor neurale netwerken (GitHub)
- Marabou-verifier voor neurale netwerken (GitHub)
- Verordening (EU) 2024/1689 (verordening artificiële intelligentie)
- Digital Omnibus on AI, Verordening (EU) 2026/1744: AI Act Explorer
- Sculley et al., "Hidden technical debt in machine learning systems", NeurIPS 2015
- Breck et al., "The ML Test Score: a rubric for ML production readiness and technical debt reduction", IEEE Big Data 2017