Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Strukturovaný výstup: Zaručené JSON

Lekce 9 z 22 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Strukturovaný výstup: Zaručené JSON
  2. Problém, který to řeší
  3. Pydantic místo ručně psaného JSON Schema
  4. Dva běžné případy použití
  5. Co vyžaduje striktní režim
  6. Klíčové poznatky

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
  • additionalProperties musí být False
  • Podporované typy: string, number, integer, boolean, array, object, null
  • Žádné oneOf ani anyOf se 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