Strukturovaný výstup: Zaručené JSON
Na této stránce
Strukturovaný výstup: Zaručené JSON
Strukturovaný výstup je jednou z nejmocnějších funkcí Responses API. Místo toho, abys doufal, že model vrátí platné JSON, mu to zaručíš poskytnutím schématu. Model je pak strukturálně nucen se ho držet. Tím se jazykový model mění z kreativního generátoru textu na spolehlivou součást automatizovaného zpracovatelského řetězce.
Problém, který to řeší
Požadavek na JSON v promptu funguje většinu času, což je přesně to, co dělá tento přístup nebezpečným. Jeden den ze sta model před svou odpověď přidá úvodní větu, zabalí vše do Markdown bloku kódu nebo přejmenuje pole – a tvůj json.loads() vyhodí výjimku v produkci u požadavku, který nedokážeš reprodukovat.
from openai import OpenAI
client = OpenAI()
# Bez struktury — model může vrátit jakýkoli formát
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Nepředvídatelný výsledek:
# Někdy platné JSON, někdy text obsahující JSON,
# někdy neočekávaný formát...
Parametr text mění povahu záruky. Deklaruješ formát json_schema spolu s očekávaným schématem a výstup se mu přizpůsobí: deserializace se stává bezpečnou operací.
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ýsledek ZARUČENĚ platné JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic místo ručně psaného JSON Schema
Ruční psaní schémat se rychle stává zdlouhavým a náchylným k překlepům. Pydantic ti umožňuje popsat je jako Python třídy, vygenerovat JSON Schema pomocí model_json_schema() a následně validovat a typovat odpověď pomocí model_validate_json(). Na konci řetězce získáš plnohodnotný Python objekt s automatickým doplňováním v editoru, nikoli anonymní slovník.
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()
}
}
)
# Parsování a validace pomocí 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ýsledek:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Nic tě neomezuje na ploché struktury. Skládáním tříd popisuješ vnořené objekty a seznamy objektů, které budeš potřebovat, jakmile vytvoříš realistický profil zákazníka: společnost 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 běžné případy použití
Prvním je extrakce: převod psaného textu na použitelný záznam. Oznámení o konferenci napsané přirozeným jazykem se stane řádkem v databázi s názvem, datem, místem a počtem účastníků – bez regulárních výrazů a bez toho, aby se to rozbilo pokaždé, když se změní formulace.
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ýsledek: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Druhým je klasifikace. Deklarací výčtu (enumeration) omezíš model na uzavřenou slovní zásobu: nemůže odpovědět „spíše pozitivní“ nebo „pozitivní“, když tvůj kód očekává positive. To je rozdíl mezi hodnotou, kterou můžeš přímo použít, a hodnotou, kterou musíš následně normalizovat.
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ýsledek: Sentiment: positive (95%)
Co vyžaduje striktní režim
Záruka s sebou nese kompromis: když je strict: True, schéma se musí držet specifické podmnožiny JSON Schema. Tato omezení jsou hlavní příčinou chyb 400 u začátečníků, takže je nejlepší je znát dříve, než na ně narazíš:
- Všechny vlastnosti musí být uvedeny v
required additionalPropertiesmusí býtFalse- Podporované typy:
string,number,integer,boolean,array,object,null - Žádné
oneOfanianyOfse smíšenými typy - Použij
Optional[str], což se přeloží jako{"anyOf": [{"type": "string"}, {"type": "null"}]}
Pravidlo ohledně required často lidi překvapí: volitelné pole se nevyjadřuje jeho odstraněním ze seznamu, ale povolením hodnoty null, přesně to, co na straně Pydantic produkuje Optional[str].
Klíčové poznatky
- Strukturovaný výstup zaručuje, že odpověď odpovídá tvému JSON schématu
- V Responses API použij
text={"format": {"type": "json_schema", ...}} - Pydantic je ideální nástroj pro definování a validaci schémat
- Pro zaručenou shodu se schématem povol
strict: True - Ideální pro extrakci dat, klasifikaci a strukturovanou generaci