Router

Router(
    models: Optional[Dict[str, str]] = None,
    device: Optional[str] = None,
    token: Optional[str] = None,
    revision: Optional[str] = None,
    revisions: Optional[Dict[str, Optional[str]]] = None,
    max_loaded: int = 2,
    default: str = "english",
    auto_task_detection: bool = False,
    standalone_repos: bool = False,
    preload: bool = False,
    lang_guess: Optional[Any] = None,
    hooks=None,
    on_predict_start=None,
    on_predict_end=None,
    hooks_raise: bool = True,
    hooks_concurrent: bool = True,
    hooks_timeout: Optional[float] = None,
    agent_kwargs: Optional[Dict[str, Any]] = None,
    sha256_digests: Optional[Dict[str, Optional[Dict[str, str]]]] = None,
)

Lädt Laya-Checkpoints lazy und schickt jede Anfrage an den richtigen.

from laya import Router

r = Router()
r.predict({"message": "Mein Konto wurde zweimal belastet"}, questions)   # -> multilingual
r.predict({"message": "I was charged twice"}, questions)                 # -> english
r.predict(state, questions, model="typed-decisions")                     # explicit

Modelle werden beim ersten Einsatz heruntergeladen und gebaut. max_loaded begrenzt, wie viele resident bleiben (der am wenigsten zuletzt genutzte wird verdrängt), weil alle drei zusammen ~1,16 Mrd. Parameter sind.

Der Standard ist 2, weil das automatische Routing immer nur zwischen english und multilingual wählt: ein Deckel von eins baut den gerade verdrängten Checkpoint bei jedem Sprachwechsel neu, was Sekunden pro Anfrage kostet, genau auf dem Verkehr, für den der Router existiert. Verkehr, der nur jemals eine Sprache sieht, baut den zweiten Checkpoint nie, der Standard kostet ihn also nichts. Senke ihn auf 1 für einen speicherbeschränkten Host und erhöhe ihn auf 3 (oder lade vor), wenn auto_task_detection, ein explizites model= oder ein explizites task= auch typed-decisions erreichen kann.

Für einen Server oder eine Demo lade stattdessen vor: ein Kaltstart kostet Sekunden, während die Erkennung Mikrosekunden kostet, selbst der Standard zahlt also ein Laden, wenn eine Sprache zum ersten Mal auftaucht.

r = Router(preload=True)                    # all three resident, routing is free
r = Router(preload=True, device="cuda")
r.preload(["english", "multilingual"])      # or just the two you serve

Hub-Revisionen sind opt-in. revision wendet einen Commit auf jedes Modell an; revisions={"english": "...", "multilingual": "..."} überschreibt das pro Modell, was nützlich ist, wenn eigenständige Repositories bei unterschiedlichen Commits geprüft wurden. Ohne beides werden der normale Standard von huggingface_hub und der vorhandene Offline-Cache verwendet.

Ein revisions-Eintrag, der None oder leer ist, bedeutet "kein Override für dieses Modell", das Modell erbt also revision -- die Form, die {"english": os.environ.get("EN_SHA")} schreibt, wenn die Variable ungesetzt ist, was dem Aufrufer nicht den Pin kosten darf, den er angefordert hat. Nichts in revisions kann ein Modell lösen, während revision die übrigen pinnt; lass revision ungesetzt und benenne stattdessen die Modelle, die du pinnen willst.

Ein leeres revision wird genauso gelesen, was eine bewusste Änderung dessen ist, was der Router weitergibt: Router(revision=" ") erreichte früher resolve_revision, wo ein wahrheitswertiger, aber leerer String den LAYA_REVISION-Fallback unterdrückte und den Standard von huggingface_hub ließ, und wird jetzt fallen gelassen, bevor er dort ankommt, sodass ein mit Leerzeichen konfigurierter Router sich wie einer ohne Konfiguration verhält und $LAYA_REVISION gilt. Das ist es, was "diese Konfigurationszeile wurde nie ausgefüllt" bedeuten muss, wenn revision und ein revisions-Eintrag gleich gelesen werden sollen.

Es ist einer von zwei Orten, an denen eine schwächere Quelle vor einem expliziten Argument landet. Der andere ist ein Per-Checkpoint-Digest-Eintrag aus LAYA_SHA256_DIGESTS, der ein über agent_kwargs übergebenes expected_sha256 schlägt; siehe den Klassen-Docstring.

