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

Avaliar os Seus Prompts: Métodos, Avaliadores e Migração para o Promptfoo

Aula 15 de 20 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. Por que deve avaliar sistematicamente
  2. Construa um conjunto de dados que reflita o seu mundo real
  3. Escolha o avaliador adequado
  4. Monte a avaliação completa
  5. Industrialize com o Promptfoo
  6. 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 de Respostas) ou reasoning_effort="none" (Chat Completions). Fontes: Utilizar o 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 o painel de controlo, bem como a API, encerrarão a 30 de novembro de 2026, incluindo os avaliadores. 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.

Por que deve avaliar sistematicamente

Não pode melhorar o que não mede. Quando altera um prompt, um modelo ou um parâmetro, como sabe que a qualidade melhorou realmente? O método espontâneo consiste em testar três ou quatro exemplos, encontrar as melhores respostas e implementar. Isto falha regularmente porque os exemplos testados são precisamente os que causaram problemas na semana passada: mede a melhoria onde a procurou e ignora as regressões introduzidas em casos que já funcionavam.

As avaliações (evals) transformam esta intuição numa medida objetiva. Até 2026, a OpenAI oferecia uma plataforma integrada para o efeito, a Evals; esta está apenas para leitura desde 31 de outubro de 2026 e encerrará a 30 de novembro. A OpenAI recomenda agora o Promptfoo, uma ferramenta de código aberto para avaliação e red teaming. A boa notícia é que ambas partilham os mesmos blocos de construção: dados de teste, prompts, modelos e critérios de pontuação. O que aprender aqui em código Python traduz-se diretamente, e a parte final da lição mostra a transição para o Promptfoo.

Três conceitos estruturam todo o processo. O conjunto de dados (dataset) é um conjunto de casos de teste com entradas e saídas esperadas: é a sua referência, o equivalente a uma suíte de testes unitários. O avaliador (grader) é um critério de avaliação — correspondência exata, LLM como juiz, pontuação — que decide se uma determinada resposta é boa. A execução (run) é uma avaliação executada num conjunto de dados com um modelo e um prompt específicos; é a unidade que compara de uma versão para a seguinte.

Construa um conjunto de dados que reflita o seu mundo real

Um caso de teste consiste numa entrada, numa saída esperada e em metadados. Estes últimos não são decorativos: são o que lhe permitirá perceber, a posteriori, que uma pontuação global de 87% esconde um colapso na categoria “código”, compensado por excelentes resultados em geografia. Sem categoria ou dificuldade, tem apenas um número agregado, e um número agregado nunca lhe diz onde intervir.

import json

# Um conjunto de dados é uma lista de casos de teste
dataset = [
    {
        "input": "What is the capital of France?",
        "expected": "Paris",
        "metadata": {"category": "geography", "difficulty": "easy"},
    },
    {
        "input": "Explain Bayes' theorem in one sentence.",
        "expected": "Bayes' theorem calculates the probability "
                    "of an event based on known conditional probabilities.",
        "metadata": {"category": "mathematics", "difficulty": "medium"},
    },
    {
        "input": "Write a Python function that reverses a list.",
        "expected": "def reverse_list(lst): return lst[::-1]",
        "metadata": {"category": "code", "difficulty": "easy"},
    },
]

# Guardar como JSONL
with open("eval_dataset.jsonl", "w") as f:
    for case in dataset:
        f.write(json.dumps(case, ensure_ascii=False) + "\n")

Um conjunto de dados inventado no escritório avalia a sua imaginação, não a sua aplicação. Os seus utilizadores formulam os seus pedidos de forma diferente da sua: erros ortográficos, perguntas incompletas, contexto implícito. A melhor fonte de casos de teste são, portanto, os seus próprios dados de produção, desde que tenha um humano a validar as respostas de referência — caso contrário, congela os erros atuais como norma.

import openai
import random

client = openai.OpenAI()

def create_dataset_from_logs(
    production_logs: list[dict],
    sample_size: int = 100,
) -> list[dict]:
    """Cria um conjunto de dados de avaliação a partir de registos de produção."""
    # Amostragem
    sample = random.sample(
        production_logs,
        min(sample_size, len(production_logs)),
    )

    dataset = []
    for log in sample:
        dataset.append({
            "input": log["prompt"],
            "expected": log["validated_response"],  # Resposta validada por um humano
            "metadata": {
                "source": "production",
                "date": log["date"],
                "original_model": log["model"],
            },
        })

    return dataset

Escolha o avaliador adequado

O avaliador de correspondência exata é o mais rigoroso e rápido. Só se adequa a tarefas onde a saída é restrita: uma classificação de três categorias, extração de um número de fatura, uma resposta de sim ou não. Se utilizado em texto livre, atribuiria zero a uma resposta perfeita simplesmente formulada de forma diferente da referência.

def exact_grader(response: str, expected: str) -> dict:
    """Avalia se a resposta corresponde exatamente."""
    score = 1.0 if response.strip().lower() == expected.strip().lower() else 0.0
    return {"score": score, "type": "exact"}

O avaliador de inclusão relaxa a restrição: verifica a presença de palavras-chave esperadas e devolve uma pontuação parcial. Esta é a ferramenta certa para respostas que devem cobrir pontos obrigatórios sem que a redação importe — uma resposta de suporte que deve mencionar o prazo de desistência e o endereço de devolução, por exemplo. A sua fraqueza é bem conhecida: um texto contendo as palavras certas numa ordem absurda obteria uma pontuação perfeita.

