Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

JSON-módus és sémakényszerítés

10. lecke 16 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. JSON-módus és sémakényszerítés
  2. JSON-módus kontra Strukturált Kimenet
  3. Strukturált Kimenet JSON Sémával
  4. Szigorú Strukturált Kimenet szabályai
  5. Segédfüggvény sémák építéséhez
  6. Példa: Strukturált adatok kinyerése
  7. A kényszerítés előnyeinek mérése
  8. Főbb megállapítások

Lecke frissítve: 2026. november 3. az OpenAI dokumentációja alapján: a temperature és a top_p paraméterek csak none gondolkodási erőfeszítés mellett fogadhatók el, míg a GPT-5.6 modellek alapértelmezetten (medium) gondolkodnak. Ezért az ezeket a paramétereket beállító hívásoknak meg kell adniuk a reasoning={"effort": "none"} (Responses API) vagy reasoning_effort="none" (Chat Completions) beállítást. Források: GPT-6 használata · GPT-5.6 Terra.

JSON-módus és sémakényszerítés

Az OpenAI Strukturált Kimenete (Structured Output) garantálja, hogy a modell válasza érvényes JSON legyen, amely megfelel az általad meghatározott sémának. Többé nincs szükség törékeny regex alapú feldolgozásra vagy formázási hibák miatti aggódásra – a kényszerítés maga a generálás szintjén történik.

Ez a nüansz kritikus fontosságú, és mindent megváltoztat egy fejlesztő számára. Ha azt kéred a promptban, hogy „válaszolj JSON-ban“, az inkább könyörgés: a modell az esetek többségében engedelmeskedik, de egyik nap előtaggal kezdi a választ („Íme a kért JSON:“), Markdown backticeket ad hozzá, vagy elfelejt egy vesszőt, és a json.loads kivételt dob éles környezetben hajnali 3-kor, a hét legnagyobb batch feldolgozása közben. A Strukturált Kimenet esetén a kényszerítés a dekódolás során érvényesül: azok a tokenek, amelyek érvénytelen vagy meg nem felelő JSON-t eredményeznének, egyszerűen nem választhatók ki. Többé nem könyörögsz, hanem érvényesítesz.

JSON-módus kontra Strukturált Kimenet

Az OpenAI két szintű kényszerítést kínál, és a különbség egyetlen szón múlik. A JSON-módus érvényes JSON-t garantál strukturális megkötések nélkül; a Strukturált Kimenet garantálja, hogy a JSON megfelel egy általad írt JSON Sémának.

A JSON-módus a probléma felét oldja meg. Biztos lehetsz benne, hogy elemezni tudod a választ, de abban nem, hogy mit tartalmaz: a modell egyik kérésnél annee nevű mezőt használhat, a következőnél year-t, vagy becsomagolhatja a listáját egy resultats objektumba, amit előző nap még nem használt. Prototípushoz vagy ember által olvasott nyers megjelenítéshez ez elegendő; amint azonban a kimenet olyan kódot táplál, amely név alapján ér el mezőket, szükséged van a második szintre.

from openai import OpenAI

client = OpenAI()

# Egyszerű JSON-módus (érvényes JSON, szabad struktú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)

Strukturált Kimenet JSON Sémával

Ez a leg erősebb funkció. Meghatározol egy JSON sémát, és az API garantálja, hogy a kimenet ehhez igazodik. Az alábbi példa egy vásárlói vélemény elemzését végzi, és illusztrálja a séma három kiegészítő felhasználási módját.

A sentiment mezőn lévő enum megakadályozza, hogy a modell olyan közbenső kategóriát találjon ki, mint a „inkább pozitív“: a négy megadott érték közül kell választania, így a kimenet közvetlenül használható szűrőben vagy irányítópulton. A score mező description leírása helyi mini-promptként funkcionál, jelzi az elvárt skálát anélkül, hogy ezt az általános utasításokban meg kellene magyaráznod, és a mezőhöz kapcsolva marad akkor is, ha a prompt evolves. Végül az aspects tömb lehetővé teszi egy ellentmondásos vélemény szétbontását – itt például egy szeretett termék, de katasztrofális kézbesítés –, ahelyett, hogy ezt az árnyalatot egyetlen senkinek sem használó pontszámba zúznánk össze.

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)
# Garantált: a result pontosan a definiált mezőket tartalmazza
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
    print(f"  - {aspect['aspect']}: {aspect['sentiment']}")

Szigorú Strukturált Kimenet szabályai

