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

Avaliação Automatizada de Prompts

Aula 16 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Avaliação Automatizada de Prompts
  2. Tipos de Avaliação
  3. Pipeline de Avaliação Completa
  4. Conjunto de Testes: Formato
  5. Integração CI/CD
  6. Painel de Avaliação
  7. Configure as Suas Guardas
  8. Pontos-chave
  9. Teste os Seus Conhecimentos

Lição atualizada a 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 de Respostas) ou reasoning_effort="none" (Chat Completions). Fontes: Utilizar o GPT-6 · GPT-5.6 Terra.

Avaliação Automatizada de Prompts

A avaliação automatizada é a pedra angular de um pipeline de engenharia de prompts maduro. Permite-lhe detetar regressões, comparar modelos e validar alterações antes da implementação. Sem ela, cada alteração de prompt é uma aposta às cegas.

Tipos de Avaliação

Três famílias de avaliadores dividem o trabalho com base na natureza da saída esperada, e quase sempre combinará várias delas.

Avaliação de Correspondência Exata

Para tarefas com uma única resposta esperada, a comparação direta é suficiente. eval_exact_match normaliza maiúsculas/minúsculas e espaços em branco antes de comparar: sem esta precaução, “Bug” e “bug” contariam como um erro, levando-o a corrigir um problema que não existe.

eval_set_match lida com casos em que a resposta é um conjunto — entidades encontradas num documento, categorias atribuídas a um artigo. Deriva precisão e recall, dois valores que contam histórias diferentes: alta precisão com baixo recall sinaliza um modelo excessivamente cauteloso que extrai apenas aquilo de que tem certeza; o inverso denuncia um modelo que alucina para preencher lacunas. O F1 resume-os convenientemente, mas não os substitui para diagnóstico.

def eval_exact_match(prediction: str, reference: str) -> bool:
    """Correspondência exata após normalização."""
    return prediction.strip().lower() == reference.strip().lower()

def eval_set_match(prediction: set, reference: set) -> dict:
    """Correspondência de conjuntos (entidades, categorias)."""
    tp = len(prediction & reference)
    fp = len(prediction - reference)
    fn = len(reference - prediction)

    precision = tp / (tp + fp) if (tp + fp) > 0 else 0
    recall = tp / (tp + fn) if (tp + fn) > 0 else 0
    f1 = (2 * precision * recall / (precision + recall)
          if (precision + recall) > 0 else 0)

    return {"precision": precision, "recall": recall, "f1": f1}

Avaliação Semântica (Embedding)

Para respostas de texto onde a redação pode variar, a correspondência exata torna-se absurda: “A sua encomenda será entregue amanhã” e “A entrega está agendada para amanhã” dizem a mesma coisa, mas teriam pontuação zero. A similaridade do cosseno entre embeddings mede a proximidade semântica em vez da correspondência de carateres, devolvendo uma pontuação contínua.

Define o limiar acima do qual uma resposta é considerada aceitável. Calibre-o com algumas dezenas de pares que classificou manualmente como “equivalentes” ou “diferentes”, e depois escolha o valor que melhor separa os dois grupos: um limiar escolhido por intuição produz resultados tão arbitrários como a ausência de medição, com a ilusão acrescida de rigor.

from openai import OpenAI
import numpy as np

client = OpenAI()

def eval_semantic_similarity(prediction: str,
                              reference: str) -> float:
    """Similaridade do cosseno entre embeddings."""
    response = client.embeddings.create(
        model="text-embedding-3-large",
        input=[prediction, reference]
    )
    emb_pred = np.array(response.data[0].embedding)
    emb_ref = np.array(response.data[1].embedding)

    similarity = float(
        np.dot(emb_pred, emb_ref) /
        (np.linalg.norm(emb_pred) * np.linalg.norm(emb_ref))
    )
    return similarity

Avaliação por LLM (LLM-as-Judge)

