jevlaya
Deutsch
Dokumentation

Schrittweise Einführung

Laya gibt eine typisierte Entscheidung zurück, keine Erlaubnis, sie auszuführen. Führe eine Entscheidungs-Engine schrittweise ein, damit die Anwendung die Kontrolle über die eigentliche Aktion behält, während Evidenz anwächst.

Dieser Leitfaden beschreibt den anwendungsseitigen Rollout rund um Laya. Laya liefert die Entscheidung, Wahrscheinlichkeiten, Konfidenz und Hook-Events; die Anwendung besitzt die bestehende Aktion, die Rollout- Policy, die Review-Grenze und das Rollback.

1. Schatten: beobachten ohne Nebenwirkungen

Führe Laya auf repräsentativem echten Verkehr aus, aber halte die bestehende Aktion maßgeblich. Ein Schatten- Datensatz sollte genug Kontext enthalten, um später einen Vergleich zu reproduzieren:

  • die Request-Klasse und das Laya-Frage-Schema;
  • Layas Antwort, Wahrscheinlichkeiten pro Option, Konfidenz, Checkpoint und run_id;
  • die bestehende Aktion und das letztendliche geprüfte oder Ground-Truth-Ergebnis;
  • Latenz, Fehler und jede Fallback- oder Review-Entscheidung.

Nutze die vorhandenen Vorhersage-Hooks für Laya-seitige Evidenz. Die Logging-Funktionen unten sind anwendungseigene Platzhalter; sie sind keine Laya-APIs:

from laya import Router

class ShadowLog:
    def on_predict_end(self, ctx):
        result = ctx.results[0] if ctx.results else None
        write_shadow_record({
            "run_id": ctx.run_id,
            "model": ctx.model,
            "decision": ctx.decision,
            "result": result,
            "elapsed_ms": ctx.elapsed_ms,
            "error": None if ctx.error is None else repr(ctx.error),
        })

router = Router(hooks=[ShadowLog()])

def handle(request):
    try:
        laya_result = router.predict(request.state, request.questions)
    except Exception as exc:
        record_laya_failure(request, exc)
        return run_incumbent_action(request)
    # The shadow result is recorded by the hook; do not execute it here.
    return run_incumbent_action(request)

Halte sensible Felder gemäß der Policy der Anwendung redigiert. Fange und protokolliere Exceptions rund um router.predict(...) an der Anwendungsgrenze. Der Vorhersage-Hook deckt den Vorhersage- Lebenszyklus ab, aber Fehler vor diesem Lebenszyklus brauchen eine Erfassung auf Anwendungsebene; nimm nicht an, dass on_predict_end sie gesehen hat. Ein Schatten-Logger darf Logging nicht in eine neue nutzerseitige Aktion verwandeln.

Siehe Vorhersage-Hooks, den Hook-Lebenszyklus und Tracing für die Ereignisreihenfolge und die run_id-Korrelation.

2. Vergleichen: Uneinigkeit ist ein Signal, kein Urteil

Vergleiche Laya mit der bestehenden Aktion bei derselben Anfrage und derselben Fragebedeutung. Eine Uneinigkeit ist nicht automatisch ein Fehler: Die bestehende Aktion kann falsch sein, die Fälle können mehrdeutig sein, oder die Aktion kann menschliches Urteil erfordern. Nutze geprüfte Labels oder Ground-Truth-Ergebnisse, wo verfügbar, und halte einen expliziten unknown- oder Review-Bucket, statt jede Uneinigkeit in einen binären Score zu zwingen.

Prüfe Vergleiche nach Checkpoint, Sprache oder Route, Frage-Schema, Aktionstyp und Risikoklasse. Erfasse Coverage und Uneinigkeit neben der Genauigkeit. Eine hohe Übereinstimmungsrate auf einer einfachen Teilmenge rechtfertigt keine Beförderung für eine andere Sprache, Aktion oder Frageform.

3. Eine Policy aus zurückgehaltener Evidenz wählen

Ein Konfidenz-Schwellenwert ist eine Anwendungs-Policy, keine von Laya gelieferte Eigenschaft. Fitte oder kalibriere die Entscheidungs-Scores auf repräsentativen zurückgehaltenen Daten und wähle dann einen Schwellenwert aus der gemessenen Genauigkeit und den Fehlerkosten bei der Coverage, die deine Anwendung tolerieren kann. Es gibt keine universelle Zahl, die über Checkpoints, Fragetypen, Sprachen oder Aktionsrisiken hinweg überträgt.

