Auxiliares

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

Resultado completo de detección para un estado.

Devuelve script, script_profile, language (lo mejor que se pueda, puede ser None), is_english, non_latin_fraction y mixed_segment (la línea o el campo que hizo que un estado mayormente en inglés no lo fuera; en caso contrario, None).

Lo que se lee son los valores de cadena. Cuando un estado tiene varios, basta con uno que no sea inglés: unir cada valor en una sola ventana dejaba que una nota larga en inglés llenara los 4000 caracteres, o superara a un mensaje corto en alemán, y ese mensaje se enviaba entonces al checkpoint de inglés (#384). El escaneo por segmentos sigue deteniéndose a los 4000 caracteres, que es lo que mantiene barato un campo enorme; un valor que no alcanzó se lee por separado después.

detect_script(text: str) -> str

Sistema de escritura dominante de text: 'latin', 'han', 'devanagari', ... o 'unknown' si no hay letras.

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

True cuando cabe esperar que el checkpoint de inglés lea este estado.

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

Elimina el historial de correo citado, las firmas y los avisos legales para mantener la entrada enfocada.

max_chars es la longitud a la que se recorta el resultado, 3000 caracteres salvo que se aumente -- consulta email_state, que toma el mismo presupuesto y lo transmite.

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

Construye un diccionario de estado limpio para la clasificación de correo.

max_chars es el presupuesto al que clean_email_body recorta el cuerpo, y conviene aumentarlo para un mensaje largo: con el valor predeterminado el cuerpo se corta a los 3000 caracteres, así que una petición que llega en los últimos párrafos nunca alcanza al modelo -- tampoco a través de predict_long, que escanea un estado en ventanas precisamente para poder leer más allá de una ventana. Se ignora cuando clean=False, que deja pasar el cuerpo entero.

Cualquier otra palabra clave se convierte en un campo del estado, así que el modelo la lee; un error de tipeo aquí es una mutación de la entrada, no un error.

triage_questions() -> Dict

Preguntas preestablecidas para el triaje de tickets de soporte al cliente.

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

Preguntas preestablecidas para el triaje de correo entrante y el filtrado de amenazas.

guard_questions() -> Dict

Preguntas preestablecidas para guardarraíles de entrada de LLM en tiempo real.

moderation_questions() -> Dict

Preguntas preestablecidas para la seguridad de contenido y la moderación.

router_questions() -> Dict

Preguntas preestablecidas para el enrutamiento 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

Devuelve las k etiquetas choice principales para state.

embed_fn asigna una lista de cadenas a un array de forma (len(texts), dim). Se llama una vez, primero con el texto de la consulta y luego con una cadena por opción en orden de criteria. Las cadenas de opción coinciden con render_options para una pregunta choice.

Cuando k es al menos el número de etiquetas, se devuelve cada etiqueta en su orden original y no se llama a embed_fn.

Los empates conservan la etiqueta anterior. La clasificación es un coseno con signo, no un suelo de similitud: una etiqueta que puntúa 0 -- ninguna señal, o un vector no finito tratado como tal -- sí supera a una etiqueta anterior que puntuó negativo, y k descarta primero las etiquetas negativas.

Con return_scores=True el retorno es el par (labels, scores), donde scores contiene el coseno con signo por etiqueta conservada en orden de clasificación -- los mismos valores que predict_shortlist informa en sus metadatos shortlist. scores es None cuando no se descartó nada, exactamente como en esos metadatos.

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]

Preselecciona cada pregunta choice y luego llama una vez a predict o system_one.

Las preguntas que no son choice se reenvían sin cambios. Una choice cuyo número de etiquetas es <= k se reenvía sin cambios y no llama a embed_fn. El dict questions del llamador no se modifica.

El dict devuelto es el resultado del modelo más una entrada shortlist. Las probabilidades de una choice preseleccionada son solo sobre las etiquetas conservadas. shortlist[qid] contiene labels, scores, k, n y passthrough. labels es el orden de clasificación que produjo una preselección, o el propio orden de criteria cuando passthrough está activado y no corrió ninguna clasificación; scores es el coseno con signo de cada etiqueta conservada en ese orden -- incluidos los negativos, nunca recortado a 0 -- o None cuando no se descartó nada.

Los argumentos de palabra clave adicionales se reenvían a predict / system_one (por ejemplo model= en un Router).

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

Agrupa por media (mean-pool) el encoder del checkpoint ya cargado en agent.

