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 do modelo de decisão System One: decisões rápidas, não autorregressivas e calibradas.

dtype é o destino do autocast, não a precisão de cada chamada. Em MPS, uma chamada só faz autocast a partir de mps_amp_min_rows linhas, então dtype pode dizer float16 enquanto uma chamada roda em float32. dtype_for(rows) retorna a precisão de uma chamada com rows linhas.

Carrega um checkpoint do Laya.

backend seleciona "eager", "auto", "compile" ou "tilelang"; consulte laya.backends. Ele tem precedência sobre fast e compile. Omita-o para manter essas flags legadas. Para ONNX, use load(backend="onnx") em vez disso.

revision fixa opcionalmente o download do Hub a um commit SHA/branch/tag explícito; quando omitido, usa o padrão normal do huggingface_hub e o cache offline existente. expected_sha256 ({path relative to the checkpoint dir: hexdigest}) verifica a integridade dos artefatos antes de qualquer peso ser analisado ou executado; é opt-in e também se aplica a diretórios locais. Um artefato ausente lança FileNotFoundError e uma divergência de digest lança ValueError; qualquer um dos dois erros recusa o carregamento.

fast=True troca a passagem direta do encoder/cabeça pelo caminho rápido do TileLang (somente CUDA, requer pip install laya[fast]); consulte Agent.accelerate.

compile=True executa o modelo sob torch.compile e ativa o reference_compile do encoder do ModernBERT. torch.compile se especializa por forma de entrada e o Laya vê uma nova em quase toda requisição, então esses grafos geralmente custam mais do que rendem; use quando o tráfego for repetitivo. fast=True tem precedência, porque o caminho do TileLang substitui a passagem direta que seria compilada. Agentes compilados executam warmup() antes de retornar; compile_warmup=False adia esse trabalho para as requisições ou uma chamada manual a warmup(). Agentes eager e fast não mudam. compile_cache=True adota um diretório persistente do Inductor do Laya (em todo o processo), respeitando qualquer TORCHINDUCTOR_CACHE_DIR existente; consulte as notas de engenharia da compilação. compile_mode="reduce-overhead" adota grafos CUDA. Ele pode reter mais memória de GPU e registra cada nova forma separadamente. As saídas CUDA são copiadas antes do próximo replay; as passagens diretas com grafos CUDA compilados são serializadas. O modo padrão continua "default".

subfolder seleciona um checkpoint de um repositório que empacota vários, por exemplo Agent("convaiinnovations/laya", subfolder="multilingual"). Só essa subpasta é baixada, então o empacotamento não custa a cada usuário a família inteira.

calibration é um caminho JSON opcional com temperature e temperature_by_options. É aplicada depois da configuração do checkpoint, então um mapa ajustado sobrescreve os escalares distribuídos sem reescrever model.safetensors.

hooks / on_predict_start / on_predict_end observam ou moldam cada predição; consulte laya.hooks. hooks_raise=False avisa e continua quando um hook falha, hooks_concurrent=False serializa os hooks que não são seguros de executar em paralelo, e hooks_timeout limita cada chamada de hook em segundos (None significa sem limite).

backend: str

O backend de inferência ativo, incluindo as flags legadas compile e fast.

backend_object

O objeto Backend instalado, ou None para um runtime legado.

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

Troca de backends; os backends indisponíveis avisam e usam eager, a menos que strict=True.

As opções vão para o construtor do backend, por exemplo warmup=False para compile ou use_graphs=False para tilelang. A troca aguarda a inferência em andamento.

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

Substitui a passagem direta do modelo pelo caminho rápido do TileLang (kernels fundidos de GEMM/GEGLU/LayerNorm/RoPE, flash attention de janela deslizante, pesos residentes de 16 bits, grafos CUDA por bucket de forma).