O modelo avalia a qualidade de uma resposta. Esta é a única abordagem viável quando não existe referência: ninguém vai escrever à mão a resposta de suporte “correta” para duzentos tickets.

O que torna um juiz utilizável resume-se a algumas coisas. Primeiro, o modelo utilizado: escolhe um modelo mais capaz como juiz, aqui gpt-5.6-sol, porque um juiz ao mesmo nível do avaliado tende a validar as suas próprias falhas. Segundo, exigir justificação: motivar cada pontuação estabiliza o julgamento e permite-lhe detetar um avaliador a usar o critério errado — uma justificação que discute o comprimento quando o critério era a clareza é um sinal de alarme. Finalmente, temperature a 0.1 garante a estabilidade da pontuação entre execuções.

def eval_llm_judge(question: str, prediction: str,
                    criteria: list[str]) -> dict:
    """Avaliação por um modelo juiz."""
    criteria_text = "\n".join(
        f"- {c}: pontuação de 1 a 5" for c in criteria
    )

    response = client.responses.create(
        model="gpt-5.6-sol",  # Modelo mais capaz como juiz
        reasoning={"effort": "none"},  # temperature exige effort none
        instructions="É um avaliador especialista e imparcial.",
        input=f"""Avalie esta resposta de acordo com os seguintes critérios:

Pergunta colocada: {question}

Resposta a avaliar: {prediction}

Critérios:
{criteria_text}

Para cada critério, atribua uma pontuação de 1 a 5 com justificação.""",
        text={
            "format": {
                "type": "json_schema",
                "name": "evaluation",
                "schema": {
                    "type": "object",
                    "properties": {
                        "scores": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "criterion": {"type": "string"},
                                    "score": {"type": "integer"},
                                    "justification": {"type": "string"}
                                },
                                "required": ["criterion", "score",
                                              "justification"],
                                "additionalProperties": False
                            }
                        },
                        "overall_score": {"type": "number"},
                        "verdict": {"type": "string"}
                    },
                    "required": ["scores", "overall_score", "verdict"],
                    "additionalProperties": False
                },
                "strict": True
            }
        },
        temperature=0.1
    )
    return json.loads(response.output_text)

Pipeline de Avaliação Completa

EvalPipeline reúne estes blocos de construção: carrega um conjunto de testes, executa o prompt em cada caso, aplica todos os avaliadores fornecidos e agrega as pontuações. Os avaliadores são passados como uma lista de funções, todos chamados com a mesma assinatura; adicionar uma métrica não requer, portanto, nenhuma modificação no pipeline, e pode executar correspondência exata, similaridade semântica e um juiz na mesma execução sem pagar pela geração três vezes.

O método summary também acumula tokens consumidos. Esta linha, aparentemente secundária, protege-o de uma armadilha comum: uma versão de prompt que ganha dois pontos de pontuação enquanto triplica a fatura não é necessariamente a escolha certa, e é melhor aprender isso no momento da compensação do que quando chega a fatura mensal.

import json
from dataclasses import dataclass
from pathlib import Path

@dataclass
class TestCase:
    """Um caso de teste para avaliação."""
    input_text: str
    expected_output: str = None
    metadata: dict = None

