CI/CD para IA: Avaliações Automatizadas
Nesta página
Lição atualizada em 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.
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