Alles andere, was laya.Agent akzeptiert, ist über agent_kwargs erreichbar, das in jeden Checkpoint eingemischt wird, den der Router baut:

Router(agent_kwargs={"lang_temperatures": {"de": {"temperature": [1.0, 1.4, 2.0]}}})
Router(agent_kwargs={"expected_sha256": {"model.safetensors": "a3f1..."}})
Router(agent_kwargs={"fast": True})

expected_sha256 dort pinnt dieselben Dateien auf jedem Checkpoint, was ein einzelner residenter Checkpoint oder eine gemeinsame tokenizer.json will. Es wird nie pauschal von den eigenen Digests eines Checkpoints verworfen: wo einer ebenfalls einen Eintrag hat, aus sha256_digests oder aus per-checkpoint LAYA_SHA256_DIGESTS, werden die beiden Maps Datei für Datei zusammengeführt, sodass eine Datei, die nur eine von ihnen nennt, trotzdem verifiziert wird.

Zwei Ausnahmen, beide bewusst und beide getestet, weil "Datei für Datei zusammengeführt" nicht die ganze Geschichte ist und der Unterschied eine Supply-Chain-Kontrolle:

• Ein flaches LAYA_SHA256_DIGESTS -- {artifact: digest} statt {model: {...}} -- ist hier gar keine Schicht. verify_digests wendet es selbst an, aber nur, wenn nichts anderes pinnt (if expected is None), also bedeutet JEDES expected_sha256, das Agent erreicht, von hier oder von einem Checkpoint-Eintrag, dass die flache Variable für diesen Ladevorgang nicht herangezogen wird. An echten Dateien verifiziert: eine flache Variable, die model.safetensors pinnt, plus eine agent_kwargs-Map, die tokenizer.json pinnt, lädt ein manipuliertes model.safetensors. Nutze die Per-Checkpoint-Form oder benenne jede Datei, die dir wichtig ist, in einer Map, wenn du beides brauchst. Dies ist unverändert gegenüber main.
• Ein expliziter {}- oder None-Eintrag MASKIERT, was sonst gelten würde -- das ist es, was "dieses eine unverifiziert laden" bedeuten muss, und test_an_explicit_none_entry_masks_a_flat_environment_map pinnt es.

Und die Rangfolge ist per Checkpoint vor gemeinsam, egal woher jedes stammt, sodass ein per-checkpoint-Eintrag, der aus LAYA_SHA256_DIGESTS synthetisiert wurde, ein hier im Code übergebenes expected_sha256 schlägt. Eine Umgebungsvariable, die ein explizites Argument schlägt, ist bei einer Kontrolle wie dieser wert, klar ausgesprochen zu werden; test_an_environment_pin_overrides_the_shared_one_per_checkpoint ist, wo das gepinnt wird.

Für eine Datei, die beide nennen, gewinnt der Per-Checkpoint-Eintrag. Die beiden sind nicht gleich spezifisch: die agent_kwargs-Map erreicht jeden Checkpoint, den der Router baut, und model.safetensors ist der eine Name, den jeder Checkpoint für eine andere Datei verwendet, ein gemeinsamer Eintrag dafür kann also keine korrekte Aussage über alle auf einmal sein. Über diese Überlappung wird nichts ausgelöst -- sie abzulehnen würde einen gemeinsamen Pin plus ein Per-Checkpoint-Override zurückweisen, was die gewöhnliche Form ist und was korrekt geladen wurde, bevor irgendetwas davon existierte. Wenn du wissen musst, gegen welchen Digest ein Checkpoint verifiziert wurde, lies es zurück: die an jeden Agent übergebene Map ist die oben beschriebene Zusammenführung.

Sowohl agent_kwargs als auch sha256_digests sind öffentlich und veränderbar, und der Eintrag eines Checkpoints wird beim Laden gelesen, nicht bei der Konstruktion, ein danach zugewiesener Pin -- oder ein in einen bestehenden Eintrag an Ort und Stelle hinzugefügter -- zählt also.

Die Namen, die der Router für sich selbst setzt -- model_id_or_path, device, token, subfolder, revision und die Hook-Argumente -- werden hier abgelehnt, statt still überschattet, und die übrigen Namen werden beim Erstellen gegen Agent.__init__ geprüft, eine falsch geschriebene Option scheitert also in der Router(...)-Zeile statt bei der ersten Anfrage.