O caminho rápido roda no dtype de autocast do agente no momento da chamada (bf16 ou fp16), então coincide com a passagem direta padrão que substitui dentro do arredondamento (consulte benchmarks/parity_fast.py). Depois de mudar agent.dtype, chame deaccelerate() e então accelerate() para reconstruí-lo. Retorna True se habilitado. Com strict=False, qualquer falha (sem CUDA, tilelang ausente) deixa o caminho padrão no lugar.

warmup(shapes=None) -> float

Executa agora a passagem direta sobre uma entrada sintética de cada forma e retorna os segundos que levou.

compile=True chama isto ao carregar, a menos que compile_warmup=False. Formas extras ainda podem ser aquecidas manualmente. fast=True constrói seus kernels e grafos CUDA por bucket de forma no primeiro uso; chamar isto antes de servir tira esse custo das primeiras requisições. Com a passagem direta padrão, são algumas passagens diretas comuns. shapes é uma lista de (rows, tokens, markers); os tokens são limitados ao max_len do agente. Nada é retornado a nenhum chamador nem registrado para ele, e os hooks não são executados.

deaccelerate()

Restaura a passagem direta padrão.

dtype_for(rows: int) -> torch.dtype

Precisão em que roda uma passagem direta com rows linhas de pergunta.

dtype é o destino do autocast, definido uma vez no momento do carregamento. Se uma passagem direta faz autocast é decidido por chamada: em MPS, só a partir de mps_amp_min_rows linhas. Isto retorna dtype quando uma passagem direta com rows linhas faz autocast, e torch.float32 quando não faz. Uma chamada a predict roda uma linha por pergunta.

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

Avalia as mesmas perguntas sobre muitos estados, empacotando-os em passagens diretas compartilhadas.

Este é o caminho de rendimento. system_one/predict tratam um estado por passagem direta; em uma GPU isso deixa a maior parte da dimensão de lote ociosa. predict_batch reúne as linhas de pergunta de vários estados em um único tensor, então uma chamada que levaria N passagens diretas sequenciais leva uma (ou ceil(len(states) / batch_size)), o que é várias vezes mais rápido por decisão na 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]

Avalia perguntas sobre um estado mais longo que a janela de contexto, escaneando-o em janelas sobrepostas e agregando por pergunta.

system_one/predict truncam um estado que excede max_len para uma única janela (a primeira, ou para uma lista de conversa a última), descartando o resto em silêncio. predict_long tokeniza o estado uma vez, divide-o em janelas de tokens sobrepostas, pontua cada janela em passagens diretas compartilhadas (via predict_batch) e combina as respostas por janela:

• noul -> P(true) é o máximo sobre as janelas (a afirmação se sustenta se alguma janela a respalda)
• choice-> a resposta da única janela mais confiante, para que um sinal localizado não seja superado pelas muitas janelas neutras das quais um documento longo é feito em sua maior parte (a média o afoga -- a maioria neutra domina)
• score -> o nível da janela mais confiante, igualmente

A probabilidade/confiança retornada é a da janela que decide, não um número calibrado para todo o documento: um máximo de noul sobre muitas janelas sobe conforme o número de janelas mesmo sem sinal, e choice pode cair em uma janela seguramente neutra quando nada no documento é decisivo. Por isso cada resposta carrega answer["window"] — o index da janela que decide, token_start/token_end dentro do estado tokenizado, e o count de janelas — para que quem chama possa inspecionar o trecho de onde veio a resposta em vez de confiar no número bruto. Esse trecho é o que o modelo leu, não apenas o que foi solicitado: a janela é limitada ao espaço que as perguntas deixam, então o que é entregue a predict_batch não é cortado outra vez.

Um estado que já cabe em uma janela é passado direto para system_one (saída idêntica).

Os hooks envolvem a inferência que responde ao estado, que para um documento que precisa de várias janelas é o único predict_batch compartilhado sobre elas: on_predict_start dispara uma vez, e ctx.states contém os textos de janela decodificados na ordem de varredura -- não o state do chamador, que foi tokenizado para produzi-los. Três desfechos decorrem do que a cadeia deixa:

• ctx.skip([result]) responde ao documento: o payload volta sem atribuição de janela e com usage["windows"] em 0, porque nada foi pontuado
• uma varredura deixada como este método a construiu: cada janela é pontuada, cada resposta carrega answer["window"], e usage["windows"] é a contagem de janelas
• uma varredura reescrita (ctx.states substituído, de qualquer forma): as respostas são agregadas sobre os estados que foram pontuados, mas nenhuma resposta carrega answer["window"] -- os deslocamentos acima descrevem as janelas deste método, não o texto que o modelo leu

Retorna um único dict de resultado, com a mesma forma de system_one, com usage["windows"] adicionado. A chave está sempre presente e conta as janelas que o modelo pontuou para produzir a resposta: 1 para um estado que cabia em uma janela, N para um documento escaneado em N janelas sobrepostas (ou o N para o qual um hook de início as reescreveu), e 0 quando um hook de início respondeu ao documento, ou não deixou estados para pontuar, antes que qualquer janela fosse lida -- em qualquer um dos dois caminhos, então uma resposta em cache nunca é lida como uma janela que o modelo leu.

Ao longo de várias janelas, as chaves de truncamento são combinadas como qualquer outro campo de usage: truncated, state_tokens e state_tokens_dropped são somados (então truncated é o número de janelas que foram cortadas, e as contagens de tokens incluem a sobreposição), e truncated_questions é a lista da última janela. As duas podem discordar: quando apenas uma janela anterior foi cortada, truncated é maior que 0 e truncated_questions está vazia. Uma janela é cortada quando é maior que o espaço que a cabeça de uma pergunta deixa. Teste usage["truncated"] > 0 aqui, não 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]

Avalia perguntas tipadas sobre o estado em uma única passagem direta paralela.

Para pontuar muitos estados de uma vez, consulte predict_batch, que compartilha passagens diretas entre eles.

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 um schema (JSON schema ou modelo pydantic) e retorna valores tipados.

Consulte laya.structured. Passe exatamente um de schema ou questions; os argumentos de palavra-chave extras são repassados 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 muitos estados contra um schema (JSON schema ou modelo pydantic) em uma única chamada em lote.

A forma de rendimento de :meth:decide: o schema é planejado uma vez e suas perguntas rodam sobre cada estado através de :meth:predict_batch (passagens diretas compartilhadas, resultados na ordem de entrada), e então as respostas de cada estado são projetadas como decide faz. Os argumentos de palavra-chave extras (batch_size=, lang=, hooks=, ...) são repassados a predict_batch. Consulte laya.structured.

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

Ajusta temperaturas por bucket a partir de registros de CPU e as armazena neste agente.

records são (qtype, logits, target, k). Construa-os com laya.calibrate.records_from_labeled quando você tiver passagens diretas rotuladas; este método não baixa pesos nem escreve model.safetensors. seed afeta apenas a divisão reservada do ECE quando compute_ece é true. O cfg do checkpoint é deixado como foi carregado.

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

Ajusta um mapa de binning por histograma sobre as temperaturas ajustadas deste agente e o armazena.

records são as mesmas tuplas (qtype, logits, target[, k]) que fit_temperatures consome. As chaves do mapa são exatamente como as de temperature_by_options, ele se compõe sobre as temperaturas atuais e é escrito por save_calibration como binning_map.

save_calibration(path: str) -> None

Escreve as temperaturas e o checkpoint para o qual foram ajustadas. Não escreve os pesos.

load_calibration(path: str) -> None

Lê neste agente um mapa JSON escrito por save_calibration.

Um arquivo sem version é tratado como versão 1 e ainda carrega. Um arquivo mais novo cujo checkpoint registrado não corresponde a este agente avisa e ainda carrega. Valores que não são números, ou que ficam fora de [TEMP_MIN, TEMP_MAX], são limitados com clamp_temperature da mesma forma que no carregamento de 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

Carrega um agente Laya.

