Przejdź do głównej treści
Polski— Wybierz język
Menu

Wyjście strukturalne: Gwarantowany JSON

Lekcja 9 z 22 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Wyjście strukturalne: Gwarantowany JSON
  2. Problem, który to rozwiązuje
  3. Pydantic zamiast ręcznie pisanego JSON Schema
  4. Dwa typowe przypadki użycia
  5. Czego wymaga tryb strict
  6. Kluczowe wnioski

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
  • additionalProperties musi mieć wartość False
  • Obsługiwane typy: string, number, integer, boolean, array, object, null
  • Brak oneOf lub anyOf z 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