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 del modelo de decisión System One: decisiones rápidas, no autorregresivas y calibradas.

dtype es el destino del autocast, no la precisión de cada llamada. En MPS una llamada solo hace autocast a partir de mps_amp_min_rows filas, así que dtype puede decir float16 mientras una llamada corre en float32. dtype_for(rows) devuelve la precisión de una llamada con rows filas.

Carga un checkpoint de Laya.

backend selecciona "eager", "auto", "compile" o "tilelang"; consulta laya.backends. Tiene prioridad sobre fast y compile. Omítelo para conservar esos flags heredados. Para ONNX usa load(backend="onnx") en su lugar.

revision fija opcionalmente la descarga del Hub a un commit SHA/rama/tag explícito; si se omite, se usan el valor predeterminado normal de huggingface_hub y la caché offline existente. expected_sha256 ({path relative to the checkpoint dir: hexdigest}) verifica la integridad de los artefactos antes de que se analice o ejecute cualquier peso; es opcional y también se aplica a directorios locales. Un artefacto faltante lanza FileNotFoundError y una discrepancia de digest lanza ValueError; cualquiera de los dos errores rechaza la carga.

fast=True sustituye el forward del encoder/cabeza por la ruta rápida de TileLang (solo CUDA, requiere pip install laya[fast]); consulta Agent.accelerate.

compile=True ejecuta el modelo bajo torch.compile y activa reference_compile del encoder de ModernBERT. torch.compile se especializa por forma de entrada y Laya ve una nueva en casi todas las peticiones, así que esos grafos suelen costar más de lo que rinden; úsalo cuando el tráfico sea repetitivo. fast=True tiene prioridad, porque la ruta de TileLang reemplaza el forward que se compilaría. Los agents compilados ejecutan warmup() antes de devolver; compile_warmup=False difiere ese trabajo a las peticiones o a una llamada manual a warmup(). Los agents eager y fast no cambian. compile_cache=True opta por un directorio Laya Inductor persistente (a nivel de proceso), respetando cualquier TORCHINDUCTOR_CACHE_DIR existente; consulta las notas de ingeniería de compilación. compile_mode="reduce-overhead" opta por grafos CUDA. Puede retener más memoria de GPU y registra cada forma nueva por separado. Las salidas CUDA se copian antes del siguiente replay; los forwards de grafos CUDA compilados se serializan. El modo predeterminado sigue siendo "default".

subfolder selecciona un checkpoint de un repositorio que empaqueta varios, p. ej. Agent("convaiinnovations/laya", subfolder="multilingual"). Solo se descarga ese subdirectorio, así que el empaquetado no le cuesta a cada usuario toda la familia.

calibration es una ruta JSON opcional con temperature y temperature_by_options. Se aplica después de la configuración del checkpoint, así que un mapa ajustado sobrescribe los escalares distribuidos sin reescribir model.safetensors.

hooks / on_predict_start / on_predict_end observan o moldean cada predicción; consulta laya.hooks. hooks_raise=False avisa y continúa cuando falla un hook, hooks_concurrent=False serializa los hooks que no son seguros de ejecutar en paralelo, y hooks_timeout limita cada llamada de hook en segundos (None significa sin límite).

backend: str

El backend de inferencia activo, incluidas las flags heredadas compile y fast.

backend_object

El objeto Backend instalado, o None para un runtime heredado.

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

Cambia de backend; los backends no disponibles avisan y usan eager a menos que strict=True.

Las opciones van al constructor del backend, p. ej. warmup=False para compile o use_graphs=False para tilelang. El cambio espera a la inferencia en curso.

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

Sustituye el forward del modelo por la ruta rápida de TileLang (kernels fusionados de GEMM/GEGLU/LayerNorm/RoPE, flash attention de ventana deslizante, pesos residentes de 16 bits, grafos CUDA por cubo de forma).