El callable embebe una lista de cadenas con agent.tok y agent.model.encoder. No ejecuta la cabeza de decisión ni descarga pesos. Un bi-encoder dedicado pasado como embed_fn normalmente preseleccionará mejor; este helper es para llamadores que solo tienen el checkpoint de Laya en memoria.

Las posiciones de padding se excluyen de la media. El indicador train/eval del encoder se deja como lo puso el llamador (un Agent cargado ya está en eval). Cada llamada usa el agent.device actual, incluso después de recaer a CPU.

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

Almacena en caché la salida de embed_fn por cadena de entrada, bajo un límite LRU.

predict_shortlist embebe la consulta más cada texto de opción en cada llamada. Cuando el mismo conjunto de opciones se preselecciona en todas las peticiones -- una lista fija de intenciones o etiquetas, como en el ejemplo BANKING77 del README -- las filas de opción no cambian entre llamadas, pero se vuelven a embeber cada vez. Envolver el embedder una vez::

embed_fn = cached_embed_fn(embed_fn_from_agent(agent))

deja la primera llamada igual y reduce cada llamada repetida a embeber solo la nueva consulta.

Las búsquedas son coincidencias exactas de cadena. Los textos que faltan en la caché se deduplican y se embeben en una sola llamada a embed_fn, así que una caché fría cuesta el mismo número de llamadas por lotes que la función sin envolver. Las filas se almacenan como float32; la caché guarda como máximo maxsize cadenas y luego desaloja la entrada menos usada recientemente, acotando la memoria a unos maxsize * dim * 4 bytes. No se almacena nada cuando embed_fn lanza una excepción o devuelve una forma incorrecta.

El wrapper es seguro para compartir entre hilos: el lock solo cubre las lecturas y escrituras de caché, nunca la llamada de embedding. El callable devuelto lleva cache_info() -- un dict con size, maxsize, hits y misses -- y cache_clear(). Vacía la caché si el modelo o los pesos detrás de embed_fn cambian.

check_min_confidence(v: Any)

