# Perché l'output JSON strutturato si rompe dopo una migrazione dell'API LLM? > Il JSON strutturato di solito si rompe dopo una migrazione di API LLM perché lo stack vecchio e quello nuovo applicano contratti diversi. Confronta schemi di richiesta, modalità di risposta, comportamento in streaming, envelope delle chiamate agli strumenti, rifiuti e regole di validazione prima di dare la colpa al prompt. Una migrazione cambia più del solo hostname. Può cambiare il modello, la serializzazione dell'SDK, le parole chiave dello schema supportate, l'ordine degli eventi di streaming, i valori di campionamento predefiniti, il comportamento di sicurezza e la posizione esatta del payload generato. Una richiesta che sembra equivalente nel codice dell'applicazione può quindi rappresentare un contratto diverso a livello di protocollo. La diagnosi più rapida consiste nel salvare una richiesta che fallisce e la sua risposta non modificata da entrambi i provider. Confronta i corpi HTTP effettivi, non gli oggetti wrapper esposti dal tuo SDK. Quel confronto di solito rivela se la rottura avviene prima della generazione, durante la generazione o mentre l'applicazione estrae e convalida il risultato. ## Distinguere gli errori di sintassi dagli errori di contratto "Il JSON è rotto" può descrivere diversi difetti. Trattarli come un unico problema porta a modifiche del prompt che nascondono la causa reale. * Un errore di sintassi produce testo che un parser JSON non riesce a leggere. * Un errore di schema produce JSON valido con chiavi, tipi, annidamenti o valori enum errati. * Un errore di estrazione si verifica quando dati strutturati validi sono presenti in un campo diverso della risposta. * Un errore di streaming si verifica quando chunk parziali vengono analizzati come documenti completi. * Un errore di rifiuto o troncamento sostituisce l'oggetto atteso con un messaggio di sicurezza o un payload incompleto. * Un errore di chiamata a tool restituisce argomenti in un envelope del tool mentre l'applicazione si aspetta testo dell'assistente. Registra queste categorie separatamente. Un'eccezione del parser, un campo obbligatorio mancante e un `400` a livello API non dovrebbero condividere un unico contatore generico di tentativi. ## Confronta i due contratti di richiesta Inizia con una matrice di migrazione campo per campo. Nomi che sembrano simili non sempre significano la stessa cosa. | Area del contratto | Stack precedente | Nuovo stack | Domanda di test | |---|---|---|---| | Modalità di output | Oggetto JSON | Oggetto vincolato allo schema | Garantisce solo la sintassi o l'intero schema? | | Posizione dello schema | Parametri del tool | Formato della risposta | Lo schema è collegato al campo corretto della richiesta? | | Rigore | Implicito | Flag esplicito | La modalità strict deve essere abilitata? | | Parole chiave non supportate | Ignorate | Rifiutate | Sono accettate unioni, formati, valori predefiniti o riferimenti? | | Chiavi aggiuntive | Consentite | Bloccate | `additionalProperties` è gestito in modo coerente? | | Streaming | Delta di testo | Eventi tipizzati | Quale evento contiene l'oggetto completato? | | Rifiuti | Testo dell'assistente | Campo dedicato | L'estrattore può distinguere un rifiuto dall'output? | Cattura la richiesta serializzata finale dopo l'elaborazione dell'SDK. I valori predefiniti introdotti dal vecchio client possono scomparire durante la migrazione. Accade anche il contrario: un nuovo SDK può aggiungere un flag strict o rinominare un campo del formato di risposta senza un evidente errore dell'applicazione. ## Riduci lo schema prima di modificare il prompt Verifica prima lo schema più piccolo possibile. Inizia con una stringa obbligatoria e nessun ramo opzionale. Aggiungi numeri interi, array, oggetti annidati, enum e strutture condizionali uno alla volta. Questo isola le funzionalità non supportate molto più rapidamente che riscrivere ripetutamente un prompt di produzione. Ad esempio, una baseline portabile potrebbe essere simile a questa: ```json { "type": "object", "properties": { "decision": { "type": "string", "enum": ["approve", "review", "reject"] }, "reason": { "type": "string" } }, "required": ["decision", "reason"], "additionalProperties": false } ``` Se funziona, il trasporto e il percorso di applicazione di base sono solidi. Se lo schema di produzione fallisce dopo l'aggiunta di una funzionalità, hai una specifica domanda di compatibilità invece di un vago problema di qualità del modello. ## Ispeziona dove risiede il payload strutturato Le migrazioni tra provider spesso rompono il codice di estrazione. Uno stack può restituire JSON in un messaggio dell'assistente, un altro in una proprietà di comodo già analizzata, e un altro ancora come argomenti del tool serializzati in stringa. Lo streaming può esporre una sequenza di eventi tipizzati anziché normali delta di testo. Crea un risultato interno normalizzato prima che il resto dell'applicazione veda la risposta: ```ts type StructuredResult = { data: T | null; raw: unknown; refusal: string | null; finishReason: string | null; validationErrors: string[]; }; ``` Mantieni `raw` durante il periodo di migrazione. È la prova necessaria per distinguere un difetto dell'output del modello da un difetto dell'adattatore. Oscura i contenuti sensibili prima di archiviare i log e imposta un periodo di conservazione appropriato per la tua applicazione. ## Non analizzare uno stream non completato Un documento JSON di solito non è valido finché non arriva il suo byte finale. Analizzare ogni delta di testo genererà errori previsti che sembrano guasti di produzione. Puoi bufferizzare l'output completo, usare un parser JSON incrementale supportato dal provider oppure consumare un evento documentato che rappresenta la risposta strutturata finalizzata. Il tuo test di streaming dovrebbe coprire più del solo caso positivo: * stringhe suddivise tra più chunk; * virgolette con escape e caratteri Unicode; * array con molti elementi; * una disconnessione prima della parentesi graffa di chiusura; * un evento di rifiuto; * un oggetto finale valido seguito da metadati di utilizzo; * argomenti del tool consegnati in più delta. Tratta un'interruzione di rete come una generazione incompleta, non come output malformato del modello. Riprovare può essere sicuro per una richiesta di classificazione in sola lettura, ma potrebbe non esserlo se il risultato attiva un effetto collaterale esterno. ## Convalida due volte, ma ripara con cautela Il provider può applicare uno schema, ma la tua applicazione dovrebbe comunque convalidare il risultato normalizzato al proprio confine di fiducia. Questo ti protegge da errori dell'adattatore, regressioni delle funzionalità e presupposti che il provider non ha mai promesso. Una sequenza pratica è: 1. Conferma che la richiesta HTTP sia riuscita. 2. Rileva esplicitamente rifiuto, troncamento o completamento di una chiamata a tool. 3. Estrai il payload strutturato completato. 4. Analizzalo una volta. 5. Convalidalo con la versione dello schema dell'applicazione. 6. Rifiuta valori sconosciuti o non sicuri prima che venga eseguita la logica di business. Evita un ciclo illimitato di "correggi questo JSON". Un modello di riparazione può cambiare il significato mentre rende la sintassi valida. Se la riparazione è accettabile, limitarla a un tentativo, fornire gli errori di convalida, preservare l'output originale e convalidare di nuovo l'oggetto riparato. Per azioni ad alto impatto, invia invece il caso in revisione. ## Crea una suite di replay per la migrazione Prima di instradare il traffico di produzione, assembla un corpus compatto a partire da forme di richiesta reali. Rimuovi dati personali o riservati, quindi includi casi che mettono alla prova i confini del tuo contratto. | Gruppo di casi | Cosa includere | Condizione di superamento | |---|---|---| | Normale | Input brevi comuni | Oggetto valido con valori attesi | | Campi opzionali | Varianti mancanti e presenti | Il comportamento obbligatorio e opzionale corrisponde al contratto | | Ambiguo | Input in conflitto o sottospecificato | Oggetto valido più uno stato di incertezza consentito | | Contesto lungo | Vicino al massimo normale dell'applicazione | Nessun troncamento ed estrazione valida | | Avversariale | Testo che chiede al modello di ignorare lo schema | Lo schema rimane intatto | | Rifiuto | Richiesta non consentita o non sicura | Il rifiuto viene rilevato senza confusione del parser | | Streaming | Confini dei chunk e disconnessioni | Solo i payload completati raggiungono la convalida | Esegui entrambi i provider con parametri stabili e registra tasso di validità, accordo semantico, tasso di rifiuto, tasso di troncamento, latenza e numero di tentativi. L'uguaglianza semantica esatta non è sempre attesa, ma la validità dello schema dovrebbe essere un criterio obbligatorio. ## Metti la compatibilità dietro un adattatore Non lasciare che i tipi di risposta del provider si propaghino in tutta la codebase. Un piccolo adattatore dovrebbe occuparsi della costruzione della richiesta, dei controlli delle capacità dello schema, dell'estrazione della risposta, dei motivi di conclusione, dei campi di utilizzo e della normalizzazione degli errori. Il resto dell'applicazione dovrebbe consumare un'unica interfaccia interna. Un gateway compatibile con OpenAI come [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=structured-json-output-after-llm-api-migration) può ridurre il lavoro di integrazione ripetuto quando un'applicazione usa modelli di testo, immagini e video. La compatibilità a livello di trasporto è utile, ma non elimina i test a livello di modello. Mantieni flag di capacità per output strutturato, tool, streaming e funzionalità dello schema invece di presumere che ogni modello dietro un endpoint compatibile si comporti allo stesso modo. Versiona insieme l'adattatore e lo schema. Quando uno schema cambia, archivia la versione dello schema con l'output così che i servizi a valle sappiano quale contratto hanno ricevuto. ## Usa un rilascio graduale con chiare condizioni di arresto Inizia con replay offline, poi traffico shadow, poi una piccola percentuale live. Non affidarti solo al successo aggregato. Un tasso di validità del 99% può comunque essere inaccettabile se l'1% di errori si concentra in richieste di pagamento, moderazione o autorizzazione. Definisci le condizioni di arresto prima del test: * qualsiasi enum non sicuro raggiunge la logica di business; * il tasso di validità dello schema scende sotto la baseline attuale; * la gestione dei rifiuti diventa ambigua; * il troncamento supera la soglia concordata; * i tentativi aumentano costo o latenza oltre il budget dell'applicazione; * le risposte raw non possono essere riconciliate con gli output normalizzati. Esegui il rollback tramite configurazione di routing anziché un deployment di emergenza del codice, quando possibile. Mantieni disponibile il vecchio adattatore finché il nuovo percorso non ha superato sia il carico di picco sia le classi di input rare. ## In conclusione I fallimenti del JSON strutturato dopo una migrazione di API LLM sono di solito mancate corrispondenze di contratto, errori di estrazione o logica di streaming incompleta, più che prova che il nuovo modello non sappia seguire le istruzioni. Confronta i payload a livello di protocollo, riduci lo schema, normalizza le risposte, convalida al confine dell'applicazione e fai il replay di un corpus rappresentativo prima di spostare il traffico. Un'API compatibile può semplificare il passaggio, ma test espliciti delle capacità restano il modo affidabile per proteggere il comportamento di produzione. ## FAQ ### Perché lo stesso prompt JSON funziona con un modello ma fallisce con un altro? La formulazione del prompt è solo un livello. Modelli e provider differiscono per modalità JSON native, supporto degli schemi, tokenizzazione, comportamento di rifiuto e quanto rigorosamente rispettano i vincoli. ### La modalità JSON è la stessa cosa dell'applicazione di JSON Schema? No. La modalità JSON può garantire solo un JSON sintatticamente valido, mentre l'applicazione dello schema vincola anche chiavi, tipi, campi obbligatori e, talvolta, proprietà aggiuntive. ### Dovrei analizzare il JSON in streaming token per token? Di solito no. Memorizza nel buffer il payload strutturato completo oppure utilizza gli eventi di streaming strutturato documentati dal provider, poi convalida dopo l'evento finale. ### Un'API compatibile con OpenAI può eliminare il lavoro di migrazione? Può ridurre le modifiche al trasporto e all'SDK, ma devi comunque verificare le funzionalità dello schema specifiche del modello, i motivi di completamento, i formati delle chiamate agli strumenti e il comportamento in caso di errore. ### Cosa dovrebbe succedere quando la validazione fallisce? Cattura la risposta grezza, classifica il guasto, ritenta solo i casi transitori sicuri e indirizza la riparazione deterministica attraverso un passaggio di validazione delimitato anziché accettare silenziosamente dati malformati. ### Qual è il test di preproduzione più veloce? Riproduci un corpus fisso di richieste normali, ambigue, avversariali, di rifiuto, a contesto lungo e in streaming su entrambi gli stack e confronta gli output convalidati campo per campo.