Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Štruktúrovaný výstup: Garantované JSON

Lekcia 9 z 22 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Štruktúrovaný výstup: Garantované JSON
  2. Problém, ktorý to rieši
  3. Pydantic namiesto ručne písaného JSON Schema
  4. Dva bežné prípady použitia
  5. Čo vyžaduje striktný režim
  6. Kľúčové poznatky

Š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
  • additionalProperties musí byť False
  • Podporované typy: string, number, integer, boolean, array, object, null
  • Žiadne oneOf ani anyOf so 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: True pre garantované dodržiavanie schémy
  • Ideálne na extrakciu dát, klasifikáciu a štruktúrovanú generáciu