Struktureret output: Garanteret JSON
På denne side
Struktureret output: Garanteret JSON
Struktureret output er en af de mest kraftfulde funktioner i Responses API. I stedet for at håbe på, at modellen returnerer gyldig JSON, garanterer du det ved at levere et skema. Modellen bliver derefter strukturelt tvunget til at følge det. Dette transformerer en sprogmodel fra en kreativ tekstgenerator til en pålidelig komponent i en automatiseret behandlingspipeline.
Problemet dette løser
At bede om JSON i prompten fungerer de fleste gange, hvilket netop er det, der gør tilgangen farlig. Én dag ud af hundrede sætter modellen en indledningssætning foran sit svar, pakker alt ind i en Markdown-kodeblok eller omdøber et felt – og din json.loads() kaster en undtagelse i produktionen på en forespørgsel, du ikke kan reproducere.
from openai import OpenAI
client = OpenAI()
# Uden struktur — modellen kan returnere ethvert format
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Uforudsigeligt resultat:
# Nogle gange gyldig JSON, nogle gange tekst der indeholder JSON,
# nogle gange et uventet format...
Parameteren text ændrer karakteren af garantien. Du deklarerer et json_schema-format sammen med det forventede skema, og outputtet overholder det: deserialisering bliver en sikker operation.
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me information about Paris.",
text={
"format": {
"type": "json_schema",
"name": "city_info",
"strict": True,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"country": {"type": "string"},
"population": {"type": "integer"},
"official_language": {"type": "string"},
"landmarks": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["name", "country", "population", "official_language", "landmarks"],
"additionalProperties": False
}
}
}
)
import json
data = json.loads(response.output_text)
print(f"City: {data['name']}")
print(f"Population: {data['population']:,}")
print(f"Landmarks: {', '.join(data['landmarks'])}")
# Resultat GARANTERET at være gyldig JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic i stedet for manuelt skrevet JSON-skema
At skrive skemaer i hånden bliver hurtigt kedeligt og udsat for taste fejl. Pydantic lader dig beskrive dem som Python-klasser, generere JSON-skemaet med model_json_schema() og derefter validere og typisere svaret med model_validate_json(). I enden af kæden får du et fuldt Python-objekt med editor-autofuldførelse i stedet for en anonym ordbog.
from pydantic import BaseModel
from typing import Optional
import json
class Product(BaseModel):
name: str
price: float
category: str
in_stock: bool
description: Optional[str] = None
response = client.responses.create(
model="gpt-5.6-terra",
input="Describe a high-end gaming laptop.",
text={
"format": {
"type": "json_schema",
"name": "product",
"strict": True,
"schema": Product.model_json_schema()
}
}
)
# Pars og valider med Pydantic
product = Product.model_validate_json(response.output_text)
print(f"Product: {product.name}")
print(f"Price: {product.price} EUR")
print(f"In stock: {'Yes' if product.in_stock else 'No'}")
# Resultat:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Intet begrænser dig til flade strukturer. Ved at sammensætte klasser beskriver du nestede objekter og lister af objekter, hvilket du får brug for, så snart du opretter en realistisk kundeprofil: en virksomhed indeholder kontakter, og hver kontakt har en adresse.
from pydantic import BaseModel
class Address(BaseModel):
street: str
city: str
postal_code: str
country: str
class Contact(BaseModel):
last_name: str
first_name: str
email: str
phone: str
address: Address
class Company(BaseModel):
name: str
sector: str
employees: int
contacts: list[Contact]
response = client.responses.create(
model="gpt-5.6-terra",
input="Generate a fictional company profile in the tech sector "
"with 2 contacts.",
text={
"format": {
"type": "json_schema",
"name": "company",
"strict": True,
"schema": Company.model_json_schema()
}
}
)
company = Company.model_validate_json(response.output_text)
print(f"Company: {company.name} ({company.sector})")
for c in company.contacts:
print(f" - {c.first_name} {c.last_name}: {c.email}")
To almindelige brugstilfælde
Det første er udtræk: at gøre skrevet tekst til en brugbar post. En konferenceannonce skrevet på naturligt sprog bliver til en databaserække med titel, dato, placering og antal deltagere – uden regulære udtryk og uden at bryde sammen, hver gang ordlyden ændres.
class Event(BaseModel):
title: str
date: str
location: str
attendees: int
text = """
The PyCon France 2026 conference will be held on November 15 and 16
at the Palais des Congrès in Lyon. More than 800 Python developers
are expected for this edition.
"""
response = client.responses.create(
model="gpt-5.6-terra",
input=f"Extract the information from this event:\n{text}",
text={
"format": {
"type": "json_schema",
"name": "event",
"strict": True,
"schema": Event.model_json_schema()
}
}
)
evt = Event.model_validate_json(response.output_text)
print(f"{evt.title} - {evt.date} at {evt.location} ({evt.attendees} attendees)")
# Resultat: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Det andet er klassificering. Ved at deklarere en enumeration begrænser du modellen til et lukket ordforråd: den kan ikke svare „ganske positiv” eller „positiv”, når din kode forventer positive. Det er forskellen mellem en værdi, du kan bruge direkte, og en værdi, du skal normalisere bagefter.
from enum import Enum
class Sentiment(str, Enum):
positive = "positive"
negative = "negative"
neutral = "neutral"
class Analysis(BaseModel):
sentiment: Sentiment
confidence: float
keywords: list[str]
response = client.responses.create(
model="gpt-5.6-terra",
input="Analyze this comment: 'Great service, fast delivery!'",
text={
"format": {
"type": "json_schema",
"name": "sentiment_analysis",
"strict": True,
"schema": Analysis.model_json_schema()
}
}
)
analysis = Analysis.model_validate_json(response.output_text)
print(f"Sentiment: {analysis.sentiment.value} ({analysis.confidence:.0%})")
# Resultat: Sentiment: positive (95%)
Hvad streng tilstand kræver
Garantien kommer med en afvejning: når strict: True, skal skemaet overholde en specifik delmængde af JSON-skema. Disse begrænsninger er den hyppigste årsag til 400-fejl for begyndere, så det er bedst at kende dem, før du støder på dem:
- Alle egenskaber skal listes i
required additionalPropertiesskal væreFalse- Understøttede typer:
string,number,integer,boolean,array,object,null - Ingen
oneOfelleranyOfmed blandede typer - Brug
Optional[str], hvilket oversættes til{"anyOf": [{"type": "string"}, {"type": "null"}]}
Reglen om required overrasker ofte folk: et valgfrit felt udtrykkes ikke ved at fjerne det fra listen, men ved at tillade værdien null, præcis hvad Optional[str] producerer på Pydantic-siden.
Vigtige pointer
- Struktureret output garanterer, at svaret overholder dit JSON-skema
- Brug
text={"format": {"type": "json_schema", ...}}i Responses API - Pydantic er det ideelle værktøj til at definere og validere skemaer
- Aktiver
strict: Truefor garanteret skema-overholdelse - Ideelt til dataudtræk, klassificering og struktureret generering