Valuta i tuoi prompt: metodi, valutatori e migrazione a Promptfoo
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: Utilizzo di GPT-6 · GPT-5.6 Terra.
Aggiornamento del 2 novembre 2026 — Piattaforma Evals. OpenAI ha annunciato la fine della sua piattaforma Evals: le valutazioni esistenti sono in sola lettura dal 31 ottobre 2026 e la dashboard insieme all’API chiuderanno il 30 novembre 2026, inclusi i valutatori (graders). OpenAI ha pubblicato una guida alla migrazione verso Promptfoo. I principi di valutazione trattati in questa lezione restano validi; cambia solo lo strumento.
Perché devi valutare in modo sistematico
Non puoi migliorare ciò che non misuri. Quando modifichi un prompt, un modello o un parametro, come fai a sapere che la qualità è effettivamente migliorata? Il metodo spontaneo consiste nel provare tre o quattro esempi, trovare le risposte migliori e procedere al deploy. Questo fallisce regolarmente perché gli esempi testati sono proprio quelli che hanno causato problemi la settimana scorsa: misuri il miglioramento dove lo hai cercato, ma ti sfuggono le regressioni introdotte in casi che già funzionavano.
Le valutazioni (evals) trasformano questa intuizione in una misura oggettiva. Fino al 2026, OpenAI offriva una piattaforma integrata per questo scopo, Evals; è in sola lettura dal 31 ottobre 2026 e chiuderà il 30 novembre. OpenAI raccomanda ora Promptfoo, uno strumento open source per la valutazione e il red teaming. La buona notizia è che entrambi condividono gli stessi mattoni fondamentali: dati di test, prompt, modelli e criteri di punteggio. Ciò che impari qui nel codice Python si traduce direttamente, e la parte finale della lezione mostra come passare a Promptfoo.
Tre concetti strutturano l’intero processo. Il dataset è un insieme di casi di test con input e output attesi: è il tuo riferimento, l’equivalente di una suite di test unitari. Il grader (valutatore) è un criterio di valutazione—corrispondenza esatta, LLM come giudice, punteggio—che decide se una data risposta è buona. L’esecuzione (run) è una valutazione eseguita su un dataset con un modello e un prompt specifici; è l’unità che confronti da una versione all’altra.
Costruisci un dataset che rispecchi il mondo reale
Un caso di test è composto da un input, un output atteso e dei metadati. Questi ultimi non sono decorativi: sono ciò che ti permetterà di realizing, a posteriori, che un punteggio complessivo dell’87% nasconde un crollo nella categoria “codice”, compensato da risultati eccellenti in geografia. Senza categoria o difficoltà, hai solo un numero aggregato, e un numero aggregato non ti dice mai dove intervenire.
import json
# Un dataset è una lista di casi di test
dataset = [
{
"input": "What is the capital of France?",
"expected": "Paris",
"metadata": {"category": "geography", "difficulty": "easy"},
},
{
"input": "Explain Bayes' theorem in one sentence.",
"expected": "Bayes' theorem calculates the probability "
"of an event based on known conditional probabilities.",
"metadata": {"category": "mathematics", "difficulty": "medium"},
},
{
"input": "Write a Python function that reverses a list.",
"expected": "def reverse_list(lst): return lst[::-1]",
"metadata": {"category": "code", "difficulty": "easy"},
},
]
# Salva come JSONL
with open("eval_dataset.jsonl", "w") as f:
for case in dataset:
f.write(json.dumps(case, ensure_ascii=False) + "\n")
Un dataset inventato in ufficio valuta la tua immaginazione, non la tua applicazione. I tuoi utenti formulano le loro richieste in modo diverso da te: errori di battitura, domande abbozzate, contesto implicito. La fonte migliore di casi di test sono quindi i tuoi dati di produzione, a condizione che un umano convalidi le risposte di riferimento; altrimenti, congeli gli errori attuali trasformandoli nella norma.
import openai
import random
client = openai.OpenAI()
def create_dataset_from_logs(
production_logs: list[dict],
sample_size: int = 100,
) -> list[dict]:
"""Crea un dataset di valutazione dai log di produzione."""
# Campionamento
sample = random.sample(
production_logs,
min(sample_size, len(production_logs)),
)
dataset = []
for log in sample:
dataset.append({
"input": log["prompt"],
"expected": log["validated_response"], # Risposta convalidata da un umano
"metadata": {
"source": "production",
"date": log["date"],
"original_model": log["model"],
},
})
return dataset
Scegli il grader giusto
Il grader a corrispondenza esatta (exact match) è il più severo e veloce. Si adatta solo a compiti dove l’output è vincolato: una classificazione in tre categorie, l’estrazione di un numero di fattura, una risposta sì o no. Usato su testo libero, darebbe zero a una risposta perfetta semplicemente formulata in modo diverso rispetto al riferimento.
def exact_grader(response: str, expected: str) -> dict:
"""Valuta se la risposta corrisponde esattamente."""
score = 1.0 if response.strip().lower() == expected.strip().lower() else 0.0
return {"score": score, "type": "exact"}
Il grader per inclusione allenta il vincolo: verifica la presenza di parole chiave attese e restituisce un punteggio parziale. Questo è lo strumento giusto per risposte che devono coprire punti obbligatori senza che la formulazione conti—una risposta di supporto che deve menzionare il periodo di recesso e l’indirizzo di reso, ad esempio. La sua debolezza è nota: un testo contenente le parole giuste in un ordine assurdo otterrebbe un punteggio perfetto.
def inclusion_grader(response: str, keywords: list[str]) -> dict:
"""Verifica che la risposta contenga le parole chiave attese."""
response_lower = response.lower()
found = sum(1 for word in keywords if word.lower() in response_lower)
score = found / len(keywords) if keywords else 0.0
return {
"score": score,
"found": found,
"total": len(keywords),
"type": "inclusion",
}
Poi c’è il più potente: un altro LLM valuta la qualità della risposta. Il grader LLM-as-Judge apprezza ciò che nessuna regola meccanica può cogliere: chiarezza, completezza, accuratezza del tono. Due dettagli implementativi lo rendono pratico. Primo, temperature=0.0: senza questo, lo stesso giudice assegnerebbe punteggi diversi alla stessa risposta da un’esecuzione all’altra, e il tuo benchmark perderebbe ogni valore comparativo. Secondo, il fallback per json.JSONDecodeError: un giudice che commenta invece di restituire JSON non dovrebbe far crashare l’intera campagna.
def llm_judge_grader(
question: str,
response: str,
expected: str,
criteria: str = "accuracy, completeness, clarity",
) -> dict:
"""Utilizza un LLM per valutare la qualità della risposta."""
judge_prompt = f"""Rate the quality of this response on a scale of 1 to 5.
Question: {question}
Expected Response: {expected}
Response to Evaluate: {response}
Criteria: {criteria}
Respond ONLY with JSON:
{{"score": <1-5>, "justification": "<short explanation>"}}"""
response_obj = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature richiede effort none
input=judge_prompt,
temperature=0.0,
)
import json
try:
result = json.loads(response_obj.output_text)
result["normalized_score"] = result["score"] / 5.0
return result
except json.JSONDecodeError:
return {"score": 0, "justification": "Parsing error", "normalized_score": 0}
Assembla la valutazione completa
L’orchestrazione non presenta difficoltà concettuali: iteri attraverso il dataset, chiami il modello con il prompt di sistema da testare, applichi il grader e aggregi i risultati. Il punto interessante è che la funzione di punteggio arriva come parametro, il che ti permette di rieseguire lo stesso identico dataset con criteri diversi a seconda della campagna—inclusione per un controllo rapido durante lo sviluppo, giudice LLM per la convalida prima della produzione.
async def run_eval(
dataset: list[dict],
model: str,
system_prompt: str,
grader_fn,
) -> dict:
"""Esegue una valutazione completa su un dataset."""
results = []
for case in dataset:
response = client.responses.create(
model=model,
instructions=system_prompt,
input=case["input"],
)
score = grader_fn(response.output_text, case["expected"])
results.append({
"input": case["input"],
"expected": case["expected"],
"obtained": response.output_text,
**score,
})
# Calcola le metriche aggregate
scores = [r["score"] for r in results if "score" in r]
return {
"model": model,
"num_cases": len(dataset),
"average_score": sum(scores) / len(scores) if scores else 0,
"min_score": min(scores) if scores else 0,
"max_score": max(scores) if scores else 0,
"results": results,
}
Il report mantiene min_score e il dettaglio di ogni caso, ed è deliberato. La media ti dice se stai facendo progressi; i casi con il punteggio peggiore ti dicono perché. Prendi l’abitudine di leggere le cinque risposte peggiori di ogni esecuzione prima di commentare la media: è lì, e raramente altrove, che troverai la prossima correzione da apportare.
Industrializza con Promptfoo
Scrivere le tue evals a mano in Python è educativo; mantenerle nel tempo è più comodo con uno strumento dedicato. La guida alla migrazione di OpenAI descrive la logica di Promptfoo: la valutazione risiede in un file di configurazione, promptfooconfig.yaml, che riunisce prompt, modello/i, casi di test e criteri—chiamati qui asserzioni. Si esegue da riga di comando, localmente o nella tua integrazione continua, e vive accanto al codice dell’applicazione.
description: Support ticket classification
prompts:
- "Classify this ticket into a single category (billing, technical, account): {{ticket}}"
providers:
- openai:gpt-6.1-sol
tests:
- vars:
ticket: "My card was charged twice this month."
assert:
- type: icontains
value: billing
- vars:
ticket: "The app crashes when I open a PDF."
assert:
- type: icontains
value: technical
promptfoo eval -c promptfooconfig.yaml --no-cache
promptfoo view
promptfoo validate config -c promptfooconfig.yaml # in caso di errore di configurazione
I grader di questa lezione riappaiono come asserzioni: corrispondenza esatta, inclusione di parole chiave e giudizio del modello. OpenAI avverte sull’ultimo punto: un grader ricreato, specialmente un giudice LLM, deve essere riconvalidato prima di essere usato per decidere su una regressione, perché i punteggi non saranno necessariamente identici da uno strumento all’altro.
Punti chiave
- Le evals trasformano l’intuizione in una misura oggettiva della qualità
- Crea i tuoi dataset da casi reali di produzione, convalidati da un umano
- Scegli il grader in base al compito: esatto per vincoli stretti, inclusione per punti obbligatori, LLM-as-Judge per le sfumature
- Imposta
temperature=0.0sul giudice per rendere i punteggi riproducibili - Esegui le evals prima di ogni modifica al prompt o al modello
- La piattaforma Evals di OpenAI chiude il 30 novembre 2026: Promptfoo, raccomandato da OpenAI, prende il sopravvento su dataset, prompt, modelli e criteri in un file di configurazione