446 lines
17 KiB
Markdown
446 lines
17 KiB
Markdown
# Structured Output and JSON Mode
|
|
|
|
**Last updated:** 2026-06-24
|
|
**Status:** GA
|
|
**Category:** Prompt Engineering & LLM Optimization
|
|
|
|
---
|
|
|
|
## Introduksjon
|
|
|
|
Strukturert output er en teknikk som tvinger LLM-modeller til å følge et spesifikt JSON Schema som du definerer i API-kallet ditt. Dette er en betydelig forbedring over den eldre JSON Mode-funksjonen, som kun garanterte syntaktisk gyldig JSON, men ikke kunne sikre at outputen følger et bestemt skjema.
|
|
|
|
**Strukturert output** gjør det mulig å:
|
|
- Definere nøyaktig hvilken datastruktur modellen skal returnere
|
|
- Eliminere parsing-feil og validerings-overhead
|
|
- Bygge robuste multi-steg workflows og integrasjoner
|
|
- Bruke type-safe objekter direkte i koden (via Pydantic i Python, for eksempel)
|
|
|
|
**JSON Mode** (eldre metode) garanterer kun at outputen er gyldig JSON, men gir ingen kontroll over strukturen. Microsoft anbefaler å bruke structured outputs fremfor JSON mode for alle nye implementasjoner på GPT-4o og nyere modeller.
|
|
|
|
**Viktig begrensning:** Strukturert output støttes for øyeblikket ikke med "bring your own data"-scenarier (Azure AI Search-integrasjon), Assistants API, eller Foundry Agents Service.
|
|
|
|
---
|
|
|
|
## Kjernekomponenter
|
|
|
|
### Response Format Types
|
|
|
|
| Type | Beskrivelse | Anbefalt bruk |
|
|
|------|-------------|---------------|
|
|
| `text` | Standard tekstformat, ingen spesifikk struktur | Generelle tekstrespons, kreativ skriving |
|
|
| `json_object` | Garanterer syntaktisk gyldig JSON, men ingen schema-validering | **Legacy** — erstattet av `json_schema` |
|
|
| `json_schema` | Tvinger modellen til å følge et JSON Schema med strict mode | **Anbefalt** for alle strukturerte output-behov |
|
|
|
|
### Structured Outputs med JSON Schema
|
|
|
|
**Python-eksempel (Microsoft Entra ID auth):**
|
|
|
|
```python
|
|
from pydantic import BaseModel
|
|
from openai import OpenAI
|
|
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
|
|
|
|
token_provider = get_bearer_token_provider(
|
|
DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
|
|
)
|
|
|
|
client = OpenAI(
|
|
base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
|
|
api_key=token_provider,
|
|
)
|
|
|
|
class CalendarEvent(BaseModel):
|
|
name: str
|
|
date: str
|
|
participants: list[str]
|
|
|
|
completion = client.beta.chat.completions.parse(
|
|
model="gpt-4o", # GPT-4o 2024-08-06 eller nyere
|
|
messages=[
|
|
{"role": "system", "content": "Extract the event information."},
|
|
{"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
|
|
],
|
|
response_format=CalendarEvent,
|
|
)
|
|
|
|
event = completion.choices[0].message.parsed
|
|
print(event) # name='Science Fair' date='Friday' participants=['Alice', 'Bob']
|
|
```
|
|
|
|
**REST API-eksempel:**
|
|
|
|
```bash
|
|
curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/chat/completions \
|
|
-H "api-key: $AZURE_OPENAI_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"model": "gpt-4o",
|
|
"messages": [
|
|
{"role": "system", "content": "Extract the event information."},
|
|
{"role": "user", "content": "Alice and Bob are going to a science fair on Friday."}
|
|
],
|
|
"response_format": {
|
|
"type": "json_schema",
|
|
"json_schema": {
|
|
"name": "CalendarEventResponse",
|
|
"strict": true,
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {"type": "string"},
|
|
"date": {"type": "string"},
|
|
"participants": {
|
|
"type": "array",
|
|
"items": {"type": "string"}
|
|
}
|
|
},
|
|
"required": ["name", "date", "participants"],
|
|
"additionalProperties": false
|
|
}
|
|
}
|
|
}
|
|
}'
|
|
```
|
|
|
|
### Function Calling med Structured Outputs
|
|
|
|
For function calling, aktiver structured outputs ved å sette `strict: true` i function-definisjonen.
|
|
|
|
**Viktig:** Strukturert output støtter ikke parallell function calling. Sett `parallel_tool_calls: false` når du bruker strict mode.
|
|
|
|
```python
|
|
from pydantic import BaseModel
|
|
import openai
|
|
from openai import OpenAI
|
|
|
|
class GetDeliveryDate(BaseModel):
|
|
order_id: str
|
|
|
|
tools = [openai.pydantic_function_tool(GetDeliveryDate)]
|
|
|
|
response = client.chat.completions.create(
|
|
model="gpt-4o",
|
|
messages=[
|
|
{"role": "system", "content": "You are a helpful customer support assistant."},
|
|
{"role": "user", "content": "What's the delivery date for order #12345?"}
|
|
],
|
|
tools=tools,
|
|
parallel_tool_calls=False # Påkrevd for structured outputs
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Arkitekturmønstre
|
|
|
|
### 1. Data Extraction Pattern
|
|
|
|
**Bruksområde:** Trekk strukturert informasjon fra ustrukturert tekst (e-poster, kundehenvendelser, dokumenter).
|
|
|
|
**Fordeler:**
|
|
- Ingen parsing-logikk nødvendig i applikasjonskoden
|
|
- Type-safe objekter direkte fra API-et
|
|
- Reduserer feilrate drastisk
|
|
|
|
**Ulemper:**
|
|
- Krever GPT-4o eller nyere modeller
|
|
- Økt token-forbruk sammenlignet med fritekst-output (marginal)
|
|
|
|
**Eksempel:**
|
|
```python
|
|
class CustomerFeedback(BaseModel):
|
|
sentiment: str # "positive", "neutral", "negative"
|
|
product_mentioned: list[str]
|
|
issues: list[str]
|
|
satisfaction_score: int # 1-5
|
|
|
|
completion = client.beta.chat.completions.parse(
|
|
model="gpt-4o",
|
|
messages=[
|
|
{"role": "system", "content": "Extract feedback details from customer email."},
|
|
{"role": "user", "content": email_text}
|
|
],
|
|
response_format=CustomerFeedback,
|
|
)
|
|
```
|
|
|
|
### 2. Multi-Step Workflow Pattern
|
|
|
|
**Bruksområde:** Bygge komplekse workflows der hvert steg produserer strukturert output som input til neste steg.
|
|
|
|
**Fordeler:**
|
|
- Lettere debugging og logging
|
|
- Kan cache mellomresultater
|
|
- Enklere å parallellisere uavhengige steg
|
|
|
|
**Ulemper:**
|
|
- Flere API-kall (økt latency og kostnad)
|
|
- Må håndtere feil i hvert steg
|
|
|
|
**Eksempel-workflow (fakta-sjekking):**
|
|
1. **Steg 1:** Trekk ut faktiske påstander fra tekst → `list[Claim]`
|
|
2. **Steg 2:** Generer søkespørsmål for hver påstand → `list[SearchQuery]`
|
|
3. **Steg 3:** Vurder pålitelighet basert på søkeresultater → `FactCheckReport`
|
|
|
|
### 3. Form-Filling Pattern
|
|
|
|
**Bruksområde:** Chatbots og assistenter som samler strukturert informasjon over flere meldinger.
|
|
|
|
**Fordeler:**
|
|
- Garanterer at alle påkrevde felter fylles ut
|
|
- Kan validere input underveis
|
|
- Enklere å integrere med backend-systemer
|
|
|
|
**Ulemper:**
|
|
- Kan føles rigid for brukere hvis ikke godt designet
|
|
- Krever state management på klientsiden
|
|
|
|
---
|
|
|
|
## Beslutningsveiledning
|
|
|
|
### Når bruke Structured Outputs vs JSON Mode
|
|
|
|
| Kriterium | Bruk Structured Outputs | Bruk JSON Mode | Bruk fritekst |
|
|
|-----------|------------------------|----------------|---------------|
|
|
| Trenger eksakt schema? | ✅ | ❌ | ❌ |
|
|
| Kun syntaktisk gyldig JSON? | ✅ | ✅ | ❌ |
|
|
| Kreativ eller fleksibel output? | ❌ | ❌ | ✅ |
|
|
| Integreres direkte med database? | ✅ | ⚠️ (må validere) | ❌ |
|
|
| Eldre modeller (GPT-3.5)? | ❌ | ✅ | ✅ |
|
|
| GPT-4o eller nyere? | ✅ | ⚠️ (deprecated) | ✅ |
|
|
|
|
### JSON Schema-begrensninger (strict mode)
|
|
|
|
| Begrensning | Detaljer |
|
|
|-------------|----------|
|
|
| **Nestingdybde** | Maks 5 nivåer |
|
|
| **Totalt antall properties** | Maks 100 properties på tvers av hele schemat |
|
|
| **Required fields** | Alle fields MÅ være `required` (bruk `["string", "null"]` for optional) |
|
|
| **additionalProperties** | MÅ være `false` for alle objekter |
|
|
| **Root type** | Kan ikke være `anyOf` |
|
|
| **Parallell function calling** | Ikke støttet med `strict: true` |
|
|
| **Usupporterte keywords** | String: `minLength`, `maxLength`, `pattern`, `format`. Number: `minimum`, `maximum`, `multipleOf`. Objects: `patternProperties`, `unevaluatedProperties`, `propertyNames`, `minProperties`, `maxProperties`. Arrays: `minItems`, `maxItems`, `uniqueItems`, `contains`, `minContains`, `maxContains`, `unevaluatedItems` |
|
|
|
|
**Støttede typer:** String, Number, Boolean, Integer, Object, Array, Enum, anyOf (nested).
|
|
|
|
**Recursive schemas:** Støttes via `$ref` og `#` (root recursion).
|
|
|
|
---
|
|
|
|
## Integrasjon med Microsoft-stakken
|
|
|
|
### Microsoft Foundry / Azure OpenAI
|
|
|
|
**API-versjon:** Structured outputs introdusert i `2024-08-01-preview`, tilgjengelig i GA-versjon `v1`.
|
|
|
|
**Støttede modeller (per 2026-06):**
|
|
- **GPT-5-serien:** gpt-5, gpt-5.1, gpt-5.1-chat, gpt-5.1-codex, gpt-5-pro, gpt-5-codex, gpt-5-mini, gpt-5-nano (hele serien støtter structured outputs)
|
|
- **GPT-4-serien:** gpt-4o (2024-08-06, 2024-11-20), gpt-4.1, gpt-4.1-mini, gpt-4.1-nano
|
|
- **o-serien:** o1, o3-mini, o3-pro, o4-mini
|
|
- **Codex:** codex-mini (2025-05-16)
|
|
|
|
**Ikke støttet med:**
|
|
- Assistants API
|
|
- Foundry Agents Service
|
|
- "Bring your own data" (Azure AI Search)
|
|
- Audio-preview modeller (gpt-4o-audio-preview og gpt-4o-mini-audio-preview, versjon 2024-12-17)
|
|
|
|
### Semantic Kernel
|
|
|
|
**Semantic Kernel** støtter structured outputs via `AzureAssistantAgent.configure_response_format()`:
|
|
|
|
```python
|
|
from pydantic import BaseModel
|
|
|
|
class ResponseModel(BaseModel):
|
|
response: str
|
|
items: list[str]
|
|
|
|
client, model = AzureAssistantAgent.setup_resources()
|
|
|
|
definition = await client.beta.assistants.create(
|
|
model=model,
|
|
name="DataExtractor",
|
|
instructions="Extract structured data from text.",
|
|
response_format=AzureAssistantAgent.configure_response_format(ResponseModel),
|
|
)
|
|
```
|
|
|
|
**Fordel:** Enklere å integrere med plugins og orchestration-logikk.
|
|
|
|
### Power Platform / Copilot Studio
|
|
|
|
**Status:** Structured outputs er ikke direkte eksponert i Copilot Studio low-code interface per 2026-02. Må brukes via custom connectors eller Power Automate med HTTP-actions mot Azure OpenAI REST API.
|
|
|
|
**Workaround:**
|
|
1. Opprett custom connector med OpenAI-endepunkt
|
|
2. Send `response_format` i request body
|
|
3. Parse JSON-output i Power Automate
|
|
|
|
---
|
|
|
|
## Offentlig sektor (Norge)
|
|
|
|
### Dataminimering og GDPR
|
|
|
|
Strukturert output kan hjelpe med **dataminimering** (GDPR Art. 5.1c) ved å:
|
|
- Kun trekke ut spesifikt definerte datafelter
|
|
- Unngå at modellen returnerer persondata som ikke er nødvendig
|
|
- Lettere å implementere anonymisering i output-schema
|
|
|
|
**Anbefaling:** Definer schema slik at sensitive felter (personnummer, helseopplysninger) kun inkluderes hvis eksplisitt nødvendig.
|
|
|
|
### AI Act (EU)
|
|
|
|
Strukturert output kan bidra til **traceability** (Art. 12):
|
|
- Logg input-schema og output-schema for hver request
|
|
- Enklere å demonstrere at modellen ikke produserer uventet output
|
|
- Støtter risikovurdering ved å definere "tillatt" output-format
|
|
|
|
### Forvaltningsloven og forsvarlighetskrav
|
|
|
|
**§ 6 (Forsvarlighetskravet):** Strukturert output øker forutsigbarheten i automatiserte vedtak:
|
|
- Reduserer risiko for at LLM-output ikke kan valideres
|
|
- Gjør det enklere å dokumentere hvordan AI-systemet fungerer
|
|
- Støtter krav om transparens i automatiserte beslutninger
|
|
|
|
**Eksempel (saksbehandling):**
|
|
```python
|
|
class CaseAssessment(BaseModel):
|
|
case_id: str
|
|
decision: str # "approve", "reject", "manual_review"
|
|
legal_basis: list[str] # Lovparagrafer
|
|
reasoning: str
|
|
confidence_score: float # 0.0-1.0
|
|
|
|
# Output er strukturert og kan logges/auditeres
|
|
```
|
|
|
|
### Schrems II og datasuverenitet
|
|
|
|
Strukturert output endrer ikke hvor data prosesseres, men:
|
|
- Kan brukes til å **filtrere ut sensitive data** før de sendes til Azure OpenAI
|
|
- Gjør det enklere å implementere "privacy-preserving prompts"
|
|
|
|
**Anbefaling:** Kombiner med Azure Private Endpoint og Customer Managed Keys for maksimal kontroll.
|
|
|
|
---
|
|
|
|
## Kostnad og lisensiering
|
|
|
|
### Prismodell
|
|
|
|
Strukturert output medfører **ingen ekstra kostnad** utover standard token-prising for Azure OpenAI. Du betaler for:
|
|
- Input tokens (prompt + schema-definisjon)
|
|
- Output tokens (JSON-strukturert output)
|
|
|
|
**Observasjon:** Schema-definisjonen (JSON Schema) legges til som del av system-prompt, så den teller mot input tokens. For komplekse schemas med mange properties, kan dette øke kostnadene marginalt (typisk 50-200 tokens per request).
|
|
|
|
### Lisensiering
|
|
|
|
Krever Azure OpenAI-ressurs med støttet modell (se over). Ingen spesiell lisens eller feature flag nødvendig.
|
|
|
|
**Microsoft 365 Copilot:** Structured outputs er ikke tilgjengelig via M365 Copilot API per 2026-02. Må bruke Azure OpenAI direkte.
|
|
|
|
---
|
|
|
|
## For arkitekten (Cosmo)
|
|
|
|
### Spørsmål å stille kunden
|
|
|
|
1. **Datakvalitet og validering**
|
|
- Hvilke datafelter er kritiske, og hvilke er "nice to have"?
|
|
- Trenger dere streng validering av output, eller kan dere tolerere noe fleksibilitet?
|
|
- Finnes det eksisterende JSON schemas dere bruker (OpenAPI, JSON Schema, etc.)?
|
|
|
|
2. **Workflow-kompleksitet**
|
|
- Er dette en enkel "input → output"-transformasjon, eller del av en flerstegs pipeline?
|
|
- Trenger dere å cache eller persistere mellomresultater?
|
|
- Skal outputen integreres direkte med database, API, eller annet system?
|
|
|
|
3. **Modenhet og risikotoleranse**
|
|
- Hva skjer hvis modellen ikke klarer å generere gyldig output? (fallback-strategi)
|
|
- Har dere logging og monitoring for å oppdage schema-violations?
|
|
- Trenger dere human-in-the-loop for kritiske beslutninger?
|
|
|
|
4. **Ytelse og kostnad**
|
|
- Hva er volumet av requests? (viktig for å estimere kostnader)
|
|
- Hva er akseptabel latency? (structured outputs kan være noe tregere enn fritekst)
|
|
- Kan dere cache schemas på klientsiden for å redusere input tokens?
|
|
|
|
5. **Sikkerhets- og compliance-krav**
|
|
- Inneholder outputen persondata eller forretningskritisk informasjon?
|
|
- Må outputen logges for audit-trail (Forvaltningsloven)?
|
|
- Trenger dere å filtrere ut sensitive data i output-schema?
|
|
|
|
### Fallgruver å unngå
|
|
|
|
| Fallgruve | Hvorfor det skjer | Hvordan unngå |
|
|
|-----------|-------------------|---------------|
|
|
| **For komplekse schemas** | Over 100 properties eller 5 nestingsnivåer → request feiler | Bryt ned i mindre schemas, bruk multi-step workflow |
|
|
| **Alle fields som required** | Glemmer at JSON Schema strict mode krever alle fields i `required` | Bruk `["string", "null"]` for optional fields |
|
|
| **Glemmer `additionalProperties: false`** | Strict mode krever dette for alle objekter | Valider schema med tool før prod |
|
|
| **Parallell function calling** | Kombinerer `strict: true` med `parallel_tool_calls: true` | Sett `parallel_tool_calls: false` eksplisitt |
|
|
| **JSON Mode vs Structured Outputs** | Bruker deprecated `json_object` for GPT-4o | Migrer til `json_schema` med `strict: true` |
|
|
| **Manglende feilhåndtering** | Anta at modellen alltid returnerer gyldig output | Sjekk `finish_reason` for "length" eller "content_filter" |
|
|
|
|
### Anbefalinger per modenhetsnivå
|
|
|
|
#### Nivå 1: Utforsker (PoC)
|
|
- Start med **enkle schemas** (< 10 properties, flat struktur)
|
|
- Bruk **Pydantic** i Python for rask prototyping
|
|
- Test mot **GPT-4o-mini** for kostnadseffektiv utvikling
|
|
- Eksperimenter med JSON Mode først hvis dere er usikre på schema-design
|
|
|
|
#### Nivå 2: Pilot (Testing i prod-lignende miljø)
|
|
- Definer **strenge schemas** med alle required fields
|
|
- Implementer **validering** av output (selv om structured outputs garanterer schema)
|
|
- Logg **schema-violations** (hvis modellen returnerer `finish_reason: "length"`)
|
|
- Mål **latency og token-forbruk** for å optimalisere
|
|
|
|
#### Nivå 3: Produksjon (Skala og drift)
|
|
- Bruk **caching** for schemas som gjenbrukes ofte
|
|
- Implementer **fallback til JSON Mode** hvis strict mode feiler
|
|
- Overvåk **error rates** og juster schemas basert på faktisk bruk
|
|
- Dokumenter **schema-endringer** i API-contract (versjonering)
|
|
|
|
#### Nivå 4: Optimalisert (Kontinuerlig forbedring)
|
|
- Bruk **recursive schemas** for dynamiske datastrukturer (trær, grafer)
|
|
- Kombiner med **function calling** for agentic workflows
|
|
- Implementer **A/B-testing** av ulike schema-designs
|
|
- Automatiser **schema-generering** fra eksisterende datamodeller (SQL, OpenAPI, etc.)
|
|
|
|
---
|
|
|
|
## Kilder og verifisering
|
|
|
|
### Microsoft Learn (Verified)
|
|
|
|
| URL | Tema | Konfidensnivå |
|
|
|-----|------|---------------|
|
|
| [Structured Outputs Guide](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/structured-outputs) | Hovedguide, API-eksempler, schema-begrensninger | **Verified** (2026-02) |
|
|
| [JSON Mode Guide](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/json-mode) | JSON Mode (legacy), sammenlikning med structured outputs | **Verified** (2026-02) |
|
|
| [API Reference (v1)](https://learn.microsoft.com/en-us/azure/foundry/openai/latest) | REST API-detaljer, response_format konfigurasjon | **Verified** (2026-02) |
|
|
| [Prompt Engineering Guide](https://learn.microsoft.com/en-us/azure/foundry/openai/concepts/prompt-engineering) | Output structure best practices | **Verified** (2026-02) |
|
|
|
|
### Azure OpenAI API-versjon
|
|
- **Introduced:** `2024-08-01-preview`
|
|
- **GA:** `v1` (2026-02)
|
|
|
|
### Konfidensvurdering per seksjon
|
|
|
|
| Seksjon | Konfidens | Kilde |
|
|
|---------|-----------|-------|
|
|
| Kjernekomponenter | **Verified** | Microsoft Learn, code samples |
|
|
| Arkitekturmønstre | **Baseline** | Generalisert fra best practices |
|
|
| Beslutningsveiledning | **Verified** | Microsoft Learn, API docs |
|
|
| Microsoft-integrasjon | **Verified** | Microsoft Learn, Semantic Kernel docs |
|
|
| Offentlig sektor | **Baseline** | GDPR/AI Act-prinsipper, ikke AI-spesifikk guidance |
|
|
| Kostnad og lisensiering | **Verified** | Azure OpenAI prising (2026-02) |
|
|
| For arkitekten | **Baseline** | Erfaring og best practices |
|
|
|
|
---
|
|
|
|
**Oppsummering:** Structured outputs er anbefalt standard for alle nye implementasjoner som krever strukturert data fra Azure OpenAI. JSON Mode bør kun brukes for legacy-støtte eller der strict schema-validering ikke er nødvendig.
|