Como escrever uma boa pergunta para o Laya: da decisão vaga à decisão tipada

Fala aí, beleza? Se o Laya tá te devolvendo decisão diferente pra ticket quase igual, antes de culpar o modelo, olha pra pergunta 😀

Resultado inconsistente no Laya quase sempre nasce do enunciado, não da rede

Tu já sabe como ele funciona: manda um estado (texto, e-mail, ticket ou JSON) mais perguntas tipadas e recebe respostas tipadas com probabilidade calibrada, tudo numa única passada pela rede

Ele não gera texto, então não existe "conversa" pra consertar a resposta depois

O que ele decide depende MUITO de como tu escreveu o enunciado e os rótulos

Neste post eu pego a mesma pergunta em versão ruim e versão boa, passo a passo, pra tu ver onde a decisão vaga vira decisão tipada

Bora ver na prática?

Antes de reescrever suas perguntas: o que você precisa ter

O Laya é uma família de modelos de decisão open source da Convai Innovations, sob licença Apache 2.0, e a referência de formato é o model card no Hugging Face

Pra seguir o post tu precisa de quatro coisas:

• Laya instalado: pip install laya, com Python 3.10 ou mais novo
• O formato da pergunta na cabeça: type, instructions com o enunciado e criteria com cada rótulo e a descrição dele
• Uma amostra de estados reais: tickets, e-mails ou JSON do seu sistema, não exemplo inventado
• A ação que cada resposta dispara: se a resposta não muda nada no seu fluxo, a pergunta nem precisa existir

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O formato base de uma pergunta choice fica assim:

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

E se liga no idioma do estado, porque ele pesa na escolha do checkpoint:

Ticket em português rodando no checkpoint em inglês já é um jeito fácil de colher inconsistência, antes mesmo de mexer na pergunta

Passo a passo: como transformar uma decisão vaga em decisão tipada

São sete passos, e em cada um tu vê a versão ruim, a versão boa e o erro que mais aparece

1. Escreva a rubrica humana antes do código:

Parece burocracia, mas é o passo que mais economiza tempo

Se duas pessoas não concordam na resposta, o modelo também não vai ser consistente, simples assim

Versão ruim (a "rubrica" que mora só na sua cabeça):

Decidir o que fazer com o ticket

Versão boa, com entrada, respostas permitidas, definição de cada rótulo e ação:

Entrada: texto do ticket enviado pelo cliente
Respostas permitidas: billing, support, sales
billing: cobrança, fatura, reembolso ou forma de pagamento
support: algo quebrado ou que não funciona como deveria
sales: interesse em comprar, fazer upgrade ou trocar de plano
Ação: billing -> fila financeira, support -> fila técnica, sales -> time comercial

Aí tu pega uma amostra de estados reais, entrega pra dois rotuladores e compara

Onde eles discordam, o critério tá mal escrito, e é ali que tu corrige antes de virar JSON

O erro comum deste passo: pular direto pro criteria e descobrir a ambiguidade só quando a produção começa a rotear errado

2. Escolha o tipo certo: choice, score ou noul?

O Laya conhece três tipos de pergunta, e cada um responde uma coisa diferente:

Versão ruim: urgência como choice, como se "baixa" e "crítica" fossem categorias sem ordem

{
  "type": "choice",
  "instructions": "How urgent is this ticket?",
  "criteria": {
    "low": "not urgent",
    "medium": "somewhat urgent",
    "high": "urgent",
    "critical": "very urgent"
  }
}

Versão boa: urgência vira score, porque é escala (cada nível descrito, como tu vê no passo 5)

E risco de cancelamento vira noul, com um enunciado de sim/não direto: Is the customer likely to cancel or dispute?

Choice com "sim" e "não" funciona (o próprio model card usa isso pra sentimento de review), mas quando o que tu quer é a probabilidade de sim pra cortar num limite, noul entrega isso direto

O erro comum deste passo: usar choice sim/não onde noul basta, ou usar choice pra algo que tem ordem natural e deveria ser score