La ruta rápida se ejecuta en el dtype de autocast del agent en el momento de la llamada (bf16 o fp16), así que coincide con el forward estándar al que reemplaza dentro del redondeo (consulta benchmarks/parity_fast.py). Después de cambiar agent.dtype, llama a deaccelerate() y luego a accelerate() para reconstruirla. Devuelve True si queda habilitada. Con strict=False, cualquier fallo (sin CUDA, falta tilelang) deja la ruta estándar en su lugar.

warmup(shapes=None) -> float

Ejecuta ahora el forward sobre una entrada sintética de cada forma y devuelve los segundos que tardó.

compile=True llama a esto al cargar a menos que compile_warmup=False. Las formas adicionales todavía pueden calentarse manualmente. fast=True construye sus kernels y grafos CUDA por cubo de forma en el primer uso; llamar a esto antes de servir saca ese costo de las primeras peticiones. Con el forward estándar son unas pocas pasadas hacia adelante normales. shapes es una lista de (rows, tokens, markers); los tokens se limitan al max_len del agent. No se devuelve ni se registra nada para ningún llamador, y los hooks no se ejecutan.

deaccelerate()

Restaura el forward estándar.

dtype_for(rows: int) -> torch.dtype

Precisión en la que corre una pasada hacia adelante con rows filas de pregunta.

dtype es el destino del autocast, fijado una vez en el momento de la carga. Si una pasada hace autocast se decide por llamada: en MPS solo a partir de mps_amp_min_rows filas. Esto devuelve dtype cuando una pasada con rows filas hace autocast, y torch.float32 cuando no. Una llamada a predict corre una fila por pregunta.

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

Evalúa las mismas preguntas sobre muchos estados, empaquetándolos en pasadas hacia adelante compartidas.

Esta es la ruta de rendimiento. system_one/predict manejan un estado por pasada hacia adelante; en una GPU eso deja inactiva la mayor parte de la dimensión de lote. predict_batch reúne las filas de pregunta de varios estados en un solo tensor, así que una llamada que tomaría N pasadas secuenciales hacia adelante toma una (o ceil(len(states) / batch_size)), lo que es varias veces más rápido por decisión en 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]

Evalúa preguntas sobre un estado más largo que la ventana de contexto, escaneándolo en ventanas superpuestas y agregando por pregunta.

system_one/predict truncan un estado que excede max_len a una sola ventana (la primera, o para una lista de conversación la última), descartando el resto en silencio. predict_long tokeniza el estado una vez, lo divide en ventanas de tokens superpuestas, puntúa cada ventana en pasadas hacia adelante compartidas (mediante predict_batch) y combina las respuestas por ventana:

• noul -> P(true) es el máximo sobre las ventanas (la afirmación se sostiene si alguna ventana la respalda)
• choice-> la respuesta de la única ventana más segura, para que una señal localizada no sea superada por las muchas ventanas neutras de las que en su mayoría se compone un documento largo (promediar la ahoga -- la mayoría neutra domina)
• score -> el nivel de la ventana más segura, igualmente

La probabilidad/confianza devuelta es la de la ventana que decide, no un número calibrado para todo el documento: un máximo de noul sobre muchas ventanas deriva hacia arriba con el número de ventanas aun sin señal, y choice puede caer en una ventana seguramente neutra cuando nada en el documento es decisivo. Por eso cada respuesta lleva answer["window"] — el index de la ventana que decide, token_start/token_end dentro del estado tokenizado, y el count de ventanas — de modo que quien la llame pueda inspeccionar el tramo del que vino la respuesta en lugar de confiar en el número bruto. Ese tramo es el que leyó el modelo, no solo el solicitado: la ventana está limitada al espacio que dejan las preguntas, así que lo que se pasa a predict_batch no se vuelve a cortar.

Un estado que ya cabe en una ventana se pasa directamente a system_one (salida idéntica).

Los hooks envuelven la inferencia que responde al estado, que para un documento que necesita varias ventanas es el único predict_batch compartido sobre ellas: on_predict_start se dispara una vez, y ctx.states contiene los textos de ventana decodificados en orden de escaneo -- no el state del llamador, que fue tokenizado para producirlos. Del resultado que deja la cadena se siguen tres desenlaces:

