JSONSchemaBench: La complessità degli schemi reali mette in crisi le garanzie di output strutturato degli LLM

La maggior parte dei team considera la decodifica vincolata un problema risolto: aggiungi uno schema JSON, ottieni JSON valido. JSONSchemaBench (arXiv:2501.10868) è il primo tentativo sistematico di mettere alla prova questa assunzione su 9.558 schemi reali, e i risultati sono meno rassicuranti di quanto il marketing lascerebbe supporre.

L'articolo​

Saibo Geng, Hudson Cooper, Michał Moskal e i colleghi di Microsoft Research presentano JSONSchemaBench, un benchmark di 9.558 schemi provenienti da fonti di produzione reali: firme di chiamata di funzione GlaiveAI, repository GitHub stratificati per complessità da banale a ultra, configurazioni API Kubernetes, schemi di analisi eventi Snowplow e la collezione JSONSchemaStore. Valutano sei framework di decodifica vincolata — Guidance, Outlines, Llamacpp, XGrammar, OpenAI Structured Outputs e Gemini — su tre assi: copertura (quale frazione di schemi il framework può gestire del tutto), efficienza (overhead di token al secondo rispetto alla generazione non vincolata) e qualità (accuratezza del compito a valle). La griglia di valutazione include anche la suite ufficiale di test JSON Schema Test Suite, che documenta 45 categorie di funzionalità che qualsiasi motore conforme dovrebbe supportare.

L'affermazione centrale è che la complessità dello schema è la variabile decisiva che separa i framework capaci da quelli fragili, e che nessun singolo framework domina su tutti e tre gli assi.

Idee chiave​

• La copertura crolla con la complessità degli schemi. Sugli schemi semplici GlaiveAI tutti i framework superano l'86%. Ma su GitHub-Hard — annidamenti multilivello, definizioni ricorsive, vincoli pattern complessi — Guidance scende al 41%, Llamacpp al 39%, XGrammar al 28% e Outlines a un catastrofico 3%. OpenAI raggiunge solo il 9% su GitHub-Hard, e Gemini non produce alcun output valido su schemi di complessità media o superiore.
• Kubernetes espone una debolezza specifica in XGrammar. Nonostante le affermazioni di velocità di XGrammar, esso raggiunge solo il 7% di copertura sugli schemi Kubernetes, probabilmente perché questi schemi si basano su pattern dipendenti dal contesto che la precomputazione indipendente dal contesto di XGrammar non può gestire. La copertura contro un benchmark che include configurazioni Kubernetes non è un optional per agenti in produzione.
• Essere sotto-vincolati è più pericoloso del fallimento di compilazione. XGrammar presenta 38 fallimenti sotto-vincolati contro la JSON Schema Test Suite — il che significa che emette JSON che viola lo schema dichiarato mentre riporta silenziosamente successo. Guidance ha solo 1 fallimento di questo tipo. Per un agente di scrittura, un errore di compilazione viene catturato in fase di progettazione; un fallimento sotto-vincolato corrompe i dati a runtime senza alcun segnale.
• Il fast-forwarding di Guidance offre un vero speedup del 50%. Quando sono presenti sequenze deterministiche lunghe (es. nomi di campi in una struttura oggetto fissa), Guidance può avanzare più token per passo di decodifica. Su Llama-3.1-8B su una A100, Guidance gira a 6–9 ms per token di output mentre la generazione non vincolata gira a 15–16 ms. Outlines è più lento della generazione non vincolata a 30–46 ms, in gran parte a causa della compilazione dell'automa iniziale che richiede 3–8 secondi per schema.
• La decodifica vincolata migliora modestamente l'accuratezza del ragionamento. Su GSM8K (matematica), Guidance porta l'accuratezza dall'80,1% (non vincolato) all'83,8%. Su Last Letter e Shuffle Objects, i guadagni sono nell'intervallo di 1–3 punti. Questo contraddice la preoccupazione ampiamente citata secondo cui forzare il formato JSON degrada la qualità delle risposte — ma l'effetto è abbastanza piccolo che la scelta del formato non dovrebbe guidare la selezione del framework.
• Nessun framework copre tutte le 45 categorie di funzionalità JSON Schema. Guidance copre 13, Llamacpp e XGrammar ne coprono 1 ciascuno, e Outlines ne copre 0. L'implicazione pratica è che qualsiasi schema che usa if/then/else, unevaluatedProperties o definizioni ricorsive $ref si comporterà in modo imprevedibile a seconda del motore sottostante.