3. Escreva instructions sem ambiguidade:

Aqui não é prompt de modelo generativo, então esquece o textão

Se tu vem de escrever prompt para modelo de raciocínio, a lógica é outra: o enunciado precisa fechar a pergunta, não abrir espaço pra interpretação

Versão ruim:

{
  "type": "choice",
  "instructions": "What about this ticket?",
  "criteria": {
    "billing": "billing",
    "support": "support",
    "sales": "sales"
  }
}

"What about this ticket?" pode ser tema, sentimento, prioridade, dono… o modelo não tem como saber

Versão boa, com o enunciado do exemplo do model card:

{
  "type": "choice",
  "instructions": "Which team should handle this ticket?",
  "criteria": {
    "billing": "invoices, charges, refunds, payment methods",
    "support": "something broken or not working",
    "sales": "buying, upgrading or changing plans"
  }
}

O erro comum deste passo: enunciado que serve pra qualquer pergunta, e aí a mesma pergunta responde coisas diferentes em estados diferentes

4. Defina criteria com rótulos mutuamente exclusivos:

Cada estado deveria caber em UM rótulo só

Se duas descrições cobrem o mesmo caso, a probabilidade se divide entre elas e a decisão fica instável

Versão ruim, com "account" aparecendo em dois rótulos:

{
  "type": "choice",
  "instructions": "Which team should handle this ticket?",
  "criteria": {
    "billing": "account and payment issues",
    "support": "technical problems or account issues",
    "sales": "anything else"
  }
}

Problema de login cai em billing ou support? E "anything else" vira lixeira de tudo que não encaixou

Versão boa: a mesma do passo 3, com descrições curtas (poucas palavras) e sem sobreposição

E tome cuidado com rótulo nulo ou duplicado: o Laya recusa a pergunta com uma mensagem que aponta o problema (o mesmo vale pra estado None e pergunta que não é dict)

O erro comum deste passo: descrição longa tentando cobrir todo caso de borda, que acaba invadindo o rótulo do lado

5. Descreva todo nível de uma pergunta score:

Em score, todo nível precisa de descrição

Nível sem descrição é rejeitado com erro 422, na hora, antes de qualquer decisão sair

O formato exato do campo de níveis tu confere no model card, aqui o que importa é o conteúdo:

"Baixa", "média" e "alta" não dizem nada sobre o ticket, só repetem a escala

A versão boa amarra cada nível a uma situação observável no texto

O erro comum deste passo: deixar o nível do topo sem descrição achando que "crítico" é óbvio (não é, e ainda dá 422)

6. Controle o número de opções:

Todas as opções de uma choice são renderizadas num orçamento fixo head_max_len de 192 tokens

Com 77 opções sobram cerca de 4 tokens por rótulo, e o texto deixa de ser distinguível

Por isso a recomendação é manter choice abaixo de cerca de 20 opções

O README mostra o impacto: com 58 rótulos do MASSIVE-INTENT numa única pergunta, o checkpoint em inglês vai de 24/58 acertos no orçamento padrão para 34/58 com --head-max-len 384

Melhora, mas a saída mais limpa é dividir numa pergunta grossa e outra fina

Versão ruim: uma choice com dezenas de intenções

Versão boa, primeiro a pergunta grossa:

{
  "type": "choice",
  "instructions": "What area is the user asking about?",
  "criteria": {
    "calendar": "meetings, events, reminders",
    "music": "playing songs or playlists",
    "weather": "forecast or current weather"
  }
}

E depois a fina, só dentro da área escolhida:

{
  "type": "choice",
  "instructions": "What does the user want to do with the calendar?",
  "criteria": {
    "create": "add a new event",
    "query": "ask about existing events",
    "remove": "delete an event"
  }
}

O erro comum deste passo: resolver tudo aumentando o orçamento de tokens e continuar com rótulos que brigam entre si

7. Combine várias perguntas no mesmo estado:

Todas as perguntas de uma chamada são respondidas na mesma passada pela rede