• ctx.skip([result]) responde al documento: la carga vuelve sin atribución de ventana y con usage["windows"] en 0, porque no se puntuó nada
• un escaneo dejado tal como lo construyó este método: se puntúa cada ventana, cada respuesta lleva answer["window"], y usage["windows"] es el recuento de ventanas
• un escaneo reescrito (ctx.states reemplazado, de cualquier forma): las respuestas se agregan sobre los estados que se puntuaron, pero ninguna respuesta lleva answer["window"] -- los desplazamientos anteriores describen las ventanas de este método, no el texto que leyó el modelo

Devuelve un único dict de resultado, con la misma forma que system_one, con usage["windows"] añadido. La clave siempre está presente y cuenta las ventanas que el modelo puntuó para producir la respuesta: 1 para un estado que cabía en una ventana, N para un documento escaneado en N ventanas superpuestas (o el N al que las reescribió un hook de inicio), y 0 cuando un hook de inicio respondió al documento, o no dejó estados que puntuar, antes de que se leyera ninguna ventana -- en cualquiera de las dos rutas, así que una respuesta en caché nunca se lee como una ventana que el modelo leyó.

A lo largo de varias ventanas, las claves de truncamiento se combinan como cualquier otro campo de usage: truncated, state_tokens y state_tokens_dropped se suman (así que truncated es el número de ventanas que se cortaron, y los recuentos de tokens incluyen la superposición), y truncated_questions es la lista de la última ventana. Las dos pueden discrepar: cuando solo se cortó una ventana anterior, truncated es mayor que 0 y truncated_questions está vacía. Una ventana se corta cuando es mayor que el espacio que deja la cabeza de una pregunta. Comprueba usage["truncated"] > 0 aquí, no 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]

Evalúa preguntas tipadas a través del estado en una sola pasada hacia adelante paralela.

Para puntuar muchos estados a la vez, consulta predict_batch, que comparte pasadas hacia adelante entre ellos.

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

Responde a state contra un schema (JSON schema o modelo pydantic) y devuelve valores tipados.

Consulta laya.structured. Pasa exactamente uno de schema o questions; los argumentos de palabra clave adicionales se reenvían a 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]

Responde a muchos estados contra un schema (JSON schema o modelo pydantic) en una sola llamada por lotes.

La forma de rendimiento de :meth:decide: el schema se planifica una vez y sus preguntas corren sobre cada estado a través de :meth:predict_batch (pasadas hacia adelante compartidas, resultados en orden de entrada), y luego las respuestas de cada estado se proyectan como lo hace decide. Los argumentos de palabra clave adicionales (batch_size=, lang=, hooks=, ...) se reenvían a predict_batch. Consulta laya.structured.

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

Ajusta temperaturas por cubo a partir de registros de CPU y las guarda en este agent.

records son (qtype, logits, target, k). Constrúyelos con laya.calibrate.records_from_labeled cuando tengas forwards etiquetados; este método no descarga pesos ni escribe model.safetensors. seed solo afecta la partición reservada de ECE cuando compute_ece es true. El cfg del checkpoint se deja tal como se cargó.

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

Ajusta un mapa de binning por histograma sobre las temperaturas ajustadas de este agent y lo guarda.

records son las mismas tuplas (qtype, logits, target[, k]) que consumía fit_temperatures. El mapa está indexado exactamente como temperature_by_options, se compone sobre las temperaturas actuales y save_calibration lo escribe como binning_map.

save_calibration(path: str) -> None

Escribe las temperaturas y el checkpoint para el que se ajustaron. No escribe los pesos.

load_calibration(path: str) -> None

Lee en este agent un mapa JSON escrito por save_calibration.

Un archivo sin version se trata como versión 1 y se carga igual. Un archivo más nuevo cuyo checkpoint registrado no coincide con este agent avisa y se carga igual. Los valores que no son números, o que quedan fuera de [TEMP_MIN, TEMP_MAX], se recortan con clamp_temperature igual que al cargar 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

Carga un agent de Laya.

