Cómo usar Laya: tutorial paso a paso de decisiones tipadas

Este tutorial muestra cómo usar Laya de principio a fin con una tarea real: enrutar tickets de soporte. Escribirás preguntas tipadas, leerás las respuestas y sus probabilidades, decidirás cuándo actuar de forma automática, procesarás tickets en bloque y medirás la precisión con tus propios datos.

Se asume que Laya ya está instalado (pip install laya, Python 3.10 o superior). Si no, empieza por Instalar Laya.

Paso 1: tu primera llamada

Una llamada a Laya recibe un state (el texto o JSON sobre el que quieres una decisión) y un conjunto de preguntas tipadas. Devuelve una respuesta por pregunta, con probabilidades, en una sola pasada del modelo.

from laya import Router

router = Router()  # descarga un checkpoint la primera vez

state = "Hi, we were billed twice for March. Please refund the duplicate today or we will cancel our plan."
questions = {
    "department": {"type": "choice", "instructions": "Which department should handle this?",
                   "criteria": {"billing": "invoices, payments, refunds",
                                "technical": "bugs, outages, system errors",
                                "other": "everything else"}},
    "urgency": {"type": "score", "instructions": "How urgent is this?",
                "criteria": ["not urgent", "soon", "blocking"]},
    "churn_risk": {"type": "noul", "instructions": "Does the user threaten to cancel or leave?"},
}

result = router.predict(state, questions)
print(result["answers"]["department"]["choice"])  # billing
print(result["routing"]["model"])                 # english

El Router elige el checkpoint por ti: el texto en inglés va a laya y los demás idiomas a laya-multilingual. En un servidor, créalo una sola vez con Router(preload=True) para que ninguna petición espere a que se cargue un modelo.

Paso 2: escribe preguntas que Laya responda bien

La redacción de las preguntas importa más que cualquier ajuste. Laya tiene tres tipos de pregunta.

choice: elige una opción. Las claves de criteria son las etiquetas que recibes; los valores son lo que lee el modelo. Describe cada opción en pocas palabras en lugar de poner solo una etiqueta, y añade una opción other para los tickets poco habituales.

score: puntúa en una escala ordenada. Pasa criteria como una lista de menor a mayor. La respuesta es el nivel esperado, así que 1.8 en una escala de tres niveles significa "casi bloqueante".

noul: responde sí o no. La respuesta es la probabilidad de que la respuesta sea sí. Si añades criteria, las claves deben ser true y false. En el checkpoint inglés, una respuesta noul puede dejarse llevar por las etiquetas de las opciones en lugar del texto, así que compruébalo con tus propios ejemplos. El proyecto sugiere cambiar las etiquetas que ve el modelo o usar en su lugar una pregunta choice de dos opciones:

{"type": "choice", "instructions": "Is this review positive?",
 "criteria": {"A": "yes, the review is positive", "B": "no, the review is negative"}}

Mantén una pregunta choice por debajo de unas 20 opciones. Todas las opciones comparten un presupuesto fijo de tokens (192 en laya y 256 en los demás checkpoints), así que las listas largas se comprimen hasta que las etiquetas parecidas se vuelven indistinguibles.

Paso 3: lee el resultado

Cada respuesta es un pequeño diccionario. Para una pregunta choice tiene este aspecto (valores de ejemplo):

{
    "type": "choice",
    "choice": "billing",
    "probabilities": {"billing": 0.91, "technical": 0.03, "other": 0.06},
    "confidence": 0.62,
    "answer_confidence": 0.91,
}

choice, score o noul es la respuesta en sí.
probabilities muestra todas las opciones; es útil para registrar y depurar. Una respuesta score incluye además un legend que asocia cada número de nivel con tu etiqueta.
answer_confidence es la probabilidad de la respuesta que devolvió Laya. Es el valor que debes usar como umbral. Es la magnitud sobre la que se ajusta la calibración y significa lo mismo para todos los tipos de pregunta.
confidence mide lo concentrada que está toda la distribución. No está calibrado, así que no lo compares con el mismo umbral.

