Avaliação Automatizada de Prompts
Nesta página
Lição atualizada a 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 de Respostas) oureasoning_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.