subfolder elige un checkpoint de un repositorio que empaqueta varios:

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 también acepta un nombre de checkpoint o alias -- los mismos que resuelve Router, así que ambos puntos de entrada leen una sola tabla:

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

Cualquier otra cosa (un id de repo del Hub, un directorio local) se pasa a Agent sin cambios.

backend selecciona "auto", "eager", "compile", "tilelang" u "onnx". ONNX devuelve el ONNXAgent existente, con onnx_path (predeterminado "laya.onnx"). Los demás backends usan Agent; un backend explícito tiene prioridad sobre los flags heredados.

revision/expected_sha256 fijan y verifican los artefactos descargados; consulta Agent. hooks / on_predict_start / on_predict_end observan o moldean cada predicción; consulta laya.hooks. calibration es la misma ruta JSON opcional que acepta 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 del modelo de decisión System One vía ONNX: decisiones rápidas optimizadas para CPU.

Carga un agent de Laya respaldado por ONNX Runtime.

load_calibration(path: str) -> None

Lee en este agent un mapa JSON escrito por 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]

Evalúa preguntas tipadas a través del estado en una sola ejecución de sesión de ONNX Runtime.

lang selecciona una sobrescritura de temperatura por idioma (consulta lang_temperatures), coincidiendo con la firma de Agent.system_one de PyTorch, de modo que cualquiera de los dos backends es intercambiable por el otro.

Se define en términos de predict_batch, exactamente como el Agent.system_one de PyTorch, para que las rutas de un solo estado y por lotes no puedan divergir.

Para puntuar muchos estados a la vez, consulta predict_batch, que comparte ejecuciones de sesión entre ellos.

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

Evalúa las mismas preguntas sobre muchos estados, compartiendo ejecuciones de sesión de ONNX Runtime.

La ruta de rendimiento, que replica laya.agent.Agent.predict_batch: system_one reúne las filas de pregunta de un estado por ejecución de sesión, así que N estados cuestan N ejecuciones. predict_batch reúne las filas de varios estados en una ejecución -- o ceil(len(states) / batch_size) de ellas -- que es donde el paralelismo propio de ONNX Runtime rinde en 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]

Evalúa preguntas sobre un estado más largo que la ventana de contexto, escaneándolo en ventanas superpuestas y agregando por pregunta.

El port a ONNX de laya.agent.Agent.predict_long, con las mismas reglas de agregación: system_one trunca un estado que excede max_len a una sola ventana, descartando el resto en silencio. predict_long tokeniza el estado una vez, lo divide en ventanas de tokens superpuestas, puntúa cada ventana a través de predict_batch -- así las ventanas comparten ejecuciones de sesión de ONNX Runtime en lugar de costar una cada una -- y combina las respuestas por ventana:

• noul -> P(true) es el máximo sobre las ventanas (la afirmación se sostiene si alguna ventana la respalda)
• choice-> la respuesta de la única ventana más segura, para que una señal localizada no sea superada por las muchas ventanas neutras de las que en su mayoría se compone un documento largo
• score -> el nivel de la ventana más segura, igualmente

La probabilidad/confianza devuelta es la de la ventana que decide, no un número calibrado para todo el documento, por las mismas razones que da el docstring de PyTorch. Cada respuesta lleva answer["window"] -- el index de la ventana que decide, token_start/token_end dentro del estado tokenizado, y el count de ventanas.

Un estado que ya cabe en una ventana se pasa directamente a system_one (salida idéntica).

Devuelve un único dict de resultado, con la misma forma que system_one, con usage["windows"] añadido. A lo largo de varias ventanas, las claves de truncamiento se suman o se arrastran igual que en Agent.predict_long: truncated es un recuento de ventanas y truncated_questions es la lista de la última ventana, así que truncated puede ser mayor que 0 mientras la lista está vacía.

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

Responde a state contra un schema (JSON schema o modelo pydantic) y devuelve valores tipados.

Consulta laya.structured. Pasa exactamente uno de schema o questions; los argumentos de palabra clave adicionales se reenvían a 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]

Responde a muchos estados contra un schema a través de predict_batch; consulta laya.structured.

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