Paso 4: actúa solo cuando Laya esté seguro

La utilidad de las probabilidades es automatizar los casos fáciles y enviar el resto a una persona o a un modelo más grande:

answer = result["answers"]["department"]

if answer["answer_confidence"] >= THRESHOLD:
    route_ticket(answer["choice"])
else:
    send_to_human(state, suggestion=answer["choice"])

No existe un THRESHOLD universal. El proyecto advierte que los checkpoints publicados son demasiado confiados y que laya-multilingual todavía no tiene temperaturas ajustadas, así que elige el umbral con tus propios datos etiquetados (paso 6). Un umbral copiado de Jev tampoco sirve, porque Jev define la confianza de otra manera.

Paso 5: procesa muchos tickets a la vez

Cuando tengas una cola pendiente, evalúala entera con las mismas preguntas usando predict_batch. Los resultados vuelven en el mismo orden que la entrada:

import laya

agent = laya.load("convaiinnovations/laya")
states = [{"body": text} for text in ticket_texts]

results = agent.predict_batch(states, questions, batch_size=64)
for text, result in zip(ticket_texts, results):
    print(result["answers"]["department"]["choice"], text[:60])

Procesar por lotes acelera mucho en GPU. En CPU ahorra poco, porque el trabajo crece con el número de states; consulta Laya en CPU para ver cifras medidas.

Paso 6: mide la precisión con tus datos

Antes de dejar que Laya actúe sobre tickets reales, etiqueta entre 50 y 200 ejemplos de tu propio tráfico y mide dos cosas: la precisión global y la precisión en las decisiones que automatizarías con tu umbral.

labelled = [
    ("I was charged twice for my subscription", "billing"),
    ("The export button crashes the app", "technical"),
    # ... tus propios ejemplos
]
THRESHOLD = 0.8
question = {"department": questions["department"]}

correct = kept = kept_correct = 0
for text, gold in labelled:
    answer = router.predict(text, question)["answers"]["department"]
    correct += answer["choice"] == gold
    if answer["answer_confidence"] >= THRESHOLD:
        kept += 1
        kept_correct += answer["choice"] == gold

print(f"accuracy: {correct / len(labelled):.2f}")
print(f"automated: {kept / len(labelled):.0%} of tickets, "
      f"accuracy on those: {kept_correct / max(kept, 1):.2f}")

Sube el umbral hasta que la precisión de las decisiones automatizadas sea aceptable para ti, y mira qué proporción de tickets se sigue automatizando en ese punto. Si las cifras no bastan, reformula las opciones (paso 2) o ajusta Laya con tus datos etiquetados.

Errores comunes al usar Laya

Demasiadas opciones en una pregunta. Por encima de unas 20, sube head_max_len o reduce antes los candidatos con predict_shortlist.
Textos largos que se recortan. El checkpoint inglés lee 512 tokens por defecto. Consulta la ventana de contexto para max_len y predict_long.
Enviar texto que no está en inglés al checkpoint inglés. Usa el Router o carga directamente laya-multilingual.
Fiarse de score en el checkpoint multilingüe sin comprobarlo. El proyecto informa de un sesgo de posición: rara vez elige el primer nivel.
Usar confidence como umbral en lugar de answer_confidence.

Preguntas frecuentes

¿Laya es un chatbot o un LLM?

No. Laya responde preguntas tipadas sobre el texto que le das y devuelve probabilidades. No escribe texto, así que no hay nada que analizar ni salida que pueda alucinar. Para respuestas abiertas, usa un LLM; para clasificación y enrutamiento, consulta Laya vs LLM.

Explora las recetas: triaje de tickets, moderación, guardrails, enrutamiento y más
Ajusta Laya con tus datos etiquetados
Autoaloja Laya como API compatible con Jev
La guía de Python con cada tipo de pregunta en detalle

Última verificación con el repositorio oficial: 26 de septiembre de 2026.