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",
)

Runtime du modèle de décision System One : décisions rapides, non autorégressives et calibrées.

dtype est la cible de l’autocast, pas la précision de chaque appel. Sur MPS un appel ne fait de l’autocast qu’à partir de mps_amp_min_rows lignes, donc dtype peut indiquer float16 alors qu’un appel tourne en float32. dtype_for(rows) renvoie la précision d’un appel avec rows lignes.

Charge un checkpoint de Laya.

backend sélectionne « eager », « auto », « compile » ou « tilelang » ; voir laya.backends. Il a la priorité sur fast et compile. Omets-le pour conserver ces flags hérités. Pour ONNX, utilise plutôt load(backend="onnx").

revision épingle éventuellement le téléchargement depuis le Hub à un commit SHA/branche/tag explicite ; si on l’omet, le défaut normal de huggingface_hub et le cache hors ligne existant sont utilisés. expected_sha256 ({path relative to the checkpoint dir: hexdigest}) vérifie l’intégrité des artefacts avant qu’aucun poids ne soit analysé ou exécuté ; il est optionnel et s’applique aussi aux répertoires locaux. Un artefact manquant lève FileNotFoundError et une divergence d’empreinte lève ValueError ; l’une ou l’autre de ces erreurs refuse le chargement.

fast=True remplace la passe avant de l’encodeur/de la tête par le chemin rapide TileLang (CUDA uniquement, nécessite pip install laya[fast]) ; voir Agent.accelerate.

compile=True exécute le modèle sous torch.compile et active reference_compile de l’encodeur de ModernBERT. torch.compile se spécialise par forme d’entrée et Laya en voit une nouvelle à presque chaque requête, donc ces graphes coûtent souvent plus qu’ils ne rapportent ; utilise-le quand le trafic est répétitif. fast=True a la priorité, car le chemin TileLang remplace la passe avant qui serait compilée. Les agents compilés exécutent warmup() avant de revenir ; compile_warmup=False reporte ce travail aux requêtes ou à un appel manuel à warmup(). Les agents eager et fast restent inchangés. compile_cache=True active un répertoire Laya Inductor persistant (à l’échelle du processus), en respectant un TORCHINDUCTOR_CACHE_DIR existant ; voir les notes d’ingénierie de compilation. compile_mode="reduce-overhead" active les graphes CUDA. Il peut retenir plus de mémoire GPU et enregistre chaque nouvelle forme séparément. Les sorties CUDA sont copiées avant la relecture suivante ; les passes avant de graphes CUDA compilés sont sérialisées. Le mode par défaut reste « default ».

subfolder sélectionne un checkpoint dans un dépôt qui en regroupe plusieurs, p. ex. Agent("convaiinnovations/laya", subfolder="multilingual"). Seul ce sous-dossier est téléchargé, donc le regroupement ne coûte pas toute la famille à chaque utilisateur.

calibration est un chemin JSON optionnel avec temperature et temperature_by_options. Il est appliqué après la configuration du checkpoint, donc une table ajustée écrase les scalaires livrés sans réécrire model.safetensors.

hooks / on_predict_start / on_predict_end observent ou façonnent chaque prédiction ; voir laya.hooks. hooks_raise=False avertit et continue quand un hook échoue, hooks_concurrent=False sérialise les hooks qui ne sont pas sûrs à exécuter en parallèle, et hooks_timeout borne chaque appel de hook en secondes (None signifie aucune limite).

backend: str

Le backend d’inférence actif, y compris les flags hérités compile et fast.

backend_object

L’objet Backend installé, ou None pour un runtime hérité.

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

Change de backend ; les backends indisponibles avertissent et utilisent eager sauf si strict=True.

Les options vont au constructeur du backend, p. ex. warmup=False pour compile ou use_graphs=False pour tilelang. Le changement attend l’inférence en cours.

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

Remplace la passe avant du modèle par le chemin rapide TileLang (kernels fusionnés GEMM/GEGLU/LayerNorm/RoPE, flash attention à fenêtre glissante, poids résidents en 16 bits, graphes CUDA par bucket de forme).