Artefakt-Digests sind opt-in und immer pro Modell: sha256_digests={"english": {...}} übergibt diese {path relative to the checkpoint dir: hexdigest}-Map an den Agent, der sie lädt, eine manipulierte oder ersetzte Gewichtsdatei wird also abgelehnt, bevor sie geparst wird. Es gibt kein Router-weites Gegenstück zu revision, weil Digests, anders als ein Commit-SHA, nicht teilbar sind: das gebündelte Repository liefert eine separate model.safetensors für jede von english, multilingual und typed-decisions, eine flache Map kann also immer nur eine davon treffen. Ein mit None oder {} gelistetes Modell fügt keine eigenen Dateien hinzu, was es unverifiziert lädt, es sei denn agent_kwargs["expected_sha256"] pinnt es; es maskiert weiterhin eine flache LAYA_SHA256_DIGESTS, und genau dafür listet man es so auf.

Dieselbe Aufteilung steht einem nur per Umgebung konfigurierten Prozess zur Verfügung: wenn LAYA_SHA256_DIGESTS eine modellverschlüsselte Map hält ({"english": {...}, "multilingual": {...}}), seeds sie diese pro Checkpoint, ein Server, der mehrere resident hält, kann also jeden mit seinen eigenen Digests pinnen, statt beim zweiten den Start zu verweigern. Eine flache LAYA_SHA256_DIGESTS behält ihre bestehende Bedeutung, angewendet von laya.revisions auf jeden Checkpoint, den der Prozess lädt, was für einen mit einem einzigen Checkpoint richtig ist. Ein Argument-Eintrag gewinnt über die Umgebung für das Modell, das er nennt. Eine verschachtelte Variable, die einige Checkpoints nennt und andere nicht, sagt nichts über die anderen: sie behalten, womit agent_kwargs["expected_sha256"] sie pinnt, denn einen Checkpoint aus der Umgebung zu pinnen ist keine Aufforderung, den Rest nicht mehr zu verifizieren.

Hooks sind opt-in und laufen auf Router-Ebene: on_route sieht die Routing-Entscheidung, on_load / on_evict sehen den Modell-Lebenszyklus, und on_predict_start / on_predict_end umhüllen den gesamten route+infer-Aufruf. Siehe laya.hooks.

load(name: str)

Gibt den Agent für name zurück und lädt und baut ihn beim ersten Einsatz.

Gleichzeitige Aufrufer teilen einen einzigen Agent, statt Duplikate zu bauen.

attach(name: str, agent: Any)

Registriert einen bereits gebauten Agent unter name, statt eine zweite Kopie zu laden.

Nützlich, wenn der Prozess aus anderen Gründen einen Checkpoint geladen hat: eine Demo, die convaiinnovations/laya bereits gebaut hat, kann ihn dem Router übergeben, statt für -- und im Speicher zu halten -- ein Duplikat mit 421 Mio. Parametern zu zahlen.

preload(names: Optional[List[str]] = None)

Lädt Checkpoints vorab herunter und baut sie, damit keine Anfrage je ein Modellladen zahlt.

Ein Kaltstart kostet Sekunden; die Spracherkennung kostet Mikrosekunden. Mit jedem residenten Checkpoint ist das Routing praktisch gratis -- was du in einem Server oder einer Demo willst. max_loaded wird erhöht, um sowohl die angeforderten Checkpoints als auch alle bereits residenten Agents aufzunehmen, sodass inkrementelles Vorladen keinen von beiden verdrängt.

unload(name: Optional[str] = None)

Gibt ein Modell frei, oder alle.

loaded_revisions: Dict[str, Optional[str]]

Commit-SHA, aus dem jeder residente Agent geladen wurde (None für lokale Pfade).

route(
    state: Union[str, dict, list, None],
    questions: Optional[Dict[str, Any]] = None,
    model: Optional[str] = None,
    task: Optional[str] = None,
    lang: Optional[str] = None,
    lang_guess: Optional[Any] = None,
    hooks=None,
    hooks_raise: Optional[bool] = None,
    hooks_timeout: Optional[float] = None,
) -> RouteDecision

