Izhod v strukturirani obliki: zajamčen JSON
Na tej strani
Izhod v strukturirani obliki: zajamčen JSON
Izhod v strukturirani obliki (Structured Output) je ena najzmogljivejših funkcij API-ja Responses. Namesto da upaš, da bo model vrnil veljaven JSON, to zajamčiš z zagotovitvijo sheme. Model je nato strukturno omejen, da ji sledi. To jezikovni model spremeni iz ustvarjalnega generatorja besedila v zanesljivo komponento avtomatiziranega obdelovalnega procesa.
Težava, ki jo to rešuje
Zahteva po JSON-u v pozivu deluje večino časa, kar je prav tisto, zaradi česar je ta pristop nevaren. Enkrat na sto poskusov model svojemu odgovoru doda uvodni stavek, vse ovije v blok kode Markdown ali preimenuje polje – in tvoj json.loads() v proizvodnem okolju vrže izjemo pri zahtevi, ki je ne moreš reproducirati.
from openai import OpenAI
client = OpenAI()
# Brez strukture — model lahko vrne katero koli obliko
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Nepredvidljiv rezultat:
# Včasih veljaven JSON, včasih besedilo, ki vsebuje JSON,
# včasih nepričakovana oblika...
Parameter text spremeni naravo zajamčenosti. Deklariraš format json_schema skupaj s pričakovano shemo in izhod se ji prilagodi: deserializacija postane varna operacija.
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'])}")
# Rezultat je ZAJAMČENO veljaven JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic namesto ročno napisane JSON sheme
Ročno pisanje shem hitro postane dolgočasno in nagnjeno k tipkarskim napakam. Pydantic ti omogoča, da jih opišeš kot razrede Python, generiraš JSON shemo z model_json_schema() in nato odgovor validiraš ter tipiziraš z model_validate_json(). Na koncu verige dobiš popoln objekt Python z samodejnim dopolnjevanjem v urejevalniku, namesto anonimnega slovarja.
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()
}
}
)
# Razčleni in validiraj s 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'}")
# Rezultat:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Nič te ne omejuje na ravne strukture. S komponiranjem razredov opišeš gnezdena objekta in sezname objektov, kar boš potreboval takoj, ko ustvariš realističen profil stranke: podjetje vsebuje kontakte, vsak kontakt pa ima naslov.
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}")
Dva pogosta primera uporabe
Prvi je ekstrakcija: pretvorba zapisanega besedila v uporaben zapis. Napoved konference, napisana v naravnem jeziku, postane vrstica v zbirki podatkov z naslovom, datumom, lokacijo in številom udeležencev – brez regularnih izrazov in brez napak, kadar se spremeni besedilo.
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)")
# Rezultat: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Drugi primer je klasifikacija. Z deklaracijo enumeracije omejiš model na zaprt besednjak: ne more odgovoriti „precej pozitiven” ali „pozitiven”, ko tvoja koda pričakuje positive. To je razlika med vrednostjo, ki jo lahko uporabiš neposredno, in vrednostjo, ki jo moraš nato normalizirati.
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%})")
# Rezultat: Sentiment: positive (95%)
Kaj zahteva strogi način
Zajamčenost ima svojo ceno: ko je strict: True, se mora shema držati določenega podnabora JSON Schema. Te omejitve so glavni vzrok za napake 400 pri začetnikih, zato jih je najbolje poznati, preden nanje naletiš:
- Vsa polja morajo biti navedena v
required additionalPropertiesmora bitiFalse- Podprti tipi:
string,number,integer,boolean,array,object,null - Brez
oneOfalianyOfz mešanimi tipi - Uporabi
Optional[str], kar se prevede v{"anyOf": [{"type": "string"}, {"type": "null"}]}
Pravilo o required pogosto preseneti ljudi: izbirnega polja ne izraziš z njegovo odstranitvijo s seznama, temveč z dovoljenjem vrednosti null, kar točno počne Optional[str] na strani Pydantic.
Ključne ugotovitve
- Strukturirani izhod zajamči, da se odgovor drži tvoje JSON sheme
- V API-ju Responses uporabi
text={"format": {"type": "json_schema", ...}} - Pydantic je idealno orodje za definiranje in validacijo shem
- Omogoči
strict: Trueza zajamčeno skladnost s shemo - Idealno za ekstrakcijo podatkov, klasifikacijo in strukturirano generiranje