Criar Avaliações Personalizadas
Nesta página
Lição atualizada em 3 de novembro de 2026 com base na documentação da OpenAI:
temperatureetop_psó são aceites com um esforço de raciocínio denone, enquanto os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificarreasoning={"effort": "none"}(API Responses) oureasoning_effort="none"(Chat Completions). Fontes: Using GPT-6 · GPT-5.6 Terra.
Atualização de 2 de novembro de 2026 — Plataforma Evals. A OpenAI anunciou o fim da sua plataforma Evals: as avaliações existentes estão apenas para leitura desde 31 de outubro de 2026, e tanto o painel de controlo como a API, incluindo os corretores, encerrarão a 30 de novembro de 2026. A OpenAI publicou um guia de migração para o Promptfoo. Os princípios de avaliação nesta lição permanecem válidos; apenas a ferramenta está a mudar.
Adapte as avaliações ao seu domínio
Os corretores genéricos não são suficientes para avaliar a qualidade no seu domínio específico. Um chatbot médico, um assistente jurídico e uma ferramenta de escrita de marketing têm cada um critérios de qualidade diferentes, e estes critérios não são apenas mais numerosos — são priorizados de forma distinta. Uma inadequação de tom numa newsletter é um incómodo; a mesma aproximação numa instrução de dosagem é um erro grave. Um corretor genérico trata ambos da mesma forma, o que equivale a não avaliar nada.
É por isso que precisa de avaliações personalizadas, construídas sobre uma grelha de avaliação explícita que traduza as suas prioridades de negócio em pesos. É essa grelha que vamos construir.
Traduza um requisito de negócio numa grelha de avaliação
Uma grelha de avaliação é uma lista de critérios ponderados que somam 1. O exercício mais útil não é codificar a estrutura, o que leva cerca de quinze linhas, mas preenchê-la: decidir que os benefícios para o cliente pesam 0,25 enquanto o comprimento pesa apenas 0,10 força uma conversa explícita com os responsáveis pelo produto. O resultado final é uma definição partilhada de “uma boa resposta” que ninguém pode contestar posteriormente.
from dataclasses import dataclass
@dataclass
class Critere:
nom: str
description: str
poids: float # 0 to 1, sum of weights = 1
@dataclass
class Rubrique:
nom: str
criteres: list[Critere]
def valider(self) -> bool:
total = sum(c.poids for c in self.criteres)
return abs(total - 1.0) < 0.01
# Example: rubric for a marketing writing assistant
rubrique_marketing = Rubrique(
nom="Qualité rédaction marketing",
criteres=[
Critere("ton", "Le ton est professionnel et engageant", 0.20),
Critere("cta", "Contient un appel à l'action clair", 0.15),
Critere("benefices", "Met en avant les bénéfices client", 0.25),
Critere("longueur", "Respecte la longueur demandée", 0.10),
Critere("grammaire", "Aucune faute de grammaire ou orthographe", 0.15),
Critere("marque", "Respecte les guidelines de la marque", 0.15),
],
)
O método valider merece ser chamado nos testes, não apenas escrito. As grelhas evoluem: adiciona um critério de conformidade, remove um que já não é útil, e a soma desvia para 1,15 sem que nada sinalize a anomalia. As pontuações permanecem calculáveis, apenas erradas, e quando comparadas entre versões levá-lo-ão a conclusões erradas.
O corretor traduz então a grelha num prompt, solicita uma pontuação de 0 a 5 por critério e recompõe uma pontuação global ponderada. Cada pontuação vem acompanhada de um breve comentário: é isso que lhe permitirá, ao rever casos negativos, compreender se o modelo respondeu mal ou se o seu critério estava mal formulado.
import openai
import json
client = openai.OpenAI()
def evaluer_multi_criteres(
question: str,
reponse: str,
rubrique: Rubrique,
) -> dict:
"""Evaluates a response against a multi-criteria rubric."""
criteres_texte = "\n".join(
f"- {c.nom} (poids: {c.poids}): {c.description}"
for c in rubrique.criteres
)
prompt = (
"Évaluez cette réponse selon les critères suivants.\n"
"Pour chaque critère, donnez un score de 0 à 5.\n\n"
f"Question posée : {question}\n"
f"Réponse à évaluer : {reponse}\n\n"
f"Critères :\n{criteres_texte}\n\n"
"Répondez en JSON avec un objet scores contenant pour chaque critère "
"un score (0-5) et un commentaire court."
)
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
input=prompt,
temperature=0.0,
)
try:
resultat = json.loads(response.output_text)
scores = resultat.get("scores", {})
# Calculate weighted score
score_pondere = 0
for critere in rubrique.criteres:
if critere.nom in scores:
score_brut = scores[critere.nom]["score"] / 5.0
score_pondere += score_brut * critere.poids
return {
"score_global": score_pondere,
"scores_details": scores,
"rubrique": rubrique.nom,
}
except (json.JSONDecodeError, KeyError):
return {"score_global": 0, "erreur": "Parsing échoué"}
Atenção ao ciclo de cálculo: um critério em falta na resposta do juiz é ignorado silenciosamente e contribui com zero para a pontuação ponderada. Uma resposta excelente poderia, portanto, ficar limitada a 0,75 simplesmente porque o juiz esqueceu uma chave. Se as suas pontuações parecerem estagnadas abaixo de um teto inexplicável, inspecione scores_details antes de culpar o modelo avaliado.
Quando a máquina julga melhor que um humano
Fazer um LLM avaliar código é um atalho dispendioso: o único veredicto que importa é a execução. O corretor abaixo concatena o código gerado e um teste, escreve-o num ficheiro temporário, executa-o e conta os sucessos. A pontuação resultante não precisa de interpretação — um teste passa ou não passa.
import subprocess
import tempfile
def evaluer_code_python(
code_genere: str,
tests: list[str],
) -> dict:
"""Evaluates Python code by executing it against tests."""
resultats_tests = []
for i, test in enumerate(tests):
code_complet = f"{code_genere}\n\n{test}"
with tempfile.NamedTemporaryFile(
mode="w", suffix=".py", delete=False
) as f:
f.write(code_complet)
f.flush()
try:
resultat = subprocess.run(
["python3", f.name],
capture_output=True,
text=True,
timeout=10,
)
succes = resultat.returncode == 0
resultats_tests.append({
"test": i,
"succes": succes,
"sortie": resultat.stdout[:200],
"erreur": resultat.stderr[:200] if not succes else "",
})
except subprocess.TimeoutExpired:
resultats_tests.append({
"test": i,
"succes": False,
"erreur": "Timeout (10s)",
})
nb_succes = sum(1 for r in resultats_tests if r["succes"])
return {
"score": nb_succes / len(tests) if tests else 0,
"tests_passes": nb_succes,
"tests_total": len(tests),
"details": resultats_tests,
}
O timeout=10 não é uma precaução de conforto: um modelo produz regularmente loops infinitos e, sem este limite, a sua campanha de avaliação fica bloqueada no primeiro caso falhado. Lembre-se também de que está a executar código que não escreveu — fora de um ambiente de desenvolvimento isolado, esta função requer uma sandbox.
O resumo ilustra um caso misto, onde parte do julgamento é mecânica e parte não é. O comprimento é mensurável: a razão calculada penaliza simetricamente um resumo demasiado curto e um demasiado longo, o que evita o truque do modelo de copiar o texto de origem para não omitir nada. A fidelidade, por outro lado, não é mensurável por uma regra e recorre ao juiz LLM, com uma pergunta direta sobre informações inventadas.
def evaluer_resume(
texte_original: str,
resume: str,
longueur_cible: int = 100,
) -> dict:
"""Evaluates summary quality."""
mots_resume = len(resume.split())
ratio_longueur = min(
mots_resume / longueur_cible,
longueur_cible / max(mots_resume, 1),
)
# Fidelity via LLM
response = client.responses.create(
model="gpt-5.6-terra",
input=(
f"Le résumé suivant est-il fidèle au texte original ? "
f"Contient-il des informations inventées ?\n\n"
f"Texte original (extrait) : {texte_original[:2000]}\n\n"
f"Résumé : {resume}\n\n"
f"Répondez en JSON avec les clés : fidélité (0-5), "
f"hallucinations (oui/non), commentaire (court)."
),
temperature=0.0,
)
try:
fidelite = json.loads(response.output_text)
except json.JSONDecodeError:
fidelite = {"fidelite": 0, "hallucinations": "inconnu"}
return {
"score_longueur": ratio_longueur,
"score_fidelite": fidelite.get("fidelite", 0) / 5.0,
"hallucinations": fidelite.get("hallucinations", "inconnu"),
"mots_resume": mots_resume,
"longueur_cible": longueur_cible,
}
Torne a avaliação repetível
Uma avaliação que volta a executar manualmente acaba por deixar de ser executada. O pipeline encapsula a grelha e mantém um histórico de campanhas, transformando uma medição pontual numa série temporal: vê que a pontuação média caiu de 0,81 para 0,79 após a alteração do prompt de terça-feira, informação que nenhuma execução isolada lhe poderia ter dado.
class PipelineEval:
"""Reusable evaluation pipeline."""
def __init__(self, nom: str, rubrique: Rubrique):
self.nom = nom
self.rubrique = rubrique
self.historique: list[dict] = []
def evaluer_batch(
self,
dataset: list[dict],
modele: str,
prompt_systeme: str,
) -> dict:
"""Evaluates a full batch and returns metrics."""
resultats = []
for cas in dataset:
response = client.responses.create(
model=modele,
instructions=prompt_systeme,
input=cas["input"],
)
eval_result = evaluer_multi_criteres(
cas["input"],
response.output_text,
self.rubrique,
)
resultats.append(eval_result)
scores = [r["score_global"] for r in resultats]
rapport = {
"pipeline": self.nom,
"modele": modele,
"nb_cas": len(dataset),
"score_moyen": sum(scores) / len(scores),
"score_min": min(scores),
"score_max": max(scores),
}
self.historique.append(rapport)
return rapport
Uma dica para começar: construa a sua primeira grelha com apenas vinte casos, faça-a pontuar em paralelo pelo juiz LLM e por um especialista de domínio e, em seguida, compare as duas séries. As discrepâncias dir-lhe-ão quais os critérios mal descritos muito antes de lhe dizerem qualquer coisa sobre a qualidade do modelo.
Pontos-chave
- Crie grelhas de avaliação específicas para o seu domínio de negócio, com pesos explícitos
- Verifique se a soma dos pesos se mantém em 1 à medida que a grelha evolui
- Combine avaliação automatizada (código, comprimento) e LLM-as-Judge (qualidade)
- Teste o código gerado executando-o, com um limite de tempo e num ambiente isolado
- Construa um pipeline reutilizável que mantenha um histórico de campanhas