Juízes: Avaliação Automatizada de LLM
Nesta página
Lição atualizada em 2 de novembro de 2026 com base no SDK
mistralai3.7.0 e na página Evaluators da Mistral:judges.createagora exigedescriptionetools(exemplos antigos falhariam), as saídas de regressão exigemmin_descriptionemax_description, e pode testar um juiz diretamente numa conversa usandojudge_conversation. Variáveis de modelo e “Campanhas” de versões anteriores já não aparecem na documentação. Fontes: Evaluators · client-python.
Automatizar a Avaliação de Qualidade
Rever manualmente milhares de conversas é impossível à escala de produção. Os Juízes resolvem este problema: são avaliadores baseados em LLM que configura uma vez — definindo instruções, modelo e formato de saída — e depois aplica a conversas ou registos de conjuntos de dados. Cada julgamento produz uma análise e um veredicto: um rótulo ou uma pontuação.
Dois Tipos de Juízes
Classificação
Um juiz de classificação atribui rótulos discretos a cada resposta. Exemplos incluem:
- Binário:
helpful/not_helpful - Multiclasse:
excellent/acceptable/poor - Categorização:
code_question/general_knowledge/troubleshooting - Segurança:
safe/needs_review/unsafe
Regressão
Um juiz de regressão atribui uma pontuação numérica dentro de um intervalo, onde define os limites:
- Classificação de utilidade de 1 a 5
- Pontuação de relevância de 0 a 100
- Nível de confiança de 0.0 a 1.0
Escrever Instruções Eficazes
As instruções do juiz determinam toda a qualidade da avaliação, e a vagueza é a principal causa de falha. “Avalie a qualidade da resposta” não significa nada para um modelo — cada execução interpretará “qualidade” de forma diferente. Uma versão funcional nomeia critérios observáveis: “Avalie se a resposta responde diretamente à pergunta feita, utilizando informações factualmente corretas.” O mesmo princípio aplica-se ao contexto: o seu juiz não sabe que está a avaliar um chatbot de suporte onde “bom” significa “resolve o problema do cliente sem o enviar para a documentação”. Se não o declarar explicitamente, ele aplicará uma definição genérica de qualidade que não é a sua.
Os casos limite merecem atenção especial, pois é aqui que as avaliações divergem. Especificar que “uma pontuação de 3 significa que a resposta está parcialmente correta, mas falta um elemento chave” estabiliza o meio da sua escala — sem esta âncora, a mesma conversa pode receber um 2, 3 ou 4 dependendo da execução. O teste final é simples: se dois avaliadores humanos a ler as suas instruções puderem discordar num dado caso, o seu critério é demasiado vago e o juiz herdará essa ambiguidade à escala.
Criar um Juiz de Classificação via SDK
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Juiz de classificação de três níveis
classifier = client.beta.observability.judges.create(
name="Support Response Quality",
description="Classifies each support chatbot response into three quality levels.",
model_name="mistral-medium-latest",
instructions="""
Evaluate the assistant's last response in the provided conversation.
Context: This is a technical support chatbot.
Criteria:
- Is the response factual and correct?
- Does it directly answer the question asked?
- Is the tone professional and empathetic?
Classify the response according to the proposed categories.
""",
output={
"type": "CLASSIFICATION",
"options": [
{"value": "excellent", "description": "Correct, complete, and professional response"},
{"value": "acceptable", "description": "Correct but incomplete response, or tone needs improvement"},
{"value": "poor", "description": "Incorrect, off-topic, or unprofessional response"},
],
},
tools=[], # No tools for this judge
)
print(f"Judge created: {classifier.id}")
Criar um Juiz de Regressão via SDK
# Juiz de regressão: Pontuação de utilidade de 1 a 5
scorer = client.beta.observability.judges.create(
name="Helpfulness Score",
description="Rates the helpfulness of the assistant's last response on a scale of 1 to 5.",
model_name="mistral-small-latest",
instructions="""
Evaluate the helpfulness of the assistant's last response on a scale of 1 to 5.
1 = Useless (off-topic, incorrect, or does not answer the question)
2 = Slightly helpful (partially correct but misses the main point)
3 = Moderately helpful (correct but incomplete or too vague)
4 = Helpful (correct and sufficiently detailed)
5 = Very helpful (correct, detailed, with clear examples or steps)
""",
output={
"type": "REGRESSION",
"min": 1,
"max": 5,
"min_description": "Useless response: off-topic, incorrect, or no answer provided",
"max_description": "Very helpful response: correct, detailed, with clear steps",
},
tools=[],
)
print(f"Judge created: {scorer.id}")
Validar Antes de Escalar
Um juiz não validado produz anotações falsas à escala. Antes de confiar num, teste-o em conversas onde conhece a resposta correta: judge_conversation aplica-o a uma lista de mensagens e devolve a sua análise e veredicto.
result = client.beta.observability.judges.judge_conversation(
judge_id=classifier.id,
messages=[
{"role": "user", "content": "My printer shows error E04, what should I do?"},
{"role": "assistant", "content": "Check the documentation."},
],
)
print(result.analysis) # The judge's reasoning
print(result.answer) # The label or score
Depois, proceda metodicamente:
- Teste em 10 a 20 casos onde predeterminou o veredicto correto
- Verifique a concordância: O juiz produz os mesmos resultados que si?
- Teste a estabilidade: Ao reexecutar nos mesmos casos, os resultados são idênticos?
- Identifique padrões de falha: Em que tipos de conversas é que o juiz comete erros?
Se a concordância for demasiado baixa, refine as instruções antes de qualquer utilização em larga escala. Uma vez validado, um juiz aplica-se a registos de conjuntos de dados (client.beta.observability.datasets.records.judge), e a mesma lógica do juiz LLM aparece nos avaliadores para avaliações offline (Lição 14).
Pontos-chave
- Um juiz LLM classifica (rotula) ou pontua (avalia) conversas, suportado por uma análise
judges.createexigename,description,model_name,instructions,outputetools- Uma saída de regressão define os seus limites (
min_description,max_description) - As instruções devem ser específicas, contextualizadas e ancoradas com exemplos de pontuação
- Valide um juiz com
judge_conversationem casos conhecidos antes de confiar nele