Routing

Router wählt für jede Anfrage einen Checkpoint und lädt seinen Agent, wenn eine Vorhersage ihn braucht. Der Standardrouter schickt englischen Text an den englischen Checkpoint und andere unterstützte Sprachen an den mehrsprachigen Checkpoint. Du kannst diese Wahl überschreiben, einen eigenen Sprachhinweis mitgeben oder den typed-decisions-Checkpoint explizit auswählen.

Diese Anleitung behandelt Modellauswahl und Lebenszyklus. Die von der Vorhersage akzeptierten Fragetypen findest du unter Schema-gesteuerte Entscheidungen; Lebenszyklus-Callbacks unter Vorhersage-Hooks.

Erste Schritte

from laya import Router

router = Router()

questions = {
    "department": {
        "type": "choice",
        "instructions": "Which department should handle this request?",
        "criteria": {
            "billing": "invoices, payments, refunds",
            "technical": "bugs, outages, system errors",
            "other": "everything else",
        },
    }
}

result = router.predict("We were billed twice. Please refund the duplicate charge.", questions)
print(result["answers"]["department"]["choice"])
print(result["routing"]["model"])

Das Erzeugen von Router() lädt standardmäßig keine Checkpoints herunter. predict() routet die Anfrage und lädt den gewählten Checkpoint dann bei der ersten Verwendung. Die erste Vorhersage kann daher länger dauern, während Dateien heruntergeladen und das Modell initialisiert wird; spätere Vorhersagen verwenden den geladenen Agent erneut.

Wie ein Checkpoint ausgewählt wird

Router.route(state, questions, ...) gibt eine RouteDecision zurück, ohne einen Checkpoint zu laden oder Inferenz auszuführen. Die Entscheidung enthält das gewählte Modell, einen für Menschen lesbaren Grund und Details zur Spracherkennung, wenn die eingebaute Erkennung verwendet wurde.

Das Routing prüft die Eingaben in dieser Reihenfolge:

model= wählt einen Checkpoint direkt aus.
task= wählt einen Checkpoint für die benannte Aufgabe aus.
Bei auto_task_detection=True wählt eine exakte Übereinstimmung mit einem der bekannten typed-decisions-Frage-ID-Sets typed-decisions aus.
Ein erkannter lang=-Wert wählt Englisch oder mehrsprachig aus.
Ein lang_guess= pro Aufruf oder das konfigurierte lang_guess des Routers wird herangezogen.
Eine eingebaute Skript- und Sprachanalyse wählt einen Checkpoint aus. Gibt es kein verlässliches Sprachsignal, verwendet der Router seinen konfigurierten default (standardmäßig Englisch).

Die erste passende Regel gewinnt. Zum Beispiel überschreibt model="multilingual" das lang="en". Ungültige Modellnamen lösen ValueError aus, statt in die Erkennung durchzufallen.

decision = router.route(
    "La aplicación se cierra cada vez que abro la configuración.",
    questions,
)
print(decision.model)   # multilingual
print(decision.reason)  # why that checkpoint was selected

RouteDecision ist dict-kompatibel, also sind ihre Felder auch über Schlüssel wie decision["model"] und decision["reason"] verfügbar. Router.predict() nimmt dieselbe Entscheidung unter dem Schlüssel "routing" des Ergebnisses auf.

Sprach-Routing überschreiben

Verwende lang=, wenn die Anwendung die Sprache der Anfrage bereits kennt. Sprach-Tags wie "en", "en-US" und "en_US.UTF-8" werden akzeptiert. Englisch routet zu english; andere erkannte Sprachcodes routen zu multilingual.

result = router.predict(state, questions, lang="de")
assert result["routing"]["model"] == "multilingual"

Hat die Anwendung einen eigenen Spracherkenner, übergib sein Ergebnis als Sprachcode mit lang_guess=. Ein Callable erhält den Zustand und kann einen Code oder None zurückgeben, um sich zu enthalten:

def detect_request_language(state):
    # Replace this with the application's detector.
    return "en" if "invoice" in str(state).lower() else None

router = Router(lang_guess=detect_request_language)

Ein sich enthaltender Hinweis erzwingt keinen Checkpoint; das Routing fährt mit der nächsten Regel fort. Das deckt None, eine leere Zeichenkette und die Codes ab, die keine Sprache benennen (C, POSIX, C.UTF-8, und, zxx, mul) – genau das, was ein Erkenner zurückgibt, wenn er nichts zu sagen hat, sodass eine Enthaltung Anfragen nicht stillschweigend an das falsche Modell binden kann.

Ein nicht erkannter Hinweis ist keine Enthaltung. Jeder andere Wert, auch "xx", False und 0, wird als „nicht Englisch“ gelesen und routet zum mehrsprachigen Checkpoint. Ein Erkenner, der einen ungültigen Code statt None zurückgibt, wählt also tatsächlich einen Checkpoint aus; und wenn das zählt, ordne seinen unbekannten Fall None zu, bevor du ihn weitergibst.

