Valutazione Automatica dei Prompt
In questa pagina
Lezione aggiornata il 3 novembre 2026 in base alla 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: Utilizzo di GPT-6 · GPT-5.6 Terra.
Valutazione Automatica dei Prompt
La valutazione automatica è la pietra angolare di una pipeline matura di ingegneria dei prompt. Ti permette di rilevare regressioni, confrontare modelli e convalidare le modifiche prima del deployment. Senza di essa, ogni modifica al prompt è una scommessa alla cieca.
Tipi di Valutazione
Tre famiglie di valutatori si dividono il lavoro in base alla natura dell’output atteso e quasi sempre ne combinerai diversi.
Valutazione per Corrispondenza Esatta
Per compiti con una singola risposta attesa, il confronto diretto è sufficiente. eval_exact_match normalizza maiuscole/minuscole e spazi bianchi prima del confronto: senza questa precauzione, “Bug” e “bug” verrebbero contati come errori, spingendoti a risolvere un problema inesistente.
eval_set_match gestisce i casi in cui la risposta è un insieme: entità trovate in un documento, categorie assegnate a un articolo. Deriva precisione e richiamo, due cifre che raccontano storie diverse: alta precisione con basso richiamo segnala un modello eccessivamente cauto che estrae solo ciò di cui è sicuro; il contrario tradisce un modello che allucina per colmare le lacune. F1 le riassume comodamente ma non le sostituisce per la diagnosi.
def eval_exact_match(prediction: str, reference: str) -> bool:
"""Corrispondenza esatta dopo normalizzazione."""
return prediction.strip().lower() == reference.strip().lower()
def eval_set_match(prediction: set, reference: set) -> dict:
"""Corrispondenza di insiemi (entità, categorie)."""
tp = len(prediction & reference)
fp = len(prediction - reference)
fn = len(reference - prediction)
precision = tp / (tp + fp) if (tp + fp) > 0 else 0
recall = tp / (tp + fn) if (tp + fn) > 0 else 0
f1 = (2 * precision * recall / (precision + recall)
if (precision + recall) > 0 else 0)
return {"precision": precision, "recall": recall, "f1": f1}
Valutazione Semantica (Embedding)
Per le risposte testuali dove la formulazione può variare, la corrispondenza esatta diventa assurda: “Il tuo ordine sarà consegnato domani” e “La consegna è prevista per domani” dicono la stessa cosa ma otterrebbero punteggio zero. La similarità del coseno tra embedding misura la prossimità semantica piuttosto che la corrispondenza carattere per carattere, restituendo un punteggio continuo.
Imposti la soglia oltre la quale una risposta è considerata accettabile. Calibrala su alcune decine di coppie che hai classificato manualmente come “equivalenti” o “diverse”, poi scegli il valore che separa meglio i due gruppi: una soglia scelta a sensazione produce risultati arbitrari quanto nessuna misurazione, con l’illusione aggiuntiva del rigore.
from openai import OpenAI
import numpy as np
client = OpenAI()
def eval_semantic_similarity(prediction: str,
reference: str) -> float:
"""Similarità del coseno tra embedding."""
response = client.embeddings.create(
model="text-embedding-3-large",
input=[prediction, reference]
)
emb_pred = np.array(response.data[0].embedding)
emb_ref = np.array(response.data[1].embedding)
similarity = float(
np.dot(emb_pred, emb_ref) /
(np.linalg.norm(emb_pred) * np.linalg.norm(emb_ref))
)
return similarity
Valutazione LLM (LLM-as-Judge)
Il modello valuta la qualità di una risposta. Questo è l’unico approccio praticabile quando non esiste un riferimento: nessuno scriverà a mano la risposta di supporto “corretta” per duecento ticket.
Ciò che rende un giudice utilizzabile si riduce a poche cose. Primo, il modello utilizzato: scegli un modello più capace come giudice, qui gpt-5.6-sol, perché un giudice allo stesso livello del valutato tende a convalidare i propri difetti. Secondo, richiedere una giustificazione: motivare ogni punteggio stabilizza il giudizio e ti permette di individuare un valutatore che usa il criterio sbagliato: una giustificazione che discute la lunghezza quando il criterio era la chiarezza è un campanello d’allarme. Infine, temperature a 0.1 garantisce la stabilità del punteggio tra le esecuzioni.
def eval_llm_judge(question: str, prediction: str,
criteria: list[str]) -> dict:
"""Valutazione da parte di un modello giudice."""
criteria_text = "\n".join(
f"- {c}: punteggio da 1 a 5" for c in criteria
)
response = client.responses.create(
model="gpt-5.6-sol", # Modello più capace come giudice
reasoning={"effort": "none"}, # temperature richiede effort none
instructions="Sei un valutatore esperto e imparziale.",
input=f"""Valuta questa risposta secondo i seguenti criteri:
Domanda posta: {question}
Risposta da valutare: {prediction}
Criteri:
{criteria_text}
Per ogni criterio, assegna un punteggio da 1 a 5 con giustificazione.""",
text={
"format": {
"type": "json_schema",
"name": "evaluation",
"schema": {
"type": "object",
"properties": {
"scores": {
"type": "array",
"items": {
"type": "object",
"properties": {
"criterion": {"type": "string"},
"score": {"type": "integer"},
"justification": {"type": "string"}
},
"required": ["criterion", "score",
"justification"],
"additionalProperties": False
}
},
"overall_score": {"type": "number"},
"verdict": {"type": "string"}
},
"required": ["scores", "overall_score", "verdict"],
"additionalProperties": False
},
"strict": True
}
},
temperature=0.1
)
return json.loads(response.output_text)
Pipeline di Valutazione Completa
EvalPipeline assembla questi mattoni: carica una suite di test, esegue il prompt su ogni caso, applica tutti i valutatori forniti e aggrega i punteggi. I valutatori vengono passati come lista di funzioni, tutte chiamate con la stessa firma; aggiungere una metrica non richiede quindi alcuna modifica alla pipeline e puoi eseguire corrispondenza esatta, similarità semantica e un giudice sulla stessa esecuzione senza pagare tre volte la generazione.
Il metodo summary accumula anche i token consumati. Questa riga apparentemente secondaria ti protegge da una trappola comune: una versione del prompt che guadagna due punti punteggio mentre triplica la fattura non è necessariamente la scelta giusta, ed è meglio scoprirlo al momento del compromesso piuttosto che quando arriva la fattura mensile.
import json
from dataclasses import dataclass
from pathlib import Path
@dataclass
class TestCase:
"""Un caso di test per la valutazione."""
input_text: str
expected_output: str = None
metadata: dict = None
class EvalPipeline:
"""Pipeline di valutazione automatica."""
def __init__(self, test_suite_path: str):
"""Carica la suite di test da un file JSON."""
data = json.loads(Path(test_suite_path).read_text())
self.test_cases = [TestCase(**tc) for tc in data]
self.results = []
def run(self, prompt_config: dict,
evaluators: list[callable]) -> dict:
"""Esegue tutti i test e valuta i risultati."""
self.results = []
for tc in self.test_cases:
# Genera risposta
response = client.responses.create(
model=prompt_config["model"],
reasoning={"effort": "none"}, # temperature richiede effort none
instructions=prompt_config["system_prompt"],
input=tc.input_text,
temperature=prompt_config.get("temperature", 0.1)
)
prediction = response.output_text
# Valuta con ogni valutatore
scores = {}
for evaluator in evaluators:
score = evaluator(
question=tc.input_text,
prediction=prediction,
reference=tc.expected_output
)
scores[evaluator.__name__] = score
self.results.append({
"input": tc.input_text,
"expected": tc.expected_output,
"prediction": prediction,
"scores": scores,
"tokens": {
"input": response.usage.input_tokens,
"output": response.usage.output_tokens
}
})
return self.summary()
def summary(self) -> dict:
"""Riassume i risultati della valutazione."""
if not self.results:
return {"error": "Nessun risultato"}
# Aggrega i punteggi per valutatore
all_scores = {}
for result in self.results:
for eval_name, score in result["scores"].items():
if eval_name not in all_scores:
all_scores[eval_name] = []
if isinstance(score, (int, float)):
all_scores[eval_name].append(score)
elif isinstance(score, dict) and "f1" in score:
all_scores[eval_name].append(score["f1"])
summary = {
"total_tests": len(self.results),
"average_scores": {
name: sum(scores) / len(scores)
for name, scores in all_scores.items()
if scores
},
"total_token_cost": sum(
r["tokens"]["input"] + r["tokens"]["output"]
for r in self.results
)
}
return summary
Suite di Test: Formato
Il formato della suite di test rimane intenzionalmente minimale: un input, l’output atteso e metadati a forma libera. Questi metadati sono più utili di quanto sembri: taggando ogni caso per categoria, scomponi i punteggi e scopri che il tuo classificatore non fallisce a caso ma su una specifica famiglia di richieste, cosa che una media globale dell’88% non rivela. I tre esempi seguenti mostrano anche cosa dovrebbe contenere una buona suite: casi chiari, come un crash all’avvio, ma anche casi che sfiorano un’altra categoria: una domanda su una funzionalità mancante assomiglia molto a un report di bug, ed è su questo confine che si decide la qualità di un classificatore.
[
{
"input_text": "Il mio pacco non è arrivato",
"expected_output": "reclamo",
"metadata": {"category": "consegna"}
},
{
"input_text": "Come attivo la modalità scura?",
"expected_output": "domanda",
"metadata": {"category": "funzionalità"}
},
{
"input_text": "L'app crasha all'avvio su iOS 18",
"expected_output": "bug",
"metadata": {"category": "tecnico"}
}
]
Integrazione CI/CD
Esegui la valutazione ad ogni modifica del prompt. La funzione ci_eval_check trasforma la misurazione in una guardia: esegue la pipeline, confronta il punteggio medio con una soglia e restituisce un booleano che la tua catena di integrazione interpreta come successo o fallimento della build. Una modifica che fa scendere la precisione sotto l’85% non raggiunge più la produzione, proprio come un unit test rotto blocca un merge.
Imposta la soglia in base al punteggio già raggiunto dalla versione corrente, non da un ideale. Impostala troppo alta e condanni il team a bypassare la verifica con disattivazioni temporanee che diventano permanenti; impostala troppo bassa e non stai controllando nulla mentre esponi un badge verde. Infine, tieni presente che la suite deve rimanere rappresentativa del traffico reale: una soglia soddisfatta su venti casi scritti due anni fa non prova nulla sulle richieste di oggi.
def ci_eval_check(prompt_config: dict,
test_suite: str,
min_score: float = 0.85) -> bool:
"""Gate CI/CD: verifica che il prompt raggiunga il punteggio minimo."""
pipeline = EvalPipeline(test_suite)
def accuracy(question, prediction, reference):
return 1.0 if prediction.strip().lower() == reference.strip().lower() else 0.0
results = pipeline.run(prompt_config, [accuracy])
avg_score = results["average_scores"].get("accuracy", 0)
print(f"Punteggio medio: {avg_score:.2%}")
print(f"Soglia minima: {min_score:.2%}")
if avg_score < min_score:
print("FALLIMENTO: punteggio sotto la soglia")
return False
print("SUCCESSO: prompt convalidato")
return True
Dashboard di Valutazione
Traccia l’evoluzione del punteggio nel tempo. Un singolo punteggio non dice nulla; la serie racconta la storia del tuo prompt e risponde alla domanda che emerge sempre nelle riunioni: stiamo facendo progressi? La funzione seguente produce una tabella Markdown che affianca, per ogni versione, il punteggio medio, i token consumati e il costo stimato. Il formato non è casuale: si incolla direttamente in una pull request, rendendo il confronto leggibile per persone che non apriranno mai il tuo codice.
def comparison_report(results: dict[str, dict]) -> str:
"""Genera un report comparativo tra versioni di prompt."""
report = "# Report di Valutazione Comparativa\n\n"
report += "| Versione | Punteggio Medio | Token Medi | Costo |\n"
report += "|---------|---------------|----------------|------|\n"
for version, data in results.items():
score = data.get("average_scores", {})
score_val = list(score.values())[0] if score else 0
tokens = data.get("total_token_cost", 0)
report += (f"| {version} | {score_val:.2%} | "
f"{tokens} | ${tokens * 5 / 1e6:.4f} |\n")
return report
Configura le Tue Guardie
Costruisci una suite di venti casi di test per un prompt reale, inserendo una manciata di casi limite piuttosto che venti esempi comodi: una suite che passa al 100% al primo tentativo non ti insegna nulla. Implementa i tre tipi di valutatore ed eseguili insieme su due versioni del tuo prompt. La corrispondenza esatta dà un numero pulito, la similarità semantica cattura riformulazioni legittime e il giudice illumina i casi in cui i primi due sono in disaccordo: questi disaccordi sono i più ricchi di lezioni su ciò che ti aspetti realmente dal modello.
Confronta, identifica la versione vincente, poi configura lo script CI che blocca il deployment se il punteggio scende. Saprai che il sistema funziona il giorno in cui rifiuta una modifica che pensavi fosse ovvia.
Punti chiave
- La valutazione automatica è essenziale per iterare con fiducia
- Combina valutazione esatta, semantica e LLM-as-judge secondo necessità
- Mantieni una suite di test che evolve con la tua applicazione
- Integra la valutazione nel tuo CI/CD con una soglia minima
- Usa un modello più capace come giudice per valutare un modello più economico
- Documenta i punteggi di ogni versione per tracciarne l’evoluzione
Metti alla Prova le Tue Conoscenze
Tecniche avanzate e industrializzazione: il controllo finale.
1. Cosa contiene un system prompt efficace?
Risposta: Ruolo, ambito, regole di comportamento, formato di output e gestione dei casi limite: scritto come una specifica, testato come codice.
2. Quando dovresti usare la self-consistency?
Risposta: Su problemi di ragionamento con risposte verificabili: genera più ragionamenti indipendenti e mantieni la risposta di maggioranza: la varianza diventa un’alleata.
3. Cosa garantisce la modalità JSON con enforcement dello schema?
Risposta: Output strettamente conforme allo schema (tipi, campi obbligatori, enum): convalidato lato API e riconvalidato nel codice (JSON Schema, Zod) per una catena senza sorprese.
4. Cos'è il grounding?
Risposta: Ancorare le risposte a fatti forniti (documenti, dati recuperati) piuttosto che alla memoria del modello: con il requisito di citare o astenersi da fonti esterne.
5. Qual è lo scopo di un catalogo di prompt versionati?
Risposta: Trattare i prompt come artefatti: versioni, test A/B, valutazioni automatiche ad ogni modifica: sai cosa gira in produzione e perché.
Il ciclo finale del corso: versiona, testa, valuta automaticamente, trasforma l’ingegneria dei prompt artigianale in una pratica di team.