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]=NonetokenOptional[str]=NonesubfolderOptional[str]=Nonefastbool=Falsecompilebool=FalserevisionOptional[str]=Noneexpected_sha256Optional[Dict[str, str]]=Nonelang_temperaturesOptional[Dict[str, Dict[str, Any]]]=Nonehooks=Noneon_predict_start=Noneon_predict_end=Nonehooks_raisebool=Truehooks_concurrentbool=Truehooks_timeoutOptional[float]=NonecalibrationOptional[str]=NonebackendOptional[str]=Nonecompile_warmupbool=Truecompile_cachebool=Falsecompile_modestr="default"
backend
backend: strDas aktive Inferenz-Backend, einschließlich der Legacy-Flags compile und fast.
backend_object
backend_objectDas installierte Backend-Objekt, oder None für eine Legacy-Laufzeit.
set_backend
set_backend(name: str = "auto", strict: bool = False, options) -> strSchaltet 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=Falseoptions
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=Truestrictbool=False
warmup
warmup(shapes=None) -> floatFü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.dtypePrä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
questionswerden gegen jeden Zustand evaluiert.questionsDict[str, Dict[str, Any]]Frage-Definitionen, genau wie von
system_oneakzeptiert.batch_sizeOptional[int]=NoneOptionaler Deckel für Zustände pro Forward-Pass.
Nonesendet sie alle in einem Pass; setze ihn, um den Spitzenspeicher zu begrenzen, wenn du viele oder lange Zustände batchst.langOptional[str]=NonehooksHookArg=NoneHooks pro Aufruf, angehängt nach den auf dem Agent installierten. Siehe
laya.hooks.on_predict_startPredictHookArg=NoneEin Start-Hook pro Aufruf. Er kann den Zustand/die Fragen umschreiben oder
ctx.skip(...)aufrufen, um die Inferenz kurzzuschließen.on_predict_endPredictHookArg=NoneEin End-Hook pro Aufruf. Er kann die Ergebnisse umschreiben.
hooks_raiseOptional[bool]=NoneÜberschreibt das
hooks_raisedes Agent für diesen Aufruf.hooks_timeoutOptional[float]=NoneÜberschreibt das
hooks_timeoutdes Agent für diesen Aufruf.max_lenOptional[int]=NoneÜberschreibt das
max_lender Agent-Konfiguration für diesen Aufruf. Ein Start-Hook kann auchctx.max_lensetzen, um das Token-Budget zu formen.head_max_lenOptional[int]=NoneÜberschreibt das
head_max_lender Agent-Konfiguration für diesen Aufruf. Ein Start-Hook kann auchctx.head_max_lensetzen.sort_by_lengthbool=FalseGruppiert ähnlich große kodierte Zustände in Fenstern von acht Batches, um Padding zu reduzieren. Erfordert ein explizites
batch_sizegröß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 mitusage["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"], undusage["windows"]ist die Fensteranzahl - ein umgeschriebener Scan (
ctx.statesersetzt, auf welche Weise auch immer): die Antworten werden über die bewerteten Zustände aggregiert, aber keine Antwort trägtanswer["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]=NoneState-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 vonmax_lenlassen -- 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 einerRuntimeWarning, 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.noulist dagegen robust,choice/scoreprofitieren von einem kleineren Fenster, wenn die entscheidende Spanne ein kleiner Teil eines langen, ansonsten neutralen Dokuments ist.strideOptional[int]=NoneToken-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]=NoneDeckel für Fenster pro Forward-Pass, um den Speicher bei sehr langen Zuständen zu begrenzen.
langOptional[str]=NoneTemperaturauswahl pro Sprache, wie in
system_one.hooksHookArg=NoneHooks pro Aufruf, angehängt nach den auf dem Agent installierten. Siehe
laya.hooks.on_predict_startPredictHookArg=NoneEin Start-Hook pro Aufruf, wie in
system_one.on_predict_endPredictHookArg=NoneEin End-Hook pro Aufruf, wie in
system_one.hooks_raiseOptional[bool]=NoneÜberschreibt das
hooks_raisedes Agent für diesen Aufruf.hooks_timeoutOptional[float]=NoneÜberschreibt das
hooks_timeoutdes 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]=Nonehooks=Noneon_predict_start=Noneon_predict_end=Nonehooks_raiseOptional[bool]=Nonehooks_timeoutOptional[float]=Nonemax_lenOptional[int]=Nonehead_max_lenOptional[int]=Nonemin_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,
) -> AnyBeantwortet 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=NonequestionsOptional[Dict[str, Any]]=Nonereturn_detailsbool=Falsemin_confidenceOptional[float]=Nonepredict_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=NonequestionsOptional[Dict[str, Any]]=Nonereturn_detailsbool=Falsemin_confidenceOptional[float]=Nonepredict_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
recordscompute_ecebool=Falseseedint=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
recordsmin_bucket_nint=MIN_BINNING_BUCKET_NMIN_BINNING_BUCKET_N
save_calibration
save_calibration(path: str) -> NoneSchreibt die Temperaturen und den Checkpoint, für den sie angepasst wurden. Schreibt keine Gewichte.
Parameter
pathstr
load_calibration
load_calibration(path: str) -> NoneLiest 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",
) -> AgentLä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]=NonetokenOptional[str]=NonesubfolderOptional[str]=Nonefastbool=Falsecompilebool=FalserevisionOptional[str]=Noneexpected_sha256Optional[Dict[str, str]]=Nonelang_temperaturesOptional[Dict[str, Dict[str, Any]]]=Nonehooks=Noneon_predict_start=Noneon_predict_end=Nonehooks_raisebool=Truehooks_concurrentbool=Truehooks_timeoutOptional[float]=NonecalibrationOptional[str]=NonebackendOptional[str]=Noneonnx_pathOptional[str]=Nonecompile_warmupbool=Truecompile_cachebool=Falsecompile_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_pathstrHuggingFace-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]=NoneOptionales HuggingFace-Token für einen privaten oder gated Checkpoint; fällt auf
$HF_TOKENzurück, genau wieAgent. Nur Tokenizer und Konfiguration werden geholt -- der Graph selbst ist der lokaleonnx_path.subfolderOptional[str]=NoneOptionaler Unterordner, wenn aus einem Repository-Bundle heruntergeladen wird.
revisionOptional[str]=NoneOptionale 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]]=NoneOptional {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
FileNotFoundErroraus und eine Digest-AbweichungValueError; beide Fehler lehnen das Laden ab.hooksHookArg=NoneOpt-in-Vorhersage-Hooks; siehe
laya.hooks.on_predict_startPredictHookArg=NoneEin Opt-in-Start-Hook, der vor der Inferenz läuft.
on_predict_endPredictHookArg=NoneEin Opt-in-End-Hook, der nach der Inferenz läuft.
hooks_raisebool=TrueWenn False, warnt ein fehlschlagender Hook und die Inferenz fährt fort.
hooks_concurrentbool=TrueWenn False, werden Hooks mit einem Lock serialisiert.
hooks_timeoutOptional[float]=NoneBegrenzt jeden Hook-Aufruf in Sekunden; None bedeutet kein Limit.
lang_temperaturesOptional[Dict[str, Dict[str, Any]]]=NoneOptionale Temperatur-Überschreibungen pro Sprache, verschlüsselt nach Sprach- code, jeweils
{"temperature": [3 floats], "temperature_by_options": {}}. Angewendet, wenn einlang=ansystem_one/predictübergeben wird, spiegelbildlich zum PyTorch-Agent; ein Backend-Wechsel verliert sonst die Kalibrierung.calibrationOptional[str]=None
load_calibration
load_calibration(path: str) -> NoneLiest 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_oneakzeptiert.langOptional[str]=NoneTemperatur-Überschreibung pro Sprache (siehe
lang_temperatures).hooksHookArg=NoneHooks pro Aufruf, angehängt nach den auf dem Agent installierten.
on_predict_startPredictHookArg=NoneEin Start-Hook pro Aufruf. Er kann den Zustand/die Fragen umschreiben oder
ctx.skip(...)aufrufen, um die Inferenz kurzzuschließen.on_predict_endPredictHookArg=NoneEin End-Hook pro Aufruf. Er kann die Ergebnisse umschreiben.
hooks_raiseOptional[bool]=NoneÜberschreibt das
hooks_raisedes Agent für diesen Aufruf.hooks_timeoutOptional[float]=NoneÜberschreibt das
hooks_timeoutdes Agent für diesen Aufruf.max_lenOptional[int]=NoneÜberschreibt das
max_lender Konfiguration für diesen Aufruf.head_max_lenOptional[int]=NoneÜberschreibt das
head_max_lender Konfiguration für diesen Aufruf.min_confidenceOptional[float]=NoneOpt-in-Enthaltungsschwelle auf
answer_confidence(#361); eine Antwort darunter wird mitlow_confidence: Truemarkiert 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
questionswerden gegen jeden Zustand evaluiert.questionsDict[str, Dict[str, Any]]Frage-Definitionen, genau wie von
system_oneakzeptiert.batch_sizeOptional[int]=NoneOptionaler Deckel für Zustände pro Session-Lauf.
Nonesendet sie alle in einem Lauf; setze ihn, um den Spitzenspeicher zu begrenzen, wenn du viele oder lange Zustände batchst.langOptional[str]=NoneTemperatur-Überschreibung pro Sprache, angewendet auf jeden Zustand; siehe
lang_temperatures.hooksHookArg=NoneHooks pro Aufruf, angehängt nach den auf dem Agent installierten.
on_predict_startPredictHookArg=NoneEin Start-Hook pro Aufruf. Er kann die Zustände/die Fragen umschreiben oder
ctx.skip(...)aufrufen, um die Inferenz kurzzuschließen.on_predict_endPredictHookArg=NoneEin End-Hook pro Aufruf. Er kann die Ergebnisse umschreiben.
hooks_raiseOptional[bool]=NoneÜberschreibt das
hooks_raisedes Agent für diesen Aufruf.hooks_timeoutOptional[float]=NoneÜberschreibt das
hooks_timeoutdes Agent für diesen Aufruf.max_lenOptional[int]=NoneÜberschreibt das
max_lender Konfiguration für diesen Aufruf.head_max_lenOptional[int]=NoneÜberschreibt das
head_max_lender Konfiguration für diesen Aufruf.sort_by_lengthbool=FalseGruppiert ähnlich große kodierte Zustände in Fenstern von acht Batches, um Padding zu reduzieren, genau wie
Agent.predict_batch. Erfordert ein explizitesbatch_sizegröß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]=NoneOpt-in-Enthaltungsschwelle auf
answer_confidence(#361); Antworten darunter werden mitlow_confidence: Truemarkiert 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_oneakzeptiert.windowOptional[int]=NoneState-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 inAgent.predict_long.strideOptional[int]=NoneToken-Schritt zwischen Fenstern. Standard ist
window // 2(50 % Überlappung).aggregatestr="auto""auto" (die Typregeln oben) ist vorerst der einzige Modus.
batch_sizeOptional[int]=NoneDeckel für Fenster pro Session-Lauf, um den Spitzenspeicher bei sehr langen Zuständen zu begrenzen.
langOptional[str]=NoneTemperaturauswahl pro Sprache, wie in
system_one.hooksHookArg=NoneHooks 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 mitctx.skip(...)antwortet, bekommtusage["windows"] == 0und keine Fenster-Zuordnung, und ein umgeschriebener Scan wird ohneanswer["window"]aggregiert.on_predict_startPredictHookArg=NoneEin Start-Hook pro Aufruf, wie in
system_one.on_predict_endPredictHookArg=NoneEin End-Hook pro Aufruf, wie in
system_one.hooks_raiseOptional[bool]=NoneÜberschreibt das
hooks_raisedes Agent für diesen Aufruf.hooks_timeoutOptional[float]=NoneÜberschreibt das
hooks_timeoutdes 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,
) -> AnyBeantwortet 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=NonequestionsOptional[Dict[str, Dict[str, Any]]]=Nonereturn_detailsbool=Falsemin_confidenceOptional[float]=Nonepredict_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=NonequestionsOptional[Dict[str, Dict[str, Any]]]=Nonereturn_detailsbool=Falsemin_confidenceOptional[float]=Nonepredict_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