JSON-módus és sémakényszerítés
Ezen az oldalon
Lecke frissítve: 2026. november 3. az OpenAI dokumentációja alapján: a
temperatureés atop_pparaméterek csaknonegondolkodá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 areasoning={"effort": "none"}(Responses API) vagyreasoning_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: truebeállítást a maximális megfelelés érdekében - Minden mezőnek
required-nek kell lennie, azadditionalPropertiespedigfalse - 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