Notiere Checkpoint und Frage-Schema-Version, Kalibrierungsmethode, Schwellenwert, Evaluierungssatz und Owner zusammen mit der Policy. Evaluiere sie neu, wenn sich diese Eingaben ändern. Konfidenz ordnet Entscheidungen; sie belegt nicht, dass eine Entscheidung korrekt ist, und hohe Konfidenz ist für sich genommen nie eine Ausführungserlaubnis.

Vier dieser sechs kommen aus dem Evaluierungs-Harness: ein laya-evals run --json-Bericht erfasst den Checkpoint-Commit, der geantwortet hat (config.revisions), die Bytes und das Frage-Schema des Datensatzes (config.dataset_sha256, config.questions_sha256) und das Gate, unter dem bewertet wurde (config.thresholds). Kalibrierungsmethode und Owner sind von der Anwendung zu erfassen. Siehe Evaluierungs-Harness für die Lauf-Identität und die Vergleichbarkeitsprüfung zwischen einer Baseline und einem Kandidaten.

Die README-Abschnitte Automated Confidence Gating, Calibration und Honest limits geben den vorhandenen Kalibrierungs- und Konfidenz-Kontext. Halte irreversible oder teure Aktionen hinter einer expliziten Review-Grenze, auch wenn ihre Konfidenz hoch ist.

4. Einen begrenzten Ausschnitt befördern

Eine Beförderung sollte eine gemessene, reversible Änderung sein, kein globaler An/Aus-Schalter. Definiere eine Eligibility-Grenze, bevor du Automatisierung aktivierst, zum Beispiel:

  • der Checkpoint, Sprache/Route und das Frage-Schema liegen im evaluierten Satz;
  • die Aktion ist reversibel oder hat einen expliziten Weg zum menschlichen Review;
  • der Anfrage fehlt kein erforderlicher Kontext und es gibt keinen Laya-Fehler;
  • der Ausschnitt hat eine Größen- oder Verkehrsobergrenze und eine benannte Rollback-Bedingung.

Beginne mit einem kleinen Canary. Behalte Review oder Fallback für ungeeignete, mehrdeutige und fehlgeschlagene Fälle. Fahre fort, beförderte Entscheidungen zu samplen, vergleiche sie mit der bestehenden Aktion und den geprüften Ergebnissen, und überwache Uneinigkeit, Coverage, Fallback-Rate, Fehler und Latenz. Rolle zurück, wenn die vereinbarte Leitplanke verletzt wird; die Beförderung ist ein begrenzter Schritt, keine dauerhafte Erklärung, dass das Modell korrekt ist.

Grenze zwischen Anwendung und Laya

Laya liefert die Entscheidungs-Evidenz und legt sie über die vorhandene API und Hooks offen. Die Anwendung besitzt das bestehende Ergebnis, die Aktionsausführung, Eligibility-Regeln, Schwellenwert, Review, Fallback und Rollback. Hooks können Evidenz protokollieren oder annotieren, aber sie machen eine wirkungsvolle Aktion nicht sicher auszuführen.

Ein praktischer Rollout ist daher:

real request
    ├─ incumbent action (authoritative)
    └─ Laya shadow decision ──> log, compare, evaluate
                                  └─ bounded eligible slice
                                      └─ review / fallback / rollback

Rollout-Checkliste

  • Schatten-Logging ist nebenwirkungsfrei und über run_id korreliert.
  • Die Vergleichsdaten enthalten das Ergebnis der bestehenden Aktion und geprüfte oder Ground-Truth-Labels, wo verfügbar.
  • Schwellenwerte sind auf repräsentativen zurückgehaltenen Daten gefittet und validiert.
  • Irreversible oder teure Aktionen haben eine explizite Review-Grenze.
  • Die Beförderung ist begrenzt, gesampelt und reversibel, mit einem benannten Fallback- und Rollback-Pfad.
  • Der Policy-Owner und der Auslöser zur Neuevaluierung sind erfasst.

Siehe auch