Come versionare un prompt usato in produzione

Una persona cambia riassumi la richiesta in assegna la richiesta alla categoria più probabile. Sono sei parole. Il comportamento, però, passa da sintesi a decisione.

Se quel testo vive in una variabile d'ambiente, in un foglio condiviso o dentro un nodo del workflow, dopo una settimana potresti non sapere quale versione ha prodotto un ticket, con quale modello, quali esempi e quali regole di uscita.

Versionare un prompt significa trattarlo come una dipendenza di produzione: ogni modifica crea un artefatto identificabile, viene valutata in condizioni comparabili, attraversa un gate e può essere ritirata senza riscrivere la storia.

Un prompt non è solo il testo che leggi

La stessa istruzione può produrre comportamenti diversi se cambiano modello, parametri, tool, schema di output, esempi, corpus o template che inserisce le variabili.

Per questo prompt-v7.txt non basta. L'unità che vuoi riprodurre comprende almeno:

• messaggi di sistema, developer e user template

• variabili con nome, tipo e obbligatorietà

• esempi inclusi nel contesto

• modello o famiglia ammessa

• parametri di generazione rilevanti

• schema dell'output e validatore

• tool e descrizioni disponibili

• policy e corpus compatibili

• set di valutazione e criteri di gate

Il testo resta centrale, ma il record deve dire in quale sistema quel testo acquisisce significato.

MLflow Prompt Registry è un esempio concreto di questa idea: conserva versioni, commit message, tag, alias e configurazione del modello. Non devi adottare per forza lo stesso strumento. Devi conservare le stesse proprietà operative: identità, immutabilità, confronto, lineage e promozione controllata.

Definisci l'unità di versione

Scrivi un manifest leggibile e machine-readable:

prompt_id: support.route_request
version: 12
template_sha256: 6d44...a890
messages:
  - role: system
    ref: prompts/support-route-v12.yaml
variables:
  - name: request_text
    type: string
    required: true
output_schema: support-route-v3.json
compatible_models:
  - family: model-a
    config_ref: deterministic-classification-v2
toolset: none
eval_set: support-routing-2026-08
release_status: candidate
derived_from: support.route_request@11

derived_from rende leggibile la genealogia. W3C PROV usa entità, attività e agenti per descrivere come un artefatto è stato prodotto e derivato. Non serve implementare l'intera ontologia per applicare il principio: collega versione sorgente, modifica, autore, processo di valutazione e risultato.

Congela il template. Se vuoi correggerlo, crea una nuova versione. La documentazione MLflow rende immutabile il template registrato proprio per preservare riproducibilità. Tag, annotazioni o stato possono evolvere; il contenuto che ha prodotto un output storico no.

Decidi cosa richiede una nuova versione:

• testo o ordine dei messaggi

• variabili e default

• esempi few-shot

• schema dell'output

• tool o descrizioni esposte

• policy che cambia l'esito ammesso

Un cambio del solo owner o di una nota editoriale può aggiornare metadata. Un cambio che può alterare l'output crea una candidate nuova.

Nomina il cambiamento, non solo la versione

v12 identifica. Non spiega.

Ogni commit dovrebbe rispondere a quattro domande:

1. quale problema osservato prova a risolvere?

2. qual è la sola variazione intenzionale?

3. quali casi possono regredire?

4. quale risultato renderebbe il cambio non promuovibile?

Esempio:

Problema: richieste miste classificate con una sola categoria
Variazione: consenti primary_category + secondary_signal
Rischio: aumento di categorie non previste e routing ambiguo
Gate: schema valido 100%; zero invii automatici; casi bloccanti invariati

Questo messaggio evita il prompt “migliorato” senza ipotesi. Se cambi istruzione, modello e schema insieme, non saprai quale superficie ha prodotto la differenza. Separa le variabili quando il rischio e il costo lo permettono.