A strict: true mód saját megkötéseket ír elő a sémára vonatkozóan. Minden mezőnek szerepelnie kell a required listában, és az additionalProperties értékének false-nak kell lennie minden objektumon. A megengedett típusok: string, number, integer, boolean, array, object és null, plusz az enum az értékek korlátozására. Ugyanakkor sem a pattern, sem a minLength/maxLength nem elfogadott: a finomhangolt validáció a kliens oldalon történik.

Ezek a szabályok elsőre meglepőek lehetnek, mert megtiltják az opcionális mezők JSON Sémában szokásos definiálását. A kompromisszum azonban kényelmes: a kódodnak soha nem kell tesztelnie, hogy létezik-e egy kulcs; az mindig ott van. Egy olyan mező esetén, amely jogosan lehet üres – például egy dokumentumból hiányzó telefonszám vagy egy folyamatban lévő szerződés befejező dátuma –, a megoldás nem az, hogy kivesszük a required listából, hanem hogy engedélyezzük a null értéket. Ami a pattern és a hosszkorlátok hiányát illeti, az a következő leckére utal: a séma garantálja a formát, de az üzleti validáció a te feladatod marad, miután megkaptad a választ.

Segédfüggvény sémák építéséhez

Minden híváshoz manuálisan megírni a text.format blokkot gyorsan unalmassá és hibára hajlamossá válik – egy hiányzó name kulcs, egy rosszul helyezett strict, és a hiba az API-tól jön vissza anélkül, hogy jelezné, hol kell keresni. Néhány sor wrapper kód centralizálja a struktúrát, alapértelmezetten alacsony hőmérsékletet alkalmaz (mivel a variabilitás nem ad hozzá semmit a kinyeréshez), és olvashatóvá teszi a hívás helyét.

def structured_query(prompt: str, schema: dict,
                     schema_name: str = "response",
                     model: str = "gpt-5.6-terra",
                     system: str = "") -> dict:
    """Wrapper Strukturált Kimenet kérésekhez."""
    response = client.responses.create(
        model=model,
        reasoning={"effort": "none"},  # a temperature megköveteli a none effortet
        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élda: Strukturált adatok kinyerése

Íme az az eset, amely önmagában igazolja e technika elsajátítását: egy egyszerű szövegként érkezett számla átalakítása a könyvelési rendszered által használható objektummá. A séma három szintet ír le: a számla fejlécét, egy beágyazott vendor objektumot és egy lines tömböt, ahol minden elem azonos alakú. A modellnek tehát meg kell találnia a dokumentum szétszórt információit, és a megfelelő helyre kell tennie őket, beleértve azt az esetet is, amikor egy sor órában van kifejezve egységek helyett, ahol az egységárat óradíjként kell érteni.

Vedd észre, hogy az összegek a sémában kinyerendő mezőkként jelennek meg, nem újraszámolandóként. A modellt arra kérjük, hogy olvasson; az aritmetikai ellenőrzés utólag történik a kódodban, ahol a sorok összege és a kinyert total_ht közötti egyszerű összehasonlítás emberi felülvizsgálatra jelöli ki a dokumentumokat.

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

A kényszerítés előnyeinek mérése

Alkalmazd ezt az elvet egy jól ismert dokumentumon: definiálj egy JSON sémát egy önéletrajz kulcsfontosságú adatainak (név, tapasztalat, készségek, végzettség) kinyerésére, és teszteld három szöveges önéletrajzon, amelyeket szándékosan heterogén elrendezésük miatt választottál ki. Ellenőrizd, hogy a kimenet megfelel-e a sémának akkor is, ha egy szakasz teljesen hiányzik.

Ezután ismételd meg ugyanazt a kinyerést Strukturált Kimenet nélkül, egyszerűen JSON-t kérve a promptban, és tedd egymás mellé a hat kimenetet. A két sorozat összehasonlítása megmutatja, mit hoz a kényszerítés: a különbség ritkán a kinyert tartalomban rejlik, szinte mindig a mezőnevek stabilitásában és a várt kulcsok jelenlétében.

Főbb megállapítások

  • A Strukturált Kimenet garantálja a sémának megfelelő JSON-t már a generálás szintjén
  • Használd a strict: true beállítást a maximális megfelelés érdekében
  • Minden mezőnek required-nek kell lennie, az additionalProperties pedig false
  • Ideális adatok kinyerésére, osztályozásra és feldolgozási folyamatokhoz
  • A finomhangolt validáció (hossz, minta) a fogadás után a kliens oldalon történik