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

Režim JSON a vynucovanie schémy

Lekcia 10 z 16 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Režim JSON a vynucovanie schémy
  2. Režim JSON verzus Štruktúrovaný výstup
  3. Štruktúrovaný výstup so schémou JSON
  4. Pravidlá pre prísny štruktúrovaný výstup
  5. Pomocník na budovanie schém
  6. Príklad: Extrakcia štruktúrovaných dát
  7. Meranie toho, čo obmedzenie prináša
  8. Kľúčové poznatky

Lekcia aktualizovaná 3. novembra 2026 na základe dokumentácie OpenAI: parametre temperature a top_p sú akceptované len pri úsilí o logické uvažovanie (reasoning effort) nastavenom na none, zatiaľ čo modely GPT-5.6 štandardne uvažujú (medium). Volania, ktoré nastavujú tieto parametre, preto musia špecifikovať reasoning={"effort": "none"} (Responses API) alebo reasoning_effort="none" (Chat Completions). Zdroje: Používanie GPT-6 · GPT-5.6 Terra.

Režim JSON a vynucovanie schémy

Štruktúrovaný výstup (Structured Output) od OpenAI garantuje, že odpoveď modelu bude platný JSON zodpovedajúci schéme, ktorú definuješ. Žiadne viac krehké parsovanie pomocou regulárnych výrazov ani chyby formátovania – obmedzenie sa aplikuje priamo na úrovni generovania.

Tento nuans je kritický a mení všetko pre vývojára. Požiadať v promte „odpovedz v JSON“ je prosba: model väčšinou poslúchne, ale jedného dňa pred svoju odpoveď pripojí „Tu je požadovaný JSON:“, pridá spätné lomky Markdown alebo zabudne čiarku a tvoje json.loads vyhodí výnimku v produkcii o tretej ráno počas najväčšej dávky týždňa. Pri štruktúrovanom výstupe sa obmedzenie aplikuje počas dekódovania: tokeny, ktoré by vytvorili neplatný alebo nevyhovujúci JSON, jednoducho nemôžu byť vybrané. Prestaneš prosiť a začneš vynucovať.

Režim JSON verzus Štruktúrovaný výstup

OpenAI ponúka dve úrovne obmedzenia a rozdiel závisí od jedného slova. Režim JSON garantuje platný JSON bez štrukturálnych obmedzení; Štruktúrovaný výstup garantuje JSON zodpovedajúci schéme JSON Schema, ktorú si napísal.

Režim JSON rieši polovicu problému. Máš istotu, že odpoveď naparsuješ, ale nie si si istý, čo obsahuje: model môže v jednej požiadavke nazvať pole annee a v ďalšej year, alebo zabaliť svoj zoznam do objektu resultats, ktorý deň predtým nepoužil. Pre prototyp alebo surový výstup určený človeku to stačí; hneď ako výstup napája kód, ktorý pristupuje k poliam podľa názvu, potrebuješ druhú úroveň.

from openai import OpenAI

client = OpenAI()

# Jednoduchý režim JSON (platný JSON, voľná štruktúra)
response = client.responses.create(
    model="gpt-5.6-terra",
    instructions="Always respond in JSON.",
    input="List 3 programming languages with their year of creation.",
    text={"format": {"type": "json_object"}}
)

import json
data = json.loads(response.output_text)
print(data)

Štruktúrovaný výstup so schémou JSON

Toto je najvýkonnejšia funkcia. Definuješ schému JSON a API garantuje, že výstup sa jej bude držať. Nasledujúci príklad analyzuje sentiment recenzie zákazníka a ilustruje tri doplnkové využitia schémy.

enum pri poli sentiment zabraňuje modelu vymyslieť si medziľahlú kategóriu ako „skôr pozitívny“: musí si vybrať medzi štyrmi poskytnutými hodnotami, čo robí výstup priamo použiteľným vo filtri alebo dashboarde. description poľa score funguje ako lokálny mini-prompt, ktorý naznačuje očakávanú škálu bez toho, aby si ju musel vysvetľovať v všeobecných inštrukciách, a zostáva pripojená k poľu, aj keď sa prompt vyvíja. Nakoniec, pole aspects ako pole ti umožňuje rozložiť rozporuplnú recenziu – tu produkt páčil, ale doručenie zlyhalo – namiesto toho, aby si túto nuansu rozdrvil do jediného skóre, ktoré nikomu nepomôže.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Analyze the sentiment of: 'The product is excellent "
          "but the delivery was catastrophic.'",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "schema": {
                "type": "object",
                "properties": {
                    "sentiment": {
                        "type": "string",
                        "enum": ["positive", "negative", "mixed", "neutral"]
                    },
                    "score": {
                        "type": "number",
                        "description": "Score from -1.0 (very negative) to 1.0 (very positive)"
                    },
                    "aspects": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "aspect": {"type": "string"},
                                "sentiment": {
                                    "type": "string",
                                    "enum": ["positive", "negative", "neutral"]
                                }
                            },
                            "required": ["aspect", "sentiment"],
                            "additionalProperties": False
                        }
                    },
                    "summary": {"type": "string"}
                },
                "required": ["sentiment", "score", "aspects", "summary"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
)

result = json.loads(response.output_text)
# Garantované: result má presne definované polia
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
    print(f"  - {aspect['aspect']}: {aspect['sentiment']}")

Pravidlá pre prísny štruktúrovaný výstup

Režim strict: true ukladá schéme vlastné obmedzenia. Všetky polia sa musia objaviť v required a additionalProperties musí byť false pri každom objekte. Povolené typy sú string, number, integer, boolean, array, object a null, plus enum na obmedzenie hodnôt. Ani pattern, ani minLength/maxLength však nie sú akceptované: jemná validácia sa deje na strane klienta.

