Output strutturati con IA: come definire, forzare e validare il formato senza perdere affidabilità

1. Progetta lo schema a partire dall'uso downstream

Un output strutturato è una risposta del modello conformata a una forma di dati prevista, come un oggetto JSON con campi definiti. L'obiettivo non è solo che la risposta «sembrì JSON»: è che il sistema che la riceve possa interpretarla in modo coerente. Per raggiungerlo, parti dal consumatore downstream e lavora all'indietro: identifica quali campi necessita, cosa farà con essi e cosa deve accadere quando l'input non contiene le informazioni richieste.

Mantieni lo schema il più piccolo possibile per il caso d'uso. Per ogni campo, documenta il tipo, se è obbligatorio, i valori consentiti, le unità e la provenienza attesa. Decidi anche come rappresentare i dati assenti. Un valore nullo, una stringa vuota e un campo omesso possono avere significati diversi; non scambiarli senza una regola esplicita. Se una data deve alimentare un database, ad esempio, preferisci un formato normalizzato e un fuso orario definito anziché accettare espressioni come «il venerdì».

Separa la struttura dalle istruzioni semantiche. Lo schema può richiedere che `data` sia una stringa, ma questo da solo non impedisce al modello di inventare una data. Le descrizioni dei campi e il prompt possono guidare l'estrazione, ma l'applicazione deve stabilire quali evidenze accetta e quale risultato usare quando non le trova. Un'opzione sicura è ammettere uno stato esplicito come `non_trovato` o un campo di evidenza, anziché forzare una risposta affermativa.

La documentazione di Azure OpenAI descrive l'uso di una definizione di schema JSON in una chiamata di inferenza e mostra esempi con Pydantic e Zod. La documentazione di Gemini presenta anche risposte in JSON conformi a uno schema ed esempi di utilizzo di modelli di dati. Queste capacità documentate sono specifiche delle API e configurazioni descritte; non dimostrano che tutti gli schemi, modelli o provider accettino esattamente le stesse restrizioni.

2. Scegli il meccanismo di output in base al compito e al provider

Ci sono tre approcci comuni, ma non sono equivalenti. Il prompting puro chiede al modello di restituire un formato specifico tramite istruzioni in linguaggio naturale. Può bastare in un prototipo o quando l'output è solo per lettura umana, ma il formato può degradarsi: compaiono spiegazioni fuori dal JSON, chiavi inaspettate o valori di tipi errati. Se il risultato alimenta codice, trattalo come un'opzione meno controllabile e valida sempre la risposta.

La modalità JSON richiede una risposta JSON. La documentazione di Azure distingue questa modalità dagli output strutturati con schema: la prima garantisce JSON valido, ma non garantisce il rispetto rigoroso dello schema fornito. Pertanto, il fatto che una risposta sia analizzabile come JSON non dimostra che abbia le chiavi, i tipi o le restrizioni richieste dall'applicazione.

Gli output strutturati con schema consentono di fornire una definizione per guidare la forma della risposta. La documentazione di Azure mostra questo meccanismo nei campi di formato della risposta, nonché esempi di integrazione con Pydantic e Zod. Gemini documenta anche la configurazione di una risposta JSON basata su schema ed esempi di estrazione e classificazione. La disponibilità specifica dipende dall'API, dal modello e dalla configurazione scelti: verifica la documentazione vigente dell'endpoint che userai effettivamente, invece di assumere che due prodotti con nomi simili abbiano lo stesso comportamento.

Le chiamate a funzioni o strumenti servono quando il modello deve proporre argomenti per un'operazione disponibile nell'applicazione, come consultare un ordine. Non equivalgono all'esecuzione della funzione né alla verifica che l'azione sia sicura: il server deve validare gli argomenti e applicare i propri controlli prima di agire. Nell'uso di output strutturati per chiamate a funzioni descritto da Azure, la documentazione avverte che le chiamate parallele non sono supportate e consiglia di disattivarle in quella configurazione. Non estrapolare quella limitazione ad altre API senza conferma.

Come regola di selezione: usa un output con schema quando l'obiettivo principale sia produrre un oggetto conforme a una definizione; usa una chiamata a funzione quando il modello debba selezionare un'operazione e proporre i suoi argomenti; e riserva il prompting puro a contesti a basso rischio o a compiti in cui una validazione locale rigorosa compensi la minore coercizione. In ogni caso, la risposta deve passare attraverso controlli dell'applicazione prima di raggiungere il sistema downstream.

3. Valida la struttura prima di elaborare la risposta

La prima barriera è analizzare la risposta con un parser del formato atteso. Per JSON, il parser deve rifiutare testo non valido, valori troncamenti e contenuto che non possa essere convertito in un oggetto. Se il provider fornisce una risposta già analizzata da un SDK, verifica comunque lo stato di completamento, i rifiuti e i campi che possano indicare una risposta incompleta; non dare per scontato di aver sempre ricevuto un risultato utilizzabile.

