Versionamento dei prompt e gestione del catalogo
In questa pagina
Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI:
temperatureetop_psono accettati solo con uno sforzo di ragionamento (reasoning effort) impostato sunone, 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.
Versionamento dei prompt e gestione del catalogo
In produzione, i tuoi prompt evolvono tanto quanto il tuo codice. Senza versionamento, perdi il controllo delle modifiche, non puoi eseguire rollback e non hai idea di quale versione sia in esecuzione in produzione. Questa lezione ti mostra come gestire i prompt come artefatti software.
Perché versionare i prompt
Una modifica al prompt può alterare radicalmente il comportamento della tua applicazione. A differenza del codice, queste modifiche sono spesso sottili e difficili da rilevare senza test automatizzati: una frase riformulata, una parola spostata, e il modello inizia a classificare male un caso su dieci ai margini. Nessun test unitario standard rileverà questa discrepanza, ma il supporto tecnico la segnalerà tre settimane dopo come una vaga lamentela sui ticket instradati male.
Il versionamento risponde a quattro esigenze distinte. Primo, la tracciabilità: sapere chi ha cambiato cosa e quando trasforma un dibattito sterile in team in una semplice verifica storica. Secondo, il rollback: quando emerge una regressione, l’obiettivo immediato non è capire il perché, ma ripristinare un comportamento noto. Terzo, il confronto delle prestazioni: ciò richiede che le versioni precedenti rimangano eseguibili esattamente come erano, con il loro modello e le loro impostazioni originali. Infine, l’audit: per i sistemi soggetti al GDPR (Regolamento Generale sulla Protezione dei Dati) o ad altri framework di conformità, devi dimostrare quali istruzioni erano in vigore in una data specifica; uno screenshot non è sufficiente.
Struttura del catalogo
La classe PromptCatalog soddisfa queste esigenze con un’infrastruttura minima: una cartella per prompt, un file JSON per versione, numerati sequenzialmente. Ogni file raggruppa il testo del prompt di sistema insieme al modello e alla temperatura associati: un prompt ottimizzato a 0.1 e lo stesso prompt a 0.7 non sono la stessa cosa, e bloccarli insieme impedisce di ripristinare il testo dimenticando le sue impostazioni.
Il campo status traccia il ciclo di vita. Una versione inizia come draft, consentendo preparazione e test senza influenzare il traffico live. Chiamare activate la sposta su active e declassa automaticamente la versione precedente a deprecated, garantendo che solo una versione serva il traffico in qualsiasi momento. Questo metodo rende il rollback banale: riattivare una versione precedente è una singola chiamata, non un deployment. La tua applicazione chiama get_active in produzione, mentre list_versions supporta revisioni e audit.
import json
from datetime import datetime
from pathlib import Path
class PromptCatalog:
"""Gestore del catalogo dei prompt con versionamento."""
def __init__(self, catalog_dir: str = "prompts/"):
self.catalog_dir = Path(catalog_dir)
self.catalog_dir.mkdir(parents=True, exist_ok=True)
def save_prompt(self, name: str, system_prompt: str,
model: str, temperature: float,
metadata: dict = None) -> str:
"""Salva una nuova versione di un prompt."""
prompt_dir = self.catalog_dir / name
prompt_dir.mkdir(exist_ok=True)
# Determina il numero di versione
versions = sorted(prompt_dir.glob("v*.json"))
version = len(versions) + 1
version_str = f"v{version:03d}"
# Salva
prompt_data = {
"name": name,
"version": version_str,
"created_at": datetime.now().isoformat(),
"model": model,
"temperature": temperature,
"system_prompt": system_prompt,
"metadata": metadata or {},
"status": "draft" # draft | active | deprecated
}
filepath = prompt_dir / f"{version_str}.json"
filepath.write_text(json.dumps(prompt_data, indent=2,
ensure_ascii=False))
return version_str
def get_prompt(self, name: str,
version: str = "latest") -> dict:
"""Recupera un prompt per nome e versione."""
prompt_dir = self.catalog_dir / name
if version == "latest":
versions = sorted(prompt_dir.glob("v*.json"))
if not versions:
raise FileNotFoundError(f"Prompt '{name}' non trovato")
filepath = versions[-1]
else:
filepath = prompt_dir / f"{version}.json"
return json.loads(filepath.read_text())
def get_active(self, name: str) -> dict:
"""Recupera la versione attiva di un prompt."""
prompt_dir = self.catalog_dir / name
for filepath in sorted(prompt_dir.glob("v*.json"),
reverse=True):
data = json.loads(filepath.read_text())
if data["status"] == "active":
return data
raise FileNotFoundError(
f"Nessuna versione attiva per '{name}'"
)
def activate(self, name: str, version: str):
"""Attiva una versione e disattiva le altre."""
prompt_dir = self.catalog_dir / name
for filepath in prompt_dir.glob("v*.json"):
data = json.loads(filepath.read_text())
if data["version"] == version:
data["status"] = "active"
elif data["status"] == "active":
data["status"] = "deprecated"
filepath.write_text(json.dumps(data, indent=2,
ensure_ascii=False))
def list_versions(self, name: str) -> list[dict]:
"""Elenca tutte le versioni di un prompt."""
prompt_dir = self.catalog_dir / name
versions = []
for filepath in sorted(prompt_dir.glob("v*.json")):
data = json.loads(filepath.read_text())
versions.append({
"version": data["version"],
"status": data["status"],
"created_at": data["created_at"],
"model": data["model"]
})
return versions
Utilizzo del catalogo nella tua applicazione
Dal lato del chiamante, la regola è semplice: il tuo codice non contiene testo del prompt; richiede la versione attiva dal catalogo. Questo mantiene i prompt modificabili senza toccare il codice dell’applicazione e impedisce che stringhe di trenta righe finiscano sepolte nel mezzo di una funzione. I metadati salvati durante l’archiviazione (autore, descrizione, changelog) non hanno effetto sull’esecuzione, ma rendono la storia leggibile sei mesi dopo, quando nessuno ricorda più perché la formulazione è cambiata.
Il dettaglio critico si trova alla fine di classifier_ticket: la risposta restituita include prompt_version. Registra questo campo con ogni risultato e l’analisi degli incidenti diventa possibile: saprai che i ticket classificati male del martedì pomeriggio provenivano tutti dalla v004, senza dover incrociare i timestamp di deployment.
from openai import OpenAI
client = OpenAI()
catalog = PromptCatalog("prompts/")
# Salva un prompt
catalog.save_prompt(
name="ticket-classifier",
system_prompt="""Sei un classificatore di ticket di supporto.
Categorizza ogni ticket come: bug, feature, question, billing.
Rispondi in JSON con category, priority (1-5), summary.""",
model="gpt-5.6-terra",
temperature=0.1,
metadata={
"author": "marie.dupont",
"description": "Classificazione automatica dei ticket Zendesk",
"changelog": "Versione iniziale"
}
)
# In produzione: usa la versione attiva
def classifier_ticket(ticket_text: str) -> dict:
"""Classifica un ticket utilizzando il prompt attivo."""
prompt_config = catalog.get_active("ticket-classifier")
response = client.responses.create(
model=prompt_config["model"],
reasoning={"effort": "none"}, # temperature richiede effort none
instructions=prompt_config["system_prompt"],
input=ticket_text,
temperature=prompt_config["temperature"]
)
return {
"result": json.loads(response.output_text),
"prompt_version": prompt_config["version"]
}
Versionamento con Git
Per i team, archivia i tuoi prompt in un repository Git dedicato. L’albero seguente segue una semplice convenzione: una cartella per prompt, contenente la sua definizione, i casi di test e il changelog. Mantenere i test accanto al prompt che verificano non è estetico: una pull request modifica entrambi insieme e il revisore giudica la modifica sulle prove piuttosto che sull’intento dichiarato.
prompts/
ticket-classifier/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
invoice-extractor/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
YAML sostituisce JSON qui per una ragione specifica: i prompt sono testi multilinea e la sintassi | li visualizza esattamente come inviati, senza caratteri di escape o \n stray. Una diff Git su questo file si legge come una diff in prosa: il revisore vede che è stata aggiunta una frase. Lo schema di output viaggia nello stesso file, quindi l’intera configurazione per una chiamata sta in un singolo artefatto.
# prompts/ticket-classifier/prompt.yaml
name: ticket-classifier
model: gpt-5.6-terra
temperature: 0.1
max_output_tokens: 500
system_prompt: |
Sei un classificatore di ticket di supporto.
Categorizza ogni ticket come: bug, feature, question, billing.
Rispondi in JSON con category, priority (1-5), summary.
schema:
type: object
properties:
category:
type: string
enum: [bug, feature, question, billing]
priority:
type: integer
summary:
type: string
required: [category, priority, summary]
additionalProperties: false
Best practices
Ciò che separa un catalogo vivo da una cartella archivio si riduce a poche regole di manutenzione. Mantieni un prompt per file: mescolare più prompt in un singolo documento rende le diff illeggibili e i rollback impossibili da mirare. Impone un changelog che documenti non cosa è cambiato (la diff lo mostra), ma perché: “aggiunta istruzione sui ticket multilingue a seguito del feedback del supporto” vale dieci righe di descrizione tecnica.
Associa sistematicamente una suite di test a ogni prompt; altrimenti, saranno gli utenti i primi a dirti quando una modifica rompe un comportamento consolidato. Instrada le modifiche ai prompt attraverso lo stesso processo di code review del codice stesso: un prompt che va in produzione senza revisione produce le stesse sorprese di un codice non revisionato. Verifica che il rollback richieda meno di un minuto e testalo in un giorno tranquillo piuttosto che durante un incidente. Infine, marca le versioni deployate con i tag per collegare inequivocabilmente il comportamento osservato a uno stato specifico del repository.
Testare il catalogo con un rollback
Configura un PromptCatalog per tre prompt reali della tua applicazione, quindi registra due o tre versioni di ciascuno evolvendo le istruzioni in piccoli passi: un’istruzione sul tono, una categoria aggiunta. Il versionamento dimostra il suo valore su queste modifiche granulari, perché sono quelle che non ricorderai di aver fatto. Configura attivazione e disattivazione e allega una suite di test a ogni prompt.
Concludi con l’esercizio più istruttivo: attiva deliberatamente una versione degradata, osserva la regressione tramite i test ed esegui il rollback cronometrandolo. Se l’operazione supera il minuto, correggi la procedura prima di aggiungere un solo prompt al catalogo: un rollback lento non è un rollback, è un incidente prolungato.
Punti chiave
- I prompt sono artefatti software che richiedono versionamento
- Ogni versione è un file JSON o YAML con metadati
- Lo stato (draft, active, deprecated) abilita il deployment graduale
- Archivia i prompt in Git con test e un changelog
- Il rollback deve essere istantaneo in caso di regressione