Tieto pravidlá môžu byť pri prvom pokuse prekvapivé, pretože zakazujú voliteľné polia tak, ako sa zvyčajne píšu v JSON Schema. Kompromis je však pohodlný: tvoj kód nikdy nemusí testovať, či kľúč existuje; je tam vždy. Pre pole, ktoré môže legitímne chýbať – chýbajúce telefónne číslo v dokumente, dátum ukončenia pre prebiehajúcu zmluvu – riešením nie je odstrániť ho z required, ale povoliť, aby bolo null. Čo sa týka absencie pattern a ohraničení dĺžky, signalizuje to nasledujúcu lekciu: schéma garantuje formu, ale business validácia zostáva tvojou úlohou po prijatí odpovede.

Pomocník na budovanie schém

Ručné písanie bloku text.format pre každé volanie sa rýchlo stáva zdĺhavým a náchylným na preklepy – chýbajúci kľúč name, misplaced strict a chyba sa vráti z API bez toho, aby naznačila, kde hľadať. Niekoľko riadkov kódu ako wrapper centralizuje štruktúru, štandardne aplikuje nízku teplotu (keďže variabilita pri extrakcii nič nepridáva) a robí miesto volania čitateľným.

def structured_query(prompt: str, schema: dict,
                     schema_name: str = "response",
                     model: str = "gpt-5.6-terra",
                     system: str = "") -> dict:
    """Wrapper pre požiadavky štruktúrovaného výstupu."""
    response = client.responses.create(
        model=model,
        reasoning={"effort": "none"},  # temperature vyžaduje effort none
        instructions=system or "Respond in JSON according to the provided schema.",
        input=prompt,
        text={
            "format": {
                "type": "json_schema",
                "name": schema_name,
                "schema": schema,
                "strict": True
            }
        },
        temperature=0.1
    )
    return json.loads(response.output_text)

Príklad: Extrakcia štruktúrovaných dát

Tu je prípad použitia, ktorý sám o sebe ospravedlňuje naučenie sa tejto techniky: transformácia faktúry prijatej ako plain text na objekt použiteľný tvojím účtovným systémom. Schéma opisuje tri úrovne – hlavičku faktúry, vnorený objekt vendor a pole lines, kde každý prvok má rovnaký tvar. Model musí teda nielen lokalizovať informácie roztrúsené po dokumente, ale aj umiestniť ich na správne miesto, vrátane riadku vyjadreného v hodinách namiesto kusov, kde je jednotková cena chápaná ako hodinová sadzba.

Všimni si, že sumy sa v schéme objavujú ako polia na extrakciu, nie na prepočet. Žiadame model, aby čítal; kontrola aritmetiky sa deje až následne v tvojom kóde, kde jednoduché porovnanie medzi súčtom riadkov a extrahovaným total_ht označí dokumenty na ľudskú kontrolu.

invoice_schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "date": {"type": "string"},
        "vendor": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "siret": {"type": "string"},
                "address": {"type": "string"}
            },
            "required": ["name", "siret", "address"],
            "additionalProperties": False
        },
        "lines": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string"},
                    "quantity": {"type": "integer"},
                    "unit_price_excl_tax": {"type": "number"},
                    "vat_percent": {"type": "number"}
                },
                "required": ["description", "quantity",
                             "unit_price_excl_tax", "vat_percent"],
                "additionalProperties": False
            }
        },
        "total_excl_tax": {"type": "number"},
        "total_incl_tax": {"type": "number"}
    },
    "required": ["invoice_number", "date", "vendor",
                  "lines", "total_excl_tax", "total_incl_tax"],
    "additionalProperties": False
}

invoice_text = """
Invoice No. 2026-0042
Date: 15/03/2026
Vendor: TechServ SARL, SIRET 123 456 789 00012
12 rue de la Paix, 75002 Paris

- REST API Development x1: 3500.00 EUR excl. tax (VAT 20%)
- Cloud hosting (3 months) x1: 450.00 EUR excl. tax (VAT 20%)
- Technical support x10h: 150.00 EUR excl. tax/h (VAT 20%)

Total excl. tax: 5450.00 EUR
Total incl. tax: 6540.00 EUR
"""

result = structured_query(
    invoice_text,
    invoice_schema,
    schema_name="invoice",
    system="Extract the data from this invoice."
)

Meranie toho, čo obmedzenie prináša

Aplikuj tento princíp na dokument, ktorý dobre poznáš: definuj schému JSON na extrakciu kľúčových informácií z životopisu – meno, skúsenosti, zručnosti, vzdelanie – a otestuj ju na troch životopisoch v plain texte, ktoré si zámerne vybral pre ich heterogénne rozloženie. Over, či výstup dodržiava schému, aj keď úplne chýba niektorá sekcia.

Potom zopakuj tú istú extrakciu bez štruktúrovaného výstupu, jednoducho požiadaním o JSON v promte, a udrž si šesť výstupov vedľa seba. Porovnanie týchto dvoch sérií ukáže, čo obmedzenie prináša: rozdiel zriedka spočíva v extrahovanom obsahu, takmer vždy v stabilite názvov polí a prítomnosti očakávaných kľúčov.

Kľúčové poznatky

  • Štruktúrovaný výstup garantuje JSON zodpovedajúci schéme na úrovni generovania
  • Použi strict: true pre maximálnu zhodu
  • Všetky polia musia byť required s additionalProperties: false
  • Ideálne pre extrakciu dát, klasifikáciu a spracovateľské pipeline
  • Jemná validácia (dĺžka, pattern) sa deje na strane klienta po prijatí