Auxiliares

analyse(state: Union[str, bytes, Mapping, list, None]) -> Dict[str, object]

Resultado completo de detecção para um estado.

Retorna script, script_profile, language (o melhor esforço possível, pode ser None), is_english, non_latin_fraction e mixed_segment (a linha ou o campo que tornou um estado em sua maior parte inglês não inglês; caso contrário, None).

O que é lido são os valores de string. Quando um estado tem vários deles, basta um que não seja inglês: juntar cada valor em uma única janela deixava uma nota longa em inglês preencher os 4000 caracteres, ou superar uma mensagem curta em alemão, e essa mensagem era então enviada ao checkpoint de inglês (#384). A varredura por segmentos ainda para aos 4000 caracteres, que é o que mantém um campo enorme barato; um valor que ela não alcançou é lido por conta própria depois.

detect_script(text: str) -> str

Sistema de escrita dominante de text: 'latin', 'han', 'devanagari', ... ou 'unknown' se não houver letras.

is_english(state: Union[str, bytes, Mapping, list, None]) -> bool

True quando se pode esperar que o checkpoint de inglês leia este estado.

clean_email_body(body: str, max_chars: int = 3000) -> str

Remove o histórico de e-mail citado, as assinaturas e os avisos legais para manter a entrada focada.

max_chars é o comprimento ao qual o resultado é cortado, 3000 caracteres a menos que seja aumentado -- consulte email_state, que usa o mesmo orçamento e o repassa.

email_state(
    subject: str,
    body: str,
    sender: Optional[str] = None,
    clean: bool = True,
    max_chars: int = 3000,
    extra,
) -> Dict

Constrói um dicionário de estado limpo para a classificação de e-mail.

max_chars é o orçamento ao qual clean_email_body corta o corpo, e vale a pena aumentá-lo para uma mensagem longa: no padrão, o corpo para após 3000 caracteres, então uma requisição que chega nos últimos parágrafos nunca alcança o modelo -- inclusive através de predict_long, que escaneia um estado em janelas justamente para poder ler além de uma janela. É ignorado quando clean=False, que passa o corpo inteiro.

Qualquer outra palavra-chave se torna um campo do estado, então o modelo a lê; um erro de digitação aqui é uma mutação da entrada, não um erro.

triage_questions() -> Dict

Perguntas predefinidas para triagem de tickets de suporte ao cliente.

email_questions(categories: Optional[Dict[str, str]] = None) -> Dict

Perguntas predefinidas para triagem de e-mail recebido e filtragem de ameaças.

guard_questions() -> Dict

Perguntas predefinidas para guardrails de entrada de LLM em tempo real.

moderation_questions() -> Dict

Perguntas predefinidas para segurança de conteúdo e moderação.

router_questions() -> Dict

Perguntas predefinidas para roteamento inteligente de modelos.

shortlist_choice(
    state: Any,
    criteria: Any,
    embed_fn: Callable[[Sequence[str]], Any],
    k: int = DEFAULT_SHORTLIST_K,
    DEFAULT_SHORTLIST_K,
    instructions: Optional[str] = None,
    return_scores: bool = False,
) -> Any

Retorna os k rótulos choice principais para state.

embed_fn mapeia uma lista de strings para um array de forma (len(texts), dim). É chamado uma vez, com o texto da consulta primeiro e depois uma string por opção na ordem de criteria. As strings de opção correspondem a render_options para uma pergunta choice.

Quando k é ao menos o número de rótulos, cada rótulo é retornado na sua ordem original e embed_fn não é chamado.

Empates mantêm o rótulo anterior. A classificação é um cosseno com sinal, não um piso de similaridade: um rótulo que pontua 0 -- nenhum sinal, ou um vetor não finito tratado como tal -- supera um rótulo anterior que pontuou negativo, e k descarta os rótulos negativos primeiro.

Com return_scores=True o retorno é o par (labels, scores), em que scores contém o cosseno com sinal de cada rótulo mantido em ordem de classificação -- os mesmos valores que predict_shortlist reporta em seus metadados shortlist. scores é None quando nada foi descartado, exatamente como naqueles metadados.

predict_shortlist(
    agent: Any,
    state: Any,
    questions: Dict[str, Dict[str, Any]],
    embed_fn: Callable[[Sequence[str]], Any],
    k: int = DEFAULT_SHORTLIST_K,
    DEFAULT_SHORTLIST_K,
    predict_kwargs: Any,
) -> Dict[str, Any]

Pré-seleciona cada pergunta choice e então chama predict ou system_one uma vez.

As perguntas que não são choice são repassadas sem alteração. Uma choice cujo número de rótulos é <= k é repassada sem alteração e não chama embed_fn. O dict questions do chamador não é modificado.

O dict retornado é o resultado do modelo mais uma entrada shortlist. As probabilidades em uma choice pré-selecionada são apenas sobre os rótulos mantidos. shortlist[qid] contém labels, scores, k, n e passthrough. labels é a ordem de classificação que uma pré-seleção produziu, ou a própria ordem de criteria quando passthrough está definido e nenhuma classificação rodou; scores é o cosseno com sinal de cada rótulo mantido nessa ordem -- negativo incluído, nunca limitado a 0 -- ou None quando nada foi descartado.

Os argumentos de palavra-chave extras são repassados a predict / system_one (por exemplo model= em um Router).

embed_fn_from_agent(
    agent: Any,
    max_length: int = 512,
    batch_size: int = 32,
) -> Callable[[Sequence[str]], np.ndarray]

Faz mean-pool (média) do encoder do checkpoint já carregado em agent.

O callable embute uma lista de strings com agent.tok e agent.model.encoder. Não executa a cabeça de decisão nem baixa pesos. Um bi-encoder dedicado passado como embed_fn normalmente pré-seleciona melhor; este helper é para chamadores que só têm o checkpoint do Laya na memória.

As posições de padding são excluídas da média. A flag train/eval do encoder é deixada como o chamador a definiu (um Agent carregado já está em eval). Cada chamada usa o agent.device atual, inclusive após o fallback para CPU.

cached_embed_fn(
    embed_fn: Callable[[Sequence[str]], Any],
    maxsize: int = 4096,
) -> Callable[[Sequence[str]], np.ndarray]

Armazena em cache a saída de embed_fn por string de entrada, sob um limite LRU.

predict_shortlist embute a consulta mais cada texto de opção em cada chamada. Quando o mesmo conjunto de opções é pré-selecionado em toda requisição -- uma lista fixa de intenções ou rótulos, como no exemplo BANKING77 do README -- as linhas de opção não mudam entre chamadas, mas são reembutidas toda vez. Envolver o embedder uma vez::

embed_fn = cached_embed_fn(embed_fn_from_agent(agent))

deixa a primeira chamada inalterada e reduz cada chamada repetida a embutir apenas a nova consulta.

As consultas são correspondências exatas de string. Os textos ausentes do cache são deduplicados e embutidos em uma única chamada a embed_fn, então um cache frio custa o mesmo número de chamadas em lote que a função sem wrapper. As linhas são armazenadas como float32; o cache mantém no máximo maxsize strings e então despeja a entrada usada menos recentemente, limitando a memória a cerca de maxsize * dim * 4 bytes. Nada é armazenado quando embed_fn lança uma exceção ou retorna uma forma incorreta.

O wrapper é seguro para compartilhar entre threads: o lock cobre apenas as leituras e escritas do cache, nunca a chamada de embedding. O callable retornado carrega cache_info() -- um dict com size, maxsize, hits e misses -- e cache_clear(). Limpe o cache se o modelo ou os pesos por trás de embed_fn mudarem.

check_min_confidence(v: Any)

Valida o limiar de abstenção opt-in min_confidence (#361, #394).

Ou um número real em [0.0, 1.0] (um limiar para cada resposta; booleanos são rejeitados mesmo que isinstance(True, int)), ou um mapeamento por bucket (consulte :func:check_min_confidence_map) de modo que o limiar possa variar conforme o número de opções. Retorna o valor em sua forma validada -- um float para o caso escalar, um dict[str, float] para o caso de mapeamento -- que as funções de gating abaixo aceitam em ambos os casos.

check_min_confidence_map(m: Dict[Any, Any]) -> Dict[str, float]

Valida um mapa de limiares de abstenção por bucket (#394).

As chaves são strings de bucket de número de opções na grafia de common.temp_bucket -- "choice:2", "choice:3-5", "score:6-10", "noul:2" e assim por diante -- além de um "default" opcional usado para qualquer bucket que o mapa não nomeie. Os valores são números reais em [0.0, 1.0]. Um limiar de confiança não se transfere entre números de opções (#394); isto permite que um chamador filtre cada bucket no nível que a sua calibração realmente conquista. Ajuste um com :func:laya.calibrate.fit_abstention_thresholds.

resolve_min_confidence(
    answer: Dict[str, Any],
    thresholds: Dict[str, float],
    default: float = 0.0,
) -> float

O limiar no qual o bucket de número de opções desta resposta é filtrado, sob um mapa por bucket.

Recorre à entrada "default" do mapa e depois a default (0.0 -- não filtra nada), para um bucket que o mapa não nomeie, de modo que um bucket não configurado nunca se abstém de forma inesperada.

flag_low_confidence(results: List[Dict[str, Any]], min_confidence: float) -> None

Marcador de abstenção opt-in (#361): marca as respostas cuja confiança cai abaixo de min_confidence.

Lê answer_confidence (max(p), a quantidade que as cifras de calibração descrevem e a que não varia com o número de opções), recorrendo a confidence se answer_confidence estiver ausente. A resposta e a confiança brutas permanecem intactas; low_confidence: True é adicionado quando a resposta cai abaixo do limiar, e removido se uma resposta antes marcada agora o ultrapassa (por exemplo, quando um dict de resultado é reutilizado ou reavaliado com um limiar diferente).

min_confidence é ou um float (um limiar para cada resposta) ou um mapeamento por bucket (#394), caso em que cada resposta é filtrada no limiar de seu próprio bucket de número de opções via :func:resolve_min_confidence.

apply_confidence_gate(
    results: List[Dict[str, Any]],
    min_confidence: Optional[float] = None,
) -> None

Relata o estado do gating de confiança, nas respostas às quais um gating foi de fato aplicado.

Um gating é uma política, e uma política cuja aplicação não pode ser observada não é uma. Com min_confidence definido, isto escreve abstention -- um dos :data:GATE_STATES -- em cada resposta, mais abstention_threshold, para que um chamador possa responder a três perguntas que de outra forma não consegue:

• que fração das decisões se absteve, em vez de inferi-la do fato de low_confidence ter sido definida por acaso;
• quantas respostas o gating não conseguiu decidir, o que um booleano não consegue expressar de forma alguma;
• qual limiar produziu estes resultados -- flag_low_confidence consome o limiar e o descarta, então sem isto uma execução em lote com limiares por classe não pode ser subdividida de novo.

GATE_UNEVALUATED é o caso que um booleano não consegue expressar: o gating foi executado e a resposta não trazia confiança utilizável, então o gating não pôde decidir. Relatar isso como aprovado é a mesma mentira que relatá-lo como um marcador.

Com min_confidence não definido, isto não escreve nada. Nem abstention, nem abstention_threshold, nem marcador. É todo o contrato: uma chamada sem gating retorna exatamente o payload que retornava antes, e a presença do campo -- não um quarto valor lido dele -- é o que diz ao chamador que o gating foi executado. Chame-o incondicionalmente, uma vez por chamada, no lugar de uma guarda if min_confidence is not None:: essa guarda é o que deixa um caminho relatando nada, que é o estado que esta função existe para distinguir.

O marcador em si continua sendo o de :func:flag_low_confidence -- isto delega em vez de reimplementar a regra, de modo que o booleano e o estado relatado não possam divergir.

Um min_confidence exatamente 0.0 foi definido, então os estados são relatados, e :func:flag_low_confidence trata 0.0 como uma operação sem efeito, porque nada pode cair abaixo dele. Toda resposta que traz uma confiança utilizável, portanto, lê passed, e o eco do limiar é o que distingue isso de uma aprovação real em um limiar real.

GATE_STATES = (GATE_PASSED, GATE_ABSTAINED, GATE_UNEVALUATED)

answer_confidence(p: np.ndarray, k: int) -> float

Massa de probabilidade sobre a resposta que está sendo reportada: max(p).

Esta é a quantidade que o escalonamento de temperatura ajusta, e a quantidade sobre a qual cada cifra de calibração neste repositório é calculada -- ambos os arneses de benchmark tomam conf = max(probs) antes de chamar ece_score. A seção de gating do README se apoia na propriedade que a acompanha: das respostas retornadas com confiança c, cerca de c delas estão certas. Essa propriedade é condicional, e a condição não é satisfeita por padrão -- ela só vale depois que as temperaturas foram ajustadas e validadas em dados reservados para este checkpoint e esta contagem de opções. Os checkpoints distribuídos são confiantes demais: choice:11+ é um aguçador de ~10x que retorna uma massa pontual em 1.0, então um limiar aplicado a eles seleciona abaixo da acurácia do modelo (issue #394).

confidence_from_probs abaixo reporta uma quantidade diferente em uma escala diferente e não traz tal garantia, então as duas não devem ser comparadas contra o mesmo limiar.

confidence_from_probs(p: np.ndarray, k: int) -> float

Confiança por entropia de Shannon normalizada: 1 - H(p) / log(k).

Quão concentrada toda a distribuição está. Útil, mas não calibrada: não é o que o escalonamento de temperatura ajusta nem o que o ECE reportado mede. Consulte answer_confidence.

ece_score(conf: np.ndarray, correct: np.ndarray, bins: int = 15) -> float

Erro de Calibração Esperado (ECE) ao longo de bins de confiança.

fit_temperatures = fit_temperature_map

fit_one_temperature(pairs: Sequence, min_n: Optional[int] = None) -> float

Ajusta um único escalar T por NLL + LBFGS sobre log T.

O resultado é clamp_temperature da escala otimizada, então fica em [TEMP_MIN, TEMP_MAX] (ou é o neutro 1.0 quando o valor não é um número). Retorna 1.0 quando são dados menos de min_n pares. min_n usa como padrão MIN_BUCKET_N (o piso por bucket). Os ajustes em nível de tipo passam MIN_TYPE_N, que é menor, então um conjunto de dados que não preenche nenhum bucket ainda obtém um escalar em vez de ficar em 1.0.

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

Ajusta escalares em nível de tipo e temperaturas por bucket.

MIN_BUCKET_N é o piso por bucket: os buckets menores são omitidos de temperature_by_options e o escalar em nível de tipo cobre eles. MIN_TYPE_N é o piso separado e menor apenas para esse escalar.

compute_ece=False (o padrão, e o caminho que Agent.fit_temperatures armazena) ajusta sobre todos os registros e não retorna nenhuma chave report. seed é ignorado nesse caminho.

compute_ece=True reserva ECE_HOLDOUT_FRAC de cada bucket, estratificado por temp_bucket, usando seed para que os mesmos registros sempre se dividam da mesma forma. As temperaturas são ajustadas apenas sobre o restante e o ECE é pontuado apenas sobre os registros reservados. report["n"] é o número de registros recebidos; report["n_eval"] é a contagem reservada em que o ECE se baseia. Um bucket que cairia abaixo de MIN_BUCKET_N após a reserva é ajustado sobre todos os seus registros, deixado fora do conjunto de avaliação e nomeado em report["buckets_excluded_from_eval"] em vez de ser descartado. n_by_bucket sempre conta a entrada completa, inclusive quando o próprio ajuste usou um subconjunto.

fit_abstention_thresholds(
    records: Iterable,
    temperature: Sequence[float],
    temperature_by_options: Dict[str, float],
    binning_map: Optional[Dict[str, Dict[str, Any]]] = None,
    target_error: float = 0.10,
    min_bucket_n: int = MIN_ABSTAIN_BUCKET_N,
    MIN_ABSTAIN_BUCKET_N,
    conservative: bool = True,
) -> Dict[str, float]

Ajusta um limiar de abstenção por temp_bucket para que um gating mantenha um erro alvo em cada bucket.

Um único min_confidence não se transfere entre números de opções (#394): as confianças calibradas de uma resposta de 2 opções e de uma de 12 opções vivem em escalas diferentes, então um único corte se abstém demais ou de menos dependendo da pergunta. Isto ajusta um corte por bucket, com chaves exatamente como temperature_by_options (common.temp_bucket, por exemplo "choice:3-5"), e o resultado é um mapa de min_confidence que :func:laya.confidence.check_min_confidence / :func:laya.confidence.apply_confidence_gate aceitam diretamente.

records são as mesmas tuplas (qtype, logits, target[, k]) que fit_temperature_map consome (records_from_labeled as constrói). A confiança é o max(p) calibrado -- os logits são escalados primeiro pela temperature / temperature_by_options ajustada, de modo que os limiares e os números que o runtime relata estão na mesma escala. target_error é o erro tolerado entre as respostas aceitas; min_bucket_n omite buckets pequenos demais para ajustar, e conservative adiciona uma margem de uma amostra. Os limiares são cortes empíricos sobre o conjunto de calibração, não uma garantia formal de cobertura -- valide em dados reservados (fit_temperature_map(..., compute_ece=True) fornece uma divisão reservada) para um gating de produção.

Passe binning_map quando o agente que servirá esses limiares tiver um instalado -- por Agent.fit_binning, ou por um payload de calibração que carregue binning_map -- porque o runtime recalibra answer_confidence através desse mapa antes que qualquer coisa o leia, então um corte ajustado sem ele é um corte numa escala que o gating nunca vê. Os limiares ficam então na escala de binning, e a ordem em que os dois foram ajustados deixa de importar. Medido em 1,200 registros sintéticos de 12 opções com target_error=0.10: o corte ajustado sem um mapa mantém 9.8% de erro sobre 50% de cobertura em confianças não binarizadas, e admite 94.5% das respostas com 25.6% de erro quando o mesmo número é comparado com as binarizadas.

fit_binning_map(
    records: Iterable,
    temperature: Sequence[float],
    temperature_by_options: Dict[str, float],
    bins: int = 15,
    min_bucket_n: int = MIN_BINNING_BUCKET_N,
    MIN_BINNING_BUCKET_N,
) -> Dict[str, Dict[str, Any]]

Ajusta um mapa de recalibração por binning de histograma por temp_bucket para answer_confidence.

O escalonamento de temperatura aplica um escalar por bucket; ele não consegue corrigir um bucket cuja curva de confiabilidade não é um simples aguçamento/amaciamento (o choice:11+ patológico que o checkpoint inglês distribuído carrega é um caso). O binning por histograma é a alternativa não paramétrica: divida as confianças calibradas de um bucket em bins bins de largura igual em [0, 1] e mapeie toda confiança que cai em um bin para a acurácia empírica daquele bin. Não precisa de nenhuma suposição de monotonicidade nem de dependência extra (apenas NumPy; a regressão isotônica exigiria o scikit-learn).

records são as mesmas tuplas (qtype, logits, target[, k]) que fit_temperature_map consome; a confiança é o max(p) calibrado (logits escalados primeiro pela temperature / temperature_by_options ajustada), então um mapa de binning se compõe sobre um mapa de temperatura em vez de substituí-lo. Retorna {bucket: {"bins": N, "values": [recalibrated confidence per bin]}}; buckets abaixo de min_bucket_n são omitidos. Aplique-o com :func:apply_binning_map. Um bin vazio (uma faixa de confiança que o conjunto de calibração nunca produziu) mapeia para o próprio ponto médio, ou seja, deixa essa região inalterada, de modo que um valor nunca visto jamais é recalibrado para um 0 fabricado.

apply_binning_map(
    confidence: float,
    bucket: str,
    binning_map: Dict[str, Dict[str, Any]],
) -> float

Recalibra um answer_confidence para o seu bucket de número de opções (common.temp_bucket).

Retorna a confiança inalterada quando o mapa não tem entrada para o bucket, de modo que um bucket para o qual o mapa não foi ajustado passa direto em vez de ser forçado a um valor errado.

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.

render_options(q: Dict) -> List[str]

Renderiza os textos de opção na ordem de índice do rótulo. A ordem semântica de Noul é sempre [false, true].

proper_reward(
    q: torch.Tensor,
    target: torch.Tensor,
    qtype: torch.Tensor,
    mask: torch.Tensor,
    w_sph: float = 0.5,
    w_rps: float = 1.0,
    log_floor: float = -9.21,
) -> torch.Tensor

Recompensa de regra de pontuação estritamente própria: log score + spherical score + ranked probability score.

q: [..., N, K] distribuições reportadas target: [N, K] (distribuições alvo one-hot ou suaves)

td_lambda_targets(p_true: torch.Tensor, batch: Dict, lam: float = 1.0) -> torch.Tensor

Alvos TD(lambda) para trajetórias de conversa de vários turnos.

QTYPES = {"choice": 0, "score": 1, "noul": 2}

QTYPE_NAMES = {v: k for k, v in QTYPES.items()}