Vai al contenuto principale
Italiano— Scegli una lingua
Menu

CI/CD per l'IA: Valutazioni Automatizzate

Lezione 18 di 20 Aggiornata il 3 novembre 2026 Avanzato
In questa pagina
  1. Integrare le valutazioni nella tua pipeline CI/CD
  2. Il principio: un gate, non un report
  3. Collegare il tutto in GitHub Actions
  4. Confronta invece di giudicare in termini assoluti
  5. Punti chiave

Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI: temperature e top_p sono accettati solo con uno sforzo di ragionamento pari a none, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificare reasoning={"effort": "none"} (API Responses) o reasoning_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