Então não tem motivo pra espremer três decisões numa pergunta só

Versão ruim, misturando time, urgência e risco num rótulo:

{
  "type": "choice",
  "instructions": "Classify this ticket",
  "criteria": {
    "billing_urgent_churn": "billing, urgent, may cancel",
    "billing_normal": "billing, not urgent",
    "support_urgent": "support, urgent"
  }
}

Cada combinação vira um rótulo, as opções explodem e a exclusividade vai pro espaço

Versão boa, no molde do exemplo do model card:

• department: choice com Which team should handle this ticket? e billing, support, sales
• urgency: score com todos os níveis descritos
• churn_risk: noul com Is the customer likely to cancel or dispute?

Três perguntas pequenas, cada uma com um tipo, no mesmo estado e na mesma chamada

O erro comum deste passo: criar rótulos compostos pra "economizar chamada", que não economiza nada

Resultado inconsistente no Laya: como diagnosticar pela resposta

A resposta já te conta qual pergunta tá ruim, é só ler

• choice devolve a distribuição completa de probabilidade
• score devolve a legenda (número -> significado) e a probabilidade de cada nível
• noul devolve a probabilidade bruta de sim

Em choice e score ainda tem a confidence, que é 1 menos a entropia normalizada

Que entropia? É a medida de quão espalhada tá a distribuição: confidence alta quer dizer probabilidade concentrada num rótulo, confidence baixa quer dizer que o modelo ficou dividido

Se a confidence cai sempre na mesma pergunta, desconfia do enunciado dela primeiro

Pra prevenir, monta um conjunto de teste que inclua:

• mensagens curtas
• erros de digitação
• mistura de idiomas
• texto irrelevante citado (tipo e-mail encaminhado)
• evidência contraditória

E no fluxo de produção, o LayaGuardrail filtra por probabilidade tanto noul quanto score agora

O threshold precisa estar entre 0 e 1, fora disso ele solta ValueError

Assim o estado que não passou do limite vai pra revisão humana em vez de disparar ação no escuro

Exemplos de perguntas bem tipadas para cenários comuns

Resumão dos pares ruim x boa pra tu adaptar:

• Roteamento de ticket (choice): ruim é What about this ticket?, boa é Which team should handle this ticket? com billing, support e sales descritos sem sobreposição
• Urgência (score): ruim é choice com "low/high", boa é score com cada nível amarrado a uma situação observável
• Risco de cancelamento (noul): ruim é rótulo composto tipo billing_urgent_churn, boa é Is the customer likely to cancel or dispute? separado
• Sentimento de review (choice): "A": "yes, the review is positive" e "B": "no, the review is negative", dois rótulos que não se cruzam
• Intenção com muitas classes: ruim é uma choice gigante, boa é pergunta grossa (área) seguida de pergunta fina (ação dentro da área)

Agora o balde de água fria, porque pergunta bem escrita não é mágica:

O 0,766 é do checkpoint que treinou no split do benchmark

Em zero-shot ele fica acima do aleatório, mas abaixo de chutar sempre a classe majoritária

Ou seja, clareza da pergunta ajuda, mas quem diz se funciona no seu caso é o seu conjunto de teste, não o número do anúncio

Próximo passo: reescreva uma pergunta e compare

Recapitulando: decisão tipada é rubrica clara, tipo certo, enunciado fechado, rótulos que não se cruzam, níveis todos descritos, poucas opções e uma decisão por pergunta

De todas as alavancas pra deixar o Laya consistente, a clareza da pergunta é a mais barata

Não precisa trocar de modelo nem de máquina, é só texto 😛

O próximo passo prático:

1. Pega a pergunta que mais falha hoje
2. Passa ela pela rubrica com dois rotuladores numa amostra
3. Reescreve instructions e criteria onde eles discordaram
4. Roda de novo no conjunto de teste e compara confidence e distribuição com a versão antiga

Se a distribuição concentrou e a confidence subiu, tu achou o problema… e ele tava na pergunta haha

Até o próximo post!