class EvalPipeline:
    """Pipeline de avaliação automatizada."""

    def __init__(self, test_suite_path: str):
        """Carrega o conjunto de testes a partir de um ficheiro JSON."""
        data = json.loads(Path(test_suite_path).read_text())
        self.test_cases = [TestCase(**tc) for tc in data]
        self.results = []

    def run(self, prompt_config: dict,
            evaluators: list[callable]) -> dict:
        """Executa todos os testes e avalia os resultados."""
        self.results = []

        for tc in self.test_cases:
            # Gerar resposta
            response = client.responses.create(
                model=prompt_config["model"],
                reasoning={"effort": "none"},  # temperature exige effort none
                instructions=prompt_config["system_prompt"],
                input=tc.input_text,
                temperature=prompt_config.get("temperature", 0.1)
            )

            prediction = response.output_text

            # Avaliar com cada avaliador
            scores = {}
            for evaluator in evaluators:
                score = evaluator(
                    question=tc.input_text,
                    prediction=prediction,
                    reference=tc.expected_output
                )
                scores[evaluator.__name__] = score

            self.results.append({
                "input": tc.input_text,
                "expected": tc.expected_output,
                "prediction": prediction,
                "scores": scores,
                "tokens": {
                    "input": response.usage.input_tokens,
                    "output": response.usage.output_tokens
                }
            })

        return self.summary()

    def summary(self) -> dict:
        """Resume os resultados da avaliação."""
        if not self.results:
            return {"error": "Sem resultados"}

        # Agregar pontuações por avaliador
        all_scores = {}
        for result in self.results:
            for eval_name, score in result["scores"].items():
                if eval_name not in all_scores:
                    all_scores[eval_name] = []
                if isinstance(score, (int, float)):
                    all_scores[eval_name].append(score)
                elif isinstance(score, dict) and "f1" in score:
                    all_scores[eval_name].append(score["f1"])

        summary = {
            "total_tests": len(self.results),
            "average_scores": {
                name: sum(scores) / len(scores)
                for name, scores in all_scores.items()
                if scores
            },
            "total_token_cost": sum(
                r["tokens"]["input"] + r["tokens"]["output"]
                for r in self.results
            )
        }
        return summary

Conjunto de Testes: Formato

O formato do conjunto de testes mantém-se intencionalmente minimalista: uma entrada, a saída esperada e metadados de forma livre. Estes metadados são mais úteis do que parecem — ao etiquetar cada caso por categoria, decompõe as pontuações e descobre que o seu classificador não está a falhar aleatoriamente, mas sim numa família específica de pedidos, algo que uma média global de 88% não revela. Os três exemplos abaixo também mostram o que um bom conjunto deve conter: casos claros, como uma falha de arranque, mas também casos que fazem fronteira com outra categoria — uma pergunta sobre uma funcionalidade em falta parece muito com um relatório de erro, e é nesta fronteira que se decide a qualidade de um classificador.

[
    {
        "input_text": "A minha encomenda ainda não chegou",
        "expected_output": "reclamação",
        "metadata": {"category": "entrega"}
    },
    {
        "input_text": "Como ativo o modo escuro?",
        "expected_output": "pergunta",
        "metadata": {"category": "funcionalidade"}
    },
    {
        "input_text": "A aplicação falha no arranque no iOS 18",
        "expected_output": "erro",
        "metadata": {"category": "técnico"}
    }
]

Integração CI/CD

Execute a avaliação em cada alteração de prompt. A função ci_eval_check transforma a medição numa guarda: executa o pipeline, compara a pontuação média com um limiar e devolve um booleano que a sua cadeia de integração interpreta como sucesso ou falha de compilação. Uma alteração que faça cair a precisão abaixo de 85% já não chega à produção, tal como um teste unitário com falha bloqueia uma fusão.

Defina o limiar com base na pontuação já alcançada pela versão atual, não num ideal. Defina-o demasiado alto e condenará a equipa a contornar a verificação com desativações temporárias que se tornam permanentes; defina-o demasiado baixo e não estará a verificar nada enquanto exibe um emblema verde. Finalmente, tenha em mente que o conjunto deve permanecer representativo do tráfego real: um limiar cumprido em vinte casos escritos há dois anos não prova nada sobre os pedidos de hoje.

def ci_eval_check(prompt_config: dict,
                   test_suite: str,
                   min_score: float = 0.85) -> bool:
    """Barreira CI/CD: verifica se o prompt atinge a pontuação mínima."""
    pipeline = EvalPipeline(test_suite)

    def accuracy(question, prediction, reference):
        return 1.0 if prediction.strip().lower() == reference.strip().lower() else 0.0

    results = pipeline.run(prompt_config, [accuracy])
    avg_score = results["average_scores"].get("accuracy", 0)

    print(f"Pontuação média: {avg_score:.2%}")
    print(f"Limiar mínimo: {min_score:.2%}")

    if avg_score < min_score:
        print("FALHA: pontuação abaixo do limiar")
        return False

    print("SUCESSO: prompt validado")
    return True