subfolder escolhe um checkpoint de um repositório que empacota vários:

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 também aceita um nome de checkpoint ou alias -- os mesmos que o Router resolve, então os dois pontos de entrada leem uma única tabela:

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

Qualquer outra coisa (um id de repositório do Hub, um diretório local) é passada ao Agent sem alteração.

backend seleciona "auto", "eager", "compile", "tilelang" ou "onnx". ONNX retorna o ONNXAgent existente, com onnx_path (padrão "laya.onnx"). Os outros backends usam Agent; um backend explícito tem precedência sobre as flags legadas.

revision/expected_sha256 fixam e verificam os artefatos baixados; consulte Agent. hooks / on_predict_start / on_predict_end observam ou moldam cada predição; consulte laya.hooks. calibration é o mesmo caminho JSON opcional aceito por 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 do modelo de decisão System One via ONNX: decisões rápidas otimizadas para CPU.

Carrega um agente Laya respaldado pelo ONNX Runtime.

load_calibration(path: str) -> None

Lê neste agente um 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]

Avalia perguntas tipadas sobre o estado em uma única execução de sessão do ONNX Runtime.

lang seleciona uma substituição de temperatura por idioma (consulte lang_temperatures), correspondendo à assinatura de Agent.system_one do PyTorch, de modo que qualquer um dos backends substitui o outro diretamente.

Definido em termos de predict_batch, exatamente como o Agent.system_one do PyTorch, para que os caminhos de estado único e em lote não possam divergir.

Para pontuar muitos estados de uma vez, consulte predict_batch, que compartilha execuções de sessão entre eles.

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

Avalia as mesmas perguntas sobre muitos estados, compartilhando execuções de sessão do ONNX Runtime.

O caminho de rendimento, espelhando laya.agent.Agent.predict_batch: system_one reúne as linhas de pergunta de um estado por execução de sessão, então N estados custam N execuções. predict_batch reúne as linhas de vários estados em uma execução -- ou ceil(len(states) / batch_size) delas -- que é onde o paralelismo próprio do ONNX Runtime rende na 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]

Avalia perguntas sobre um estado mais longo que a janela de contexto, escaneando-o em janelas sobrepostas e agregando por pergunta.

O port para ONNX de laya.agent.Agent.predict_long, com as mesmas regras de agregação: system_one trunca um estado que excede max_len para uma única janela, descartando o resto em silêncio. predict_long tokeniza o estado uma vez, divide-o em janelas de tokens sobrepostas, pontua cada janela através de predict_batch -- assim as janelas compartilham execuções de sessão do ONNX Runtime em vez de custar uma cada -- e combina as respostas por janela:

• noul -> P(true) é o máximo sobre as janelas (a afirmação se sustenta se alguma janela a respalda)
• choice-> a resposta da única janela mais confiante, para que um sinal localizado não seja superado pelas muitas janelas neutras das quais um documento longo é feito em sua maior parte
• score -> o nível da janela mais confiante, igualmente

A probabilidade/confiança retornada é a da janela que decide, não um número calibrado para todo o documento, pelas mesmas razões que o docstring do PyTorch apresenta. Cada resposta carrega answer["window"] -- o index da janela que decide, token_start/token_end dentro do estado tokenizado, e o count de janelas.

Um estado que já cabe em uma janela é passado direto para system_one (saída idêntica).

Retorna um único dict de resultado, com a mesma forma de system_one, com usage["windows"] adicionado. Ao longo de várias janelas, as chaves de truncamento são somadas ou carregadas da mesma forma que em Agent.predict_long: truncated é uma contagem de janelas e truncated_questions é a lista da última janela, então truncated pode ser maior que 0 enquanto a lista está vazia.

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 um schema (JSON schema ou modelo pydantic) e retorna valores tipados.

Consulte laya.structured. Passe exatamente um de schema ou questions; os argumentos de palavra-chave extras são repassados 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 muitos estados contra um schema através de predict_batch; consulte laya.structured.

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