Štruktúrovaný výstup: Garantované JSON
Na tejto strane
Štruktúrovaný výstup: Garantované JSON
Štruktúrovaný výstup je jednou z najsilnejších funkcií API Responses. Namiesto toho, aby si dúfal, že model vráti platné JSON, mu to zaručíš poskytnutím schémy. Model je potom štrukturálne nútený ju dodržiavať. Tým sa jazykový model mení z kreatívneho generátora textu na spoľahlivú súčasť automatizovaného spracovateľského pipeline.
Problém, ktorý to rieši
Požiadavka na JSON v prompte funguje väčšinou času, čo je presne dôvod, prečo je tento prístup nebezpečný. Raz za sto prípadov model predradí svoju odpoveď úvodnou vetou, zabalí všetko do bloku kódu Markdown alebo premenuje pole – a tvoje json.loads() vyhodí výnimku v produkcii pri požiadavke, ktorú nedokážeš reprodukovať.
from openai import OpenAI
client = OpenAI()
# Bez štruktúry — model môže vrátiť akýkoľvek formát
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Nepredvídateľný výsledok:
# Niekedy platné JSON, niekedy text obsahujúci JSON,
# niekedy neočakávaný formát...
Parameter text mení povahu záruky. Deklaruješ formát json_schema spolu s očakávanou schémou a výstup sa jej prispôsobí: deserializácia sa stáva bezpečnou operáciou.
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'])}")
# Výsledok je GARANTOVANE platné JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic namiesto ručne písaného JSON Schema
Ručné písanie schém sa rýchlo stáva zdĺhavým a náchylným na preklepy. Pydantic ti umožňuje opisovať ich ako Python triedy, generovať JSON Schému pomocou model_json_schema() a následne validovať a typovať odpoveď pomocou model_validate_json(). Na konci reťazca dostaneš plnohodnotný Python objekt s automatickým dopĺňaním v editore, namiesto anonymného slovníka.
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()
}
}
)
# Parsovanie a validácia pomocou 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'}")
# Výsledok:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Nič ťa neobmedzuje na ploché štruktúry. Skladaním tried opisuješ vnorené objekty a zoznamy objektov, čo budeš potrebovať hneď, ako vytvoríš realistický profil zákazníka: spoločnosť obsahuje kontakty a každý kontakt má 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 bežné prípady použitia
Prvým je extrakcia: premena písaného textu na použiteľný záznam. Oznámenie o konferencii napísané prirodzeným jazykom sa stane riadkom v databáze s názvom, dátumom, miestom a počtom účastníkov – bez regulárnych výrazov a bez toho, aby sa to pokazilo vždy, keď sa zmení formulácia.
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)")
# Výsledok: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Druhým je klasifikácia. Deklarovaním enumerácie obmedzíš model na uzavretú slovnú zásobu: nemôže odpovedať „skôr pozitívne“ alebo „pozitívny“, keď tvoj kód očakáva positive. To je rozdiel medzi hodnotou, ktorú môžeš použiť priamo, a hodnotou, ktorú musíš následne normalizovať.
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%})")
# Výsledok: Sentiment: positive (95%)
Čo vyžaduje striktný režim
Záruka so sebou nesie kompromis: keď je strict: True, schéma sa musí držať konkrétnej podmnožiny JSON Schema. Tieto obmedzenia sú hlavnou príčinou chýb 400 u začiatočníkov, preto je najlepšie poznať ich skôr, než na ne narazíš:
- Všetky vlastnosti musia byť uvedené v
required additionalPropertiesmusí byťFalse- Podporované typy:
string,number,integer,boolean,array,object,null - Žiadne
oneOfanianyOfso zmiešanými typmi - Použi
Optional[str], čo sa prekladá ako{"anyOf": [{"type": "string"}, {"type": "null"}]}
Pravidlo o required často ľudí prekvapí: voliteľné pole sa nevyjadruje jeho odstránením zo zoznamu, ale povolením hodnoty null, presne to, čo produkuje Optional[str] na strane Pydantic.
Kľúčové poznatky
- Štruktúrovaný výstup zaručuje, že odpoveď dodržiava tvoju JSON schému
- Použi
text={"format": {"type": "json_schema", ...}}v API Responses - Pydantic je ideálnym nástrojom na definovanie a validáciu schém
- Povoľ
strict: Truepre garantované dodržiavanie schémy - Ideálne na extrakciu dát, klasifikáciu a štruktúrovanú generáciu