Entscheidet, welcher Checkpoint verwendet wird, und lässt dann on_route-Hooks ihn beobachten oder ersetzen.

ctx.decision ist die RouteDecision; ein Hook kann sie ersetzen (zum Beispiel, um einen Checkpoint zu pinnen), und die Ersetzung ist das, was zurückgegeben und verwendet wird. hooks sind Hooks pro Aufruf, angehängt nach den auf dem Router installierten.

predict(
    state: Union[str, dict, list],
    questions: Dict[str, Any],
    model: Optional[str] = None,
    task: Optional[str] = None,
    lang: Optional[str] = None,
    lang_guess: Optional[Any] = None,
    hooks=None,
    on_predict_start=None,
    on_predict_end=None,
    hooks_raise: Optional[bool] = None,
    hooks_timeout: Optional[float] = None,
    max_len: Optional[int] = None,
    head_max_len: Optional[int] = None,
    min_confidence: Optional[float] = None,
) -> Dict[str, Any]

Routet und beantwortet dann jede Frage in einem Forward-Pass auf dem gewählten Checkpoint.

Das Ergebnis ist die übliche system_one-Nutzlast plus ein routing-Schlüssel, der die Entscheidung aufzeichnet. Hooks on_predict_start / on_predict_end auf Router-Ebene umhüllen den gesamten route+infer-Aufruf und sehen ctx.decision; siehe laya.hooks. max_len / head_max_len überschreiben das Token-Budget des Agent für diesen Aufruf (ein Start-Hook kann ctx.max_len / ctx.head_max_len setzen).

predict_long(
    state: Union[str, dict, list],
    questions: Dict[str, Any],
    model: Optional[str] = None,
    task: Optional[str] = None,
    lang: Optional[str] = None,
    lang_guess: Optional[Any] = None,
    window: Optional[int] = None,
    stride: Optional[int] = None,
    aggregate: str = "auto",
    batch_size: Optional[int] = None,
    hooks=None,
    on_predict_start=None,
    on_predict_end=None,
    hooks_raise: Optional[bool] = None,
    hooks_timeout: Optional[float] = None,
) -> Dict[str, Any]

Routet und scannt dann jedes Fenster des Zustands, statt nur das erste.

predict bewertet einen Zustand aus einem einzigen Fenster: alles jenseits von max_len wird abgeschnitten (das erste Fenster, oder bei einer Gesprächsliste das letzte) und erreicht das Modell nie. Dies routet genau wie predict -- dieselben model/task/lang-Hinweise, dieselben Hooks auf Router-Ebene, derselbe routing-Schlüssel und usage -- und bewertet den gerouteten Zustand mit dem predict_long dieses Agent, das ihn in überlappende Fenster teilt und pro Frage aggregiert. Die Aggregationsregeln sind die von laya.agent.Agent.predict_long: noul nimmt das stärkste Fenster, choice/score das sicherste.

Hooks pro Aufruf (hooks, on_predict_start, on_predict_end, hooks_raise, hooks_timeout) umhüllen den gesamten route+scan genau so, wie sie predict umhüllen: der Scan läuft zuletzt, ein Start-Hook, der antwortet (ctx.skip(...)) oder den Zustand umschreibt, gewinnt also. max_len / head_max_len werden hier nicht akzeptiert -- ein Fenster wird durch window oder das Checkpoint-Budget bemessen, und das Überschreiben der Einzelfenster-Truncation ist genau das, wofür predict_long da ist.

decide(
    state: Union[str, dict, list],
    schema: Any = None,
    questions: Optional[Dict[str, Any]] = None,
    return_details: bool = False,
    min_confidence: Optional[float] = None,
    predict_kwargs,
) -> Any

Beantwortet state gegen ein Schema (JSON-Schema oder Pydantic-Modell) und gibt typisierte Werte zurück.

Siehe laya.structured. Übergib genau eines von schema oder questions; zusätzliche Schlüsselwortargumente (zum Beispiel model=, task=, hooks=) werden an predict weitergegeben.

decide_batch(
    states: Sequence[Any],
    schema: Any = None,
    questions: Optional[Dict[str, Any]] = None,
    return_details: bool = False,
    min_confidence: Optional[float] = None,
    predict_kwargs,
) -> List[Any]