La seconda barriera è validare contro uno schema locale. JSON Schema consente di esprimere tipi, campi obbligatori, enumerazioni, restrizioni di lunghezza e regole per proprietà aggiuntive, tra le altre condizioni. Le librerie di validazione possono convertire queste regole in errori azionabili prima che l'output raggiunga un database o un'API. L'implementazione specifica dipende dal linguaggio e dalla versione dello schema: verifica la compatibilità della libreria scelta con le parole chiave e il dialetto usati dal tuo contratto, e testa la combinazione nella integrazione continua.

Non copiare senza revisione lo schema accettato dal provider come contratto definitivo dell'applicazione. Il provider può accettare solo un sottoinsieme delle regole, o trasformare un modello di dati di una libreria in una definizione compatibile con la sua API. Mantieni una fonte di verità per il tuo contratto e, se il provider richiede una rappresentazione ridotta, genera o adatta lo schema di chiamata senza eliminare le regole critiche di validazione locale.

La validazione deve essere rigorosa ai limiti del sistema. Rifiuta proprietà inaspettate se potrebbero alterare il comportamento; converti i tipi solo quando la conversione sia inequivoca e documentata; ed evita di «riparare» automaticamente valori dubbi. Se un campo deve essere un intero, convertire `12,5` in `12` non è una riparazione innocua: può cambiare il significato. Conserva l'errore, l'identificatore della richiesta e la versione dello schema per poter diagnosticare i guasti senza accettare silenziosamente dati difettosi.

4. Verifica il contenuto e rappresenta l'incertezza

Una risposta strutturalmente corretta può essere semanticamente falsa. Per misurare questa differenza, valuta i campi rispetto all'input originale e alle fonti di riferimento disponibili, non rispetto alla fluidità della spiegazione del modello. Nell'estrazione, conserva evidenza testuale sufficiente per localizzare il dato nel documento. Nella classificazione, conserva la regola o il segnale che ha permesso di assegnare la categoria. Nell'arricchimento, identifica quali valori provengono dall'input e quali dipendono da una fonte esterna autorizzata.

Progetta una rappresentazione esplicita per l'incertezza. A seconda del caso, può essere un valore nullo accompagnato da uno stato, un elenco di candidati o un marchio di revisione. Evita di chiedere una percentuale di confidenza senza definire cosa significhi e come verrà calibrata: un numero generato dal modello stesso non è, di per sé, una probabilità verificata. Se usi un punteggio, misuralo con un set etichettato e decidi le soglie in base al costo degli errori e delle revisioni, non per intuizione.

L'escalation umana deve essere un percorso normale del pipeline, non un'eccezione improvvisata. Invia in revisione i casi ambigui, quelli privi di evidenza, quelli che violano regole di business e quelli che implicano una decisione ad alto impatto. Il revisore deve vedere l'input, l'output proposto, l'evidenza e il motivo dell'escalation. Se una correzione umana viene salvata come dato di addestramento o come esempio di regressione, registra anche la sua provenienza e la politica applicabile.

L'evidenza disponibile qui supporta capacità di output basate su schema per Azure OpenAI e Gemini, ma non quantifica tassi di errore di formato rispetto a tassi di errore semantico. Non consente inoltre di stabilire una soglia universale di confidenza. Pertanto, misura entrambe le classi di errore nel tuo stesso compito: un basso tasso di JSON non valido non dimostra un'estrazione corretta, e un buon risultato su un campione piccolo non garantisce il comportamento in produzione.

5. Testa il sistema e monitora il suo comportamento in produzione

Costruisci un set di regressione con esempi rappresentativi e casi limite prima di distribuire modifiche al prompt, allo schema, al modello o al SDK. Includi input puliti, input incompleti, dati contraddittori, caratteri inaspettati, documenti lunghi e casi in cui la risposta corretta sia «non trovato». Per ogni caso, conserva un'aspettativa verificabile: risultato atteso, campi che devono restare assenti e condizioni che obbligano a escalare.

Misura separatamente la validità sintattica, la conformità allo schema, l'accuratezza di ogni campo e il tasso di escalation. Una singola metrica aggregata può nascondere che il sistema produce JSON perfetto ma classifica male, o che indovina la maggior parte dei campi e fallisce proprio in quelli di maggiore impatto. Segmenta i risultati per tipo di input, versione del modello, template del prompt e versione dello schema.

In produzione, registra metriche che consentano di rilevare degradazioni: risposte non analizzabili, errori di validazione, campi nulli, valori fuori intervallo, disaccordi con fonti di riferimento e proporzione di revisioni umane. Definisci allarmi e un percorso di recupero, ad esempio ritenere record dubbi o tornare a una versione precedente. Non conservare dati sensibili non necessari nei log; conserva solo ciò che è richiesto per debug, audit e conformità alla politica applicabile.

Prima di cambiare provider o meccanismo, ripeti i test con lo stesso campione e gli stessi criteri di accettazione. Le funzioni documentate non sono intercambiabili in tutti i dettagli, e una migrazione può modificare quali restrizioni sono ammesse o come vengono rappresentate le risposte. Tratta la configurazione di produzione come parte del contratto: provider, endpoint, modello, schema, SDK, prompt e politica di retry devono essere versionati e auditabili.

Continua a esplorare

Correzioni e trasparenza

Se trovi un dato errato o non aggiornato, inviaci la pagina e la fonte da verificare.