Le chemin rapide s’exécute dans le dtype d’autocast de l’agent au moment de l’appel (bf16 ou fp16), donc il correspond à la passe avant standard qu’il remplace à l’arrondi près (voir benchmarks/parity_fast.py). Après avoir changé agent.dtype, appelle deaccelerate() puis accelerate() pour le reconstruire. Renvoie True si il est activé. Avec strict=False, toute défaillance (pas de CUDA, tilelang absent) laisse le chemin standard en place.

warmup(shapes=None) -> float

Exécute dès maintenant la passe avant sur une entrée synthétique de chaque forme et renvoie les secondes que cela a pris.

compile=True appelle ceci au chargement, sauf si compile_warmup=False. Des formes supplémentaires peuvent toujours être préchauffées manuellement. fast=True construit ses kernels et ses graphes CUDA par bucket de forme au premier usage ; appeler ceci avant de servir sort ce coût des premières requêtes. Avec la passe avant standard, ce sont quelques passes avant ordinaires. shapes est une liste de (rows, tokens, markers) ; les jetons sont plafonnés au max_len de l’agent. Rien n’est renvoyé à un appelant ni enregistré pour lui, et les hooks ne s’exécutent pas.

deaccelerate()

Restaure la passe avant standard.

dtype_for(rows: int) -> torch.dtype

Précision dans laquelle tourne une passe avant avec rows lignes de question.

dtype est la cible de l’autocast, fixée une fois au chargement. Le fait qu’une passe avant fasse de l’autocast se décide par appel : sur MPS uniquement à partir de mps_amp_min_rows lignes. Ceci renvoie dtype quand une passe avant avec rows lignes fait de l’autocast, et torch.float32 sinon. Un appel predict traite une ligne par question.

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]]

Évalue les mêmes questions sur de nombreux états, en les regroupant dans des passes avant partagées.

C’est le chemin de débit. system_one/predict traitent un état par passe avant ; sur un GPU cela laisse la majeure partie de la dimension de lot inactive. predict_batch rassemble les lignes de question de plusieurs états dans un seul tenseur, donc un appel qui prendrait N passes avant séquentielles en prend une (ou ceil(len(states) / batch_size)), ce qui est plusieurs fois plus rapide par décision sur GPU.

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]

Évalue des questions sur un état plus long que la fenêtre de contexte, en le parcourant en fenêtres chevauchantes et en agrégeant par question.

system_one/predict tronquent un état qui dépasse max_len à une seule fenêtre (la première, ou pour une liste de conversation la dernière), en abandonnant le reste en silence. predict_long tokenise l’état une fois, le découpe en fenêtres de jetons chevauchantes, score chaque fenêtre dans des passes avant partagées (via predict_batch), et combine les réponses par fenêtre :

• noul -> P(true) est le max sur les fenêtres (l’énoncé tient si une fenêtre le soutient)
• choice-> la réponse de la fenêtre la plus confiante, pour qu’un signal localisé ne soit pas mis en minorité par les nombreuses fenêtres neutres dont un long document est majoritairement fait (la moyenne le noie -- la majorité neutre domine)
• score -> le niveau de la fenêtre la plus confiante, de même

La probabilité/confiance renvoyée est celle de la fenêtre décisive, pas un nombre calibré pour tout le document : un max noul sur beaucoup de fenêtres dérive vers le haut avec le nombre de fenêtres même sans signal, et choice peut tomber sur une fenêtre résolument neutre quand rien dans le document n’est décisif. Chaque réponse porte donc answer["window"] — l’index de la fenêtre décisive, token_start/token_end dans l’état tokenisé, et le count de fenêtres — pour qu’un appelant puisse inspecter l’intervalle d’où vient la réponse plutôt que de faire confiance au nombre brut. Cette plage est celle que le modèle a lue, pas seulement celle demandée : la fenêtre est plafonnée à la place que laissent les questions, donc ce qui est transmis à predict_batch n’est pas tronqué une seconde fois.

Un état qui tient déjà dans une seule fenêtre est passé directement à system_one (sortie identique).

Les hooks enveloppent l’inférence qui répond à l’état, laquelle, pour un document nécessitant plusieurs fenêtres, est l’unique predict_batch partagé sur elles : on_predict_start se déclenche une fois, et ctx.states contient les textes de fenêtre décodés dans l’ordre de parcours -- pas le state de l’appelant, qui a été tokenisé pour les produire. Trois issues découlent de ce que la chaîne laisse derrière elle :

