CI/CD per l'IA: Valutazioni Automatizzate
In questa pagina
Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI:
temperatureetop_psono accettati solo con uno sforzo di ragionamento pari anone, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificarereasoning={"effort": "none"}(API Responses) oreasoning_effort="none"(Chat Completions). Fonti: Using GPT-6 · GPT-5.6 Terra.
Integrare le valutazioni nella tua pipeline CI/CD
Distribuire una modifica al prompt in produzione senza valutazione è come distribuire codice senza test. Il paragone è più accurato di quanto sembri: in entrambi i casi, la modifica sembra banale, è stata verificata manualmente su uno o due esempi e l’effetto collaterale si manifesta tre giorni dopo per un utente che non te lo dirà mai. La differenza è che una regressione del prompt non genera un’eccezione: l’applicazione continua a rispondere, semplicemente peggio.
L’obiettivo è rendere la valutazione automatizzata un gate obbligatorio nel tuo processo di distribuzione, garantendo che ogni modifica mantenga o migliori la qualità. È esattamente ciò che affronteremo ora.
Il principio: un gate, non un report
La pipeline di valutazione si integra nel tuo flusso di distribuzione utilizzando un meccanismo familiare. Uno sviluppatore modifica un prompt o un parametro, il commit attiva la pipeline CI e le valutazioni vengono eseguite automaticamente sul dataset di riferimento. Se i punteggi soddisfano le soglie, la distribuzione prosegue; altrimenti, viene bloccata, con un report dettagliato che indica quale valutazione è fallita e di quanto.
Il punto critico è proprio questo comportamento di blocco. Una CI che produce un bel report senza fermare la pipeline diventa un artefatto che nessuno controlla dopo due settimane. Solo un codice di uscita diverso da zero trasforma la misurazione in una barriera di sicurezza.
Lo script seguente legge una configurazione, carica ogni dataset, esegue i casi e confronta il punteggio medio con la soglia dichiarata. Il metodo di punteggio — la semplice inclusione di parole chiave — è intenzionalmente rudimentale: un controllo CI deve essere veloce, deterministico e indipendente da un giudice il cui punteggio potrebbe variare da un’esecuzione all’altra.
import json
import sys
import openai
from pathlib import Path
client = openai.OpenAI()
def load_eval_config(path: str = "evals/config.json") -> dict:
"""Carica la configurazione di valutazione."""
with open(path) as f:
return json.load(f)
def load_dataset(path: str) -> list[dict]:
"""Carica un dataset 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:
"""Esegue le valutazioni per la 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 richiede effort none
instructions=prompt,
input=case["input"],
temperature=0.0,
)
# Valutazione semplice per inclusione di parole chiave
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 # Nessun criterio specifico
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]:
"""Genera un report per la CI e indica se è OK."""
lines = ["# Report di Valutazione AI\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"(soglia: {r['threshold']:.0%}, {r['num_cases']} casi)"
)
report = "\n".join(lines)
return report, all_pass
Nota che il prompt viene letto da un file anziché essere scritto direttamente nello script. È questo che rende possibile l’attivazione: un prompt versionato nel repository produce un diff e un diff può attivare una valutazione. Finché i tuoi prompt vivono come stringhe letterali sparse nel codice della tua applicazione, una corretta automazione non è possibile.
La configurazione dichiara una valutazione per compito, ciascuna con la propria soglia.
{
"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
}
]
}
Il divario tra queste due soglie è il cuore del metodo. La classificazione dei ticket è un compito chiuso: sotto 0,90, la funzionalità non eroga il servizio atteso. La generazione di riassunti è un compito aperto, giudicato su parole chiave che un buon testo potrebbe legittimamente formulare in modo diverso; richiedere 0,90 bloccherebbe ogni distribuzione e porterebbe rapidamente a disattivare il controllo. Calibra ogni soglia in base ai punteggi osservati in produzione piuttosto che su un numero tondo che sembra rassicurante.
Collegare il tutto in GitHub Actions
Il workflow si attiva solo su percorsi rilevanti — prompt, valutazioni, codice di integrazione AI — così una modifica al foglio di stile non consuma chiamate 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
Due dettagli meritano attenzione. La chiave API passa attraverso i segreti del repository, mai attraverso il file del workflow, che è leggibile da chiunque abbia accesso al codice. E la pubblicazione del report usa if: always(), altrimenti l’artefatto non verrebbe prodotto quando le valutazioni falliscono — che è proprio l’unico caso in cui hai bisogno di leggerlo.
Lo script di ingresso mette insieme il tutto: scrive il report su disco per l’artefatto, lo stampa nei log e imposta il codice di uscita che consente o blocca il resto della pipeline.
#!/usr/bin/env python3
"""Script di valutazione per 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)
# Scrive il report
Path("evals/report.md").write_text(report)
print(report)
# Codice di uscita per CI
if not all_pass:
print("\nAlcune valutazioni sono fallite. Distribuzione bloccata.")
sys.exit(1)
else:
print("\nTutte le valutazioni sono superate.")
sys.exit(0)
if __name__ == "__main__":
main()
Confronta invece di giudicare in termini assoluti
Una soglia fissa risponde alla domanda «È abbastanza buono?». Non risponde a «È meglio di prima?», che è spesso la vera domanda. Un prompt riscritto può rimanere sopra la soglia perdendo però tre punti rispetto alla versione precedente: la CI diventa verde e il degrado entra in produzione senza che nessuno se ne accorga.
Il test di regressione esegue quindi entrambe le versioni sullo stesso dataset, nella stessa campagna, e confronta le medie. Una tolleranza del 5% assorbe il rumore intrinseco agli output generativi; oltre tale limite, il verdetto è esplicito.
def prompt_regression_test(
current_prompt: str,
previous_prompt: str,
dataset: list[dict],
model: str,
degradation_threshold: float = 0.05,
) -> dict:
"""Verifica che un nuovo prompt non degradi le prestazioni."""
scores_current = []
scores_previous = []
for case in dataset:
# Valuta con il prompt corrente
r1 = client.responses.create(
model=model, instructions=current_prompt,
reasoning={"effort": "none"}, # temperature richiede effort none
input=case["input"], temperature=0.0,
)
# Valuta con il prompt precedente
r2 = client.responses.create(
model=model, instructions=previous_prompt,
reasoning={"effort": "none"}, # temperature richiede 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",
}
Questo test raddoppia il numero di chiamate e, di conseguenza, i costi e la durata. Riservalo alle modifiche dei prompt, tenendolo fuori dal percorso dei commit ordinari, ed eseguilo su un sottoinsieme rappresentativo anziché sull’intero dataset di riferimento.
Punti chiave
- Integra le valutazioni nella tua pipeline CI/CD come test unitari
- Versiona i prompt in file: senza un diff, nessuna attivazione è possibile
- Definisci soglie minime per tipo di valutazione, calibrate sui dati di produzione
- Blocca le distribuzioni tramite codice di uscita quando i punteggi scendono sotto le soglie
- Testa le regressioni confrontando prompt nuovi e vecchi sullo stesso dataset