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 alvo do autocast, não a precisão de cada chamada. No MPS uma chamada só faz autocast a partir de mps_amp_min_rows linhas, pelo que dtype pode dizer float16 enquanto uma chamada corre em float32. dtype_for(rows) devolve a precisão de uma chamada com rows linhas.

Carrega um checkpoint da Laya.

backend seleciona "eager", "auto", "compile" ou "tilelang"; consulta laya.backends. Tem prioridade sobre fast e compile. Omite-o para manter essas flags legadas. Para ONNX usa load(backend="onnx") em vez disso.

revision fixa opcionalmente a transferência do Hub a um commit SHA/ramo/etiqueta explícito; quando omitido, usam-se o valor predefinido normal do huggingface_hub e a cache offline existente. expected_sha256 ({path relative to the checkpoint dir: hexdigest}) verifica a integridade dos artefactos antes de qualquer peso ser analisado ou executado; é opcional e aplica-se também a diretórios locais. Um artefacto em falta lança FileNotFoundError e uma divergência de digest lança ValueError; qualquer dos dois erros recusa o carregamento.

fast=True substitui o forward do encoder/cabeça pelo caminho rápido do TileLang (apenas CUDA, requer pip install laya[fast]); consulta Agent.accelerate.

compile=True executa o modelo sob torch.compile e ativa o reference_compile do encoder do ModernBERT. O torch.compile especializa-se por forma de entrada e a Laya vê uma nova em quase todos os pedidos, pelo que esses grafos costumam custar mais do que rendem; usa-o quando o tráfego for repetitivo. fast=True tem prioridade, porque o caminho do TileLang substitui o forward que seria compilado. Agentes compilados executam warmup() antes de devolver; compile_warmup=False adia esse trabalho para os pedidos ou uma chamada manual a warmup(). Agentes eager e fast não mudam. compile_cache=True adota um diretório persistente do Inductor da Laya (em todo o processo), respeitando qualquer TORCHINDUCTOR_CACHE_DIR existente; consulta as notas de engenharia da compilação. compile_mode="reduce-overhead" adota grafos CUDA. Pode reter mais memória de GPU e regista cada nova forma em separado. As saídas CUDA são copiadas antes do próximo replay; as passagens com grafos CUDA compilados são serializadas. O modo predefinido continua "default".

subfolder seleciona um checkpoint de um repositório que empacota vários, p. ex. Agent("convaiinnovations/laya", subfolder="multilingual"). Apenas essa subpasta é transferida, pelo que o empacotamento não custa a cada utilizador a família inteira.

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

hooks / on_predict_start / on_predict_end observam ou moldam cada previsão; consulta 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, p. ex. warmup=False para compile ou use_graphs=False para tilelang. A troca aguarda a inferência em curso.

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

Substitui o forward 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 cubo de forma).

O caminho rápido corre no dtype de autocast do agent no momento da chamada (bf16 ou fp16), pelo que coincide com o forward padrão que substitui dentro do arredondamento (consulta benchmarks/parity_fast.py). Depois de alterar agent.dtype, chama deaccelerate() e depois accelerate() para o reconstruir. Devolve True se ficar ativado. Com strict=False, qualquer falha (sem CUDA, falta o tilelang) deixa o caminho padrão no lugar.

warmup(shapes=None) -> float

Executa agora o forward sobre uma entrada sintética de cada forma e devolve os segundos que demorou.

compile=True chama isto ao carregar, a menos que compile_warmup=False. Formas adicionais podem ainda ser aquecidas manualmente. fast=True constrói os seus kernels e grafos CUDA por cubo de forma no primeiro uso; chamar isto antes de servir tira esse custo dos primeiros pedidos. Com o forward padrão são umas poucas passagens normais. shapes é uma lista de (rows, tokens, markers); os tokens são limitados ao max_len do agent. Não se devolve nem se regista nada para nenhum chamador, e os hooks não correm.

deaccelerate()

Restaura o forward padrão.

dtype_for(rows: int) -> torch.dtype

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

dtype é o alvo do autocast, definido uma vez no momento do carregamento. Se uma passagem faz autocast é decidido por chamada: no MPS só a partir de mps_amp_min_rows linhas. Isto devolve dtype quando uma passagem com rows linhas faz autocast, e torch.float32 quando não. Uma chamada a predict corre 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 partilhadas.

Este é o caminho de elevado débito. system_one/predict tratam de um estado por passagem; numa GPU isso deixa inativa a maior parte da dimensão de lote. predict_batch reúne as linhas de pergunta de vários estados num único tensor, pelo que uma chamada que levaria N passagens 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 do que a janela de contexto, analisando-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 partilhadas (através de predict_batch), e combina as respostas por janela:

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

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

