Wyjście strukturalne: Gwarantowany JSON
Na tej stronie
Wyjście strukturalne: Gwarantowany JSON
Wyjście strukturalne (Structured Output) to jedna z najpotężniejszych funkcji Responses API. Zamiast mieć nadzieję, że model zwróci poprawny JSON, gwarantujesz to, dostarczając schemat. Model jest wówczas strukturalnie ograniczony do jego przestrzegania. Przekształca to model językowy z kreatywnego generatora tekstu w niezawodny komponent zautomatyzowanego potoku przetwarzania danych.
Problem, który to rozwiązuje
Proszenie o JSON w prompcie działa większość czasu, co właśnie czyni to podejście niebezpiecznym. Raz na sto przypadków model poprzedza odpowiedź zdaniem wstępnym, opakowuje wszystko w blok kodu Markdown lub zmienia nazwę pola – a Twój json.loads() wyrzuca wyjątek w środowisku produkcyjnym przy żądaniu, którego nie jesteś w stanie odtworzyć.
from openai import OpenAI
client = OpenAI()
# Bez struktury — model może zwrócić dowolny format
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Nieprzewidywalny wynik:
# Czasami poprawny JSON, czasami tekst zawierający JSON,
# czasami nieoczekiwany format...
Parametr text zmienia naturę tej gwarancji. Deklarujesz format json_schema wraz z oczekiwanym schematem, a wynik jest mu podporządkowany: deserializacja staje się operacją bezpieczną.
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'])}")
# Wynik GWARANTOWANIE poprawny jako JSON:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic zamiast ręcznie pisanego JSON Schema
Ręczne pisanie schematów szybko staje się żmudne i podatne na literówki. Pydantic pozwala opisywać je jako klasy Pythona, generować schemat JSON za pomocą model_json_schema(), a następnie walidować i typować odpowiedź metodą model_validate_json(). Na końcu łańcucha otrzymujesz pełny obiekt Pythona z autouzupełnianiem w edytorze, zamiast anonimowego słownika.
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()
}
}
)
# Parsowanie i walidacja z 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'}")
# Wynik:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Nic nie ogranicza Cię do struktur płaskich. Komponując klasy, opisujesz zagnieżdżone obiekty i listy obiektów, co będzie Ci potrzebne, gdy tylko stworzysz realistyczny profil klienta: firma zawiera kontakty, a każdy kontakt ma adres.
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}")
Dwa typowe przypadki użycia
Pierwszym jest ekstrakcja: zamiana tekstu pisanego na użyteczny rekord. Ogłoszenie konferencyjne napisane językiem naturalnym staje się wierszem w bazie danych z tytułem, datą, lokalizacją i liczbą uczestników – bez wyrażeń regularnych i bez awarii przy każdej zmianie sformułowania.
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)")
# Wynik: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Drugim przypadkiem jest klasyfikacja. Deklarując enumerację, ograniczasz model do zamkniętego słownictwa: nie może odpowiedzieć „raczej pozytywny“ ani „pozytywny“, gdy Twój kod oczekuje positive. To różnica między wartością, której możesz użyć bezpośrednio, a wartością, którą musisz później znormalizować.
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%})")
# Wynik: Sentiment: positive (95%)
Czego wymaga tryb strict
Gwarancja niesie ze sobą kompromis: gdy strict: True, schemat musi adherować do określonego podzbioru JSON Schema. Te ograniczenia są główną przyczyną błędów 400 u początkujących, więc najlepiej poznać je, zanim się z nimi zetkniesz:
- Wszystkie właściwości muszą być wymienione w
required additionalPropertiesmusi mieć wartośćFalse- Obsługiwane typy:
string,number,integer,boolean,array,object,null - Brak
oneOflubanyOfz mieszanymi typami - Używaj
Optional[str], co tłumaczy się na{"anyOf": [{"type": "string"}, {"type": "null"}]}
Zasada dotycząca required często zaskakuje: pola opcjonalnego nie wyraża się poprzez usunięcie go z listy, lecz przez dopuszczenie wartości null, dokładnie tak, jak robi to Optional[str] po stronie Pydantic.
Kluczowe wnioski
- Wyjście strukturalne gwarantuje, że odpowiedź będzie zgodna z Twoim schematem JSON
- Używaj
text={"format": {"type": "json_schema", ...}}w Responses API - Pydantic to idealne narzędzie do definiowania i walidacji schematów
- Włącz
strict: True, aby uzyskać gwarancję zgodności ze schematem - Idealne rozwiązanie do ekstrakcji danych, klasyfikacji i generowania strukturalnego