Izlaz u strukturiranom obliku: zajamčeni JSON
Na ovoj stranici
Izlaz u strukturiranom obliku: zajamčeni JSON
Izlaz u strukturiranom obliku (Structured Output) jedna je od najmoćnijih značajki API-ja Responses. Umjesto da se nadaš kako će model vratiti ispravan JSON, to zajamčuješ davanjem sheme. Model je tada strukturno prisiljen slijediti je. Time jezični model pretvaraš iz kreativnog generatora teksta u pouzdanu komponentu automatiziranog procesnog lanca.
Problem koji ovo rješava
Traženje JSON-a u promptu većinom funkcionira, što je upravo ono što ovaj pristup čini opasnim. Jedan dan od stotinu model će odgovor započeti uvodnom rečenicom, sve zamotati u Markdown blok koda ili preimenovati polje – i tvoj json.loads() u produkciji baci iznimku na zahtjev koji ne možeš reproducirati.
from openai import OpenAI
client = OpenAI()
# Bez strukture — model može vratiti bilo koji format
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Nepredvidiv rezultat:
# Ponekad ispravan JSON, ponekad tekst koji sadrži JSON,
# ponekad neočekivani format...
Parametar text mijenja prirodu jamstva. Deklariraš format json_schema zajedno s očekivanom shemom, a izlaz joj se prilagođava: deserializacija postaje sigurna 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 ispravan JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic umjesto ručno pisanog JSON Schema
Ručno pisanje shema brzo postaje zamorno i podložno tipfelerskim greškama. Pydantic ti omogućuje da ih opišeš kao Python klase, generiraš JSON Shemu s model_json_schema(), a zatim validiraš i tipiziraš odgovor s model_validate_json(). Na kraju lanca dobivaš puni Python objekt s automatskim dovršavanjem u uređivaču, umjesto anonimnog rječnika.
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()
}
}
)
# Parsiranje i validacija s Pydanticom
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šta te ne ograničava na ravne strukture. Sastavljanjem klasa opisuješ ugniježđene objekte i liste objekata, što ćeš trebati čim kreiraš realističan profil kupca: tvrtka sadrži kontakte, a svaki kontakt ima adresu.
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 česta slučaja upotrebe
Prvi je ekstrakcija: pretvaranje pisanog teksta u upotrebljivi zapis. Najava konferencije napisana prirodnim jezikom postaje redak u bazi podataka s naslovom, datumom, lokacijom i brojem sudionika – bez regularnih izraza i bez kvarova kad god se promijeni formulacija.
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 je klasifikacija. Deklariranjem enumeracije ograničavaš model na zatvoreni rječnik: ne može odgovoriti „prilično pozitivno“ ili „pozitivno“ kada tvoj kod očekuje positive. To je razlika između vrijednosti koju možeš izravno upotrijebiti i one koju moraš naknadno 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%)
Što zahtijeva strogi način rada (strict mode)
Jamstvo nosi kompromis: kada je strict: True, shema se mora pridržavati određenog podskupa JSON Sheme. Ta su ograničenja vodeći uzrok grešaka 400 za početnike, pa ih je najbolje upoznati prije nego što na njih naiđeš:
- Sva svojstva moraju biti navedena u
required additionalPropertiesmora bitiFalse- Podržani tipovi:
string,number,integer,boolean,array,object,null - Bez
oneOfilianyOfs mješovitim tipovima - Koristi
Optional[str], što se prevodi u{"anyOf": [{"type": "string"}, {"type": "null"}]}
Pravilo o required često iznenadi ljude: opcionalno polje ne izražavaš njegovim uklanjanjem s popisa, već dopuštanjem vrijednosti null, točno onako kako Optional[str] proizvodi na strani Pydantica.
Ključne točke
- Strukturirani izlaz jamči da odgovor poštuje tvoju JSON shemu
- U API-ju Responses koristi
text={"format": {"type": "json_schema", ...}} - Pydantic je idealan alat za definiranje i validaciju shema
- Omogući
strict: Trueza zajamčenu usklađenost sa shemom - Idealno za ekstrakciju podataka, klasifikaciju i strukturirano generiranje