Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Criar Avaliações Personalizadas

Aula 16 de 20 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. Adapte as avaliações ao seu domínio
  2. Traduza um requisito de negócio numa grelha de avaliação
  3. Quando a máquina julga melhor que um humano
  4. Torne a avaliação repetível
  5. Pontos-chave

Lição atualizada em 3 de novembro de 2026 com base na documentação da OpenAI: temperature e top_p só são aceites com um esforço de raciocínio de none, enquanto os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificar reasoning={"effort": "none"} (API Responses) ou reasoning_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