Perché le applicazioni di IA hanno bisogno di risultati strutturati?
Le applicazioni IA hanno bisogno di risultati strutturati perché il software non può interpretare in modo affidabile un paragrafo discorsivo: ha bisogno ogni volta degli stessi campi, con gli stessi nomi e tipi. Una frase in più o un campo mancante possono far fallire il passaggio successivo della tua applicazione.
Immagina una start-up di logistica fittizia con 12 persone, Parcelwise. La sua sviluppatrice, Sana, sta creando uno strumento che legge le email dei clienti e compila un modulo di modifica della consegna: riferimento dell'ordine, data richiesta, nuovo indirizzo ed eventuale richiesta di rimborso. Un'email tipica recita: 'Ciao, ordine PW-88213, giovedì non sono a casa, potete passare sabato? Oppure lasciatelo al n. 14. Altrimenti annullate e rimborsate per favore.' Nella prima versione, Sana chiede al modello di 'rispondere in JSON'. La maggior parte delle risposte viene elaborata correttamente, ma alcune iniziano con 'Certo, ecco il JSON', altre chiamano il campo 'date' invece di 'requested_date' e una restituisce la data come 'sabato'.
Che cos'è uno schema JSON e perché è utile?
Uno schema JSON è una descrizione formale dei dati attesi: quali campi esistono, quali sono obbligatori, di che tipo è ciascuno e quali valori sono ammessi. Fornire al modello uno schema trasforma 'rispondi in JSON, per favore' in un contratto che il tuo codice può verificare.
Per Sana, lo schema stabilisce che: order_reference è una stringa obbligatoria; requested_date è una stringa obbligatoria in formato data, oppure null se non è stata indicata alcuna data; new_address è una stringa oppure null; refund_requested è un valore booleano obbligatorio; non sono ammessi altri campi. Quest'ultima regola impedisce al modello di aggiungere campi di commento.
In che modo le API dei modelli supportano risposte strutturate?
Le API dei principali modelli consentono di inviare uno schema JSON insieme alla richiesta, e l'output del modello è vincolato a rispettarlo.
OpenAI
La funzionalità di output strutturati di OpenAI vincola le risposte a uno schema JSON fornito quando la modalità rigorosa è attiva. La documentazione la distingue dalla precedente modalità JSON, che garantisce solo un JSON valido, non la conformità al tuo schema, e consiglia gli output strutturati quando disponibili.
Anthropic
L'API di Claude offre risultati JSON conformi a uno schema fornito dall'utente, oltre a un'opzione rigorosa nelle definizioni degli strumenti che permette di convalidare i dati in ingresso rispetto allo schema dello strumento. La documentazione elenca le caratteristiche degli schemi supportate e quelle che restituiscono un errore.
L'API di Gemini accetta uno schema JSON per le risposte e supporta un sottoinsieme definito delle parole chiave dello schema. La documentazione precisa che, anche se l'output è JSON sintatticamente corretto, occorre comunque convalidare i valori nell'applicazione.
Perché servono comunque la convalida e nuovi tentativi?
La convalida resta necessaria perché uno schema controlla la struttura dei dati, non la correttezza dei valori. Una risposta perfettamente strutturata può comunque contenere una data sbagliata, un riferimento d'ordine inventato o un indicatore di rimborso che il cliente non ha mai richiesto.
Esegui la convalida su due livelli. Per prima cosa, controlla la struttura con una libreria di validazione degli schemi, come Pydantic in Python o Zod in JavaScript, presenti negli esempi della documentazione di OpenAI, Anthropic e Google. Poi controlla le regole aziendali: il riferimento dell’ordine rispetta il formato previsto ed esiste nel sistema? La data è futura e corrisponde a un giorno di consegna? L’indirizzo si trova in una zona servita? Gestisci anche i casi documentati dai fornitori: un rifiuto, che potrebbe non rispettare il tuo schema, e una risposta interrotta dal limite massimo di token, che lascia un JSON incompleto.
Riprova con cautela. Se un controllo fallisce, effettua un solo nuovo tentativo che includa l'errore specifico, ad esempio 'requested_date deve essere una data; l’email dice sabato e la data dell’ordine è 14 ottobre'. Limita i nuovi tentativi a uno o due, poi inoltra l'email a una persona.
Come si presenta un risultato strutturato debole rispetto a uno robusto?
Versione debole: l'istruzione dice 'Estrai i dettagli e rispondi in JSON.' L'app legge qualsiasi risposta riceva. Per l'email riportata sopra riceve campi chiamati order e date, un valore di data pari a 'sabato' e un valore di rimborso pari a true, perché il modello ha interpretato 'altrimenti annulla e basta' come una richiesta esplicita. Il modulo viene compilato in modo errato e il cliente riceve un rimborso che non voleva.
Versione robusta: la richiesta include lo schema di Sana con la modalità rigorosa e il prompt spiega ogni campo, specificando anche che 'refund_requested è true solo se il cliente chiede un rimborso senza condizioni'. Il modello restituisce order_reference PW-88213, requested_date con la data del sabato successivo, new_address null, refund_requested false e conditional_request, un campo che Sana ha aggiunto allo schema proprio per questo caso, impostato su 'rimborso se non è possibile consegnare sabato o a un vicino'. La convalida conferma che l'ordine esiste e che sabato è un giorno di consegna. Poiché l'email contiene una richiesta condizionata, le regole la inoltrano a una persona per la decisione finale.
Quali sono gli errori più comuni negli output strutturati?
L'errore più comune è considerare dati in formato JSON valido come dati corretti. Altri errori: affidarsi solo alle istruzioni per l'IA quando l'API consente di imporre uno schema, usare nomi di campo vaghi senza descrizioni, forzare un valore quando la risposta onesta è null, ignorare i rifiuti e le risposte troncate e riprovare senza dire al modello che cosa non andava.
Dove si collocano gli output strutturati nel catalogo di Tosheo.ai?
Output strutturato è una lezione del percorso di programmazione nel corso per creare applicazioni di IA, nella categoria Creazione di applicazioni di IA. La versione pratica completa con codice, in cui definisci uno schema, chiami un'API, convalidi le risposte e aggiungi un nuovo tentativo, è disponibile dopo l'iscrizione nel percorso di programmazione, con un riscontro basato su una griglia di valutazione per ogni passaggio.