Ein praxisorientierter Leitfaden für KI-Entwicklerinnen und -Entwickler, die zu einem Modell oder einer LLM-Funktion gefragt wurden: „Woher wissen Sie, dass es funktioniert?“, und darauf keinen Beweis liefern können. Sie bauen in etwa 400 Zeilen Python die Evidenz, die einen Beweis ersetzt: ein Evaluierungs-Harness mit Slice-Metriken und einem Pass/Fail-Vertrag, Property-based- und metamorphe Tests, Kalibrierung und Conformal Prediction, Ausgabeverträge und eine Regressionsevaluierung für einen LLM-Schritt, Drift-Prüfungen, ein CI-Gate und eine exakte formale Verifikation eines kleinen neuronalen Netzes. Jeder Block unten wurde ausgeführt, und die gezeigte Ausgabe ist echt.
Diese Technote begleitet unseren Blogbeitrag Beweisbare Korrektheit scheitert bei KI: welche Evidenz Sie stattdessen aufbauen sollten, der die geschäftliche und regulatorische Seite behandelt. Stand der Fakten: 16. November 2026.
Für wen das ist, was Sie bauen, Voraussetzungen
Für wen das ist: ML- und KI-Engineers, Data Scientists, die Modelle ausliefern, und Plattform-Engineers, die die Pipelines darum herum verantworten. Sie kennen Python und pytest; Vorkenntnisse in formalen Methoden brauchen Sie nicht.
Was Sie bauen: ein kleines Projekt, evidence/, rund um einen Klassifikator für Kreditrückzahlungen, trainiert auf synthetischen Daten mit bekannter Ground Truth, sowie einen Schritt zur Rechnungsextraktion, der stellvertretend für ein LLM steht. Jede Datei erzeugt eine Art von Evidenz; gate.sh führt sie alle aus und lässt den Build fehlschlagen, wenn eine davon fehlschlägt.
Voraussetzungen: Python 3.10 oder neuer (wir haben 3.12 verwendet), etwa 300 MB Speicherplatz für die Bibliotheken, eine beliebige Laptop-CPU. Weder GPU noch API-Schlüssel sind nötig. Getestet haben wir mit 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 und pytest 9.2.0.
Schritt 0: Einrichtung
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
Schritt 1: Daten mit bekannter Ground Truth
Echte Daten sind besser für echte Entscheidungen, aber zum Erlernen der Techniken wollen Sie einen Datensatz, bei dem Sie die richtige Antwort kennen. Hier hängt die Rückzahlung vom Einkommen (steigend), von der Schuldenquote (fallend), von den Beschäftigungsjahren (steigend) und von der Region ab, wobei die kleinste Region etwas schlechter dasteht. Jeder Test unten hat daher ein korrektes Ergebnis.
"""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
Schritt 2: das Modell trainieren, mit zwei eingebauten Regeln
Der HistGradientBoostingClassifier von scikit-learn akzeptiert monotonic_cst, womit der Score gezwungen wird, sich bei steigendem Merkmal in eine Richtung zu bewegen [1]. Wir trainieren ein Modell mit diesen Einschränkungen und eines ohne, damit wir sehen, was die Tests aufdecken.
"""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")
Schritt 3: ein Evaluierungs-Harness mit Vertrag
Der Vertrag kommt einer Spezifikation am nächsten: Schwellenwerte, die vor dem Training mit dem Fachbereich vereinbart wurden. Das Harness meldet die Held-out-ROC-AUC (wie gut der Score Rückzahler vor Ausfällen einordnet), den Brier-Score und den Expected Calibration Error (ECE, die durchschnittliche Abweichung zwischen vorhergesagter Wahrscheinlichkeit und beobachteter Häufigkeit), danach dieselben Werte pro Region mit Bootstrap-Konfidenzintervallen von 95 %. Das Gate prüft das untere Ende des Intervalls jedes Slices, sodass ein kleiner Slice nicht durch Glück bestehen kann, und es endet bei einem Fehlschlag mit einem Exit-Code ungleich null, was es erst CI-tauglich macht.
"""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
Beachten Sie die Breiten: Der Slice west mit 1.026 Fällen hat ein fast doppelt so breites Intervall wie north. Beide Modelle bestehen. Allein anhand dieser Zahlen könnten Sie sich nicht zwischen ihnen entscheiden; das ist Unterspezifikation im Kleinen: eine Pipeline, viele Modelle mit demselben Held-out-Score [2].
Schritt 4: Property-based und metamorphe Tests
Ein Property-based Test formuliert eine Regel und lässt eine Bibliothek die Eingaben erzeugen. Hypothesis erzeugt Hunderte von Fällen, und wenn einer fehlschlägt, reduziert es ihn auf das einfachste fehlschlagende Beispiel [3]. Ein metamorpher Test ist eine Eigenschaft, die zwei Läufe zueinander in Beziehung setzt: Sie kennen den richtigen Score für eine Antragstellerin nicht, aber Sie wissen, dass mehr Einkommen ihn nicht senken darf. Die Idee stammt aus dem Softwaretest, wo sie für Programme ohne verlässliches Testorakel entwickelt wurde [4]; CheckList übertrug dieselbe Idee als Invarianz- und Richtungstests auf NLP-Modelle [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
Das Modell ohne Einschränkungen bewertet bei gleicher AUC einen Antragsteller mit £33k Einkommen mit 0.835 und denselben Antragsteller mit £34k mit 0.826. Hypothesis hat das gefunden und auf runde Zahlen reduziert. Ihr fehlschlagendes Beispiel kann abweichen, da die Generierung zufällig erfolgt; Hypothesis speichert Fehlschläge in seiner lokalen Datenbank und spielt sie beim nächsten Lauf zuerst erneut ab. Die Lösung bestand hier darin, die Regel ins Modell einzubauen; wo das nicht geht, meldet der Test es trotzdem, und das Gate blockiert das Release.
Schritt 5: Kalibrierung und Conformal Prediction
Ein Score von 0.8 sollte bedeuten, dass etwa 80 % solcher Antragsteller zurückzahlen. Moderne neuronale Netze sind oft übermäßig selbstsicher [6]; unsere Bäume waren bereits gut kalibriert (ECE 0.014). Wenn Ihre es nicht sind, passt CalibratedClassifierCV von scikit-learn eine Korrektur auf Held-out-Daten an.
Conformal Prediction geht weiter: Es verwandelt die Scores eines beliebigen Modells in Vorhersage-Mengen, die das wahre Label mit einer gewählten Wahrscheinlichkeit enthalten, hier 90 %, unter der einzigen Annahme, dass neue Daten mit den Kalibrierungsdaten austauschbar sind (grob: aus derselben Population stammen) [7]. In NumPy braucht es dafür drei Schritte.
"""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
Zwei Lehren. Erstens gilt die Garantie im Mittel über Kalibrierungsziehungen, nicht für jede einzelne: Einzelne Ziehungen reichten von 0.885 bis 0.913, und der Mittelwert lag bei 0.899, gemessen an einem festen Testset, das sein eigenes Rauschen hinzufügt. Zweitens, und für den Fachbereich nützlicher, erhält die Hälfte der Antragsteller die Menge {repay, default}: Das Modell kann sich bei 90 % Konfidenz nicht entscheiden. Das ist Ihre Warteschlange für die menschliche Prüfung, und ihre Größe ist ein Kostenfaktor, den Sie jetzt beziffern können.
MAPIE kapselt dieselbe Methode, mit mehr Conformity-Scores und Unterstützung für Regression. Version 1 hat die API geändert; dies ist die Form für 1.x [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
Gleiche Abdeckung, gleiche mittlere Mengengröße (halb Einzelmengen, halb Paare): Die NumPy-Version und die Bibliothek stimmen überein.
Schritt 6: Ausgabeverträge und Regressionsevaluierungen für einen LLM-Schritt
Die Ausgabe eines LLM ist Text; Ihr System braucht Daten. Behandeln Sie jede Antwort als nicht vertrauenswürdige Eingabe. Pydantic validiert die Struktur (Typen, erlaubte Werte, Pflichtfelder) und lässt Sie deterministische fachliche Prüfungen ergänzen, etwa „Netto plus MwSt. ergibt Gesamtbetrag“ [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
Beachten Sie, was nicht markiert wurde: "net":"100", ein String, wurde akzeptiert und konvertiert, weil der standardmäßige Lax-Modus von Pydantic numerische Strings umwandelt. Wenn das Modell exakte Typen liefern soll, setzen Sie model_config = ConfigDict(strict=True). Leiten Sie Fehlschläge dann weiter: einmal mit der Fehlermeldung im Prompt wiederholen und wiederholte Fehlschläge an einen Menschen geben.
Validierung beweist die Form, nicht die Wahrheit. Für die Wahrheit brauchen Sie ein Golden Set: echte Fälle mit von Menschen geprüften Antworten, Feld für Feld bewertet und mit dem produktiven Release verglichen, bevor eine Prompt- oder Modelländerung ausgeliefert wird.
"""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 enthalten outputs_v1.json und outputs_v2.json aufgezeichnete Antworten für vier Rechnungen (in v2 ist eine Währung falsch und eine Summe geht nicht auf), sodass das Beispiel ohne API-Schlüssel läuft. In Ihrem Projekt ruft extract() das Modell mit Temperatur 0 und einer festgelegten Modellversion auf, und Sie speichern die Rohantworten zusammen mit dem Score, damit sich ein Fehlschlag später untersuchen lässt. Vier Fälle sind eine Demonstration; ein brauchbares Golden Set umfasst einige hundert, ausgewählt so, dass sie Ihre Slices und Ihre früheren Vorfälle abdecken.
Schritt 7: Drift-Monitoring
Jede Garantie oben setzt voraus, dass die Produktionsdaten wie Ihre Evaluierungsdaten aussehen. Prüfen Sie, ob das noch so ist. Der Population Stability Index (PSI) misst, wie weit sich eine Verteilung über feste Bins verschoben hat; der Zwei-Stichproben-Kolmogorov-Smirnov-Test (KS) fragt, ob zwei Stichproben aus derselben Verteilung stammen könnten.
"""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
Das verschobene Einkommen wird von beiden Maßen erkannt, und die Score-Verteilung bewegt sich mit. Aber sehen Sie sich years_employed in derselben Population an: KS liefert p = 0.03, beim üblichen 5-%-Niveau „signifikant“, obwohl nichts falsch ist. Führen Sie jeden Tag genug Tests aus, und einige schlagen zufällig an; bei großen Stichproben werden auch winzige, harmlose Verschiebungen signifikant. Alarmieren Sie auf Effektgrößen wie den PSI (eine gängige Faustregel im Kredit-Scoring wertet unter 0,1 als stabil und über 0,25 als starke Verschiebung; justieren Sie das anhand Ihrer eigenen Historie) und vor allem auf Ergebnisse, sobald Labels vorliegen.
Schritt 8: formale Verifikation eines kleinen Netzes
Für ein kleines ReLU-Netz können Sie Aussagen beweisen wie „für jeden Antragsteller mit einem Einkommen von £50k bis £200k, einer Schuldenquote von höchstens 0,25 und beliebiger Beschäftigungshistorie sagt das Netz voraussichtliche Rückzahlung voraus“. Zwei Methoden, beide in unter 100 Zeilen:
- Interval Bound Propagation schiebt den Eingabequader durch jede Schicht. Die Methode ist korrekt (wenn sie sagt, dass die Eigenschaft gilt, dann gilt sie), aber unvollständig (sie kann daran scheitern, eine wahre Eigenschaft zu beweisen, weil die Schranken locker sind).
- Gemischt-ganzzahlige lineare Optimierung kodiert jede ReLU exakt mit einer Binärvariable und fragt einen Solver nach dem wahren Minimum der Ausgabe über dem Quader. Sie ist vollständig, aber das Problem ist im Allgemeinen NP-vollständig [10] und skaliert daher nur auf kleine Netze.
milpvon SciPy verwendet den 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
Lesen Sie die drei Zeilen. Die erste Eigenschaft wird allein durch Intervalle bewiesen. Die zweite ist wahr, aber Intervalle konnten das nicht zeigen; der exakte Solver schon. Die dritte ist falsch, und der Solver liefert den ungünstigsten Antragsteller, ein konkretes Gegenbeispiel zur Diskussion mit dem Fachbereich. Die Zufallsstichproben kamen dem wahren Minimum jedes Mal nahe, erreichten es aber nie; deshalb sind Stichproben eine Plausibilitätsprüfung und kein Beweis.
Die Grenzen: Dieses Netz hat 16 versteckte Neuronen. Für größere Netze verwenden Sie einen spezialisierten Verifizierer: α,β-CROWN, der VNN-COMP von 2021 bis 2025 jedes Jahr gewonnen hat und für lokale Eigenschaften eine Skalierung auf Faltungsnetze mit Millionen von Parametern angibt, oder Marabou [12][13]. Keiner von ihnen beweist irgendetwas über die Antworten eines großen Sprachmodells. Und ein Beweis gilt für eine Modellversion und einen Eingabequader: Führen Sie ihn bei jedem Neutraining erneut aus, im Gate.
Schritt 9: das Release-Gate in CI
Evidenz, die nicht durchgesetzt wird, verfällt. gate.sh führt alles oben Genannte aus und stoppt beim ersten Fehlschlag:
#!/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"
Ein minimaler GitHub-Actions-Workflow, der es bei jedem Pull Request ausführt (zur Veranschaulichung der Struktur; wir haben gate.sh lokal ausgeführt, nicht 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 }
Betrieb in der Produktion
- Alles festschreiben. Legen Sie Bibliotheksversionen in einer Lock-Datei fest und erfassen Sie den Hash des Modellartefakts, den Daten-Snapshot und den Git-Commit in
eval_report.json. Ein Bericht, den Sie keiner Modellversion zuordnen können, ist keine Evidenz. - Container. Führen Sie das Gate im selben Image aus, das Sie deployen, damit die Tests dieselben NumPy- und scikit-learn-Builds sehen wie die Produktion. Das alles läuft auf der CPU; die Property-Tests und der Verifizierer waren auf einem Laptop in Sekunden fertig.
- Threads. Setzen Sie
OMP_NUM_THREADSbewusst, sowohl in CI als auch beim Serving. Auf unserer gemeinsam genutzten Build-Maschine dauerte eine einzeilige Vorhersage mit Standard-Threading 150 ms und mit einem Thread 1,3 ms. - Monitoring. Planen Sie
drift.pygegen eine tägliche Stichprobe protokollierter Eingaben und Scores ein, exportieren Sie den PSI pro Merkmal als Metriken in Ihren bestehenden Monitoring-Stack und alarmieren Sie über den normalen Bereitschaftsweg. Verknüpfen Sie Ergebnisse mit Vorhersagen, sobald Labels vorliegen, und führen Sie das Evaluierungs-Harness erneut darauf aus. - Weiterführendes. Googles ML Test Score listet 28 Tests und Monitoring-Prüfungen für die Produktionsreife auf und ist ein gutes Audit dessen, was Sie übersehen haben [17]; Sculley et al. erklären, warum die Datenpipelines und der Glue-Code rund um ein Modell dieselbe Sorgfalt brauchen wie das Modell selbst [16].
- Den Nachweis aufbewahren. Speichern Sie die Ausgabe jedes Gate-Laufs mit dem Release. Wenn ein Auditor oder ein Kunde fragt, woher Sie wussten, dass das Modell einsatztauglich war, ist das die Antwort.
Fallstricke und Debugging
- Hypothesis-Tests sind sehr langsam. Thread-Überbelegung in OpenMP; setzen Sie
OMP_NUM_THREADS=1. Setzen Sie außerdemdeadline=None, weil Modellaufrufe eine schwankende Latenz haben. - Ein Property-Test schlägt bei einer winzigen Abweichung fehl. Gleitkomma-Rauschen; vergleichen Sie mit einer Toleranz (wir verwenden 1e-9) und legen Sie fest, welche Abweichung für den Fachbereich relevant ist.
- Die Conformal Coverage liegt unter dem Ziel. Bei einer einzelnen Kalibrierungsziehung kann das vorkommen; prüfen Sie den Mittelwert über mehrere Ziehungen. Liegt sie weit darunter, sind Ihre Kalibrierungsdaten nicht mit der Produktion austauschbar, oft wegen eines zeitlichen Trends: Kalibrieren Sie auf aktuellen Daten.
- Die MILP ist langsam oder schlägt fehl. Engen Sie die Eingabeschranken ein, denn lockere Schranken ergeben schwache Kodierungen, und prüfen Sie
res.success. Ab einigen hundert Neuronen wechseln Sie zu einem spezialisierten Verifizierer. - Die LLM-Regressionsevaluierung schwankt. Setzen Sie die Temperatur auf 0, legen Sie die Modellversion fest, und wenn die Ausgaben immer noch variieren, führen Sie jeden Fall mehrmals aus und prüfen Sie im Gate die Erfolgsquote.
Wie Sie die Evidenz selbst bewerten
Testen Sie Ihre Tests. Bauen Sie einen bekannten Fehler ein und bestätigen Sie, dass das Gate ihn erkennt: Das Modell ohne Einschränkungen ist genau das für die Property-Tests, outputs_v2.json ist einer für die LLM-Evaluierung, und die verschobenen Einkommen sind einer für die Drift. Behalten Sie diese eingebauten Fehler im Repository und führen Sie sie in CI als Tests aus, deren Fehlschlag erwartet wird, damit eine defekte Prüfung nicht stillschweigend besteht.
Alternativen
| Bedarf | Was wir verwendet haben | Alternativen | Wann wechseln |
|---|---|---|---|
| Evaluierungs-Harness | Reines scikit-learn und NumPy | MLflow-Evaluierung, die Evaluierungsfunktionen Ihres Experiment-Trackers | Viele Modelle und Teams; Sie brauchen eine Oberfläche und eine Historie |
| Property-Tests | Hypothesis | CheckList (Verhaltenstests für NLP) | Textmodelle, bei denen Störungen sprachlicher Natur sind |
| Unsicherheit | NumPy Split Conformal, MAPIE | CalibratedClassifierCV nur für die Kalibrierung | Sie brauchen kalibrierte Scores, keine Mengen |
| LLM-Ausgabe | Pydantic plus ein Golden Set | Structured-Output-Modi der Anbieter, LLM-Evaluierungs-Frameworks | Viele Prompts; Sie wollen Dashboards und Bewertung per LLM-as-Judge |
| Drift | PSI und KS in SciPy | Evidently und ähnliche Monitoring-Bibliotheken | Viele Merkmale; Sie wollen Berichte und Dashboards |
| Verifikation | Intervallschranken und SciPy MILP | α,β-CROWN, Marabou | Netze mit mehr als einigen hundert Neuronen |
FAQ
Reicht das für den EU AI Act? Es erzeugt die Art von Evidenz, die die Artikel 9 und 15 verlangen (Tests anhand vorab definierter Metriken und probabilistischer Schwellenwerte, angegebene Genauigkeit, Robustheit), aber für die Konformität braucht es zusätzlich Risikomanagement, Data Governance, Dokumentation und Prozesse für die menschliche Aufsicht [14]. Nach dem Digital Omnibus gelten die eigenständigen Hochrisiko-Pflichten nach Anhang III ab dem 2. Dezember 2027 [15].
Brauche ich das alles für jedes Modell? Nein. Skalieren Sie es nach dem Risiko: Ein internes Such-Ranking braucht vielleicht die Schritte 3, 6 und 7; eine Kreditentscheidung braucht alle, plus unabhängige Validierung.
Kann ich ein LLM formal verifizieren? Nicht seine Antworten. Sie können den deterministischen Code darum herum verifizieren, sein Ausgabeformat einschränken und kleine Klassifikatoren verifizieren, die daneben stehen, etwa einen Router oder ein Guard-Modell.
Warum synthetische Daten? Damit jeder Test eine bekannte richtige Antwort hat. Setzen Sie Ihre Daten ein und behalten Sie die Struktur; die Schwellenwerte im Vertrag werden sich ändern.
Wenn Sie Unterstützung dabei möchten, Evaluierungs-Harnesses, Release-Gates und Monitoring für Ihre eigenen Modelle aufzubauen, sehen Sie sich unseren Service MLOps-Einrichtung an.
Quellen
- scikit-learn-Benutzerhandbuch: histogrammbasiertes Gradient Boosting, monotone Einschränkungen
- D'Amour et al., „Underspecification presents challenges for credibility in modern machine learning“, arXiv 2011.03395 (JMLR, 2022)
- Hypothesis-Dokumentation
- 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 und Bates, „A gentle introduction to conformal prediction and distribution-free uncertainty quantification“, arXiv 2107.07511
- MAPIE-Dokumentation
- Pydantic-Dokumentation: Validatoren
- Katz et al., „Reluplex: an efficient SMT solver for verifying deep neural networks“, CAV 2017
- SciPy-Dokumentation: scipy.optimize.milp
- α,β-CROWN-Verifizierer für neuronale Netze (GitHub)
- Marabou-Verifizierer für neuronale Netze (GitHub)
- Verordnung (EU) 2024/1689 (Verordnung über künstliche Intelligenz)
- Digital Omnibus zur KI, Verordnung (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