Valida el umbral de abstención opcional min_confidence (#361, #394).

O bien un número real en [0.0, 1.0] (un umbral para cada respuesta; los booleanos se rechazan aunque isinstance(True, int)), o un mapping por cubo (consulta :func:check_min_confidence_map) para que el umbral pueda diferir según el número de opciones. Devuelve el valor en su forma validada -- un float para el caso escalar, un dict[str, float] para el caso de mapping --, que las funciones de gate de abajo aceptan ambas.

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

Valida un mapping de umbrales de abstención por cubo (#394).

Las claves son cadenas de cubo de número de opciones con la grafía de common.temp_bucket -- "choice:2", "choice:3-5", "score:6-10", "noul:2" y así sucesivamente --, más un "default" opcional que se usa para cualquier cubo que el mapping no nombre. Los valores son floats en [0.0, 1.0]. Un umbral de confianza no se transfiere entre números de opciones (#394); esto permite a quien llama filtrar cada cubo al nivel que su calibración realmente gana. Ajusta uno con :func:laya.calibrate.fit_abstention_thresholds.

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

El umbral al que se filtra el cubo de número de opciones de esta respuesta, bajo un mapping por cubo.

Recurre a la entrada "default" del mapping, y luego a default (0.0 -- no filtrar nada), para un cubo que el mapping no nombre, así que un cubo sin configurar nunca se abstiene por sorpresa.

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

Marcador de abstención opcional (#361): marca las respuestas cuya confianza cae por debajo de min_confidence.

Lee answer_confidence (max(p), la cantidad que describen las cifras de calibración y la que no deriva con el número de opciones), y recurre a confidence si falta answer_confidence. La respuesta y la confianza brutas se mantienen intactas; se añade low_confidence: True cuando la respuesta cae por debajo del umbral, y se elimina si una respuesta marcada antes ahora lo supera (por ejemplo, cuando se reutiliza un dict de resultado o se reevalúa con un umbral distinto).

min_confidence es un float (un umbral para cada respuesta) o un mapping por cubo (#394), en cuyo caso cada respuesta se filtra con el umbral de su propio cubo de número de opciones mediante :func:resolve_min_confidence.

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

Informa del estado del gate de confianza, sobre las respuestas a las que realmente se aplicó un gate.

Un gate es una política, y una política cuya aplicación no puede observarse no lo es. Con min_confidence definido, esto escribe abstention -- uno de :data:GATE_STATES -- en cada respuesta, más abstention_threshold, para que quien llama pueda responder tres preguntas que de otro modo no puede:

• qué fracción de las decisiones se abstuvo, en lugar de inferirlo de si low_confidence quedó definido por casualidad;
• en cuántas respuestas el gate no pudo decidir, algo que un booleano no puede expresar en absoluto;
• qué umbral produjo estos resultados -- flag_low_confidence consume el umbral y lo descarta, así que sin esto una ejecución por lotes con umbrales por clase no se puede volver a dividir.

GATE_UNEVALUATED es el caso que un booleano no puede expresar: el gate se ejecutó y la respuesta no llevaba confianza utilizable, así que el gate no pudo decidir. Informar de eso como aprobado es la misma mentira que informarlo como un flag.

Con min_confidence sin definir, esto no escribe nada. Ningún abstention, ningún abstention_threshold, ningún flag. Ese es todo el contrato: una llamada sin gate devuelve exactamente el payload que devolvía antes, y la presencia del campo -- no un cuarto valor leído de él -- es lo que le dice a quien llama que el gate se ejecutó. Llámalo incondicionalmente, una vez por llamada, en lugar de un guard if min_confidence is not None:: ese guard es lo que deja una ruta que no informa nada en absoluto, que es el estado que esta función existe para distinguir.

El flag en sí sigue siendo de :func:flag_low_confidence -- esto delega en lugar de reimplementar la regla, así que el booleano y el estado informado no pueden divergir.

Un min_confidence de exactamente 0.0 sí estaba definido, así que se informan estados, y :func:flag_low_confidence trata 0.0 como un no-op porque nada puede caer por debajo. Toda respuesta que lleva una confianza utilizable se lee por tanto como passed, y el eco del umbral es lo que distingue eso de un aprobado real con un umbral real.

GATE_STATES = (GATE_PASSED, GATE_ABSTAINED, GATE_UNEVALUATED)

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

Masa de probabilidad sobre la respuesta que se reporta: max(p).

Esta es la cantidad que ajusta el escalado de temperatura, y la cantidad sobre la que se calcula cada cifra de calibración en este repositorio -- ambos arneses de benchmark toman conf = max(probs) antes de llamar a ece_score. La sección de gating del README se apoya en la propiedad que la acompaña: de las respuestas devueltas con confianza c, alrededor de c son correctas. Esa propiedad es condicional, y la condición no se cumple por defecto -- solo se sostiene después de que las temperaturas se han ajustado y validado sobre datos reservados para este checkpoint y este número de opciones. Los checkpoints distribuidos son demasiado confiados: choice:11+ es un agudizador de ~10x que devuelve una masa puntual en 1.0, así que un umbral aplicado a ellos selecciona por debajo de la exactitud del modelo (issue #394).

confidence_from_probs más abajo reporta una cantidad distinta en una escala distinta y no conlleva tal garantía, así que no se deben comparar contra el mismo umbral.

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

Confianza por entropía de Shannon normalizada: 1 - H(p) / log(k).

Cuán concentrada está toda la distribución. Es útil, pero no está calibrada: no es lo que ajusta el escalado de temperatura ni lo que mide el ECE reportado. Consulta answer_confidence.

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

Error de calibración esperado (ECE) a lo largo de bins de confianza.

fit_temperatures = fit_temperature_map

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

Ajusta un único escalar T mediante NLL + LBFGS sobre log T.

El resultado es clamp_temperature de la escala optimizada, así que queda en [TEMP_MIN, TEMP_MAX] (o es el neutro 1.0 cuando el valor no es un número). Devuelve 1.0 cuando se dan menos de min_n pares. min_n toma por defecto MIN_BUCKET_N (el suelo por cubo). Los ajustes a nivel de tipo pasan MIN_TYPE_N, que es más bajo, así que un conjunto de datos que no llena ningún cubo igual obtiene un escalar en lugar de quedarse en 1.0.

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

Ajusta escalares a nivel de tipo y temperaturas por cubo.

MIN_BUCKET_N es el suelo por cubo: los cubos más pequeños se omiten de temperature_by_options y el escalar a nivel de tipo los cubre. MIN_TYPE_N es el suelo separado y más bajo solo para ese escalar.

compute_ece=False (el valor predeterminado, y la ruta que guarda Agent.fit_temperatures) ajusta sobre todos los registros y no devuelve ninguna clave report. seed se ignora en esta ruta.

compute_ece=True reserva ECE_HOLDOUT_FRAC de cada cubo, estratificado por temp_bucket, usando seed para que los mismos registros siempre se dividan igual. Las temperaturas se ajustan solo sobre el resto y el ECE se puntúa solo sobre los registros reservados. report["n"] es el número de registros recibidos; report["n_eval"] es el recuento reservado en el que se basa el ECE. Un cubo que caería por debajo de MIN_BUCKET_N tras la reserva se ajusta sobre todos sus registros, se deja fuera del conjunto de evaluación y se nombra en report["buckets_excluded_from_eval"] en lugar de descartarse. n_by_bucket siempre cuenta la entrada completa, incluso cuando el ajuste mismo usó un 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 un umbral de abstención por temp_bucket para que un gate mantenga un error objetivo en cada cubo.

Un único min_confidence no se transfiere entre números de opciones (#394): la confianza calibrada de una respuesta de 2 opciones y de una de 12 viven en escalas distintas, así que un corte se abstiene de más o de menos según la pregunta. Esto ajusta en su lugar un corte por cubo, indexado exactamente como temperature_by_options (common.temp_bucket, p. ej. "choice:3-5"), y el resultado es un mapa de min_confidence que :func:laya.confidence.check_min_confidence / :func:laya.confidence.apply_confidence_gate aceptan directamente.

records son las mismas tuplas (qtype, logits, target[, k]) que consume fit_temperature_map (records_from_labeled las construye). La confianza es el max(p) calibrado -- los logits se escalan primero por la temperature / temperature_by_options ajustadas, así que los umbrales y los números que reporta el runtime están en la misma escala. target_error es el error tolerado entre las respuestas aceptadas; min_bucket_n omite los cubos demasiado pequeños para ajustarse, y conservative añade un margen de una muestra. Los umbrales son cortes empíricos sobre el conjunto de calibración, no una garantía formal de cobertura -- valida sobre datos reservados (fit_temperature_map(..., compute_ece=True) da una partición reservada) para un gate de producción.

Pasa binning_map cuando el agent que servirá estos umbrales tenga uno instalado -- por Agent.fit_binning, o por un payload de calibración que lleve binning_map --, porque el runtime recalibra answer_confidence a través de ese mapa antes de que nada lo lea, así que un corte ajustado sin él es un corte sobre una escala que el gate nunca ve. Los umbrales están entonces en la escala con binning, y el orden en que se ajustaron los dos deja de importar. Medido sobre 1,200 registros sintéticos de 12 opciones con target_error=0.10: el corte ajustado sin mapa mantiene 9.8% de error sobre 50% de cobertura en confianzas sin binning, y admite 94.5% de las respuestas con 25.6% de error una vez que el mismo número se compara contra confianzas con binning.

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 un mapa de recalibración por binning de histograma por temp_bucket para answer_confidence.

El escalado de temperatura aplica un escalar por cubo; no puede corregir un cubo cuya curva de fiabilidad no sea un simple agudizamiento/suavizamiento (el patológico choice:11+ que lleva el checkpoint inglés distribuido es uno). El binning por histograma es la alternativa no paramétrica: divide las confianzas calibradas de un cubo en bins bins de igual anchura sobre [0, 1], y mapea cada confianza que cae en un bin a la exactitud empírica de ese bin. No necesita ninguna suposición de monotonicidad ni dependencia extra (solo NumPy; la regresión isotónica arrastraría scikit-learn).

records son las mismas tuplas (qtype, logits, target[, k]) que consume fit_temperature_map; la confianza es el max(p) calibrado (logits escalados por la temperature / temperature_by_options ajustadas primero), así que un mapa de binning se compone sobre un mapa de temperatura en lugar de reemplazarlo. Devuelve {bucket: {"bins": N, "values": [recalibrated confidence per bin]}}; los cubos por debajo de min_bucket_n se omiten. Aplícalo con :func:apply_binning_map. Un bin vacío (un rango de confianza que el conjunto de calibración nunca produjo) se mapea a su propio punto medio, es decir, deja esa región sin cambios, así que un valor no visto nunca se recalibra a un 0 inventado.

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

Recalibra una answer_confidence para su bucket de número de opciones (common.temp_bucket).

Devuelve la confianza sin cambios cuando el mapa no tiene entrada para el cubo, así que un cubo para el que el mapa no se ajustó pasa de largo en lugar de ser forzado a un valor incorrecto.

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.

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

Renderiza los textos de opción en orden de índice de etiqueta. El orden semántico de Noul es siempre [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 regla de puntuación estrictamente proper: log score + spherical score + ranked probability score.

q: [..., N, K] distribuciones reportadas target: [N, K] (distribuciones objetivo one-hot o suaves)

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

Objetivos TD(lambda) para trayectorias de conversación de varios turnos.

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

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