Thema: Anhang D. Schwellenwertkalibrierung
Schwierigkeitsgrad: Mittelstufe
Geschätzte Lernzeit: 3-4 Stunden
Voraussetzungen: Vertrautheit mit den Grundkonzepten von SDD (Software-Defined Diagnostics/Delivery)
Verständnis der Metriken MTTR, SLA, CI/CD und Incident-Management
Erfahrung mit der Linux-Befehlszeile (bash) und Python
Grundlegendes Verständnis von Mutationstests und der Funktionsweise von LLMs (Tokens, Spezifikationen)
Lernziele: Das Prinzip der paarweisen Schwellenwertkalibrierung verstehen und anwenden, ohne den „Schutzkreis abzubauen", wenn nur eine Metrik verschoben wird.
Die Schwellenwerte für Mutationstests (Kapitel 5) in Abhängigkeit vom Preis eines P0-Verlusts und der Komplexität des Routing-Graphen anpassen.
Die Gewichtungen und Schwellenwerte der Schattenspezifikations-Auktion (Kapitel 6) unter Berücksichtigung des Preises einer falschen Eskalation und der Wichtigkeit früher Signale konfigurieren.
Die Stufen-Token-Budgets (Kapitel 9) für verschiedene Lastprofile und Incident-Ströme optimieren.
Die Ausprägungen von Goodharts Gesetz (Kapitel 10) bei der Konfiguration von Guard-Metriken erkennen und verhindern.
Übersicht: Dieser Lernleitfaden widmet sich Anhang D – der Schwellenwertkalibrierung im AgentClinic-Produktionsprozess. Schwellenwertkalibrierung ist nicht nur das Ändern von Zahlen in Konfigurationsdateien; es ist die Feinabstimmung der Balance zwischen Risiken, Fehlerkosten und verfügbaren Ressourcen. Das Material sammelt Stufentabellen (Niedrig / Standard / Hoch), praktische Übungen zur Schwellenwertverschiebung und Indikatoren für deren Überprüfung. Der Schlüsselakzent liegt darauf, dass Schwellenwerte nur paarweise Sinn ergeben: Die Änderung eines Parameters muss von der Neuberechnung des verbundenen Parameters begleitet werden, sonst verliert das System seine Stabilität.
Schlüsselkonzepte: Paarweise Kalibrierung: Prinzip, demzufolge Schwellenwerte nicht isoliert geändert werden dürfen. Eine Verschiebung eines Werts ohne Neuberechnung des verbundenen Werts bricht das Schutzsystem (z. B. ein Anstieg von strict_reject_rate bei sinkender depth_of_diagnostics ist ein Symptom von Goodhart).
Mutationstests (d.1): Bewertung der Qualität des Diagnoseprozesses auf Basis künstlicher Fehler. Hängt vom Preis eines P0-Verlusts (Wahrscheinlichkeit, einen kritischen Vorfall zu verpassen) und der Komplexität des Routing-Graphen ab.
Auswahl von Schattenspezifikationen (d.2): Auktionsprozess, bei dem Gewichtungen (mttr_gain, early_signal, false_escalation) bestimmen, welche Spezifikationen aktiv werden. Erfordert eine Balance zwischen Reaktionsgeschwindigkeit und Anzahl falscher Positivmeldungen.
Stufen-Budgets (d.3): Verteilung der Rechenressourcen (in Tokens) zwischen lokaler (local) und externer (frontier) Stufe. Die Änderung der Anteile wirkt sich direkt auf die SLA der Phasen aus.
Schutz vor Goodhart (d.4): Schutzmechanismus für Metriken vor Manipulation, bei dem die Optimierung zugunsten einer Zahl das tatsächliche Ergebnis verschlechtert. Wird über Invarianten gesteuert: silent_p0, manual_review_rate, audit_trace_coverage.
Produktionsreife (d.5): Bewertung der Release-Bereitschaft eines Artefakts (standardmäßig 23/25). Beinhaltet harte blockierende Invarianten wie audit_trace_coverage = 1.0, die nicht durch die Gesamtpunktzahl umgangen werden können.
Übungsaufgaben: Name: Kalibrierung der Diagnosetiefe (D.1)
Problem: Sie müssen überprüfen, wie eine Verschärfung des Diagnosetiefen-Schwellenwerts (depth_of_diagnostics_min) einen bestehenden Validator beeinflusst. Es gilt, den Standardlauf mit einem Lauf bei überhöhten Anforderungen (Schwellenwert 5 statt 3) zu vergleichen.
Lösung: 1. Wechseln Sie in das Verzeichnis cd book2/examples/stress-mutator.
- Erstellen Sie den Ordner out und kopieren Sie die Datei mit den erwarteten Fehlern dorthin: cp expected/expected_failures.json out/expected_failures_depth5.json.
- Ersetzen Sie den Schwellenwert in der Datei: sed -i 's/"depth_of_diagnostics_min": 3/"depth_of_diagnostics_min": 5/' out/expected_failures_depth5.json.
- Führen Sie die Berechnung mit den Standardwerten aus (erfolgreich, da die durchschnittliche Tiefe 4 > 3 ist).
- Führen Sie die Berechnung mit den neuen Erwartungen aus (endet mit Fehler, da 4 < 5). Die Differenz zeigt den Preis der Schwellenwertverschärfung.
Komplexität: intermediate
Name: Schattenspezifikations-Auktion mit konservativem Profil (D.2)
Problem: Das Team hat entschieden, dass falsche Eskalationen zu teuer sind. Es muss eine Auktion mit einem neuen Gewichtungsprofil gestartet werden, bei dem die Strafe für falsche Eskalationen auf 0,8 erhöht und die Gewichtung des frühen Signals auf 0,2 gesenkt wird.
Lösung: 1. Wechseln Sie nach cd book2/examples/shadow-auction.
- Starten Sie das Scoring-Skript mit den neuen Gewichtungen: python3 scripts/score.py --candidates candidates/candidates.yaml --incidents data/incidents.jsonl --weights "0.3,0.4,0.2,0.8" --out out/scorebook.json.
- Starten Sie die Entscheidungsfindung mit einem Budget von 2000 Tokens: python3 scripts/decide.py --scorebook out/scorebook.json --budget-tokens 2000 --keep-threshold 0.70 --reject-threshold 0.40 --out-auction out/auction.json.
- Analysieren Sie das Ergebnis: shadow.p0.voice_handoff sollte in disputed wechseln, da die Formel Risiken nun strenger bewertet.
Komplexität: advanced
Name: Test des Stufen-Budgets bei Ausfall (D.3)
Problem: Es gilt, eine Situation mit gekürztem Budget von 5M Tokens (4,5M local / 0,5M frontier) zu simulieren und zu prüfen, wie das System einen 45-minütigen Ausfall der lokalen Stufe übersteht, sodass token_health_min nicht unter 0,5 fällt.
Lösung: 1. Wechseln Sie nach cd book2/examples/budget-keeper.
- Kompilieren Sie den Plan: python3 scripts/compile.py --budget-spec specs/budget_network_5m.yaml --out out/budget_plan_5m.json.
- Starten Sie die Ausfallsimulation: python3 scripts/simulate.py --plan out/budget_plan_5m.json --scenario scenarios/fail_local_45m.json --out out/fail_result_5m.json.
- Überprüfen Sie die Invarianten: python3 scripts/inspect.py --result out/fail_result_5m.json --query "failover_to_frontier==2 && degraded_queue==18 && token_health_min>=0.5".
- Stellen Sie sicher, dass Budgetänderungen ohne Aktualisierung der Phasenkontingente einen Fehler verursachen (compile.py schlägt fehl).
Komplexität: intermediate
Name: Umgehen der Goodhart-Metrik-Schutzmaßnahmen (D.4)
Problem: In der Praxis überprüfen, wie die Schwächung von nur zwei unabhängigen Schutzmaßnahmen (z. B. manual_review_rate und silent_p0) es ermöglicht, ein schlechtes Release „durchzudrücken", das eigentlich hätte blockiert werden müssen.
Lösung: 1. Wechseln Sie nach cd book2/examples/goodhart-validator.
- Schwächen Sie den Schwellenwert silent_p0 von 0,05 auf 0,08 in der lokalen Kopie der Spezifikation.
- Starten Sie die Validierung (das Skript sollte „rot" bleiben, da die Metrik 0,18 immer noch über 0,08 liegt).
- Erstellen Sie eine „gefährliche" Konfiguration, indem Sie zwei Schwellenwerte gleichzeitig schwächen (z. B. edge_drift auf 0,10 und silent_p0 auf 0,20).
- Starten Sie die Validierung mit schlechten Metriken (fixtures/new_metrics_bad.json) – das System besteht die Prüfung, was beweist, dass punktuelle Kalibrierung nicht zulässig ist.
Komplexität: advanced
Fallstudien: Name: Anormaler Anstieg verpasster kritischer Vorfälle (P0)
Szenario: In einem großen Finanzprojekt (hohes Risikoprofil) führte das Team einen automatisierten SDD-Prozess ein. Anfangs wurden die Standard-Schwellenwerte von AgentClinic verwendet: silent_p0 ≤ 5 % und manual_review_rate ≥ 15 %. Mit der Zeit begannen die Entwickler, sich über die Verlangsamung der CI-Pipeline aufgrund manueller Prüfungen zu beschweren.
Aufgabe: Zur Beschleunigung des Prozesses wurde der Schwellenwert manual_review_rate auf 8 % gesenkt (Parameter „Niedrig"), während silent_p0 bei 5 % blieb. Dies führte dazu, dass das System begann, neue Klassen von Vorfällen zu verpassen, die nicht in der historischen Datenbasis enthalten waren (Schattenspezifikationen). Die MTTR-Metrik sank formal, aber die Anzahl katastrophaler P0-Verluste stieg (Symptom von Goodharts Gesetz).
Lösung: Die SRE-Ingenieure kehrten zum Prinzip der paarweisen Kalibrierung zurück. Der Schwellenwert manual_review_rate wurde auf 15 % zurückgesetzt. Gleichzeitig wurde das Budget für Hinweis-Beispiele auf 12 Slots erhöht (Stufe „Hoch"), um die Belastung zu kompensieren. Alle Änderungen wurden in validation.md dokumentiert.
Ergebnis: Die Anzahl verpasster P0 kehrte auf zulässige Werte zurück (< 1–2 %). Der Prozess stabilisierte sich, das System klassifizierte strittige Fälle durch die Wiederherstellung des Gleichgewichts zwischen Automatisierung und manueller Kontrolle wieder korrekt.
Gewonnene Erkenntnisse: Die Senkung des Anteils manueller Prüfungen ohne Berücksichtigung der Dynamik des eingehenden Stroms führt zu einem Anstieg von P0-Verlusten.
Die Metriken MTTR und manual_review_rate haben eine negative Wechselbeziehung; sie dürfen nur paarweise geändert werden.
Prozessbeschleunigung darf nicht durch Schwächung der Guard-Metriken erreicht werden.
Verwandte Konzepte: Schutz von Metriken vor Goodhart (D.4)
Paarweise Schwellenwertkalibrierung
Preis eines P0-Verlusts
Name: Servicedegradation bei Ausfall der lokalen LLM-Stufe
Szenario: Eine E-Commerce-Plattform mit 600 Vorfällen pro Tag verwendete ein Budget von 10M Tokens mit Aufteilung 90 % auf local-coder und 10 % auf frontier. Dies entsprach dem Profil „Standard", aber der tatsächliche Strom gehörte zur Kategorie „Hoch".
Aufgabe: Während eines saisonellen Verkaufs begann der lokale LLM-Anbieter regelmäßig (wöchentlich) auszufallen. Die Reserve von 1M Tokens auf der frontier-Stufe war in wenigen Minuten erschöpft. Das ausgelöste Failover versetzte das System in den Modus degraded_queue, was zu stundenlangen Verzögerungen bei der Wiederherstellung kritischer Dienste führte.
Lösung: Es wurde eine Neuberechnung der Stufen-Budgets (Abschnitt D.3) vorgenommen. Das Gesamtbudget wurde auf 25M Tokens erhöht und das Verhältnis auf 80/20 geändert. Für die Stufe local wurde ein duplizierter Anbieter hinzugefügt. Die Spezifikationen budget_plan_phases wurden aktualisiert, damit die frontier-Stufe alle „strittigen" Fälle bei einem Ausfall des Hauptanbieters aufnehmen kann.
Ergebnis: Beim nächsten Ausfall des lokalen Clusters wechselte das System reibungslos auf frontier. token_health_min fiel nicht unter 0,5, und die Benutzerbedienung wurde nicht unterbrochen.
Gewonnene Erkenntnisse: Das Token-Budget und die Anteile local/frontier müssen dem tatsächlichen Spitzen-Incident-Strom entsprechen.
Die Aufteilung 9M/1M ist starr an die SLA nach Phasen gebunden; eine Änderung der Anteile erfordert eine Aktualisierung der Spezifikationen.
Bei wöchentlichen Ausfällen von local-coder muss die Reserve mindestens 15–20 % betragen.
Verwandte Konzepte: Stufen-Budgets (D.3)
CI-SLA-Fenster
Empfindlichkeit gegenüber Ausfall von local-coder
Lerntipps: Ändern Sie Schwellenwerte nicht beim ersten Lesen: Das Lernminimum jedes Kapitels ist auf Standard-Schwellenwerte ausgelegt. Beginnen Sie mit der Kalibrierung erst, wenn die Standardwerte für Ihren Strom nicht mehr passen.
Suchen Sie nach Goodhart-Symptomen: Wenn sich eine Metrik (z. B. strict_reject_rate oder MTTR) beständig verbessert, während die damit verbundene Metrik (depth_of_diagnostics oder manual_review_rate) sinkt, optimieren Sie den Prozess nicht, sondern brechen Sie das Schutzsystem.
Dokumentieren Sie jede Änderung: Jede Verschiebung einer Zeile in den Tabellen muss von einem Eintrag in validation.md mit klarer Begründung begleitet sein (Preis des Verlusts hat sich geändert, Strom ist gewachsen usw.).
Visualisieren Sie Abhängigkeiten: Verwenden Sie Mermaid-Diagramme (wie in Abschnitt D.4), um zu verstehen, wie sich eine Änderung an einem Knoten (z. B. audit_trace_coverage) auf den gesamten Metrik-Graphen auswirkt.
Zusätzliche Ressourcen: Kapitel 5, 6, 9, 10, 11 (Grundkurs): Basiskontext zum Verständnis der Prozesse, für die in Anhang D die Schwellenwerte konfiguriert werden.
Datei validation.md: Vorlage zur Dokumentation der Begründungen für Schwellenwertverschiebungen. Bei der Übertragung des Prozesses in Ihr eigenes Projekt zwingend zu verwenden.
Repository book2/examples/: Enthält die Quellskripte immunity_score.py, score.py, compile.py sowie die Konfigurationsdateien JSON/YAML zur Durchführung der Übungen.
Zusammenfassung: Anhang D ist ein tiefer Einstieg in die Feinabstimmung der Schwellenwerte von AgentClinic-Production. Die wichtigste Erkenntnis: Schwellenwerte existieren nie im Vakuum. Jede Kalibrierung ist ein Abwägen von Risiken. Sie können nicht einfach den Schwellenwert für manuelle Reviews senken, um die Pipeline zu beschleunigen, ohne gleichzeitig den Schutz vor P0-Verlusten zu verstärken. Sie können das Token-Budget nicht ändern, ohne die SLA der Phasen zu überarbeiten. Der erfolgreiche Betrieb des Systems erfordert eine kontinuierliche Überwachung der Indikatoren (z. B. den Anteil strittiger Reviews oder die Kosten falscher Eskalationen) und eine rechtzeitige, paarweise Überarbeitung der Konfigurationen.