Die eingebaute Erkennung ist eine leichtgewichtige Skript- und Sprachheuristik, kein universelles Spracherkennungsmodell. Sie analysiert Zeichenkettenwerte in text-, dict- und list-Zuständen; Wörterbuchschlüssel werden ignoriert, weil sie oft englische Feldnamen sind. Kurzer oder mehrdeutiger Text kann den Standard-Checkpoint verwenden. Für bekannte Arbeitslasten sind eine explizite Sprache oder ein von der Anwendung bereitgestellter Hinweis vorhersehbarer.

Typed-decisions auswählen

Der typed-decisions-Checkpoint wird standardmäßig nicht automatisch ausgewählt. Wähle ihn explizit aus:

result = router.predict(state, questions, model="typed-decisions")
# `task="typed_decisions"` is also accepted.

Alternativ setzt du auto_task_detection=True. Der Router prüft dann, ob die Frage-IDs exakt mit einem seiner bekannten typisierten Entscheidungs-Workflows übereinstimmen. Er leitet die Aufgabe nicht aus der Formulierung der Frage ab, und das Hinzufügen unzusammenhängender Frage-IDs verhindert eine exakte Übereinstimmung.

router = Router(auto_task_detection=True)

Routing prüfen, ohne Modelle zu laden

Verwende route(), um eine einzelne Entscheidung zu prüfen, oder route_batch(), um eine Sequenz zu prüfen. Keine der beiden Methoden lädt Checkpoints, sodass beide nützlich sind, um Routing-Regeln zu debuggen, bevor du Inferenz ausführst.

requests = [
    {"state": "Please refund the duplicate charge.", "questions": questions},
    {"state": "Necesito ayuda con mi factura.", "questions": questions},
]

decisions = router.route_batch(requests)
for decision in decisions:
    print(decision.model, decision.reason)

Jeder Eintrag von route_batch() braucht state und questions; optionale Routing-Überschreibungen (model, task, lang und lang_guess) werden pro Eintrag angegeben. Entscheidungen bleiben in Eingabereihenfolge.

Laden und Speicher

Standardmäßig lädt der Router einen Checkpoint beim ersten Bedarf und hält höchstens zwei Agenten resident. Automatisches Sprach-Routing braucht normalerweise nur den englischen und den mehrsprachigen Checkpoint. Können Anfragen auch typed-decisions auswählen, kann ein kleines max_loaded einen anderen Agenten verdrängen und dazu führen, dass er beim nächsten Bedarf erneut geladen wird.

# Load only the checkpoints this process serves, before accepting requests.
router = Router()
router.preload(["english", "multilingual"])

print(router.loaded)  # currently resident checkpoint names
router.unload("multilingual")

Router(preload=True) lädt alle konfigurierten Checkpoints vor. Das Vorladen hebt das Limit für residente Modelle an, damit die angeforderte Menge passt. Um eine Arbeitslast mit drei Checkpoints ohne Vorladen zu steuern, setze max_loaded=3. Verwende unload(), um einen Agenten freizugeben, oder router.unload(), um alle Agenten freizugeben. Ein Router, der als Kontextmanager verwendet wird, entlädt seine Agenten, wenn der Block endet:

with Router(preload=True) as router:
    result = router.predict(state, questions)

Du kannst beim Erzeugen des Routers auch device="cpu", device="cuda" oder ein anderes unterstütztes PyTorch-Gerät übergeben. Verfügbarkeit und Speicher entscheiden, welche Geräte ein bestimmtes Modell ausführen können.

Gemischte Batches

predict_batch() akzeptiert Anfragen mit unterschiedlichen Zuständen, Modellen, Sprachen und Frage-Schemas. Der Router trifft zuerst für jede Anfrage eine Entscheidung, gruppiert die Arbeit nach Checkpoint und kompatiblem Frage-Schema und stellt die Ergebnisse dann in der ursprünglichen Eingabereihenfolge wieder her.

requests = [
    {"state": "Please refund the duplicate charge.", "questions": questions},
    {"state": "Mi cuenta fue cobrada dos veces.", "questions": questions},
    {"state": "A third request", "questions": questions, "model": "typed-decisions"},
]

results = router.predict_batch(requests, batch_size=8)

Jede Anfrage braucht state und questions; sie darf außerdem model, task, lang oder lang_guess enthalten. Anfragen, die einen Checkpoint und ein Frage-Schema teilen, können einen gemeinsamen Batch-Vorwärtspass des Agenten teilen. Unterschiedliche Schemas oder Checkpoints werden in getrennten Gruppen behandelt. batch_size begrenzt die Anzahl der Zustände, die zusammen an den Agenten übergeben werden; die Ergebnisse entsprechen weiterhin der Anfragereihenfolge.

Einen Einstiegspunkt wählen

Verwende route() oder route_batch(), wenn du Entscheidungen prüfen musst, ohne Modelle zu laden.
Verwende predict() für eine einzelne Anfrage und predict_batch() für mehrere, möglicherweise heterogene Anfragen.
Verwende Agent direkt, wenn die Anwendung bereits einen Checkpoint gewählt und geladen hat und kein automatisches Routing braucht.

Siehe die Router-API-Referenz für Details zu Konstruktor und Methoden.