Gli sviluppatori possono ora garantire che il JSON restituito da un LLM sia conforme a una forma predefinita collegando gli schemi Zod al Vercel AI SDK o all'API tool-use di Anthropic, eliminando i crash a runtime che si verificano quando un modello aggiunge un campo inaspettato.

La necessità di una protezione concreta è diventata evidente a gennaio, quando un classificatore rilasciato in produzione ha iniziato a restituire una seconda chiave "explanation" dopo tre settimane di funzionamento impeccabile. Il codice si aspettava un singolo campo, quindi la chiave extra ha innescato un'eccezione — senza alcun deploy del codice. L'incidente illustra un problema più ampio: la maggior parte dei tutorial si ferma a JSON.parse(response), assumendo che il modello rispetti lo schema del prompt. In realtà, gli LLM spesso deviano — cambiando il case, aggiungendo campi o racchiudendo l'output in blocchi markdown — portando a una corruzione silenziosa dei dati o a fallimenti totali.

Perché il parsing JSON grezzo non è sicuro

Gli LLM sono addestrati per essere utili, non obbedienti. Un prompt che richiede

{ "category": "string" }

non vincola il modello a quella struttura esatta. Anche un prompt ben scritto può essere sovrascritto dalle euristiche interne del modello, specialmente quando un'impostazione della temperatura incoraggia la creatività o quando un'istruzione successiva lo spinge a elaborare maggiormente. Il risultato è un flusso di testo che sembra JSON ma devia abbastanza da mandare in errore i parser che si aspettano una forma rigorosa.

Quando tale discrepanza raggiunge il codice di produzione, il costo è immediato: un'eccezione sollevata, una richiesta fallita e potenzialmente una cascata di errori a valle. Nei grandi servizi, quei minuti di downtime si traducono in perdita di entrate e in una diminuzione della fiducia degli utenti.

Zod + Vercel AI SDK: una rete di sicurezza in tre passaggi

Zod è un validatore di schemi TypeScript-first che può descrivere l'esatta forma dei dati che un modello dovrebbe emettere. Combinato con l'helper Output.object del Vercel AI SDK, la validazione avviene automaticamente dopo che il modello ha generato la sua risposta.

  1. Definisci lo schema – scrivi un oggetto Zod che rispecchi il JSON desiderato. Per un semplice classificatore potrebbe essere z.object({ category: z.string() }); per un estrattore di fatture complesso, lo schema può annidare oggetti, array e discriminated unions.
  2. Passalo all'SDK – racchiudi lo schema con Output.object(schema). L'SDK inietta un prompt che dice al modello di restituire un blocco JSON corrispondente allo schema e analizza il risultato con safeParse di Zod.
  3. Gestisci i fallimenti – safeParse restituisce un oggetto di risultato invece di sollevare un'eccezione. Se il parsing fallisce, comunica l'errore al modello e riprova. Il modello può essere istruito a correggere l'output in base al messaggio di validazione esatto, trasformando la maggior parte dei casi limite in un ciclo di auto-correzione.

Poiché l'SDK gestisce il prompting, il parsing e la logica di retry in un unico punto, gli sviluppatori sostituiscono una serie di manipolazioni di stringhe ad hoc con una singola chiamata con controllo dei tipi.

Anthropic tool use: forzare l'output strutturato

Quando si lavora direttamente con l'API di Anthropic, la stessa garanzia può essere ottenuta tramite il "tool use". Uno strumento (tool) è definito come una funzione il cui schema di input è espresso in JSON Schema; il modello di Anthropic chiamerà lo strumento solo se può soddisfare lo schema. Impostando tool_choice su "any" (o un nome specifico di uno strumento), il modello è costretto a restituire un blocco strutturato invece di testo libero.

Il flusso di lavoro rispecchia l'approccio di Vercel:

  • Scrivi uno schema Zod.
  • Convertilo in un payload JSON Schema per la definizione dello strumento.
  • Includi lo strumento nella richiesta e richiedi al modello di invocarlo.
  • Analizza la risposta dello strumento con zod.safeParse.

Se il modello produce ancora dati malformati, si applica lo stesso pattern di retry con feedback.

Quando la validazione fallisce comunque

Anche con l'applicazione dello schema, si verificano occasionali discrepanze. Le ragioni includono:

  • Allucinazione del modello: il modello potrebbe generare una stringa che sembra JSON ma contiene errori di sintassi.
  • Prompt leakage: i turni di conversazione precedenti possono far trapelare istruzioni di formattazione che sovrascrivono la richiesta dello schema.
  • Differenze di versione: le nuove versioni dei modelli a volte cambiano il modo in cui interpretano le chiamate agli strumenti.

La mitigazione raccomandata è un ciclo di retry leggero. In caso di errore di parsing, il codice invia un prompt di follow-up come: "Il tuo ultimo output non era un JSON valido. Conteneva... Per favore, restituisci solo i campi definiti nello schema". Poiché l'errore di validazione è esplicito, il modello può correggersi senza l'intervento umano.

Considerazioni su prestazioni e costi

L'aggiunta della validazione Zod introduce un sovraccarico della CPU trascurabile: l'operazione safeParse viene eseguita in microsecondi per i payload tipici. La latenza di rete rimane invariata; l'ulteriore round-trip per un tentativo di riprova si verifica solo nel raro caso di errore. In pratica, il costo di una singola eccezione evitata supera di gran lunga l'incremento marginale del tempo di richiesta.

Controargomentazione: l'imposizione dello schema è eccessiva?

Alcuni sviluppatori sostengono che gli schemi rigidi limitino la flessibilità del modello, specialmente quando nuovi campi potrebbero fornire un contesto prezioso. Il compromesso è tra sicurezza e apertura. Nei servizi mission-critical — elaborazione dei pagamenti, verifica dell'identità, reporting di conformità — la prevedibilità vince. Nei prototipi esplorativi, un approccio più permissivo può essere accettabile, ma anche lì una protezione minima (ad es. z.object({}).passthrough()) può intercettare errori di parsing catastrofici senza scartare estensioni utili.

Cosa monitorare in seguito

  • Evoluzione dell'SDK: la roadmap dell'AI SDK di Vercel include policy di retry integrate e una reportistica degli errori più ricca, il che snellirà ulteriormente il ciclo di riparazione.
  • Standardizzazione degli strumenti: man mano che sempre più provider adottano convenzioni per il tool-use, potrebbero emergere validatori di schema cross-provider, riducendo la necessità di adattatori specifici per ogni provider.
  • Pattern della community: le librerie open-source stanno iniziando a includere gli schemi Zod insieme ai prompt template, rendendo il workflow "schema-first" una risorsa riutilizzabile.

In sintesi

Trattando uno schema Zod come un contratto che il modello non può violare, gli sviluppatori passano da fragili espedienti basati su JSON.parse a una pipeline deterministica in cui i campi inaspettati causano un errore di validazione controllato, non un crash in produzione. La combinazione dell'helper Output.object di Vercel e del meccanismo di tool-use di Anthropic trasforma gli LLM da generatori di testo imprevedibili in affidabili fornitori di dati, permettendo ai team di concentrarsi sulla logica di business invece che sull'infinito debugging dei casi limite.