Um estado que já cabe numa janela é passado diretamente a 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 partilhado sobre elas: on_predict_start dispara uma vez, e ctx.states contém os textos de janela descodificados por ordem de análise -- não o state do chamador, que foi tokenizado para os produzir. Do que a cadeia deixa atrás seguem-se três desfechos:

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

Devolve um único dict de resultado, com a mesma forma que system_one, com usage["windows"] acrescentado. A chave está sempre presente e conta as janelas que o modelo pontuou para produzir a resposta: 1 para um estado que cabia numa janela, N para um documento analisado em N janelas sobrepostas (ou o N para que 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 de qualquer janela ser lida -- em qualquer dos caminhos, pelo que 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 (pelo que 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 só uma janela anterior foi cortada, truncated é acima de 0 e truncated_questions está vazia. Uma janela é cortada quando é maior do que o espaço que a cabeça de uma pergunta deixa. Testa 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 através do estado numa única passagem paralela.

Para pontuar muitos estados de uma vez, consulta predict_batch, que partilha passagens 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 devolve valores tipados.

Consulta laya.structured. Passa exatamente um de schema ou questions; os argumentos de palavra-chave adicionais são reencaminhados para 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) numa única chamada em lote.

A variante de elevado débito de :meth:decide: o schema é planeado uma vez e as suas perguntas correm sobre cada estado através de :meth:predict_batch (passagens partilhadas, resultados por ordem de entrada), e depois as respostas de cada estado são projetadas como decide o faz. Os argumentos de palavra-chave adicionais (batch_size=, lang=, hooks=, ...) são reencaminhados para 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 registos de CPU e guarda-as neste agent.

records são (qtype, logits, target, k). Constrói-os com laya.calibrate.records_from_labeled quando tiveres forwards etiquetados; este método não transfere pesos nem escreve model.safetensors. seed só afeta a partição reservada de ECE quando compute_ece é true. O cfg do checkpoint fica 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 agent e guarda-o.

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, compõe-se sobre as temperaturas atuais e é escrito por save_calibration como binning_map.

save_calibration(path: str) -> None

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

load_calibration(path: str) -> None

Lê para este agent um mapa JSON escrito por save_calibration.

Um ficheiro sem version é tratado como versão 1 e é carregado mesmo assim. Um ficheiro mais recente cujo checkpoint registado não corresponde a este agent avisa mas é carregado mesmo assim. Os valores que não são números, ou que ficam fora de [TEMP_MIN, TEMP_MAX], são limitados com clamp_temperature, tal como no carregamento de um 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 agent da 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, pelo que 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 devolve o ONNXAgent existente, com onnx_path (predefinição "laya.onnx"). Os outros backends usam Agent; um backend explícito tem prioridade sobre as flags legadas.

revision/expected_sha256 fixam e verificam os artefactos transferidos; consulta Agent. hooks / on_predict_start / on_predict_end observam ou moldam cada previsão; consulta laya.hooks. calibration é o mesmo caminho JSON opcional aceite 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 agent da Laya assente no ONNX Runtime.

load_calibration(path: str) -> None

Lê para este agent 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 através do estado numa única execução de sessão do ONNX Runtime.

lang seleciona uma sobreposição de temperatura por idioma (consulta lang_temperatures), correspondendo à assinatura de Agent.system_one do PyTorch, para que qualquer dos backends seja substituível pelo outro.

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

Para pontuar muitos estados de uma vez, consulta predict_batch, que partilha 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, partilhando execuções de sessão do ONNX Runtime.

O caminho de elevado débito, que replica laya.agent.Agent.predict_batch: system_one reúne as linhas de pergunta de um estado por execução de sessão, pelo que N estados custam N execuções. predict_batch reúne as linhas de vários estados numa execução -- ou ceil(len(states) / batch_size) delas -- que é onde o paralelismo próprio do ONNX Runtime compensa 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 do que a janela de contexto, analisando-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 -- para que as janelas partilhem execuções de sessão do ONNX Runtime em vez de custarem uma cada -- e combina as respostas por janela:

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

A probabilidade/confiança devolvida é a da janela que decide, não um número calibrado para todo o documento, pelos mesmos motivos que o docstring do PyTorch indica. Cada resposta transporta 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 numa janela é passado diretamente a system_one (saída idêntica).

Devolve um único dict de resultado, com a mesma forma que system_one, com usage["windows"] acrescentado. Ao longo de várias janelas, as chaves de truncamento são somadas ou transportadas da mesma forma que em Agent.predict_long: truncated é uma contagem de janelas e truncated_questions é a lista da última janela, pelo que truncated pode ser acima de 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 devolve valores tipados.

Consulta laya.structured. Passa exatamente um de schema ou questions; os argumentos de palavra-chave adicionais são reencaminhados para 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; consulta laya.structured.

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