Cosa regge — e cosa no​

Il contributo più forte del benchmark è la selezione degli schemi. Le valutazioni precedenti usavano schemi giocattolo o collezioni di un'unica fonte. Includere configurazioni Kubernetes accanto alle firme di chiamata di funzione è il giusto tipo di diversità avversaria. La stratificazione per complessità (da banale a ultra) offre anche ai professionisti una curva di calibrazione: se i tuoi schemi assomigliano a chiamate di funzione GlaiveAI, XGrammar o Guidance vanno entrambi bene; se assomigliano a manifesti Kubernetes, le tue opzioni si restringono rapidamente.

La debolezza principale è la valutazione greedy a campione singolo. Misurare la copertura con una generazione per schema sottostima la capacità reale — un framework potrebbe fallire il 20% delle volte ma riuscire al secondo tentativo. L'articolo lo riconosce, ma non riporta numeri pass@k con campionamento della temperatura, che sarebbero rilevanti per sistemi in produzione che riprovano in caso di errore.

Il confronto mescola anche modelli non comparabili. I framework open source (Guidance, Outlines, Llamacpp, XGrammar) sono testati su Llama-3.2-1B, mentre OpenAI e Gemini eseguono i propri modelli non divulgati. Il 9% di copertura di OpenAI su GitHub-Hard potrebbe riflettere tanto la capacità del modello quanto l'architettura di decodifica vincolata. Un confronto equo richiederebbe un accesso controllato ai modelli — cosa che gli autori ovviamente non possono imporre ai fornitori proprietari.

Perché questo conta per l'AI finanziaria​

Ogni agente di scrittura Beancount genera output strutturato. Se l'agente emette direttive Beancount come JSON prima di convertirle in sintassi .beancount, o se chiama strumenti tramite schemi JSON, l'affidabilità di quella generazione JSON non è un dettaglio — è tutto il gioco. L'articolo FinTrace ha mostrato che i modelli all'avanguardia falliscono nel ragionare sugli output degli strumenti; JSONSchemaBench rivela un problema ortogonale: anche prima del ragionamento, il livello di formattazione può emettere silenziosamente output non conformi.

Il risultato Kubernetes è particolarmente eloquente per Beancount. Gli schemi di ledger non sono sacche piatte di coppie chiave-valore. Le gerarchie di conti, i metadati delle transazioni e le strutture dei tag creano pattern ricorsivi annidati simili agli oggetti API Kubernetes. Un framework che segna il 7% su Kubernetes non è pronto per schemi di ledger complessi, indipendentemente dalla velocità del suo overhead per token.

Il modo di fallimento sotto-vincolato è quello per cui perderei il sonno. Un agente Beancount che usa XGrammar potrebbe emettere una transazione che supera il controllo di validazione interno del framework ma viola lo schema effettivo — e l'agente non avrebbe alcun motivo di riprovare. La corruzione silenziosa è peggiore del fallimento visibile.

Cosa leggere dopo​

• XGrammar (arXiv:2411.15100, Dong et al.) — l'articolo tecnico dietro uno dei framework più veloci testati, che spiega la suddivisione token indipendente/dipendente dal contesto e perché gli schemi Kubernetes lo stressano.
• Grammar-Aligned Decoding / ASAp (NeurIPS 2024) — mostra che il masking dei token nella decodifica vincolata può distorcere la distribuzione di probabilità del modello e propone un algoritmo di campionamento corretto; il fondamento teorico per le preoccupazioni sulla qualità che il benchmark misura solo indirettamente.
• XGrammar-2 (arXiv:2601.04426) — un seguito che estende XGrammar a schemi dinamici in contesti agentici dove lo schema stesso cambia durante una sessione multi-turno, direttamente rilevante per agenti Beancount che adattano il loro formato di output in base a quali tipi di conto sono attivi.