• ctx.skip([result]) répond au document : la charge revient sans attribution de fenêtre et avec usage["windows"] à 0, parce que rien n’a été scoré
• un parcours laissé tel que cette méthode l’a construit : chaque fenêtre est scorée, chaque réponse porte answer["window"], et usage["windows"] est le nombre de fenêtres
• un parcours réécrit (ctx.states remplacé, de quelque façon que ce soit) : les réponses sont agrégées sur les états qui ont été scorés, mais aucune réponse ne porte answer["window"] -- les décalages ci-dessus décrivent les fenêtres de cette méthode, pas le texte que le modèle a lu

Renvoie un seul dict de résultat, de même forme que system_one, avec usage["windows"] ajouté. La clé est toujours présente et compte les fenêtres que le modèle a scorées pour produire la réponse : 1 pour un état qui tenait dans une fenêtre, N pour un document parcouru en N fenêtres chevauchantes (ou le N auquel un hook de début les a réécrites), et 0 quand un hook de début a répondu au document, ou n’a laissé aucun état à scorer, avant qu’aucune fenêtre ne soit lue -- sur l’un ou l’autre chemin, pour qu’une réponse en cache ne se lise jamais comme une fenêtre que le modèle a lue.

Sur plusieurs fenêtres, les clés de troncature sont combinées comme tout autre champ de usage : truncated, state_tokens et state_tokens_dropped sont sommés (donc truncated est le nombre de fenêtres qui ont été coupées, et les comptes de jetons incluent le chevauchement), et truncated_questions est la liste de la dernière fenêtre. Les deux peuvent diverger : quand seule une fenêtre antérieure a été coupée, truncated est supérieur à 0 et truncated_questions est vide. Une fenêtre est coupée quand elle est plus grande que la place que laisse la tête d’une question. Teste usage["truncated"] > 0 ici, pas is True.

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]

Évalue des questions typées sur un état en une seule passe avant parallèle.

Pour scorer beaucoup d’états à la fois, voir predict_batch, qui partage les passes avant entre eux.

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

Répond à state contre un schéma (schéma JSON ou modèle pydantic) et renvoie des valeurs typées.

Voir laya.structured. Passe exactement l’un de schema ou questions ; les arguments nommés supplémentaires sont transmis à predict / system_one.

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]

Répond à de nombreux états contre un seul schéma (schéma JSON ou modèle pydantic) en un appel par lots.

La forme haut débit de :meth:decide : le schéma est planifié une fois et ses questions tournent sur chaque état via :meth:predict_batch (passes avant partagées, résultats dans l’ordre d’entrée), puis les réponses de chaque état sont projetées comme le fait decide. Les arguments nommés supplémentaires (batch_size=, lang=, hooks=, ...) sont transmis à predict_batch. Voir laya.structured.

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

Ajuste des températures par bucket à partir d’enregistrements CPU et les stocke sur cet agent.

records sont (qtype, logits, target, k). Construis-les avec laya.calibrate.records_from_labeled quand tu as des passes avant étiquetées ; cette méthode ne télécharge pas de poids ni n’écrit model.safetensors. seed n’affecte que la partition ECE réservée quand compute_ece est true. Le cfg du checkpoint est laissé tel que chargé.

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

Ajuste une table de binning par histogramme par-dessus les températures ajustées de cet agent et la stocke.

records sont les mêmes tuples (qtype, logits, target[, k]) que ceux consommés par fit_temperatures. La table est indexée exactement comme temperature_by_options, se compose par-dessus les températures actuelles, et save_calibration l’écrit sous le nom binning_map.

save_calibration(path: str) -> None

Écrit les températures et le checkpoint pour lequel elles ont été ajustées. N’écrit pas les poids.

load_calibration(path: str) -> None

Lit sur cet agent une table JSON écrite par save_calibration.

Un fichier sans version est traité comme la version 1 et se charge quand même. Un fichier plus récent dont le checkpoint enregistré ne correspond pas à cet agent avertit et se charge quand même. Les valeurs qui ne sont pas des nombres, ou qui sortent de [TEMP_MIN, TEMP_MAX], sont bornées avec clamp_temperature de la même façon qu’au chargement d’un checkpoint.

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

Charge un agent Laya.

