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

CI/CD para IA: Avaliações Automatizadas

Aula 18 de 20 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. Integrar Avaliações no Seu Pipeline CI/CD
  2. O Princípio: Uma Barreira, Não um Relatório
  3. Ligar Tudo no GitHub Actions
  4. Comparar em Vez de Julgar em Termos Absolutos
  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 de Respostas) ou reasoning_effort="none" (Chat Completions). Fontes: Utilizar o GPT-6 · GPT-5.6 Terra.

Integrar Avaliações no Seu Pipeline CI/CD

Implementar uma alteração de prompt em produção sem avaliação é como implementar código sem testes. A comparação é mais precisa do que possa parecer: em ambos os casos, a alteração parece trivial, foi verificada manualmente num ou dois exemplos, e o efeito secundário surge três dias depois para um utilizador que não lho vai comunicar. A diferença é que uma regressão de prompt não levanta uma exceção — a aplicação continua a responder, apenas pior.

O objetivo é tornar a avaliação automatizada uma etapa obrigatória no seu processo de implementação, garantindo que cada alteração mantém ou melhora a qualidade. É exatamente isso que vamos abordar de seguida.

O Princípio: Uma Barreira, Não um Relatório

O pipeline de avaliação integra-se no seu fluxo de implementação através de um mecanismo familiar. Um programador modifica um prompt ou um parâmetro, o commit aciona o pipeline de CI e as avaliações são executadas automaticamente contra o conjunto de dados de referência. Se as pontuações cumprirem os limiares, a implementação continua; caso contrário, é bloqueada, com um relatório detalhado a indicar qual a avaliação que falhou e em que medida.

O ponto crítico é o comportamento de bloqueio. Uma CI que produz um relatório bonito sem parar o pipeline torna-se num artefacto que ninguém consulta passadas duas semanas. Apenas um código de saída diferente de zero transforma a medição numa guarda de segurança.

O script abaixo lê uma configuração, carrega cada conjunto de dados, executa os casos e compara a pontuação média com o limiar declarado. O método de pontuação — inclusão simples de palavras-chave — é intencionalmente rudimentar: uma verificação de CI deve ser rápida, determinística e independente de um avaliador cuja pontuação possa variar de uma execução para outra.

import json
import sys
import openai
from pathlib import Path

client = openai.OpenAI()

def load_eval_config(path: str = "evals/config.json") -> dict:
    """Carrega a configuração de avaliação."""
    with open(path) as f:
        return json.load(f)

def load_dataset(path: str) -> list[dict]:
    """Carrega um conjunto de dados JSONL."""
    cases = []
    with open(path) as f:
        for line in f:
            cases.append(json.loads(line))
    return cases

def run_ci_evals(config: dict) -> dict:
    """Executa avaliações para CI."""
    results = {}

    for eval_config in config["evaluations"]:
        name = eval_config["name"]
        dataset = load_dataset(eval_config["dataset"])
        threshold = eval_config["min_threshold"]
        model = eval_config["model"]
        prompt = Path(eval_config["prompt_file"]).read_text()

        scores = []
        for case in dataset:
            response = client.responses.create(
                model=model,
                reasoning={"effort": "none"},  # temperature requires effort none
                instructions=prompt,
                input=case["input"],
                temperature=0.0,
            )

            # Avaliação simples por inclusão de palavras-chave
            if "keywords" in case:
                response_lower = response.output_text.lower()
                found = sum(
                    1 for word in case["keywords"]
                    if word.lower() in response_lower
                )
                score = found / len(case["keywords"])
            else:
                score = 1.0  # Sem critério específico

            scores.append(score)

        avg_score = sum(scores) / len(scores)
        passed = avg_score >= threshold

        results[name] = {
            "score": avg_score,
            "threshold": threshold,
            "passed": passed,
            "num_cases": len(dataset),
        }

    return results

def ci_report(results: dict) -> tuple[str, bool]:
    """Gera um relatório para CI e indica se está tudo OK."""
    lines = ["# Relatório de Avaliação de IA\n"]
    all_pass = True

    for name, r in results.items():
        status = "PASS" if r["passed"] else "FAIL"
        if not r["passed"]:
            all_pass = False
        lines.append(
            f"- [{status}] {name}: {r['score']:.2%} "
            f"(limiar: {r['threshold']:.0%}, {r['num_cases']} casos)"
        )

    report = "\n".join(lines)
    return report, all_pass

Repare que o prompt é lido a partir de um ficheiro em vez de ser escrito diretamente no script. É isto que torna o acionamento possível: uma versão do prompt com controlo de versões no repositório produz um diff, e um diff pode acionar uma avaliação. Enquanto os seus prompts existirem como literais de string dispersos pelo código da sua aplicação, a automação adequada não é possível.

A configuração declara uma avaliação por tarefa, cada uma com o seu próprio limiar.

{
  "evaluations": [
    {
      "name": "ticket-classification",
      "dataset": "evals/datasets/classification.jsonl",
      "prompt_file": "prompts/classification.txt",
      "model": "gpt-5.6-terra",
      "min_threshold": 0.90
    },
    {
      "name": "resume-generation",
      "dataset": "evals/datasets/resumes.jsonl",
      "prompt_file": "prompts/resume.txt",
      "model": "gpt-5.6-terra",
      "min_threshold": 0.75
    }
  ]
}