Il controllo delle modifiche di un workflow AI aiuta a mappare dipendenze e impatto. Il registro prompt applica quel controllo a un artefatto specifico.

Congela baseline e candidate

Prima della modifica identifica la versione realmente usata, non quella che la documentazione dice di usare.

La baseline include:

• ID e hash del prompt

• modello e configurazione

• schema e toolset

• set di casi

• ambiente e dipendenze

• risultati e difetti noti

La candidate cambia solo le superfici dichiarate. Esegui entrambe sullo stesso input e conserva output, trace, punteggi e disposizione per caso.

Un confronto per media può nascondere regressioni. Segmenta almeno per:

• casi normali

• casi limite

• input incompleti

• richieste fuori scopo

• esempi con conseguenze alte

• lingue o formati realmente supportati

Il dataset di test per un workflow AI ti aiuta a mantenere casi e attese. Nel registro prompt, ogni evaluation run punta alla versione esatta del dataset. Se il set cambia durante il confronto, salva un nuovo ID e non sovrapporre i risultati.

Valuta il comportamento con oracoli adatti

Non tutto si misura con similarità testuale. Scegli l'oracolo vicino al lavoro.

MLflow documenta un ciclo in cui una nuova versione viene valutata sullo stesso set e i risultati vengono confrontati. Il punto non è lo strumento: è il legame persistente fra prompt_version, eval_run, casi e scorer.

NIST chiede set, metriche e strumenti TEVV documentati. Registra anche i limiti del valutatore. Un LLM judge può essere utile, ma non deve essere l'unica prova per schema, permessi, dati o azioni che possono essere controllati deterministicamente.

Definisci casi bloccanti separati dalla score aggregata. Una candidate che migliora il tono ma inizia a produrre una categoria vietata non è migliore per quel workflow.

Conserva input e output senza creare un archivio indiscriminato

La riproducibilità non autorizza a copiare dati sensibili nel registro. Usa:

• fixture sintetiche per la regressione

• identificatori o hash per collegare record protetti

• campioni sanitizzati con regole esplicite

• accessi limitati e tempi di conservazione

• tracce ridotte ai campi necessari per la decisione

Se un caso reale rivela un difetto, crea una variante minima che mantenga la struttura del fallimento senza conservare PII o contenuto cliente.

Il registro del prompt non deve contenere segreti, prompt proprietari in viste pubbliche o intere conversazioni “per sicurezza”. Separa metadata accessibili, artefatto protetto ed evidenza di valutazione.

Separa versione immutabile e alias di ambiente

Una versione risponde a che cosa è stato eseguito?. Un alias risponde a quale versione deve usare questo ambiente adesso?

support.route_request@11  ← versione immutabile
support.route_request@12  ← versione immutabile

development → 12
staging     → 12
production  → 11

Quando la candidate passa il gate, sposti production da 11 a 12 con una decisione registrata. L'applicazione può continuare a usare un riferimento stabile, mentre il registro conserva la versione concreta dietro l'alias.

MLflow usa proprio alias mutabili sopra versioni del prompt. La separazione facilita promozione e ritorno, ma introduce un rischio: l'alias può cambiare mentre un processo usa ancora una copia in cache.

Il piano di release deve quindi specificare:

• chi può spostare l'alias

• quale gate e quale ricevuta sono necessari

• tempo massimo di propagazione

• comportamento delle cache

• esecuzioni già in corso

• versione da usare nei retry

• controllo della versione effettivamente caricata

Non usare latest in produzione se il tuo processo richiede approvazione: “più recente” e “approvato” non sono la stessa cosa.

Promuovi per stadi

Un possibile flusso è:

1. draft: testo in revisione, nessun runtime

2. candidate: manifest completo ed evaluation run associato

3. staging: integrazione con schema, tool simulati e dipendenze reali ma isolate

4. shadow: input reale ammesso, zero effetti, confronto con baseline

5. limited: traffico o casi limitati con gate chiaro