subfolder choisit un checkpoint dans un dépôt qui en regroupe plusieurs :

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 accepte aussi un nom de checkpoint ou un alias -- les mêmes que résout Router, donc les deux points d’entrée lisent une seule table :

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

Tout le reste (un id de dépôt Hub, un répertoire local) est transmis à Agent inchangé.

backend sélectionne « auto », « eager », « compile », « tilelang » ou « onnx ». ONNX renvoie l’ONNXAgent existant, avec onnx_path (par défaut « laya.onnx »). Les autres backends utilisent Agent ; un backend explicite a la priorité sur les flags hérités.

revision/expected_sha256 épinglent et vérifient les artefacts téléchargés ; voir Agent. hooks / on_predict_start / on_predict_end observent ou façonnent chaque prédiction ; voir laya.hooks. calibration est le même chemin JSON optionnel accepté par Agent.

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,
)

Runtime du modèle de décision System One via ONNX : décisions rapides optimisées pour CPU.

Charge un agent Laya propulsé par ONNX Runtime.

load_calibration(path: str) -> None

Lit sur cet agent une table JSON écrite par save_calibration.

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]

Évalue des questions typées sur un état en une seule exécution de session ONNX Runtime.

lang sélectionne une substitution de température par langue (voir lang_temperatures), en accord avec la signature de Agent.system_one de PyTorch, de sorte que l’un ou l’autre backend remplace l’autre sans changement.

Défini en termes de predict_batch, exactement comme l’est Agent.system_one de PyTorch, pour que les chemins mono-état et par lots ne puissent pas diverger.

Pour scorer beaucoup d’états à la fois, voir predict_batch, qui partage les exécutions de session entre eux.

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]]

Évalue les mêmes questions sur de nombreux états, en partageant les exécutions de session ONNX Runtime.

Le chemin de débit, calqué sur laya.agent.Agent.predict_batch : system_one rassemble les lignes de question d’un état par exécution de session, donc N états coûtent N exécutions. predict_batch rassemble les lignes de plusieurs états en une exécution -- ou ceil(len(states) / batch_size) d’entre elles -- ce qui est là où le parallélisme propre d’ONNX Runtime est payant sur CPU.

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]

Évalue des questions sur un état plus long que la fenêtre de contexte, en le parcourant en fenêtres chevauchantes et en agrégeant par question.

Le portage ONNX de laya.agent.Agent.predict_long, avec les mêmes règles d’agrégation : system_one tronque un état qui dépasse max_len à une seule fenêtre, en abandonnant le reste en silence. predict_long tokenise l’état une fois, le découpe en fenêtres de jetons chevauchantes, score chaque fenêtre via predict_batch -- ainsi les fenêtres partagent des exécutions de session ONNX Runtime plutôt que d’en coûter une chacune -- et combine les réponses par fenêtre :

• noul -> P(true) est le max sur les fenêtres (l’énoncé tient si une fenêtre le soutient)
• choice-> la réponse de la fenêtre la plus confiante, pour qu’un signal localisé ne soit pas mis en minorité par les nombreuses fenêtres neutres dont un long document est majoritairement fait
• score -> le niveau de la fenêtre la plus confiante, de même

La probabilité/confiance renvoyée est celle de la fenêtre décisive, pas un nombre calibré pour tout le document, pour les mêmes raisons que celles données par le docstring PyTorch. Chaque réponse porte answer["window"] -- l’index de la fenêtre décisive, token_start/token_end dans l’état tokenisé, et le count de fenêtres.

Un état qui tient déjà dans une seule fenêtre est passé directement à system_one (sortie identique).

Renvoie un seul dict de résultat, de même forme que system_one, avec usage["windows"] ajouté. Sur plusieurs fenêtres, les clés de troncature sont sommées ou portées de la même façon que dans Agent.predict_long : truncated est un nombre de fenêtres et truncated_questions est la liste de la dernière fenêtre, donc truncated peut être supérieur à 0 alors que la liste est vide.

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

Répond à state contre un schéma (schéma JSON ou modèle pydantic) et renvoie des valeurs typées.

Voir laya.structured. Passe exactement l’un de schema ou questions ; les arguments nommés supplémentaires sont transmis à predict / system_one.

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]

Répond à de nombreux états contre un seul schéma via predict_batch ; voir laya.structured.

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