# Varför går strukturerad JSON-utdata sönder efter en LLM-API-migrering? > Strukturerad JSON går vanligtvis sönder efter en LLM-API-migrering eftersom gamla och nya stackar tillämpar olika kontrakt. Jämför begärandescheman, svarslägen, streamingbeteende, kuvert för verktygsanrop, avböjanden och valideringsregler innan du skyller på prompten. En migrering ändrar mer än värdnamnet. Den kan ändra modellen, SDK-serialisering, stödda schemanyckelord, ordning för strömningshändelser, standardvärden för sampling, säkerhetsbeteende och den exakta platsen för den genererade nyttolasten. En begäran som ser likvärdig ut i applikationskoden kan därför representera ett annat kontrakt över nätet. Den snabbaste diagnosen är att spara en misslyckad begäran och dess oförändrade svar från båda leverantörerna. Diffa de faktiska HTTP-kropparna, inte de wrapper-objekt som ditt SDK exponerar. Den jämförelsen avslöjar vanligtvis om felet uppstår före generering, under generering eller medan din applikation extraherar och validerar resultatet. ## Separera syntaxfel från kontraktsfel "JSON gick sönder" kan beskriva flera olika defekter. Att behandla dem som ett problem leder till promptändringar som döljer den verkliga orsaken. * Ett syntaxfel producerar text som en JSON-parser inte kan läsa. * Ett schemafel producerar giltig JSON med fel nycklar, typer, nästning eller enumvärden. * Ett extraktionsfel uppstår när giltig strukturerad data finns i ett annat svarsfält. * Ett strömningsfel uppstår när partiella delar tolkas som kompletta dokument. * Ett avvisnings- eller trunkeringsfel ersätter det förväntade objektet med ett säkerhetsmeddelande eller en ofullständig nyttolast. * Ett verktygsanropsfel returnerar argument i ett verktygsomslag medan applikationen förväntar sig assistenttext. Logga dessa kategorier separat. Ett parserundantag, ett saknat obligatoriskt fält och en API-nivå `400` bör inte dela en generisk återförsöksräknare. ## Jämför de två begärandekontrakten Börja med en fält-för-fält-migreringsmatris. Namn som ser liknande ut betyder inte alltid samma sak. | Kontraktsområde | Gammal stack | Ny stack | Testfråga | |---|---|---|---| | Utdataläge | JSON-objekt | Schemabundet objekt | Garanterar det endast syntax eller hela schemat? | | Schemats placering | Verktygsparametrar | Svarsformat | Är schemat kopplat till rätt begärandefält? | | Strikthet | Implicit | Explicit flagga | Måste strikt läge aktiveras? | | Icke-stödda nyckelord | Ignoreras | Avvisas | Accepteras unioner, format, standardvärden eller referenser? | | Ytterligare nycklar | Tillåtna | Blockerade | Hanteras `additionalProperties` konsekvent? | | Strömning | Textdeltan | Typade händelser | Vilken händelse innehåller det slutförda objektet? | | Avvisningar | Assistenttext | Dedikerat fält | Kan extraktorn skilja avvisning från utdata? | Fånga den slutliga serialiserade begäran efter SDK-bearbetning. Standardvärden som införts av den gamla klienten kan försvinna under migreringen. Det omvända händer också: ett nytt SDK kan lägga till en strikt flagga eller byta namn på ett svarsformatsfält utan ett uppenbart applikationsfel. ## Minska schemat innan du ändrar prompten Testa det minsta möjliga schemat först. Börja med en obligatorisk sträng och inga valfria grenar. Lägg till heltal, arrayer, nästlade objekt, enums och villkorliga strukturer en i taget. Detta isolerar icke-stödda funktioner mycket snabbare än att upprepade gånger skriva om en produktionsprompt. Till exempel kan en portabel baslinje se ut så här: ```json { "type": "object", "properties": { "decision": { "type": "string", "enum": ["approve", "review", "reject"] }, "reason": { "type": "string" } }, "required": ["decision", "reason"], "additionalProperties": false } ``` Om detta fungerar är transporten och den grundläggande tillämpningsvägen sund. Om produktionsschemat misslyckas efter att en funktion lagts till har du en specifik kompatibilitetsfråga istället för ett vagt modellkvalitetsproblem. ## Inspektera var den strukturerade nyttolasten finns Leverantörsmigreringar bryter ofta extraktionskoden. En stack kan returnera JSON i ett assistentmeddelande, en annan i en parsad bekvämlighetsegenskap och en tredje som strängifierade verktygsargument. Strömning kan exponera en sekvens av typade händelser istället för vanliga textdeltan. Skapa ett normaliserat internt resultat innan resten av applikationen ser svaret: ```ts type StructuredResult = { data: T | null; raw: unknown; refusal: string | null; finishReason: string | null; validationErrors: string[]; }; ``` Behåll `raw` under migreringsperioden. Det är beviset som behövs för att skilja ett modellutdatafel från ett adapterfel. Redigera bort känsligt innehåll innan du lagrar loggar och ange en lagringsperiod som är lämplig för din applikation. ## Tolka inte en oavslutad ström Ett JSON-dokument är vanligtvis ogiltigt tills dess sista byte anländer. Att tolka varje textdelta kommer att generera förväntade fel som ser ut som produktionsfel. Antingen buffra hela utdata, använd en leverantörsstödd inkrementell JSON-parser, eller konsumera en dokumenterad händelse som representerar det slutförda strukturerade svaret. Ditt strömningstest bör täcka mer än happy path: * strängar uppdelade över flera delar; * escapade citattecken och Unicode-tecken; * arrayer med många element; * en frånkoppling före den avslutande klammerparentesen; * en avvisningshändelse; * ett giltigt slutligt objekt följt av användningsmetadata; * verktygsargument levererade i flera deltan. Behandla ett nätavbrott som en ofullständig generering, inte som felaktig modellutdata. Att försöka igen kan vara säkert för en skrivskyddad klassificeringsbegäran, men det kanske inte är säkert om resultatet utlöser en extern bieffekt. ## Validera två gånger, men reparera försiktigt Leverantören kan tillämpa ett schema, men din applikation bör fortfarande validera det normaliserade resultatet vid sin förtroendegräns. Detta skyddar dig från adapterfel, funktionsregressioner och antaganden som leverantören aldrig lovade. En praktisk sekvens är: 1. Bekräfta att HTTP-begäran lyckades. 2. Identifiera avvisning, trunkering eller slutförande av verktygsanrop explicit. 3. Extrahera den slutförda strukturerade nyttolasten. 4. Tolka den en gång. 5. Validera den med applikationens schemaversion. 6. Avvisa okända eller osäkra värden innan affärslogiken körs. Undvik en obegränsad "fixa denna JSON"-loop. En reparationsmodell kan ändra betydelse medan den gör syntaxen giltig. Om reparation är acceptabel, begränsa den till ett försök, tillhandahåll valideringsfelen, bevara den ursprungliga utdatan och validera det reparerade objektet igen. För högriskåtgärder, skicka ärendet för granskning istället. ## Bygg en migreringsåterspelningsoch-svit Innan du dirigerar produktionstrafik, sammanställ en kompakt korpus från verkliga begärandeformer. Ta bort personliga eller konfidentiella data och inkludera sedan fall som utmanar gränserna för ditt kontrakt. | Fallgrupp | Vad som ska inkluderas | Godkännandevillkor | |---|---|---| | Normal | Vanliga korta indata | Giltigt objekt med förväntade värden | | Valfria fält | Saknade och närvarande varianter | Obligatoriskt och valfritt beteende matchar kontraktet | | Tvetydig | Motstridiga eller underbestämda indata | Giltigt objekt plus ett tillåtet osäkerhetstillstånd | | Lång kontext | Nära applikationens normala maximum | Ingen trunkering och giltig extraktion | | Adversariell | Text som ber modellen ignorera schemat | Schemat förblir intakt | | Avvisning | Otillåten eller osäker begäran | Avvisning upptäcks utan parserförvirring | | Strömning | Delgränser och frånkopplingar | Endast slutförda nyttolaster når validering | Kör båda leverantörerna med stabila parametrar och registrera giltighetsgrad, semantisk överensstämmelse, avvisningsfrekvens, trunkeringsfrekvens, latens och antal återförsök. Exakt semantisk likhet förväntas inte alltid, men schemagiltighet bör vara en hård grind. ## Lägg kompatibilitet bakom en adapter Låt inte leverantörens svarstyper läcka genom hela kodbasen. En liten adapter bör äga begärandekonstruktion, kontroller av schemakapacitet, svarsextraktion, avslutsorsaker, användningsfält och felnormalisering. Resten av applikationen bör konsumera ett internt gränssnitt. En OpenAI-kompatibel gateway som [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=structured-json-output-after-llm-api-migration) kan minska upprepade integrationsarbeten när en applikation använder text-, bild- och videomodeller. Kompatibilitet på transportlagret är användbart, men det tar inte bort modellnivåtestning. Behåll kapacitetsflaggor för strukturerad utdata, verktyg, strömning och schemafunktioner istället för att anta att varje modell bakom en kompatibel slutpunkt beter sig identiskt. Versionshantera adaptern och schemat tillsammans. När ett schema ändras, lagra schemaversionen med utdatan så att nedströms tjänster vet vilket kontrakt de fick. ## Använd en stegvis utrullning med tydliga stoppvillkor Börja med offline-återspelning, sedan skuggtrafik, sedan en liten live-procent. Förlita dig inte enbart på aggregerad framgång. En giltighetsgrad på 99 % kan fortfarande vara oacceptabel om de 1 % misslyckandena klustrar i betalnings-, modererings- eller auktoriseringsbegäranden. Definiera stoppvillkor före testet: * någon osäker enum når affärslogiken; * schemagiltighetsgraden sjunker under nuvarande baslinje; * avvisningshanteringen blir tvetydig; * trunkeringen ökar bortom den överenskomna tröskeln; * återförsök ökar kostnad eller latens bortom applikationens budget; * råa svar kan inte stämmas av mot normaliserade utdata. Rulla tillbaka via routningskonfiguration istället för en nödkodutrullning när det är möjligt. Behåll den gamla adaptern tillgänglig tills den nya vägen har överlevt både toppbelastning och ovanliga indataklasser. ## Sammanfattning Strukturerade JSON-fel efter en LLM API-migrering är vanligtvis kontraktsavvikelser, extraktionsmisstag eller ofullständig strömningslogik snarare än bevis på att den nya modellen inte kan följa instruktioner. Diffa nyttolasterna över nätet, krymp schemat, normalisera svar, validera vid applikationsgränsen och spela upp en representativ korpus innan du flyttar trafik. Ett kompatibelt API kan förenkla flytten, men explicita kapacitetstester förblir det tillförlitliga sättet att skydda produktionsbeteende. ## FAQ ### Varför fungerar samma JSON-prompt med en modell men misslyckas med en annan? Promptens formulering är bara ett lager. Modeller och leverantörer skiljer sig åt när det gäller inbyggda JSON-lägen, schemastöd, tokenisering, vägranbeteende och hur strikt de följer begränsningar. ### Är JSON-läge samma sak som JSON Schema-tvingande? Nej. JSON-läge kan bara garantera syntaktiskt giltig JSON, medan schematillämpning även begränsar nycklar, typer, obligatoriska fält och ibland ytterligare egenskaper. ### Bör jag parsa strömmad JSON token för token? Vanligtvis inte. Buffra hela den strukturerade nyttolasten eller använd leverantörens dokumenterade händelser för strukturerad streaming och validera sedan efter den sista händelsen. ### Kan ett OpenAI-kompatibelt API eliminera migreringsarbete? Det kan minska ändringar i transport och SDK, men du behöver fortfarande verifiera modellspecifika schemafunktioner, avslutningsorsaker, format för verktygsanrop och felbeteende. ### Vad ska hända när validering misslyckas? Fånga råsvaret, klassificera felet, försök bara igen i säkra, övergående fall och låt deterministisk reparation gå genom ett avgränsat valideringssteg i stället för att tyst acceptera felformad data. ### Vilket är det snabbaste förproduktionstestet? Spela upp en fast korpus av normala, tvetydiga, adversariella, avböjnings-, långkontext- och streamingförfrågningar mot båda stackarna och jämför validerade utdata fält för fält.