Lotook
Structured outputs is een functie van een LLM API die het antwoord van een model laat voldoen aan een door u opgegeven JSON Schema. Met constrained decoding compileert de API uw schema tot een grammatica of toestandsmachine die de generatie van tokens beperkt en zo syntaxisfouten en ontbrekende velden voorkomt bij de API’s van OpenAI, Anthropic en Google.
Wat zijn Structured Outputs in een LLM API?
Structured outputs in een LLM API beperkt de door een model gegenereerde tokens, zodat het volledige antwoord overeenkomt met een door de ontwikkelaar opgegeven JSON Schema. Zowel Anthropic als Google beschrijft het onderliggende mechanisme als constrained decoding: voordat de sampling begint, compileert de API uw schema tot een grammatica of eindige toestandsmachine die elk volgend token uitsluit dat de structuur, sleutelnamen of waardetypen van het schema zou schenden.
Zonder structured outputs werkt een taalmodel in een prompt vragen om in JSON te antwoorden niet consistent in productie. De documentatie van Anthropic noemt vier veelvoorkomende soorten fouten wanneer alleen op promptinstructies wordt vertrouwd: parsefouten door ongeldige JSON-syntaxis, ontbrekende verplichte velden, inconsistente gegevenstypen en schemaovertredingen die foutafhandeling en nieuwe pogingen vereisen. In de praktijk zien die fouten er bijvoorbeeld zo uit:
- Parsefouten door ongeldige JSON-syntaxis: Niet-afgesloten accolades, afsluitende komma’s of Markdown-tekst rond de gegevens kunnen bijvoorbeeld een JSON-parser verstoren.
- Ontbrekende verplichte velden: Een model kan bijvoorbeeld een sleutel weglaten die de applicatiecode verderop verwacht.
- Inconsistente gegevenstypen: Een numeriek veld kan bijvoorbeeld als tekenreeks binnenkomen, of een enkele waarde in plaats van een array.
- Schemaovertredingen die foutafhandeling en nieuwe pogingen vereisen: Niet-gevraagde sleutels of waarden buiten het bereik dwingen bijvoorbeeld tot herhalingslussen en defensieve validatiecode.
Constrained decoding maakt sterk geformuleerde opmaakinstructies in uw prompt overbodig. Om applicatietypen in overeenstemming te houden met het schema dat u aan de API doorgeeft, bieden OpenAI en Google native SDK-hulpmiddelen die Pydantic BaseModel-klassen in Python en Zod-objecten in JavaScript accepteren. De Python SDK van Anthropic accepteert een Pydantic-model via client.messages.parse() en parseert het antwoord naar dat type.
Waarin verschillen Structured Outputs van JSON mode en JSON met alleen een prompt?
Structured outputs garandeert naleving van uw exacte JSON Schema, terwijl JSON mode en instructies met alleen een prompt geen specifieke eigenschapsnamen, geneste structuren of verplichte velden kunnen afdwingen.
JSON mode was de tussenstap voordat volledige schemabeperkingen bestonden. Bij OpenAI zorgt het inschakelen van JSON mode via { "type": "json_object" } ervoor dat het model syntactisch geldige JSON produceert, mits het verzoek geen uitzonderingsgeval treft, zoals het opraken van uitvoertokens midden in een object. De documentatie van OpenAI noemt echter expliciete beperkingen: u moet ergens in de gesprekscontext een instructie opnemen om JSON uit te voeren, anders geeft de API een fout als het woord JSON ontbreekt en kan het model anders een eindeloze stroom witruimte genereren totdat het de tokenlimiet bereikt.
OpenAI beschrijft structured outputs als de evolutie van JSON mode en raadt aan structured outputs te gebruiken waar dat wordt ondersteund, en JSON mode te bewaren voor oudere modellen zoals gpt-4-turbo en eerdere versies.
| Functie | JSON met alleen prompt | JSON mode | Structured Outputs |
|---|---|---|---|
| Geldige JSON-syntaxis gegarandeerd | Nee | Ja, tenzij afgekapt | Ja, tenzij geweigerd of afgekapt |
| Dwingt exact schema en typen af | Nee | Nee | Ja |
| Vereist JSON-instructie in prompt | Ja | Ja, vereist door OpenAI | Nee |
| Voorkomt nieuwe opmaakpogingen | Nee | Gedeeltelijk | Ja, voor de schemavorm |
| Native parsing met Pydantic en Zod | Handmatig | Handmatig | Ondersteund door SDK’s van leveranciers |
Structured Outputs versus Function Calling: wanneer gebruikt u welke?
Structured outputs formatteert het uiteindelijke antwoord van het model aan uw applicatie of eindgebruiker, terwijl function calling het model tijdens de uitvoering verbindt met externe tools, API’s en gegevensbronnen.
Ontwikkelaars verwarren de twee functies vaak omdat beide op JSON Schema-definities berusten. OpenAI en Google trekken dezelfde architecturale grens:
- Gebruik structured outputs wanneer u het definitieve assistentbericht netjes wilt formatteren voor uw UI, database of downstream-pipeline, bijvoorbeeld voor gegevensextractie of gestructureerde classificatie.
- Gebruik function calling (tool use) wanneer het model een actie moet aanvragen, actuele gegevens moet opzoeken of een backendroutine moet aanroepen voordat het kan antwoorden. Lees onze gids over tool calling en MCP voor meer informatie over tooldefinities in moderne protocollen.
OpenAI biedt strikte schema’s in twee verschillende vormen: function calling met strikte schema’s om het model met tools of gegevens te verbinden, en een json_schema-antwoordformaat om het antwoord aan de gebruiker te structureren. Anthropic scheidt zijn functies in output_config.format voor het definitieve antwoord van Claude en strict: true op afzonderlijke tools om geldige toolnamen en invoerargumenten te garanderen, en ondersteunt expliciet het gebruik van beide in één verzoek. De combinatie is vooral praktisch in workflows met AI-agenten, waarin tussentijdse toolaanroepen en de uiteindelijke samenvatting aan strikte afspraken moeten voldoen.
Hoe OpenAI, Anthropic en Google Structured Outputs implementeren
OpenAI, Anthropic en Google implementeren structured outputs elk via schemacompilatie, vanaf november 2026, maar hun verzoekparameters, ondersteunde JSON Schema-sleutelwoorden en complexiteitslimieten verschillen.
| Aanbieder | Inschakelen | SDK-schemahulpmiddelen | Belangrijke schemaregels | Belangrijke limieten |
|---|---|---|---|---|
| OpenAI | Responses API text.format of Chat Completions response_format met type: "json_schema" en strict: true |
Pydantic BaseModel (Python), Zod (JS) |
Root moet een object zijn, geen anyOf; alle velden in required; additionalProperties: false vereist; sleutels in schemavolgorde uitgegeven |
Maximaal 5.000 eigenschappen, 10 nestniveaus, 120.000 tekens voor namen/enums, 1.000 enumwaarden |
| Anthropic Claude | output_config.format met type: "json_schema", plus strict: true op tools |
client.messages.parse() met Pydantic (Python) |
Ondersteunt $ref/$defs, anyOf en allOf (met beperkingen); additionalProperties: false vereist; geen grenzen voor getallen of tekenreekslengte |
Maximaal 20 strikte tools, 24 optionele parameters, 16 unionparameters, 180s compilatietime-out; grammaticacache van 24 uur |
| Google Gemini API | Antwoordconfiguratie met teksttype, mime_type: "application/json" en schema |
Pydantic (Python), Zod (JS) | Ondersteunt minimum/maximum, minItems/maxItems, prefixItems; verwijdert niet-ondersteunde grenzen zonder melding |
Grote of diep geneste schema’s mislukken met 400 INVALID_ARGUMENT |
OpenAI
OpenAI ondersteunt structured outputs vanaf GPT-4o en beveelt gpt-6-astra aan voor nieuwe projecten. Een API-aanroep met strict: true en een niet-ondersteund sleutelwoord zoals allOf, not, if/then/else, dependentRequired of dependentSchemas geeft een fout terug in plaats van ongemerkt te mislukken. OpenAI ondersteunt tekenreeksformaten waaronder date-time, time, date, duration, email, hostname, ipv4, ipv6 en uuid, evenals numerieke grenzen (minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf) en arraygrenzen (minItems, maxItems).
Anthropic Claude
Anthropic ondersteunt structured outputs voor alle modellen op de Messages API, maar niet binnen Managed Agents. Als u client.messages.parse() in de Python SDK gebruikt, worden niet-ondersteunde beperkingen zoals minimum, maximum, minLength en maxLength automatisch naar veldbeschrijvingen verplaatst zodat Claude de bedoeling ziet, en valideert de SDK de teruggegeven gegevens lokaal tegen uw oorspronkelijke Pydantic-model.
Claude bewaart gecompileerde grammatica’s 24 uur na het laatste gebruik in de cache; een wijziging van de schemastructuur of de toolset maakt die grammaticacache ongeldig, maar het aanpassen van veldnamen of beschrijvingen niet. Omdat Claude ook een automatische systeemprompt ontvangt die het JSON-formaat uitlegt, stijgt het aantal invoertokens licht en maakt een wijziging van output_config.format de promptcache van het gesprek ongeldig. Verplichte eigenschappen worden eerst uitgegeven, gevolgd door optionele. Structured outputs werkt met streaming, tokens tellen en Batch processing (met 50 procent korting van Anthropic). De combinatie van JSON-uitvoer met Citations geeft echter een 400-fout en structured outputs is niet compatibel met het vooraf invullen van berichten.
Google Gemini API
Google noemt gegevensextractie, gestructureerde classificatie en agentworkflows als belangrijkste toepassingen van structured outputs in Gemini. Anders dan OpenAI en Anthropic verwijdert en negeert Gemini verschillende sleutelwoorden zonder foutmelding, waaronder minLength, maxLength, minProperties, maxProperties, uniqueItems, contains, minContains en maxContains. Voer altijd Pydantic model_validate_json() of Zod .parse() uit op antwoorden van Gemini om die beperkingen in de applicatiecode af te dwingen. Als Gemini 400 INVALID_ARGUMENT teruggeeft voor een te complex schema, adviseert Google om nestingen af te vlakken, optionele velden of enums te verminderen, eigenschapsnamen te verkorten en niet-structurele regels naar veldbeschrijvingen te verplaatsen.
Hoe ontwerpt u een betrouwbaar JSON Schema voor LLMs?
Een betrouwbaar JSON Schema voor structured outputs van LLMs blijft vlak, maakt velden verplicht en gebruikt typen die null toestaan in plaats van optionele sleutels. Schema’s ontwerpen volgens gedeelde regels voor meerdere aanbieders helpt compilatiefouten en onverwachte afwijzingen tijdens uitvoering te voorkomen.
Gebruik deze checklist voordat u een schema voor OpenAI, Claude of Gemini uitbrengt:
- Houd de nesting ondiep: Vlak diep geneste objecten waar mogelijk af om ruim onder de grens van 10 niveaus van OpenAI te blijven en compilatieafwijzingen door Gemini of Claude te voorkomen.
- Maak elk veld verplicht: Neem elke objectsleutel op in
required, omdat OpenAI deze regel strikt handhaaft en Claude het totaal aan optionele parameters per verzoek op 24 begrenst. - Gebruik unions die null toestaan voor ontbrekende gegevens: Geef optionele waarden weer met
"type": ["string", "null"]in plaats van sleutels uitrequiredweg te laten. - Beperk objecten: Stel
"additionalProperties": falsein voor elke objectdefinitie, zoals OpenAI en Anthropic beide vereisen. - Beperk vaste keuzes met enums: Vervang vrije tekenreekscategorieën door expliciete
enum-arrays als alleen een bekende reeks labels geldig is. - Schrijf duidelijke beschrijvingen: Zet domeinregels en genegeerde beperkingen, zoals gewenste tekenlengtes of terugvalinstructies, in de
descriptionvan elke eigenschap.
Hieronder staat een voorbeeldschema voor het classificeren van een klantenserviceticket. Het volgt de bovenstaande regels voor meerdere aanbieders: een object als root, alle velden verplicht, een veld dat null toestaat voor optionele metadata, additionalProperties: false en een enum voor routering.
{
"type": "object",
"additionalProperties": false,
"required": ["category", "urgency", "summary", "order_id"],
"properties": {
"category": {
"type": "string",
"enum": ["billing", "bug_report", "account_access", "other"],
"description": "Primary topic of the support message."
},
"urgency": {
"type": "string",
"enum": ["low", "normal", "high"],
"description": "Escalation priority based on user impact."
},
"summary": {
"type": "string",
"description": "One-sentence summary of the issue in 25 words or fewer."
},
"order_id": {
"type": ["string", "null"],
"description": "Order identifier if present in the message, otherwise null."
}
}
}Wat kan er nog misgaan met Structured Outputs?
Structured outputs garandeert geldige syntaxis volgens uw schema, maar productieapplicaties krijgen nog steeds te maken met weigeringen, afgekapt tokens, gehallucineerde waarden, afwijkend hoofdlettergebruik in enums, vertraging bij het eerste verzoek en niet-vertrouwde gebruikersinvoer. Door schemaovereenstemming als syntaxiscontrole te behandelen en niet als waarheids- of veiligheidscontrole, voorkomt u ongemerkte fouten in productie.
Veiligheidsweigeringen en afkappen bij de tokenlimiet
Modellen kunnen onveilige gebruikersverzoeken nog steeds weigeren of midden in de generatie stoppen wanneer de limiet voor uitvoertokens wordt bereikt. Bij OpenAI vult een veiligheidsweigering een afzonderlijk veld refusal dat niet aan uw JSON Schema voldoet. Bij Anthropic Claude geeft een weigering HTTP 200 terug met stop_reason ingesteld op "refusal" (waarvoor nog steeds kosten worden gerekend) en gaat deze boven uw schema; evenzo geeft het bereiken van de uitvoerlimiet stop_reason "max_tokens" met onvolledige JSON terug. Controleer altijd weigeringsindicatoren en stopredenen voordat u JSON.parse() of een validator aanroept.
Schema-geldige maar feitelijk onjuiste waarden
Constrained decoding dwingt het model uw schema te vullen, ook als de brontekst geen antwoord bevat of de aannames van het schema tegenspreekt. Een antwoord kan alle controles op type en enum doorstaan en toch verzonnen datums, verkeerde categorieën of aannemelijk klinkende gissingen bevatten. OpenAI adviseert om het model in de prompt te instrueren wat het moet teruggeven als de invoer niet verenigbaar is met het schema, bijvoorbeeld null of lege velden. Google waarschuwt ontwikkelaars waarden in code aan bedrijfsregels te toetsen. Lees voor meer informatie over waarom zelfverzekerde antwoorden toch fout kunnen zijn onze gids over AI-hallucinatiepercentages.
Hoofdlettergebruik van enums bij Claude en compilatielatentie
Twee operationele bijzonderheden verrassen teams tijdens de uitrol:
- Hoofdlettergebruik van enums bij Claude: Anthropic merkt op dat hoofdlettergebruik van enums bij constrained decoding niet gegarandeerd is. Vergelijk teruggegeven enumtekenreeksen daarom hoofdletterongevoelig in uw applicatielogica.
- Compilatievertraging bij het eerste verzoek: Claude voegt extra vertraging toe wanneer een nieuw schema voor het eerst wordt gecompileerd tot een grammatica, voordat het 24 uur in de cache wordt opgeslagen. OpenAI noemt een vergelijkbare vertraging bij de eerste schemaverwerking voor fijn afgestemde modellen.
Prompt Injection binnen veldwaarden
De uitvoerstructuur beperken neutraliseert geen kwaadaardige instructies die zijn verborgen in niet-vertrouwde tekst die wordt samengevat of geëxtraheerd naar een JSON-tekenreeksveld. Een model kan correct geldige JSON teruggeven waarvan het veld summary of notes geïnjecteerde instructies of misleidende inhoud voor downstream-tools of menselijke beoordelaars bevat. Behandel elke geparseerde veldwaarde als niet-vertrouwde invoer en lees onze inleiding over wat prompt injection is voordat u geëxtraheerde velden aan geautomatiseerde acties doorgeeft.
Veelgestelde vragen
Vertraagt structured outputs de antwoorden van LLMs?
Structured outputs kan bij het eerste verzoek met een nieuw schema vertraging toevoegen, terwijl latere verzoeken uit de cache zonder compilatieoverhead verlopen. Anthropic bewaart gecompileerde Claude-grammatica’s 24 uur na het laatste gebruik, tenzij u de schemastructuur of tooldefinities wijzigt. OpenAI noemt extra latentie bij de eerste schemaverwerking alleen bij fijn afgestemde modellen.
Kan een LLM nog hallucineren bij gebruik van structured outputs?
Ja, een LLM kan nog steeds waarden hallucineren terwijl het JSON teruggeeft die voor 100 procent aan het schema voldoet. Constrained decoding beperkt de syntaxis van tokens en veldtypen, niet de feitelijke juistheid. Als de invoer vereiste informatie mist, kan het model waarden verzinnen om verplichte sleutels te vullen, tenzij u velden toestaat die null kunnen zijn en aangeeft wanneer null moet worden teruggegeven.
Moet ik Pydantic of Zod gebruiken met structured output API’s?
Native SDK-schemahulpmiddelen helpen applicatietypen en API-schema’s op elkaar af te stemmen. OpenAI en Google ondersteunen zowel Pydantic in Python als Zod in JavaScript, terwijl de Python SDK van Anthropic Pydantic ondersteunt via client.messages.parse(). Deze hulpmiddelen zetten uw modellen om in JSON Schema, parseren antwoorden naar getypeerde objecten en valideren beperkingen zoals tekenreekslengtes die Gemini verwijdert of Anthropic naar veldbeschrijvingen verplaatst.
Wat gebeurt er als een model een verzoek weigert terwijl structured outputs is ingeschakeld?
Als een model een verzoek om veiligheidsredenen weigert, gaat de weigering boven uw JSON Schema. OpenAI plaatst de uitleg in een apart refusal-veld in plaats van het schema te volgen, terwijl Anthropic HTTP 200 teruggeeft met stop_reason ingesteld op "refusal". Uw applicatie moet die velden controleren voordat zij JSON probeert te parseren.
Waarom wijst Claude of Gemini mijn JSON Schema af met een 400-fout?
Zowel Claude als Gemini wijst schema’s die de interne complexiteitslimieten van grammatica of toestandsmachine overschrijden af met een 400-fout. Claude geeft ook een 400-fout terug als u niet-ondersteunde schemafuncties zoals recursieve schema’s of numerieke grenzen opneemt, of als u JSON-uitvoer combineert met Citations. Geneste objecten afvlakken, namen verkorten en optionele of unionparameters verminderen lost compilatieafwijzingen meestal op.
