Risultati strutturati: ottenere JSON affidabile da un modello linguistico

La prima versione di ogni integrazione LLM analizza la prosa. Chiedi "i tre rischi principali, uno per riga", suddivisi sui ritorni a capo, e funziona fino al giorno in cui il modello scrive prima una frase introduttiva. Esistono output strutturati per terminare quel ciclo: passi al modello uno schema JSON, il decodificatore è vincolato in modo che non possa emettere nulla che lo violi e ottieni indietro un carico utile con i campi richiesti. Questa garanzia è reale ma più limitata di quanto sembri, e la differenza sta nel luogo in cui vivono gli insetti.

Cosa copre effettivamente la garanzia

Garanzie di decodifica vincolate forma. La risposta verrà analizzata come JSON, avrà le tue chiavi, i tipi corrisponderanno e i campi enum conterranno uno dei valori elencati. Questo è un grande miglioramento rispetto a pronta-e-speranza.

Non garantisce nulla in merito contenuto. Un campo digitato come stringa conterrà una stringa; se quella stringa sia accurata o inventata per soddisfare lo schema non è cambiata rispetto a prima. In effetti uno schema rigoroso rende l'invenzione leggermente più probabile, perché un campo obbligatorio deve essere riempito con qualcosa e il modello non ha modo di dire "non presente nella fonte". Questo è il singolo errore più comune nella produzione: un require invoice_number in un documento che non ne ha.

Progetta attorno ad esso. Consenti null dove l'assenza è possibile, aggiungi un esplicito found: boolean o a "unknown" enum e non rendere mai obbligatorio un campo a meno che la risposta non esista realmente in ogni input.

Progettare uno schema che un modello possa riempire

Gli schemi scritti per la convalida e gli schemi scritti per la generazione hanno un aspetto diverso. Alcune regole che valgono per tutti i fornitori:

• Battiti piatti nidificati. Ogni livello di nidificazione è un luogo in cui il modello perde traccia. Tre oggetti superficiali estratti in tre richiami colpiscono un albero profondamente annidato.
• Le enumerazioni battono le corde libere. Se un campo ha cinque valori legittimi, elencali. Rimuovi un'intera classe di codice di normalizzazione e il decodificatore vincolato lo applica per te.
• I nomi dei campi sono istruzioni. due_date_iso8601 produce un output migliore di date con il formato spiegato in un prompt separato. I nomi sono nel contesto; usali.
• Utilizzo description sui campi. La maggior parte dei provider passa le descrizioni dello schema al modello. Una clausola per campo ambiguo è più economica e più affidabile di un paragrafo di istruzioni in prosa sopra.
• Impostato additionalProperties: false. Diversi provider lo richiedono comunque per la modalità rigorosa e impedisce al modello di inventare utilmente una chiave aggiuntiva che il parser ignora silenziosamente.
• Preferisci matrici di oggetti piatti alle mappe. Le chiavi dinamiche, un oggetto i cui nomi di proprietà sono sconosciuti in anticipo, sono scarsamente supportate dalle modalità rigorose e difficili da digitare sul lato ricevente.

I provider limitano inoltre quali parole chiave dello schema JSON supportano in modalità rigorosa: oneOf, i vincoli del modello, i limiti numerici e la ricorsione sono comunemente limitati o ignorati. Supponiamo che lo schema vincoli solo la struttura e applichi tu stesso le regole aziendali dopo l'analisi.

Convalidare comunque

Anche con una modalità rigorosa, convalida ogni risposta prima che tocchi il tuo database. La modalità rigorosa può essere disabilitata da una modifica della configurazione, un percorso di fallback potrebbe colpire un modello che non la supporta, un nuovo tentativo di rete potrebbe restituire un oggetto errore e la risposta potrebbe essere troncata da un limite token a metà oggetto, che produce JSON non valido che nessuna modalità schema impedisce.

Quando un payload fallisce, la domanda utile è quale campo e perché. IL Convalidatore dello schema JSON prende il documento e lo schema e riporta una riga per problema, con il percorso del puntatore JSON, la parola chiave non riuscita e il valore effettivamente trovato. Questo è esattamente il modulo che desideri per due scopi: correggere lo schema durante lo sviluppo e restituirlo in un nuovo tentativo: un rapporto di validazione non riuscita incollato in un messaggio di follow-up è una richiesta di riparazione straordinariamente efficace, poiché il modello può vedere esattamente cosa ha sbagliato.

Limita i tentativi a uno o due. A un modello che fallisce due volte uno schema viene solitamente richiesto qualcosa che l'input non contiene e al terzo tentativo lo inventerà.

Da un payload di esempio al codice

La maggior parte degli schemi nasce come risposta di esempio che qualcuno ha incollato in una chat. Trasformarlo manualmente in codice digitato e convalidato è noioso e soggetto a errori, quindi non farlo.

Incolla il campione in Schema da JSON a Zod e ottieni uno schema Zod più il tipo TypeScript dedotto. Deduce per campo anziché digitare tutto come una stringa: vengono ottenuti valori che assomigliano a e-mail, URL, UUID o date ISO .email(), .url(), .uuid() E .datetime() invece che nudo z.string(), gli array portano il loro tipo di elemento e un campo il cui tipo varia a seconda delle occorrenze diventa un'unione anziché scegliere silenziosamente il primo che ha visto. Vale la pena alimentare deliberatamente quest'ultimo comportamento: incollare tre o quattro risposte reali concatenate, non una, in modo che i campi facoltativi e polimorfici vengano visualizzati come unioni invece di essere bloccati su qualunque cosa contenga il primo campione.

Se hai bisogno solo dei tipi e non della convalida runtime, perché il payload proviene da una fonte di cui ti fidi già, JSON in TypeScript produce le interfacce direttamente, con oggetti annidati suddivisi come sottointerfacce denominate anziché come BLOB anonimi incorporati.

Mantieni dritta la direzione della verità: una definizione di schema, con tutto il resto generato da essa. Uno schema Zod e uno schema JSON mantenuti separatamente non saranno d'accordo entro un mese e il disaccordo emergerà come un errore di analisi della produzione piuttosto che come un fallimento del test.

Leggendo cosa è tornato

Le risposte dei modelli arrivano ridotte su una riga, il che rende infelice il loro esame. IL Formattatore JSON rientra e li ordina in qualcosa di leggibile e la sua convalida rileva immediatamente il caso di troncamento: un carico utile che termina a metà stringa è la firma di un limite di hit token e la correzione è un limite di output più elevato o uno schema più piccolo, non una modifica immediata.

Quando confronti ciò che due modelli hanno prodotto dallo stesso input o controlli se una modifica tempestiva ha alterato l'output in modi non previsti, differenzia i payload formattati anziché leggerli entrambi. Le differenze strutturali invisibili in un muro di JSON - un campo che silenziosamente è diventato una stringa di cifre invece di un numero - risaltano immediatamente in un diff.

Controllo delle versioni

Gli schemi cambiano e l'output del modello cambia con loro. Inserisci un campo versione nel payload dal primo giorno, in modo che i record archiviati mantengano la forma in cui sono stati scritti. Il retrofitting che dopo aver ottenuto un milione di righe di JSON senza tag è il tipo di migrazione per cui nessuno pianifica il tempo.

Tutti questi strumenti vengono eseguiti localmente nel tuo browser, il che è più importante del solito per questo flusso di lavoro: i payload di esempio che stai trasformando in schemi sono solitamente risposte API reali con dati reali dei clienti al loro interno e non dovrebbero essere caricati su un servizio di formattazione per essere abbelliti.