6. production: alias promosso e ricevuta verificata

7. deprecated: non usato per nuovi run, conservato per storia e rollback

Non tutti i prompt richiedono shadow o limited rollout. Una frase in un assistente interno in sola lettura e un prompt che prepara pagamenti hanno conseguenze diverse. Usa rischio e reversibilità, non un rituale uguale per tutti.

Ogni passaggio registra chi ha deciso, quale evidenza ha visto, quale limite resta e quale ritorno è disponibile. Una promozione non cancella la baseline.

Registra la versione realmente eseguita

Il runtime deve emettere una ricevuta che contenga almeno:

trace_id: tr_90114
prompt_id: support.route_request
prompt_version: 12
prompt_hash: 6d44...a890
alias_requested: production
alias_resolved_at: 2026-09-02T09:14:22+02:00
model_config_ref: deterministic-classification-v2
output_schema: support-route-v3

Senza questa prova, il registro racconta l'intenzione, non l'esecuzione. Cache, deployment parziali, worker longevi o fallback possono usare una versione diversa.

Collega la ricevuta ai segnali del monitoraggio di un workflow AI in produzione. Se aumentano errori o astensioni, devi poter segmentare per versione concreta e non solo per data.

Non inserire il prompt completo nei log se è protetto. ID, hash e riferimento sono sufficienti per risalire all'artefatto nel perimetro autorizzato.

Prova il rollback prima della promozione

Possiamo rimettere v11 non è un piano. Verifica:

• che la versione precedente sia ancora disponibile

• che modello, schema e tool compatibili esistano

• che l'alias possa tornare indietro

• che cache e worker ricarichino il riferimento

• che i job in corso abbiano una disposizione definita

• che gli output prodotti dalla candidate non vengano reinterpretati con la baseline

Il rollback del prompt non annulla side effect già avvenuti. Se la candidate ha creato bozze, inviato messaggi o modificato record, serve riconciliazione separata.

Definisci due trigger:

• automatico: schema invalido, tool vietato, leakage o altro caso deterministico

• decisionale: calo su qualità, aumento di review o comportamento ambiguo entro soglie contestuali

Un trigger automatico può spostare l'alias o fermare l'esecuzione solo se l'operazione è autorizzata e sicura. Altrimenti deve bloccare nuovi run e chiamare l'owner.

Esempio fittizio: prompt per instradare richieste

Un team usa v11 per assegnare una richiesta a billing, technical o other. Le richieste miste finiscono spesso in other. La v12 introduce secondary_signal e una regola di astensione quando mancano elementi.

Il team:

• registra v12 con derived_from=v11

• mantiene modello, temperatura e schema base

• aggiunge il solo campo opzionale allo schema v3

• esegue v11 e v12 sugli stessi 180 casi sintetici

• controlla label, schema, abstain e casi ad alto impatto

• scopre che v12 migliora i casi misti ma astiene su alcune richieste brevi legittime

Invece di promuovere per la media, aggiunge esempi brevi al set e rivede l'istruzione. Nasce v13. Solo v13 passa i casi bloccanti e viene messa in staging.

La ricevuta del primo run di produzione conferma hash e schema attesi. V11 resta deprecated, non cancellata, finché la finestra operativa non rende inutile il ritorno.

Think, Build, Enable applicato ai prompt

Think: definisci il lavoro, l'errore che vuoi correggere, la sola variabile in modifica e i casi che non possono regredire.

Build: crea versioni immutabili, lega dipendenze ed eval, confronta baseline e candidate e separa alias da artefatto.

Enable: assegna owner, registra la versione realmente eseguita, osserva per versione e prova rollback e comunicazione.

Porta workflow, prompt e casi a MAIKER HUB per progettare automazioni e agent AI con n8n. Un prompt governato non è quello con il nome più ordinato. È quello che puoi ricostruire, valutare, promuovere e ritirare senza indovinare.