Dokumentation

Agent

laya.Agent lädt einen Checkpoint und beantwortet typisierte Fragen zu einem Zustand. laya.load ist ein Kürzel für Agent(...), und laya.RLAgent ist ein Alias von Agent. ONNXAgent führt ein exportiertes ONNX-Modell auf der CPU aus; importiere es aus laya.onnx_agent.

Namen, Typen, Standardwerte und Code bleiben auf Englisch; der Rest ist übersetzt (noch nicht übersetzte Einträge werden im englischen Original angezeigt).

Agent

Agent(
    model_id_or_path: str = "convaiinnovations/laya",
    device: Optional[str] = None,
    token: Optional[str] = None,
    subfolder: Optional[str] = None,
    fast: bool = False,
    compile: bool = False,
    revision: Optional[str] = None,
    expected_sha256: Optional[Dict[str, str]] = None,
    lang_temperatures: Optional[Dict[str, Dict[str, 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,
    calibration: Optional[str] = None,
    backend: Optional[str] = None,
    compile_warmup: bool = True,
    compile_cache: bool = False,
    compile_mode: str = "default",
)

Basisklassen: HookRegistry

Laufzeit des Entscheidungsmodells System One: schnelle, nicht-autoregressive, kalibrierte Entscheidungen.

dtype ist das Ziel des Autocast, nicht die Präzision jedes Aufrufs. Auf MPS führt ein Aufruf Autocast nur ab mps_amp_min_rows Zeilen aus, deshalb kann dtype float16 sagen, während ein Aufruf in float32 läuft. dtype_for(rows) gibt die Präzision eines Aufrufs mit rows Zeilen zurück.

Lade einen Laya-Checkpoint.

backend wählt "eager", "auto", "compile" oder "tilelang"; siehe laya.backends. Er hat Vorrang vor fast und compile. Lass ihn weg, um diese Legacy-Flags beizubehalten. Für ONNX nutze stattdessen load(backend="onnx").

revision bindet den Hub-Download optional an einen expliziten Commit-SHA/Branch/Tag; fehlt er, werden der normale Standard von huggingface_hub und der vorhandene Offline-Cache verwendet. expected_sha256 ({path relative to the checkpoint dir: hexdigest}) verifiziert die Integrität der Artefakte, bevor ein Gewicht geparst oder ausgeführt wird; es ist opt-in und gilt auch für lokale Verzeichnisse. Ein fehlendes Artefakt löst FileNotFoundError aus und eine Digest-Abweichung ValueError; beide Fehler lehnen das Laden ab.

fast=True tauscht den Forward von Encoder/Kopf gegen den schnellen TileLang-Pfad (nur CUDA, benötigt pip install laya[fast]); siehe Agent.accelerate.

compile=True führt das Modell unter torch.compile aus und schaltet ModernBERTs Encoder-Flag reference_compile ein. torch.compile spezialisiert pro Eingabeform, und Laya sieht fast bei jeder Anfrage eine neue, also kosten diese Graphen meist mehr, als sie einbringen; nutze es, wenn der Verkehr repetitiv ist. fast=True hat Vorrang, weil der TileLang-Pfad den Forward ersetzt, der kompiliert würde. Kompilierte Agents führen warmup() aus, bevor sie zurückkehren; compile_warmup=False verschiebt diese Arbeit auf Anfragen oder einen manuellen warmup()-Aufruf. Eager- und Fast-Agents bleiben unverändert. compile_cache=True aktiviert ein persistentes Laya-Inductor-Verzeichnis (prozessweit), unter Beachtung eines vorhandenen TORCHINDUCTOR_CACHE_DIR; siehe die Compile-Engineering-Notizen. compile_mode="reduce-overhead" aktiviert CUDA-Graphen. Das kann mehr GPU-Speicher belegen und zeichnet jede neue Form separat auf. CUDA-Ausgaben werden vor dem nächsten Replay kopiert; kompilierte CUDA-Graph-Forwards werden serialisiert. Der Standardmodus bleibt "default".

subfolder wählt einen Checkpoint aus einem Repository, das mehrere bündelt, z. B. Agent("convaiinnovations/laya", subfolder="multilingual"). Nur dieser Unterordner wird heruntergeladen, das Bündeln kostet also nicht jedem Nutzer die ganze Familie.

calibration ist ein optionaler JSON-Pfad mit temperature und temperature_by_options. Es wird nach der Checkpoint-Konfiguration angewendet, eine angepasste Map überschreibt also die mitgelieferten Skalare, ohne model.safetensors neu zu schreiben.

hooks / on_predict_start / on_predict_end beobachten oder formen jede Vorhersage; siehe laya.hooks. hooks_raise=False warnt und fährt fort, wenn ein Hook fehlschlägt, hooks_concurrent=False serialisiert Hooks, die nicht sicher parallel laufen, und hooks_timeout begrenzt jeden Hook-Aufruf in Sekunden (None bedeutet kein Limit).

Parameter

model_id_or_pathstr= "convaiinnovations/laya"
deviceOptional[str]= None
tokenOptional[str]= None
subfolderOptional[str]= None
fastbool= False
compilebool= False
revisionOptional[str]= None
expected_sha256Optional[Dict[str, str]]= None
lang_temperaturesOptional[Dict[str, Dict[str, Any]]]= None
hooks= None
on_predict_start= None
on_predict_end= None
hooks_raisebool= True
hooks_concurrentbool= True
hooks_timeoutOptional[float]= None
calibrationOptional[str]= None
backendOptional[str]= None
compile_warmupbool= True
compile_cachebool= False
compile_modestr= "default"

backend

backend: str

Das aktive Inferenz-Backend, einschließlich der Legacy-Flags compile und fast.

backend_object

backend_object

Das installierte Backend-Objekt, oder None für eine Legacy-Laufzeit.

set_backend

set_backend(name: str = "auto", strict: bool = False, options) -> str

Schaltet das Backend um; nicht verfügbare Backends warnen und verwenden eager, außer strict=True.

Optionen gehen an den Backend-Konstruktor, z. B. warmup=False für compile oder use_graphs=False für tilelang. Das Umschalten wartet auf laufende Inferenz.

Parameter

namestr= "auto"
strictbool= False
options

accelerate

accelerate(use_graphs: bool = True, strict: bool = False)

Ersetzt den Modell-Forward durch den schnellen TileLang-Pfad (fusionierte GEMM/GEGLU/LayerNorm/RoPE-Kernel, Flash Attention mit gleitendem Fenster, 16-Bit-residente Gewichte, CUDA-Graphen pro Form-Bucket).

Der schnelle Pfad läuft im Autocast-dtype des Agent zum Zeitpunkt des Aufrufs (bf16 oder fp16), stimmt also innerhalb der Rundung mit dem Standard-Forward überein, den er ersetzt (siehe benchmarks/parity_fast.py). Nach einer Änderung von agent.dtype rufst du deaccelerate() und dann accelerate() auf, um ihn neu zu bauen. Gibt True zurück, wenn er aktiviert ist. Mit strict=False lässt jeder Fehler (kein CUDA, tilelang fehlt) den Standard-Pfad bestehen.

Parameter

use_graphsbool= True
strictbool= False

warmup

warmup(shapes=None) -> float

Führt den Forward jetzt auf synthetischer Eingabe jeder Form aus und gibt die dafür benötigten Sekunden zurück.

compile=True ruft dies beim Laden auf, außer compile_warmup=False. Zusätzliche Formen können weiterhin manuell gewärmt werden. fast=True baut seine Kernel und CUDA-Graphen pro Form-Bucket beim ersten Einsatz; dies vor dem Ausliefern aufzurufen, verlagert diese Kosten aus den ersten Anfragen heraus. Mit dem Standard-Forward sind es ein paar gewöhnliche Forward-Pässe. shapes ist eine Liste aus (rows, tokens, markers); die Tokens werden auf das max_len des Agent begrenzt. Es wird nichts zurückgegeben oder für einen Aufrufer aufgezeichnet, und Hooks laufen nicht.

Parameter

shapes= None

deaccelerate

deaccelerate()

Stellt den Standard-Forward wieder her.

dtype_for

dtype_for(rows: int) -> torch.dtype

Präzision, in der ein Forward-Pass mit rows Frage-Zeilen läuft.

dtype ist das Ziel des Autocast, einmal beim Laden gesetzt. Ob ein Forward Autocast ausführt, wird pro Aufruf entschieden: auf MPS nur ab mps_amp_min_rows Zeilen. Dies gibt dtype zurück, wenn ein Forward mit rows Zeilen Autocast ausführt, und torch.float32, wenn nicht. Ein predict-Aufruf läuft mit einer Zeile pro Frage.

Parameter

rowsint

predict_batch

predict_batch(
    states: List[Union[str, dict, list]],
    questions: Dict[str, Dict[str, Any]],
    batch_size: Optional[int] = None,
    lang: Optional[str] = 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,
    sort_by_length: bool = False,
    min_confidence: Optional[float] = None,
) -> List[Dict[str, Any]]

Evaluiert dieselben Fragen über viele Zustände und packt sie in gemeinsame Forward-Pässe.

Das ist der Durchsatz-Pfad. system_one/predict verarbeiten einen Zustand pro Forward-Pass; auf einer GPU bleibt so der größte Teil der Batch-Dimension ungenutzt. predict_batch sammelt die Frage-Zeilen mehrerer Zustände in einen Tensor, sodass ein Aufruf, der N sequenzielle Forward-Pässe bräuchte, einen braucht (oder ceil(len(states) / batch_size)), was pro Entscheidung auf der GPU mehrere Male schneller ist.

Parameter

statesList[Union[str, dict, list]]

Eine Liste von Zuständen (jeweils ein Textstring, JSON-Dict oder eine Liste von Gesprächsrunden). Dieselben questions werden gegen jeden Zustand evaluiert.

questionsDict[str, Dict[str, Any]]

Frage-Definitionen, genau wie von system_one akzeptiert.

batch_sizeOptional[int]= None

Optionaler Deckel für Zustände pro Forward-Pass. None sendet sie alle in einem Pass; setze ihn, um den Spitzenspeicher zu begrenzen, wenn du viele oder lange Zustände batchst.

langOptional[str]= None
hooksHookArg= None

Hooks pro Aufruf, angehängt nach den auf dem Agent installierten. Siehe laya.hooks.

on_predict_startPredictHookArg= None

Ein Start-Hook pro Aufruf. Er kann den Zustand/die Fragen umschreiben oder ctx.skip(...) aufrufen, um die Inferenz kurzzuschließen.

on_predict_endPredictHookArg= None

Ein End-Hook pro Aufruf. Er kann die Ergebnisse umschreiben.

hooks_raiseOptional[bool]= None

Überschreibt das hooks_raise des Agent für diesen Aufruf.

hooks_timeoutOptional[float]= None

Überschreibt das hooks_timeout des Agent für diesen Aufruf.

max_lenOptional[int]= None

Überschreibt das max_len der Agent-Konfiguration für diesen Aufruf. Ein Start-Hook kann auch ctx.max_len setzen, um das Token-Budget zu formen.

head_max_lenOptional[int]= None

Überschreibt das head_max_len der Agent-Konfiguration für diesen Aufruf. Ein Start-Hook kann auch ctx.head_max_len setzen.

sort_by_lengthbool= False

Gruppiert ähnlich große kodierte Zustände in Fenstern von acht Batches, um Padding zu reduzieren. Erfordert ein explizites batch_size größer als eins und kleiner als die Anzahl der Zustände; andernfalls hat es keine Wirkung. Die Ergebnisse behalten die Eingabereihenfolge. Dies puffert bis zu acht Batches tokenisierter Zustände statt einen. Änderungen der Batch-Formen können die Fließkomma-Vorhersagen leicht verändern.

min_confidenceOptional[float]= None

Rückgabewert

Eine Liste von Ergebnis-Dicts pro Zustand, jedes in der Form identisch mit der Ausgabe von system_one und per Index an states ausgerichtet.

predict_long

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

Evaluiert Fragen über einen Zustand, der länger als das Kontextfenster ist, indem er in überlappenden Fenstern gescannt und pro Frage aggregiert wird.

system_one/predict kürzen einen Zustand, der max_len überschreitet, auf ein einzelnes Fenster (das erste, oder bei einer Gesprächsliste das letzte), und verwerfen den Rest stillschweigend. predict_long tokenisiert den Zustand einmal, teilt ihn in überlappende Token-Fenster, bewertet jedes Fenster in gemeinsamen Forward-Pässen (über predict_batch) und kombiniert die Antworten pro Fenster:

  • noul -> P(true) ist das Maximum über die Fenster (die Aussage gilt, wenn ein Fenster sie stützt)
  • choice-> die Antwort aus dem einzelnen sichersten Fenster, damit ein lokalisiertes Signal nicht von den vielen neutralen Fenstern überstimmt wird, aus denen ein langes Dokument überwiegend besteht (Mitteln ertränkt es -- die neutrale Mehrheit dominiert)
  • score -> die Stufe aus dem sichersten Fenster, ebenso

Die zurückgegebene Wahrscheinlichkeit/Konfidenz ist die des entscheidenden Fensters, keine kalibrierte Zahl für das ganze Dokument: ein noul-Maximum über viele Fenster driftet mit der Fensteranzahl nach oben, selbst ohne Signal, und choice kann auf einem sicher neutralen Fenster landen, wenn nichts im Dokument entscheidend ist. Jede Antwort trägt daher answer["window"] — den index des entscheidenden Fensters, token_start/token_end in den tokenisierten Zustand und die Fenster-count — damit ein Aufrufer die Spanne prüfen kann, aus der die Antwort kam, statt der rohen Zahl zu vertrauen. Diese Spanne ist die, die das Modell gelesen hat, nicht bloß die angeforderte: das Fenster ist auf den Platz begrenzt, den die Fragen lassen, das an predict_batch Gegebene wird also nicht noch einmal gekürzt.

Ein Zustand, der bereits in ein Fenster passt, wird direkt an system_one übergeben (identische Ausgabe).

Die Hooks umhüllen die Inferenz, die den Zustand beantwortet, die bei einem Dokument mit mehreren Fenstern der eine gemeinsame predict_batch über sie ist: on_predict_start feuert einmal, und ctx.states hält die dekodierten Fenstertexte in Scan-Reihenfolge -- nicht den state des Aufrufers, der tokenisiert wurde, um sie zu erzeugen. Aus dem, was die Kette hinterlässt, folgen drei Ausgänge:

  • ctx.skip([result]) beantwortet das Dokument: die Nutzlast kommt ohne Fenster- Zuordnung und mit usage["windows"] auf 0 zurück, weil nichts bewertet wurde
  • ein Scan, so gelassen, wie diese Methode ihn gebaut hat: jedes Fenster wird bewertet, jede Antwort trägt answer["window"], und usage["windows"] ist die Fensteranzahl
  • ein umgeschriebener Scan (ctx.states ersetzt, auf welche Weise auch immer): die Antworten werden über die bewerteten Zustände aggregiert, aber keine Antwort trägt answer["window"] -- die Offsets oben beschreiben die Fenster dieser Methode, nicht den Text, den das Modell gelesen hat

Parameter

stateUnion[str, dict, list]
questionsDict[str, Dict[str, Any]]
windowOptional[int]= None

State-Tokens pro Fenster. Standard ist das State-Budget des Checkpoints (max_len - head_max_len - 8), und beide Wege werden auf den Platz begrenzt, den die Fragen für den State innerhalb von max_len lassen -- den kleinsten dieser Plätze, weil eine Fensterliste für jede Frage bewertet wird. Ein breiteres Fenster wird auf dem Weg zum Modell erneut gekürzt, also wird es stattdessen begrenzt, mit einer RuntimeWarning, wenn der Aufrufer es angefordert hat. Die Optionen sind es, die den Platz klein machen: beim englischen Checkpoint lässt eine 2-Optionen-Frage 483 Tokens für den State und eine mit 100 Optionen lässt 100. Ein kleineres Fenster isoliert ein lokalisiertes Signal besser (eine kurze entscheidende Spanne ist ein größerer Anteil seines Fensters, sodass dieses Fenster sie klar klassifiziert), auf Kosten von mehr Fenstern; der große Standard bevorzugt Kontext und Durchsatz. noul ist dagegen robust, choice/score profitieren von einem kleineren Fenster, wenn die entscheidende Spanne ein kleiner Teil eines langen, ansonsten neutralen Dokuments ist.

strideOptional[int]= None

Token-Schritt zwischen Fenstern. Standard ist die Hälfte des effektiven Fensters (50 % Überlappung), damit eine Spanne nahe einer Grenze trotzdem ganz in einem Fenster landet. Ein Schritt über das effektive Fenster hinaus wird abgelehnt statt begrenzt: die Tokens zwischen jedem Fensterpaar würden von keinem Fenster gelesen, was genau der Fehler ist, den diese Methode verhindern soll.

aggregatestr= "auto"

"auto" (die Typregeln oben) ist vorerst der einzige Modus.

batch_sizeOptional[int]= None

Deckel für Fenster pro Forward-Pass, um den Speicher bei sehr langen Zuständen zu begrenzen.

langOptional[str]= None

Temperaturauswahl pro Sprache, wie in system_one.

hooksHookArg= None

Hooks pro Aufruf, angehängt nach den auf dem Agent installierten. Siehe laya.hooks.

on_predict_startPredictHookArg= None

Ein Start-Hook pro Aufruf, wie in system_one.

on_predict_endPredictHookArg= None

Ein End-Hook pro Aufruf, wie in system_one.

hooks_raiseOptional[bool]= None

Überschreibt das hooks_raise des Agent für diesen Aufruf.

hooks_timeoutOptional[float]= None

Überschreibt das hooks_timeout des Agent für diesen Aufruf.

Ausnahmen

ValueError: aggregate ist etwas anderes als "auto"; die Optionen der Fragen füllen die ganze Sequenz, sodass kein Platz für den State bleibt; oder stride geht über das effektive Fenster hinaus, sodass Tokens zwischen zwei Fenstern von nichts gelesen würden.

Gibt ein einzelnes Ergebnis-Dict zurück, dieselbe Form wie system_one, mit hinzugefügtem usage["windows"]. Der Schlüssel ist immer vorhanden und zählt die Fenster, die das Modell bewertet hat, um die Antwort zu erzeugen: 1 für einen Zustand, der in ein Fenster passte, N für ein in N überlappenden Fenstern gescanntes Dokument (oder das N, auf das ein Start-Hook sie umgeschrieben hat), und 0, wenn ein Start-Hook das Dokument beantwortet hat oder keine Zustände zum Bewerten übrig ließ, bevor ein Fenster gelesen wurde -- auf beiden Pfaden, damit eine zwischengespeicherte Antwort nie als ein Fenster gelesen wird, das das Modell gelesen hat.

Über mehrere Fenster werden die Truncation-Schlüssel wie jedes andere usage-Feld kombiniert: truncated, state_tokens und state_tokens_dropped werden summiert (sodass truncated die Anzahl der gekürzten Fenster ist und die Token-Zählungen die Überlappung einschließen), und truncated_questions ist die Liste des letzten Fensters. Die beiden können sich widersprechen: wenn nur ein früheres Fenster gekürzt wurde, ist truncated über 0 und truncated_questions leer. Ein Fenster wird gekürzt, wenn es größer ist als der Platz, den der Kopf einer Frage lässt. Prüfe hier usage["truncated"] > 0, nicht is True.

system_one

system_one(
    state: Union[str, dict, list],
    questions: Dict[str, Dict[str, Any]],
    lang: Optional[str] = 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]

Evaluiert typisierte Fragen über den Zustand in einem einzigen, parallelen Forward-Pass.

Parameter

stateUnion[str, dict, list]

Textstring, JSON-Dict oder Liste von Gesprächsrunden.

questionsDict[str, Dict[str, Any]]

Dictionary, das question_id -> Frage-Definition abbildet.

  • choice: {"type": "choice", "instructions": "...", "criteria": {"optA": "...", ...}}

  • score: {"type": "score", "instructions": "...", "criteria": ["lvl0", "lvl1", ...]}

  • noul: {"type": "noul", "instructions": "...", "criteria": {"false": "...", "true": "..."}, "labels": {"false": "B", "true": "A"}}

    Noul-criteria und -labels sind optional. Labels steuern nur den Text, der dem Modell gezeigt wird; ihre Schlüssel behalten die false/true-Semantik, und der zurückgegebene noul-Wert ist immer P(true). Zur Kompatibilität sind die Labels standardmäßig false/true.

langOptional[str]= None
hooks= None
on_predict_start= None
on_predict_end= None
hooks_raiseOptional[bool]= None
hooks_timeoutOptional[float]= None
max_lenOptional[int]= None
head_max_lenOptional[int]= None
min_confidenceOptional[float]= None

Rückgabewert

Dictionary mit Antworten, Wahrscheinlichkeiten, kalibrierter Konfidenz und Token-Nutzung. Leere Fragen liefern leere Antworten und null Token-Nutzung ohne Tokenisierung oder einen Modell-Forward-Pass.

Wenn das Kopf-Budget zwei Optionen mit derselben Token-Spanne übrig lässt, trägt usage einen options-Eintrag für jede Frage, bei der das geschah -- total, distinct und tokens_per_option --, weil eine unter 42 unterscheidbaren Spannen von 58 gewählte Antwort eine Obergrenze hat, die die des Budgets und nicht die des Modells ist. Fragen, deren Optionen alle überleben, fehlen, eine Anfrage, die nichts kollabiert, bleibt also unverändert.

usage meldet außerdem, ob der Zustand passte: truncated, state_tokens, state_tokens_dropped und truncated_questions (die Fragen, deren Kopf zu wenig Platz ließ). Ein Aufrufer, dem wichtig ist, ob die Antwort den ganzen Zustand sah, sollte usage["truncated"] lesen, statt aus der Länge des Gesendeten zu schätzen.

Um viele Zustände auf einmal zu bewerten, siehe predict_batch, das Forward-Pässe über sie teilt.

decide

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 werden an predict / system_one weitergegeben.

Parameter

stateUnion[str, dict, list]
schemaAny= None
questionsOptional[Dict[str, Any]]= None
return_detailsbool= False
min_confidenceOptional[float]= None
predict_kwargs

decide_batch

decide_batch(
    states: List[Union[str, dict, list]],
    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 (gemeinsame Forward-Pässe, Ergebnisse in Eingabereihenfolge), dann werden die Antworten jedes Zustands projiziert wie bei decide. Zusätzliche Schlüsselwortargumente (batch_size=, lang=, hooks=, ...) werden an predict_batch weitergegeben. Siehe laya.structured.

Parameter

statesList[Union[str, dict, list]]
schemaAny= None
questionsOptional[Dict[str, Any]]= None
return_detailsbool= False
min_confidenceOptional[float]= None
predict_kwargs

fit_temperatures

fit_temperatures(records, compute_ece: bool = False, seed: int = 0) -> Dict[str, Any]

Passt Temperaturen pro Bucket aus CPU-Aufzeichnungen an und speichert sie auf diesem Agent.

records sind (qtype, logits, target, k). Baue sie mit laya.calibrate.records_from_labeled, wenn du gelabelte Forwards hast; diese Methode lädt keine Gewichte herunter und schreibt kein model.safetensors. seed beeinflusst nur den zurückgehaltenen ECE-Split, wenn compute_ece true ist. Die Checkpoint-cfg bleibt wie geladen.

Parameter

records
compute_ecebool= False
seedint= 0

fit_binning

fit_binning(
    records,
    min_bucket_n: int = MIN_BINNING_BUCKET_N,
    MIN_BINNING_BUCKET_N,
) -> Dict[str, Any]

Passt ein Histogramm-Binning-Mapping auf die angepassten Temperaturen dieses Agent an und speichert es.

records sind dieselben (qtype, logits, target[, k])-Tupel, die fit_temperatures konsumiert. Das Mapping ist genau wie temperature_by_options verschlüsselt, setzt auf den aktuellen Temperaturen auf und wird von save_calibration als binning_map geschrieben.

Parameter

records
min_bucket_nint= MIN_BINNING_BUCKET_N
MIN_BINNING_BUCKET_N

save_calibration

save_calibration(path: str) -> None

Schreibt die Temperaturen und den Checkpoint, für den sie angepasst wurden. Schreibt keine Gewichte.

Parameter

pathstr

load_calibration

load_calibration(path: str) -> None

Liest eine von save_calibration geschriebene JSON-Map auf diesen Agent.

Eine Datei ohne version wird als Version 1 behandelt und lädt trotzdem. Eine neuere Datei, deren aufgezeichneter Checkpoint nicht zu diesem Agent passt, warnt und lädt trotzdem. Werte, die keine Zahlen sind oder außerhalb von [TEMP_MIN, TEMP_MAX] liegen, werden mit clamp_temperature begrenzt, genau wie beim Laden eines Checkpoints.

Parameter

pathstr

load

load(
    model_id_or_path: str = "convaiinnovations/laya",
    device: Optional[str] = None,
    token: Optional[str] = None,
    subfolder: Optional[str] = None,
    fast: bool = False,
    compile: bool = False,
    revision: Optional[str] = None,
    expected_sha256: Optional[Dict[str, str]] = None,
    lang_temperatures: Optional[Dict[str, Dict[str, 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,
    calibration: Optional[str] = None,
    backend: Optional[str] = None,
    onnx_path: Optional[str] = None,
    compile_warmup: bool = True,
    compile_cache: bool = False,
    compile_mode: str = "default",
) -> Agent

Lädt einen Laya-Agent.

subfolder wählt einen Checkpoint aus einem Repository, das mehrere bündelt:

laya.load("convaiinnovations/laya")                           # English (repo root)
laya.load("convaiinnovations/laya", subfolder="multilingual")
laya.load("convaiinnovations/laya", fast=True)                # TileLang GPU fast path
laya.load("convaiinnovations/laya", compile=True)              # torch.compile the model

model_id_or_path akzeptiert auch einen Checkpoint-Namen oder Alias -- dieselben, die Router auflöst, sodass beide Einstiegspunkte eine Tabelle lesen:

laya.load("typed-decisions")
laya.load("ml")                                               # multilingual

Alles andere (eine Hub-Repo-ID, ein lokales Verzeichnis) wird unverändert an Agent übergeben.

backend wählt "auto", "eager", "compile", "tilelang" oder "onnx". ONNX gibt den vorhandenen ONNXAgent zurück, mit onnx_path (Standard "laya.onnx"). Andere Backends nutzen Agent; ein explizites Backend hat Vorrang vor den Legacy-Flags.

revision/expected_sha256 binden und verifizieren die heruntergeladenen Artefakte; siehe Agent. hooks / on_predict_start / on_predict_end beobachten oder formen jede Vorhersage; siehe laya.hooks. calibration ist derselbe optionale JSON-Pfad, den Agent akzeptiert.

Parameter

model_id_or_pathstr= "convaiinnovations/laya"
deviceOptional[str]= None
tokenOptional[str]= None
subfolderOptional[str]= None
fastbool= False
compilebool= False
revisionOptional[str]= None
expected_sha256Optional[Dict[str, str]]= None
lang_temperaturesOptional[Dict[str, Dict[str, Any]]]= None
hooks= None
on_predict_start= None
on_predict_end= None
hooks_raisebool= True
hooks_concurrentbool= True
hooks_timeoutOptional[float]= None
calibrationOptional[str]= None
backendOptional[str]= None
onnx_pathOptional[str]= None
compile_warmupbool= True
compile_cachebool= False
compile_modestr= "default"

ONNXAgent

ONNXAgent(
    model_id_or_path: str,
    onnx_path: str = "laya.onnx",
    token: Optional[str] = None,
    subfolder: Optional[str] = None,
    revision: Optional[str] = None,
    expected_sha256: Optional[Dict[str, str]] = None,
    hooks=None,
    on_predict_start=None,
    on_predict_end=None,
    hooks_raise: bool = True,
    hooks_concurrent: bool = True,
    hooks_timeout: Optional[float] = None,
    lang_temperatures: Optional[Dict[str, Dict[str, Any]]] = None,
    calibration: Optional[str] = None,
)

Basisklassen: HookRegistry

Laufzeit des Entscheidungsmodells System One über ONNX: schnelle, für CPU optimierte Entscheidungen.

Lädt einen Laya-Agent mit ONNX Runtime im Rücken.

Parameter

model_id_or_pathstr

HuggingFace-Hub-ID oder lokaler Pfad zum ursprünglichen PyTorch-Checkpoint (wird verwendet, um Tokenizer und Konfiguration zu laden).

onnx_pathstr= "laya.onnx"

Pfad zur exportierten .onnx-Datei.

tokenOptional[str]= None

Optionales HuggingFace-Token für einen privaten oder gated Checkpoint; fällt auf $HF_TOKEN zurück, genau wie Agent. Nur Tokenizer und Konfiguration werden geholt -- der Graph selbst ist der lokale onnx_path.

subfolderOptional[str]= None

Optionaler Unterordner, wenn aus einem Repository-Bundle heruntergeladen wird.

revisionOptional[str]= None

Optionale Hub-Revision (Commit-SHA/Branch/Tag). Wenn sie fehlt, werden der normale Standard von huggingface_hub und der vorhandene Offline-Cache verwendet.

expected_sha256Optional[Dict[str, str]]= None

Optional {path relative to the checkpoint dir: hexdigest}, verifiziert, bevor eine Checkpoint-Datei geparst wird; opt-in, und gilt auch für lokale Verzeichnisse. Ein fehlendes Artefakt löst FileNotFoundError aus und eine Digest-Abweichung ValueError; beide Fehler lehnen das Laden ab.

hooksHookArg= None

Opt-in-Vorhersage-Hooks; siehe laya.hooks.

on_predict_startPredictHookArg= None

Ein Opt-in-Start-Hook, der vor der Inferenz läuft.

on_predict_endPredictHookArg= None

Ein Opt-in-End-Hook, der nach der Inferenz läuft.

hooks_raisebool= True

Wenn False, warnt ein fehlschlagender Hook und die Inferenz fährt fort.

hooks_concurrentbool= True

Wenn False, werden Hooks mit einem Lock serialisiert.

hooks_timeoutOptional[float]= None

Begrenzt jeden Hook-Aufruf in Sekunden; None bedeutet kein Limit.

lang_temperaturesOptional[Dict[str, Dict[str, Any]]]= None

Optionale Temperatur-Überschreibungen pro Sprache, verschlüsselt nach Sprach- code, jeweils {"temperature": [3 floats], "temperature_by_options": {}}. Angewendet, wenn ein lang= an system_one/predict übergeben wird, spiegelbildlich zum PyTorch-Agent; ein Backend-Wechsel verliert sonst die Kalibrierung.

calibrationOptional[str]= None

load_calibration

load_calibration(path: str) -> None

Liest eine von save_calibration geschriebene JSON-Map auf diesen Agent.

Parameter

pathstr

system_one

system_one(
    state: Union[str, dict, list],
    questions: Dict[str, Dict[str, Any]],
    lang: Optional[str] = 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]

Evaluiert typisierte Fragen über den Zustand in einem Lauf der ONNX-Runtime-Session.

lang wählt eine Temperatur-Überschreibung pro Sprache (siehe lang_temperatures) und entspricht der Signatur von Agent.system_one in PyTorch, sodass jedes Backend ein Drop-in für das andere ist.

Definiert über predict_batch, genau wie das PyTorch-Agent.system_one, damit die Einzelzustand- und Batch-Pfade nicht auseinanderdriften können.

Parameter

stateUnion[str, dict, list]

Textstring, JSON-Dict oder Liste von Gesprächsrunden.

questionsDict[str, Dict[str, Any]]

Frage-Definitionen mit den Formen, die Agent.system_one akzeptiert.

langOptional[str]= None

Temperatur-Überschreibung pro Sprache (siehe lang_temperatures).

hooksHookArg= None

Hooks pro Aufruf, angehängt nach den auf dem Agent installierten.

on_predict_startPredictHookArg= None

Ein Start-Hook pro Aufruf. Er kann den Zustand/die Fragen umschreiben oder ctx.skip(...) aufrufen, um die Inferenz kurzzuschließen.

on_predict_endPredictHookArg= None

Ein End-Hook pro Aufruf. Er kann die Ergebnisse umschreiben.

hooks_raiseOptional[bool]= None

Überschreibt das hooks_raise des Agent für diesen Aufruf.

hooks_timeoutOptional[float]= None

Überschreibt das hooks_timeout des Agent für diesen Aufruf.

max_lenOptional[int]= None

Überschreibt das max_len der Konfiguration für diesen Aufruf.

head_max_lenOptional[int]= None

Überschreibt das head_max_len der Konfiguration für diesen Aufruf.

min_confidenceOptional[float]= None

Opt-in-Enthaltungsschwelle auf answer_confidence (#361); eine Antwort darunter wird mit low_confidence: True markiert zurückgegeben.

Rückgabewert

Dictionary mit Antworten, Wahrscheinlichkeiten, kalibrierter Konfidenz und Token-Nutzung.

Um viele Zustände auf einmal zu bewerten, siehe predict_batch, das Session-Läufe über sie teilt.

predict_batch

predict_batch(
    states: List[Union[str, dict, list]],
    questions: Dict[str, Dict[str, Any]],
    batch_size: Optional[int] = None,
    lang: Optional[str] = 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,
    sort_by_length: bool = False,
    min_confidence: Optional[float] = None,
) -> List[Dict[str, Any]]

Evaluiert dieselben Fragen über viele Zustände und teilt Läufe der ONNX-Runtime-Session.

Der Durchsatz-Pfad, spiegelbildlich zu laya.agent.Agent.predict_batch: system_one sammelt die Frage-Zeilen eines Zustands pro Session-Lauf, N Zustände kosten also N Läufe. predict_batch sammelt die Zeilen mehrerer Zustände in einen Lauf -- oder ceil(len(states) / batch_size) davon --, wo sich die eigene Parallelität von ONNX Runtime auf der CPU auszahlt.

Parameter

statesList[Union[str, dict, list]]

Eine Liste von Zuständen (jeweils ein Textstring, JSON-Dict oder eine Liste von Gesprächsrunden). Dieselben questions werden gegen jeden Zustand evaluiert.

questionsDict[str, Dict[str, Any]]

Frage-Definitionen, genau wie von system_one akzeptiert.

batch_sizeOptional[int]= None

Optionaler Deckel für Zustände pro Session-Lauf. None sendet sie alle in einem Lauf; setze ihn, um den Spitzenspeicher zu begrenzen, wenn du viele oder lange Zustände batchst.

langOptional[str]= None

Temperatur-Überschreibung pro Sprache, angewendet auf jeden Zustand; siehe lang_temperatures.

hooksHookArg= None

Hooks pro Aufruf, angehängt nach den auf dem Agent installierten.

on_predict_startPredictHookArg= None

Ein Start-Hook pro Aufruf. Er kann die Zustände/die Fragen umschreiben oder ctx.skip(...) aufrufen, um die Inferenz kurzzuschließen.

on_predict_endPredictHookArg= None

Ein End-Hook pro Aufruf. Er kann die Ergebnisse umschreiben.

hooks_raiseOptional[bool]= None

Überschreibt das hooks_raise des Agent für diesen Aufruf.

hooks_timeoutOptional[float]= None

Überschreibt das hooks_timeout des Agent für diesen Aufruf.

max_lenOptional[int]= None

Überschreibt das max_len der Konfiguration für diesen Aufruf.

head_max_lenOptional[int]= None

Überschreibt das head_max_len der Konfiguration für diesen Aufruf.

sort_by_lengthbool= False

Gruppiert ähnlich große kodierte Zustände in Fenstern von acht Batches, um Padding zu reduzieren, genau wie Agent.predict_batch. Erfordert ein explizites batch_size größer als eins und kleiner als die Anzahl der Zustände; andernfalls hat es keine Wirkung. Die Ergebnisse behalten die Eingabereihenfolge. Änderungen der Batch-Formen können die Fließkomma-Vorhersagen nahe der Entscheidungsschwellen leicht verändern.

min_confidenceOptional[float]= None

Opt-in-Enthaltungsschwelle auf answer_confidence (#361); Antworten darunter werden mit low_confidence: True markiert zurückgegeben.

Rückgabewert

Eine Liste von Ergebnis-Dicts pro Zustand, jedes in der Form identisch mit der Ausgabe von system_one und per Index an states ausgerichtet.

predict_long

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

Evaluiert Fragen über einen Zustand, der länger als das Kontextfenster ist, indem er in überlappenden Fenstern gescannt und pro Frage aggregiert wird.

Der ONNX-Port von laya.agent.Agent.predict_long, mit denselben Aggregationsregeln: system_one kürzt einen Zustand, der max_len überschreitet, auf ein einzelnes Fenster und verwirft den Rest stillschweigend. predict_long tokenisiert den Zustand einmal, teilt ihn in überlappende Token-Fenster, bewertet jedes Fenster über predict_batch -- sodass die Fenster Läufe der ONNX- Runtime-Session teilen, statt je einen zu kosten -- und kombiniert die Antworten pro Fenster:

  • noul -> P(true) ist das Maximum über die Fenster (die Aussage gilt, wenn ein Fenster sie stützt)
  • choice-> die Antwort aus dem einzelnen sichersten Fenster, damit ein lokalisiertes Signal nicht von den vielen neutralen Fenstern überstimmt wird, aus denen ein langes Dokument überwiegend besteht
  • score -> die Stufe aus dem sichersten Fenster, ebenso

Die zurückgegebene Wahrscheinlichkeit/Konfidenz ist die des entscheidenden Fensters, keine kalibrierte Zahl für das ganze Dokument, aus denselben Gründen, die der PyTorch-Docstring nennt. Jede Antwort trägt answer["window"] -- den index des entscheidenden Fensters, token_start/token_end in den tokenisierten Zustand und die Fenster-count.

Ein Zustand, der bereits in ein Fenster passt, wird direkt an system_one übergeben (identische Ausgabe).

Parameter

stateUnion[str, dict, list]

Textstring, JSON-Dict oder Liste von Gesprächsrunden.

questionsDict[str, Dict[str, Any]]

Frage-Definitionen, genau wie von system_one akzeptiert.

windowOptional[int]= None

State-Tokens pro Fenster. Standard ist das State-Budget pro Frage (max_len - head_max_len - 8). Kleinere Fenster isolieren ein lokalisiertes Signal besser auf Kosten von mehr Fenstern, wie in Agent.predict_long.

strideOptional[int]= None

Token-Schritt zwischen Fenstern. Standard ist window // 2 (50 % Überlappung).

aggregatestr= "auto"

"auto" (die Typregeln oben) ist vorerst der einzige Modus.

batch_sizeOptional[int]= None

Deckel für Fenster pro Session-Lauf, um den Spitzenspeicher bei sehr langen Zuständen zu begrenzen.

langOptional[str]= None

Temperaturauswahl pro Sprache, wie in system_one.

hooksHookArg= None

Hooks pro Aufruf, angehängt nach den auf dem Agent installierten. Sie folgen dem Vertrag von Agent.predict_long: Sie umhüllen die Inferenz, die den Zustand beantwortet, ein Start-Hook, der mit ctx.skip(...) antwortet, bekommt usage["windows"] == 0 und keine Fenster-Zuordnung, und ein umgeschriebener Scan wird ohne answer["window"] aggregiert.

on_predict_startPredictHookArg= None

Ein Start-Hook pro Aufruf, wie in system_one.

on_predict_endPredictHookArg= None

Ein End-Hook pro Aufruf, wie in system_one.

hooks_raiseOptional[bool]= None

Überschreibt das hooks_raise des Agent für diesen Aufruf.

hooks_timeoutOptional[float]= None

Überschreibt das hooks_timeout des Agent für diesen Aufruf.

Gibt ein einzelnes Ergebnis-Dict zurück, dieselbe Form wie system_one, mit hinzugefügtem usage["windows"]. Über mehrere Fenster werden die Truncation-Schlüssel summiert oder genauso getragen wie in Agent.predict_long: truncated ist eine Fensteranzahl und truncated_questions ist die Liste des letzten Fensters, sodass truncated über 0 liegen kann, während die Liste leer ist.

decide

decide(
    state: Union[str, dict, list],
    schema: Any = None,
    questions: Optional[Dict[str, 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 werden an predict / system_one weitergegeben.

Parameter

stateUnion[str, dict, list]
schemaAny= None
questionsOptional[Dict[str, Dict[str, Any]]]= None
return_detailsbool= False
min_confidenceOptional[float]= None
predict_kwargs

decide_batch

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

Beantwortet viele Zustände gegen ein Schema über predict_batch; siehe laya.structured.

Parameter

statesList[Union[str, dict, list]]
schemaAny= None
questionsOptional[Dict[str, Dict[str, Any]]]= None
return_detailsbool= False
min_confidenceOptional[float]= None
predict_kwargs

Quantisierter Export

scripts/export_onnx.py --quantize schreibt eine quantisierte INT8-Kopie (nur Gewichte) neben den fp32-Export (laya.onnx erzeugt auch laya.int8.onnx). Die dynamische Quantisierung wandelt die MatMul-Gewichte in int8 um und berechnet den Aktivierungs-Scale zur Laufzeit pro Eingabe, sodass kein Kalibrierungsdatensatz nötig ist; ONNXAgent lädt das Ergebnis, indem onnx_path darauf zeigt. Auf der CPU ist es rund 2x schneller als das Eager-Modell und ~1.8x schneller als der fp32-ONNX-Graph, und je nach Checkpoint 1.4-2.8x kleiner.

INT8 kostet echte Genauigkeit, ist also eine Größen-/Latenz-Option und nicht kostenlos — setze es nicht dort ein, wo die kalibrierte Wahrscheinlichkeit oder Konfidenz zählt. Die Skalen sind standardmäßig pro Tensor; --per-channel aktiviert Gewichte pro Channel, aber auf dem dynamischen Pfad bricht das das Entscheidungsmodell zusammen (die Übereinstimmung mit dem Eager-Modell fiel auf ~32% am englischen Checkpoint und ~40% am mehrsprachigen, gegenüber ~67% / ~83% pro Tensor; siehe Issue #790). Selbst pro Tensor driftet es am größeren Checkpoint merklich; genauigkeitssicheres int8 bräuchte QAT oder eine SmoothQuant-artige Behandlung von Ausreißern. Der int8-Graph läuft nur auf der CPU: ONNX Runtime hat keinen INT8-MatMul-Kernel auf dem CUDAExecutionProvider, und ein GPU-Provider fällt still pro Knoten zurück.

python scripts/export_onnx.py --model convaiinnovations/laya --output laya.onnx --quantize