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

Režim JSON a vynucování schématu

Lekce 10 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Režim JSON a vynucování schématu
  2. Režim JSON vs. Strukturovaný výstup
  3. Strukturovaný výstup s JSON Schema
  4. Pravidla pro přísný strukturovaný výstup
  5. Pomocník pro vytváření schémat
  6. Příklad: Extrakce strukturovaných dat
  7. Měření přínosu omezení
  8. Klíčové poznatky

Lekce aktualizována 3. listopadu 2026 na základě dokumentace OpenAI: parametry temperature a top_p jsou přijímány pouze při úsilí o uvažování (reasoning effort) nastaveném na none, zatímco modely GPT-5.6 ve výchozím nastavení uvažují (medium). Volání, která tyto parametry nastavují, musí proto specifikovat reasoning={"effort": "none"} (Responses API) nebo reasoning_effort="none" (Chat Completions). Zdroje: Using GPT-6 · GPT-5.6 Terra.

Režim JSON a vynucování schématu

Strukturovaný výstup (Structured Output) od OpenAI garantuje, že odpověď modelu bude platným JSONem odpovídajícím schématu, které definuješ. Žádné více křehké parsování pomocí regulárních výrazů ani chyby formátování – omezení se aplikuje přímo na úrovni generování.

Tento nuance je zásadní a pro vývojáře mění vše. Žádost „odpověz v JSONu“ v promptu je prosba: model většinou poslechne, ale jednoho dne prefixed svou odpověď větou „Zde je požadovaný JSON:“, přidá zpětná lomítka Markdownu nebo zapomene čárku a tvůj json.loads vyhodí výjimku v produkci ve 3 hodiny ráno při největší dávce týdne. U Strukturovaného výstupu se omezení aplikuje během dekódování: tokeny, které by vytvořily neplatný nebo nevyhovující JSON, prostě nemohou být vybrány. Přestaneš prosit a začneš vynucovat.

Režim JSON vs. Strukturovaný výstup

OpenAI nabízí dvě úrovně omezení a rozdíl spočívá v jediném slově. Režim JSON garantuje platný JSON bez strukturálních omezení; Strukturovaný výstup garantuje JSON odpovídající schématu JSON Schema, které jsi napsal.

Režim JSON řeší polovinu problému. Máš jistotu, že odpověď naparsuješ, ale nevíš, co obsahuje: model může pojmenovat pole annee v jednom požadavku a year v dalším, nebo zabalit svůj seznam do objektu resultats, který den předtím nepoužil. Pro prototyp nebo surový výstup určený člověku to stačí; jakmile výstup napájí kód, který přistupuje k polím podle jména, potřebuješ druhou úroveň.

from openai import OpenAI

client = OpenAI()

# Jednoduchý režim JSON (platný JSON, volná struktura)
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)

Strukturovaný výstup s JSON Schema

Toto je nejmocnější funkce. Definuješ JSON schéma a API garantuje, že výstup se mu bude řídit. Níže uvedený příklad analyzuje sentiment recenze zákazníka a ilustruje tři doplňková využití schématu.

enum u pole sentiment zabraňuje modelu vymýšlet si промежуточnou kategorii jako „spíše pozitivní“: musí si vybrat ze čtyř poskytnutých hodnot, což činí výstup přímo použitelným ve filtru nebo dashboardu. description pole score funguje jako lokální mini-prompt, který označuje očekávanou škálu, aniž bys ji musel vysvětlovat v obecných instrukcích, a zůstává připojeno k poli, i když se prompt vyvíjí. Nakonec pole aspects typu array ti umožňuje rozložit rozporuplnou recenzi – zde produkt líbivý, ale dodání katastrofální – místo aby se tato nuance rozdrtila do jediného skóre, které 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)
# Garance: result má přesně definovaná pole
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
    print(f"  - {aspect['aspect']}: {aspect['sentiment']}")

Pravidla pro přísný strukturovaný výstup

Režim strict: true ukládá schématu vlastní omezení. Všechna pole se musí objevit v required a additionalProperties musí být false u každého objektu. Povolené typy jsou string, number, integer, boolean, array, object a null, plus enum pro omezení hodnot. Ani pattern, ani minLength/maxLength však nejsou přijímány: jemné validace probíhá na straně klienta.

Tato pravidla mohou být při prvním pokusu překvapivá, protože zakazují volitelná pole tak, jak jsou obvykle psána v JSON Schema. Kompromis je však pohodlný: tvůj kód nikdy nemusí testovat, zda klíč existuje; je tam vždy. Pro pole, které může legitimně být prázdné – chybějící telefonní číslo v dokumentu, datum ukončení probíhající smlouvy – řešením není odstranit jej z required, ale povolit, aby bylo null. Co se týče absence pattern a omezení délky, signalizuje to další lekci: schéma garantuje formu, ale obchodní validace zůstává tvou prací, jakmile je odpověď přijata.

Pomocník pro vytváření schémat

Ruční psaní bloku text.format pro každý požadavek se rychle stává zdlouhavým a náchylným k překlepům – chybějící klíč name, špatně umístěné strict a chyba přichází z API bez indication, kde hledat. Několik řádků wrapper kódu centralizuje strukturu, ve výchozím nastavení aplikuje nízkou teplotu (protože variabilita nic nepřidává k extrakci) a činí místo volání čitelným.

def structured_query(prompt: str, schema: dict,
                     schema_name: str = "response",
                     model: str = "gpt-5.6-terra",
                     system: str = "") -> dict:
    """Wrapper pro požadavky Strukturované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)

Příklad: Extrakce strukturovaných dat

Zde je případ použití, který sám o sobě ospravedlňuje naučení se této techniky: transformace faktury přijaté jako prostý text na objekt použitelný tvým účetním systémem. Schéma popisuje tři úrovně – hlavičku faktury, vnořený objekt vendor a pole lines, kde každý prvek má stejný tvar. Model musí tedy nejen lokalizovat informace rozptýlené v dokumentu, ale také je umístit na správné místo, včetně řádku vyjádřeného v hodinách místo jednotek, kde je jednotková cena chápána jako hodinová sazba.

Všimni si, že součty se ve schématu objevují jako pole k extrakci, nikoli k přepočtu. Žádáme model, aby četl; kontrola aritmetiky probíhá až poté v tvém kódu, kde jednoduché porovnání mezi součtem řádků a extrahovaným total_ht označí dokumenty k lidské revizi.

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."
)

Měření přínosu omezení

Aplikuj tento princip na dokument, který dobře znáš: definuj JSON schéma pro extrakci klíčových informací z životopisu – jméno, zkušenosti, dovednosti, vzdělání – a otestuj jej na třech životopisech v prostém textu, které jsi záměrně vybral pro jejich heterogenní rozložení. Ověř, že výstup respektuje schéma, i když zcela chybí některá sekce.

Poté opakuj stejnou extrakci bez Strukturovaného výstupu, jednoduše požadováním JSONu v promptu, a ponech si všech šest výstupů vedle sebe. Porovnání obou sérií ukáže, co omezení přináší: rozdíl zřídka spočívá v extrahovaném obsahu, téměř vždy ve stabilitě názvů polí a přítomnosti očekávaných klíčů.

Klíčové poznatky

  • Strukturovaný výstup garantuje JSON odpovídající schématu na úrovni generování
  • Použij strict: true pro maximální shodu
  • Všechna pole musí být required s additionalProperties: false
  • Ideální pro extrakci dat, klasifikaci a zpracovatelské pipeline
  • Jemná validace (délka, pattern) probíhá na straně klienta po přijetí