Painel de Avaliação

Acompanhe a evolução da pontuação ao longo do tempo. Uma única pontuação não diz nada; a série conta a história do seu prompt e responde à pergunta que surge sempre nas reuniões: estamos a progredir? A função abaixo produz uma tabela Markdown colocando lado a lado, para cada versão, a pontuação média, os tokens consumidos e o custo estimado. O formato não é acidental: cola diretamente num pull request, tornando a comparação legível para pessoas que nunca abrirão o seu código.

def comparison_report(results: dict[str, dict]) -> str:
    """Gera um relatório comparativo entre versões de prompts."""
    report = "# Relatório de Avaliação Comparativa\n\n"
    report += "| Versão | Pontuação Média | Tokens Médios | Custo |\n"
    report += "|---------|---------------|----------------|------|\n"

    for version, data in results.items():
        score = data.get("average_scores", {})
        score_val = list(score.values())[0] if score else 0
        tokens = data.get("total_token_cost", 0)
        report += (f"| {version} | {score_val:.2%} | "
                   f"{tokens} | ${tokens * 5 / 1e6:.4f} |\n")

    return report

Configure as Suas Guardas

Construa um conjunto de vinte casos de teste para um prompt real, colocando alguns casos limite em vez de vinte exemplos confortáveis: um conjunto que passa a 100% na primeira tentativa não lhe ensina nada. Implemente os três tipos de avaliadores e execute-os em conjunto em duas versões do seu prompt. A correspondência exata dá um número limpo, a similaridade semântica deteta reformulações legítimas e o juiz ilumina os casos onde os dois primeiros discordam — estas discordâncias são as mais ricas em lições sobre o que realmente espera do modelo.

Compare, identifique a versão vencedora e, em seguida, configure o script CI que bloqueia a implementação se a pontuação cair. Saberá que o sistema funciona no dia em que rejeitar uma alteração que pensava ser óbvia.

Pontos-chave

  • A avaliação automatizada é essencial para iterar com confiança
  • Combine avaliação exata, semântica e LLM-as-judge conforme necessário
  • Mantenha um conjunto de testes que evolua com a sua aplicação
  • Integre a avaliação no seu CI/CD com um limiar mínimo
  • Utilize um modelo mais capaz como juiz para avaliar um modelo mais barato
  • Documente as pontuações de cada versão para acompanhar a evolução

Teste os Seus Conhecimentos

Técnicas avançadas e industrialização: a verificação final.

1. O que contém um system prompt eficaz?

Resposta: Papel, âmbito, regras de comportamento, formato de saída e tratamento de casos limite — escrito como uma especificação, testado como código.

2. Quando deve utilizar autoconsistência?

Resposta: Em problemas de raciocínio com respostas verificáveis: gere múltiplos raciocínios independentes e mantenha a resposta maioritária — a variância torna-se uma aliada.

3. O que garante o modo JSON com imposição de esquema?

Resposta: Saída estritamente conforme ao esquema (tipos, campos obrigatórios, enums) — validada no lado da API e revalidada no código (JSON Schema, Zod) para uma cadeia sem surpresas.

4. O que é o grounding?

Resposta: Ancorar respostas em factos fornecidos (documentos, dados recuperados) em vez da memória do modelo — com o requisito de citar ou abster-se de fontes externas.

5. Qual é o objetivo de um catálogo de prompts versionado?

Resposta: Tratar prompts como artefactos: versões, testes A/B, avaliações automatizadas em cada alteração — sabe o que está a correr em produção e porquê.

O ciclo final do curso — versionar, testar, avaliar automaticamente — transforma a engenharia de prompts artesanal numa prática de equipa.