def inclusion_grader(response: str, keywords: list[str]) -> dict:
    """Verifica se a resposta contém as palavras-chave esperadas."""
    response_lower = response.lower()
    found = sum(1 for word in keywords if word.lower() in response_lower)
    score = found / len(keywords) if keywords else 0.0
    return {
        "score": score,
        "found": found,
        "total": len(keywords),
        "type": "inclusion",
    }

Depois, existe o mais poderoso: outro LLM avalia a qualidade da resposta. O avaliador LLM-as-Judge aprecia o que nenhuma regra mecânica consegue — clareza, completude, precisão do tom. Dois detalhes de implementação tornam-no prático. Primeiro, temperature=0.0: sem isto, o mesmo juiz atribuiria pontuações diferentes à mesma resposta de uma execução para outra, e o seu ponto de referência perderia todo o valor comparativo. Segundo, a recuperação para json.JSONDecodeError: um juiz que comenta em vez de devolver JSON não deve fazer falhar toda a campanha.

def llm_judge_grader(
    question: str,
    response: str,
    expected: str,
    criteria: str = "accuracy, completeness, clarity",
) -> dict:
    """Utiliza um LLM para avaliar a qualidade da resposta."""
    judge_prompt = f"""Rate the quality of this response on a scale of 1 to 5.

Question: {question}
Expected Response: {expected}
Response to Evaluate: {response}

Criteria: {criteria}

Respond ONLY with JSON:
{{"score": <1-5>, "justification": "<short explanation>"}}"""

    response_obj = client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        input=judge_prompt,
        temperature=0.0,
    )

    import json
    try:
        result = json.loads(response_obj.output_text)
        result["normalized_score"] = result["score"] / 5.0
        return result
    except json.JSONDecodeError:
        return {"score": 0, "justification": "Parsing error", "normalized_score": 0}

Monte a avaliação completa

A orquestração não apresenta dificuldade conceptual: itera sobre o conjunto de dados, chama o modelo com o prompt de sistema a testar, aplica o avaliador e agrega. O ponto interessante é que a função de pontuação entra como um parâmetro, o que lhe permite repetir exatamente o mesmo conjunto de dados com critérios diferentes dependendo da campanha — inclusão para uma verificação rápida durante o desenvolvimento, juiz LLM para validação antes da produção.

async def run_eval(
    dataset: list[dict],
    model: str,
    system_prompt: str,
    grader_fn,
) -> dict:
    """Executa uma avaliação completa num conjunto de dados."""
    results = []

    for case in dataset:
        response = client.responses.create(
            model=model,
            instructions=system_prompt,
            input=case["input"],
        )

        score = grader_fn(response.output_text, case["expected"])
        results.append({
            "input": case["input"],
            "expected": case["expected"],
            "obtained": response.output_text,
            **score,
        })

    # Calcular métricas agregadas
    scores = [r["score"] for r in results if "score" in r]
    return {
        "model": model,
        "num_cases": len(dataset),
        "average_score": sum(scores) / len(scores) if scores else 0,
        "min_score": min(scores) if scores else 0,
        "max_score": max(scores) if scores else 0,
        "results": results,
    }

O relatório mantém o min_score e o detalhe de cada caso, e isso é deliberado. A média diz-lhe se está a avançar; os casos com pior pontuação dizem-lhe porquê. Adote o hábito de ler as cinco piores respostas de cada execução antes de comentar a média: é aí, e raramente noutro lugar, que encontrará a próxima correção a fazer.

Industrialize com o Promptfoo

Escrever as suas avaliações à mão em Python é educativo; mantê-las ao longo do tempo é mais confortável com uma ferramenta dedicada. O guia de migração da OpenAI descreve a lógica do Promptfoo: a avaliação reside num ficheiro de configuração, promptfooconfig.yaml, que reúne prompts, modelo(s), casos de teste e critérios — aqui chamados asserções. É executado a partir da linha de comandos, localmente ou na sua integração contínua, e vive ao lado do código da aplicação.

description: Support ticket classification
prompts:
  - "Classify this ticket into a single category (billing, technical, account): {{ticket}}"
providers:
  - openai:gpt-6.1-sol
tests:
  - vars:
      ticket: "My card was charged twice this month."
    assert:
      - type: icontains
        value: billing
  - vars:
      ticket: "The app crashes when I open a PDF."
    assert:
      - type: icontains
        value: technical
promptfoo eval -c promptfooconfig.yaml --no-cache
promptfoo view
promptfoo validate config -c promptfooconfig.yaml   # in case of configuration error

Os avaliadores nesta lição reaparecem como asserções: correspondência exata, inclusão de palavras-chave e julgamento por modelo. A OpenAI alerta para o último ponto: um avaliador recriado, especialmente um juiz LLM, deve ser revalidado antes de ser usado para decidir sobre uma regressão, porque as pontuações não serão necessariamente idênticas de uma ferramenta para outra.

Pontos-chave

  • As evals transformam a intuição numa medida objetiva de qualidade
  • Crie os seus conjuntos de dados a partir de casos reais de produção, validados por um humano
  • Escolha o avaliador com base na tarefa: exato para restrito, inclusão para pontos obrigatórios, LLM-as-Judge para nuances
  • Defina temperature=0.0 no juiz para tornar as pontuações reproduzíveis
  • Execute evals antes de cada alteração de prompt ou modelo
  • A plataforma Evals da OpenAI encerra a 30 de novembro de 2026: o Promptfoo, recomendado pela OpenAI, assume os conjuntos de dados, prompts, modelos e critérios num ficheiro de configuração