Beantwortet viele Zustände gegen ein Schema (JSON-Schema oder Pydantic-Modell) in einem gebatchten Aufruf.

Die Durchsatz-Form von :meth:decide: das Schema wird einmal geplant und seine Fragen laufen über jeden Zustand durch :meth:predict_batch (gruppierte Forward-Pässe, Ergebnisse in Eingabereihenfolge), dann werden die Antworten jedes Zustands projiziert wie bei decide. Zusätzliche Schlüsselwort- argumente (batch_size=, model=, hooks=, ...) werden an predict_batch weitergegeben. Siehe laya.structured.

route_batch(
    requests: Sequence[Dict[str, Any]],
    hooks_timeout: Optional[float] = None,
    hooks=None,
    hooks_raise: Optional[bool] = None,
) -> List[RouteDecision]

Routet einen heterogenen Anfrage-Batch, ohne Checkpoints zu laden.

Jede Anfrage ist ein Mapping mit state und questions plus denselben optionalen Routing-Überschreibungen, die :meth:route akzeptiert: model, task, lang und lang_guess. Die zurückgegebenen Entscheidungen bewahren die Eingabereihenfolge.

Dies ist absichtlich von der Inferenz getrennt, damit Aufrufer Routing-Entscheidungen prüfen oder aggregieren können, bevor sie Modellladekosten zahlen.

predict_batch(
    requests: Sequence[Dict[str, Any]],
    batch_size: Optional[int] = None,
    hooks_timeout: Optional[float] = None,
    min_confidence: Optional[float] = None,
    sort_by_length: bool = False,
    hooks=None,
    on_predict_start=None,
    on_predict_end=None,
    hooks_raise: Optional[bool] = None,
) -> List[Dict[str, Any]]

Routet und führt einen heterogenen Anfrage-Batch mit minimalem Modellwechsel aus.

Anfragen werden zuerst geroutet und nach Checkpoint gruppiert. Innerhalb jedes Checkpoints werden Anfragen, die dasselbe Frage-Schema teilen, an Agent.predict_batch übergeben, damit ihre Zustände Forward-Pässe teilen können. Die Ergebnisse werden dann in die ursprüngliche Anfragereihenfolge zurückversetzt.

Anfragen können unabhängig model, task, lang, lang_guess, max_len oder head_max_len angeben und unterschiedliche Frage-Schemata verwenden. max_len / head_max_len sind die Pro-Anfrage-Form der Token-Budget-Überschreibung, die predict als Aufrufargumente nimmt: Sie setzen die State- und Fragekopf- Budgets des Checkpoints für genau diese eine Anfrage, eine breite Frage kann also gestellt werden, ohne die anderen Anfragen des Batches auf dasselbe Fenster zu schrumpfen. Anfragen, die unterschiedliche Budgets verlangen, werden in separate Forward-Pässe aufgeteilt, da ein Agent.predict_batch-Aufruf ein Budget für alle seine Zustände trägt. Ein Start-Hook kann trotzdem einen der beiden Werte auf ctx ersetzen.

Predict-Hooks auf Router-Ebene laufen pro Anfrage, wie predict sie ausführt: jede Anfrage erhält ihren eigenen PredictContext, sodass on_predict_start den Zustand, die Fragen oder das Token-Budget dieser Anfrage ersetzen oder sie per ctx.skip(...) überspringen kann und on_predict_end ihr Ergebnis sieht und ersetzen darf. Anfragen werden für den Forward-Pass gruppiert, nachdem ihre Start-Hooks gelaufen sind, und die Anfragen einer Checkpoint-Gruppe enden in umgekehrter Reihenfolge, in der sie starteten. Wenn eine Checkpoint-Gruppe fehlschlägt, schlägt jede ihrer Anfragen, deren Start-Hook lief, mit der Ausnahme fehl, auch ein Cache-Treffer: jede bekommt on_error und dann on_predict_end, bevor die Ausnahme sich fortpflanzt.

RouteDecision()

Das Routing-Ergebnis: welches Modell, warum und was erkannt wurde.

Verhält sich wie ein Dict, serialisiert also direkt in eine API-Antwort.

DEFAULT_MODELS = {
    "english": (BUNDLE_REPO, None),
    "multilingual": (BUNDLE_REPO, "multilingual"),
    "typed-decisions": (BUNDLE_REPO, "typed-decisions"),
}