A diferença entre estes dois limiares é o cerne do método. A classificação de tickets é uma tarefa fechada: abaixo de 0,90, a funcionalidade não presta o serviço esperado. O resumo é uma tarefa aberta, julgada por palavras-chave que um bom texto pode legitimamente formular de forma diferente; exigir 0,90 bloquearia todas as implementações e levaria rapidamente à desativação da verificação. Calibre cada limiar com base nas pontuações observadas em produção, e não num número redondo que pareça tranquilizador.

Ligar Tudo no GitHub Actions

O fluxo de trabalho é acionado apenas em caminhos relevantes — prompts, avaliações, código de integração de IA — para que uma alteração numa folha de estilos não consuma chamadas à API.

# .github/workflows/eval-ai.yml
name: AI Evaluation

on:
  pull_request:
    paths:
      - "prompts/**"
      - "evals/**"
      - "src/ai/**"

jobs:
  evaluate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - run: pip install openai

      - name: Run evals
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: python evals/run_ci.py

      - name: Publish report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: eval-report
          path: evals/report.md

Dois detalhes merecem atenção. A chave da API passa através dos segredos do repositório, nunca através do ficheiro de fluxo de trabalho, que é legível por qualquer pessoa com acesso ao código. E a publicação do relatório utiliza if: always(), caso contrário o artefacto não seria produzido quando as avaliações falham — que é precisamente o único caso em que precisa de o ler.

O script de entrada une tudo: escreve o relatório no disco para o artefacto, imprime-o nos registos e define o código de saída que permite ou bloqueia o resto do pipeline.

#!/usr/bin/env python3
"""Script de avaliação para CI — evals/run_ci.py"""

import sys
from pathlib import Path

def main():
    config = load_eval_config("evals/config.json")
    results = run_ci_evals(config)
    report, all_pass = ci_report(results)

    # Escrever o relatório
    Path("evals/report.md").write_text(report)
    print(report)

    # Código de saída para CI
    if not all_pass:
        print("\nAlgumas avaliações falharam. Implementação bloqueada.")
        sys.exit(1)
    else:
        print("\nTodas as avaliações foram aprovadas.")
        sys.exit(0)

if __name__ == "__main__":
    main()

Comparar em Vez de Julgar em Termos Absolutos

Um limiar fixo responde à pergunta «Isto é suficientemente bom?». Não responde a «Isto é melhor do que antes?», que é frequentemente a verdadeira questão. Um prompt reescrito pode manter-se acima do limiar enquanto perde três pontos em comparação com a versão anterior: a CI fica verde e a degradação entra em produção sem que ninguém se aperceba.

O teste de regressão executa, portanto, ambas as versões no mesmo conjunto de dados, na mesma campanha, e compara as médias. Uma tolerância de 5% absorve o ruído inerente às saídas generativas; além disso, o veredito é explícito.

def prompt_regression_test(
    current_prompt: str,
    previous_prompt: str,
    dataset: list[dict],
    model: str,
    degradation_threshold: float = 0.05,
) -> dict:
    """Verifica se um novo prompt não degrada o desempenho."""
    scores_current = []
    scores_previous = []

    for case in dataset:
        # Avaliar com o prompt atual
        r1 = client.responses.create(
            model=model, instructions=current_prompt,
            reasoning={"effort": "none"},  # temperature requires effort none
            input=case["input"], temperature=0.0,
        )
        # Avaliar com o prompt anterior
        r2 = client.responses.create(
            model=model, instructions=previous_prompt,
            reasoning={"effort": "none"},  # temperature requires effort none
            input=case["input"], temperature=0.0,
        )

        s1 = evaluate_response(r1.output_text, case)
        s2 = evaluate_response(r2.output_text, case)
        scores_current.append(s1)
        scores_previous.append(s2)

    avg_current = sum(scores_current) / len(scores_current)
    avg_previous = sum(scores_previous) / len(scores_previous)
    delta = avg_current - avg_previous

    return {
        "current_score": avg_current,
        "previous_score": avg_previous,
        "delta": delta,
        "regression": delta < -degradation_threshold,
        "verdict": "OK" if delta >= -degradation_threshold else "REGRESSION",
    }

Este teste duplica o número de chamadas e, consequentemente, o custo e a duração. Reserve-o para alterações de prompts, mantendo-o fora do caminho de commits ordinários, e execute-o num subconjunto representativo em vez de no seu conjunto de dados de referência completo.

Pontos-chave

  • Integre as avaliações no seu pipeline CI/CD como testes unitários
  • Coloque os prompts sob controlo de versões em ficheiros: sem um diff, nenhum acionamento é possível
  • Defina limiares mínimos por tipo de avaliação, calibrados com dados de produção
  • Bloqueie implementações através do código de saída quando as pontuações caírem abaixo dos limiares
  • Teste regressões comparando prompts novos e antigos no mesmo conjunto de dados