Validálás JSON Schema és Zod segítségével
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 (reasoning effort) mellett fogadhatók el, míg a GPT-5.6 modellek alapértelmezetten (medium) gondolkodnak. Az ezeket a paramétereket beállító hívásoknak ezért expliciten 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.
Validálás JSON Schema és Zod segítségével
A Strukturált Kimenet (Structured Output) garantálja a válasz szerkezetét, de az adatok szemantikai érvényességét nem. Egy „email“ mező tartalmazhat olyan karakterláncot, amely nem érvényes e-mail cím. A kliens oldali validálás JSON Schema vagy Zod használatával elengedhetetlen kiegészítője egy robusztus folyamatnak.
Miért kell validálni az átvétel után?
Vedd számba, mit garantál az API, és a munkamegosztás azonnal világossá válik. Az OpenAI Strukturált Kimenete biztosítja, hogy a JSON szintaktikailag helyes legyen, hogy a deklarált típusok betartásra kerüljenek – egy karakterlánc karakterlánc marad, egy egész szám egész szám marad –, hogy minden kötelező mező jelen legyen, és hogy az enum által korlátozott értékek a listába tartozzanak. Ezen a négy ponton nyugodt szívvel írhatod a kódodat.
Minden más rád hárul, ami négy problémakört fed le. A formátumi korlátozások kiesnek a szigorú sémából: semmi sem akadályozza meg a modellt abban, hogy jean.dupont(at)example.fr formátumban adjon vissza egy értéket egy email mezőben, vagy 15/03/2026 formátumú dátumot adjon, amikor ISO formátumot vársz. A határértékeket sem ellenőrzi: sem a karakterlánc hosszát, sem a számok tartományát nem vizsgálja; egy 350 éves életkor hiba nélkül átmegy. A mezők közötti konzisztencia is elérhetetlen marad – egy end_date, amely korábbi, mint a start_date, tökéletesen érvényes JSON. És az üzleti logikai érvényességnek nincs oka foglalkoztatni az API-t: egy SIRET-számnak (francia cégazonosító) tizennégy számjegyből kell állnia, de ez a te domain-tudásod, nem a dekódolóé.
Ez a négy problémakör közös ijesztő tulajdonsággal bír: nem okoznak látható hibákat. Egy rosszul formázott e-mail cím, amelyet elmentesz az adatbázisba, csak hetekkel később válik nyilvánvalóvá, amikor a e-mail kampány visszapattan. Innen a szabály: validálj mentés előtt, soha utána.
Python validálás jsonschema segítségével
A gyakorlati következmény az, hogy ugyanahhoz az adathoz két sémára van szükséged. Az elsőt küldöd az API-nak: szándékosan lecsupaszított, csak arra korlátozódik, amit a szigorú mód elfogad. A második nálad marad, és ez hordozza a finomhangolt korlátozásokat – format, pattern, minimum, maximum. Ez a látszólagos duplikáció a felelősségek szétválasztását szolgálja: az egyik keretezi a generálást, a másik védi a tárolódat. Az alábbi példában csak a role enum jelenik meg mindkettőben, mert ez az egyetlen korlátozás, amelyet mindkét szint ki tud fejezni.
import json
from jsonschema import validate, ValidationError
# Séma az OpenAI API-hoz (szigorú, formátum/pattern nélkül)
api_schema = {
"type": "object",
"properties": {
"email": {"type": "string"},
"age": {"type": "integer"},
"role": {"type": "string", "enum": ["admin", "user", "viewer"]}
},
"required": ["email", "age", "role"],
"additionalProperties": False
}
# Kiterjesztett séma a kliens oldali validáláshoz
validation_schema = {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"pattern": r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z]{2,}$"
},
"age": {
"type": "integer",
"minimum": 0,
"maximum": 150
},
"role": {"type": "string", "enum": ["admin", "user", "viewer"]}
},
"required": ["email", "age", "role"]
}
def validate_response(data: dict) -> tuple[bool, str]:
"""Érvényesíti az LLM választ a kiterjesztett séma alapján."""
try:
validate(instance=data, schema=validation_schema)
return True, "Valid"
except ValidationError as e:
return False, f"Error: {e.message}"
Validálás Pydantic segítségével
A Pydantic gyakran kényelmesebb, mint a jsonschema a Pythonban történő validáláshoz, és a különbség abban rejlik, mit kapsz kimenetként. A jsonschema csak igen/nem választ ad, és egy szótárat (dictionary) hagy rád, amelyet data["email"] módon kezelsz, szerkesztői segítség nélkül. A Pydantic ezzel szemben egy típusos objektumot ad vissza: működik az automatikus kiegészítés, az attribútum nevében lévő elírás már íráskor kiszűrődik, és az adat ezután konverzió nélkül áramlik tovább.
A ContactExtraction modell közvetlenül a meződeklarációkban fejezi ki a határértékeket. A date_extraction mezőn lévő field_validator azt az esetet fedezi le, amelyet egyetlen típusannotáció sem képes kezelni: a karakterlánc valóban karakterlánc, de valós dátumot kell reprezentálnia – a 2026-02-31 kielégít bármilyen ésszerű pattern-t, mégsem létezik. A kinyerő függvény bemutatja a teljes láncolatot, az API-nak küldött lecsupaszított sémától a validált példányosításig.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Validációs séma kontaktadatok kinyeréséhez."""
last_name: str = Field(min_length=2, max_length=100)
first_name: str = Field(min_length=2, max_length=100)
email: EmailStr
phone: str = Field(pattern=r"^\+?[0-9\s\-\.]{10,15}$")
company: str
title: str
extraction_date: str
@field_validator("extraction_date")
@classmethod
def validate_date(cls, v):
try:
date.fromisoformat(v)
return v
except ValueError:
raise ValueError(f"Invalid date: {v}")
def extract_and_validate(text: str) -> ContactExtraction:
"""Kinyer egy kontaktot és validálja az adatokat."""
# Séma az API-hoz (finomhangolt korlátozások nélkül)
api_schema = {
"type": "object",
"properties": {
"last_name": {"type": "string"},
"first_name": {"type": "string"},
"email": {"type": "string"},
"phone": {"type": "string"},
"company": {"type": "string"},
"title": {"type": "string"},
"extraction_date": {"type": "string"}
},
"required": ["last_name", "first_name", "email", "phone",
"company", "title", "extraction_date"],
"additionalProperties": False
}
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Extract contact information. "
"Date format: YYYY-MM-DD.",
input=text,
text={
"format": {
"type": "json_schema",
"name": "contact",
"schema": api_schema,
"strict": True
}
}
)
data = json.loads(response.output_text)
# Pydantic validálás finomhangolt korlátozásokkal
return ContactExtraction(**data)
Validálás Zod segítségével (TypeScript/Node.js)
Ha a backended TypeScriptben íródott, a Zod a referenciaeszköz, és hoz egy előnyt, amit a Pydanticnak nem kell nyújtania: a z.infer közvetlenül a validációs sémából vezeti le a TypeScript típust. Egyszer írod le a struktúrát, és a fordító ezután ismeri az Invoice szerkezetét anélkül, hogy párhuzamos interfészt kellene karbantartanod, így nincs kockázata az eltérésnek.
Az alábbi számla séma illusztrálja a munkamegosztást: az API oldalán a siret csupán egy karakterlánc; a Zod oldalán pontosan tizennégy karakterből kell állnia, és csak számjegyeket tartalmazhat. A végső parse kivételt dob, ha az adat nem illik a mintába, és ez a kívánt viselkedés – egy hangos hiba, amely megszakítja a dokumentumfeldolgozást, jobb, mint egy fantázia SIRET-számú számla, amely ott pihen az adatbázisban tízezer másik között.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Zod séma finomhangolt validálásokkal
const InvoiceSchema = z.object({
number: z.string().regex(/^[A-Z]{2}-\d{4}-\d{4}$/),
date: z.string().date(),
amount_excl_tax: z.number().positive(),
vat_rate: z.number().min(0).max(100),
amount_incl_tax: z.number().positive(),
supplier: z.object({
name: z.string().min(2),
siret: z.string().length(14).regex(/^\d+$/),
}),
});
type Invoice = z.infer<typeof InvoiceSchema>;
async function extractInvoice(text: string): Promise<Invoice> {
const response = await client.responses.create({
model: "gpt-5.6-terra",
instructions: "Extract invoice data.",
input: text,
text: {
format: {
type: "json_schema",
name: "invoice",
schema: {
type: "object",
properties: {
number: { type: "string" },
date: { type: "string" },
amount_excl_tax: { type: "number" },
vat_rate: { type: "number" },
amount_incl_tax: { type: "number" },
supplier: {
type: "object",
properties: {
name: { type: "string" },
siret: { type: "string" },
},
required: ["name", "siret"],
additionalProperties: false,
},
},
required: ["number", "date", "amount_excl_tax",
"vat_rate", "amount_incl_tax", "supplier"],
additionalProperties: false,
},
strict: true,
},
},
});
const data = JSON.parse(response.output_text);
// Zod validálás finomhangolt korlátozásokkal
return InvoiceSchema.parse(data);
}
Mintázat: újrapróbálkozás javítással
Amikor a validálás sikertelen, küldd vissza a hibát a modellnek javításra. Ez a reflex megváltoztatja a hiba természetét: a rossz formátumú dátum nem egy felhasználó felé buborékoló kivétel lesz, hanem egy néhány száz milliszekundumos extra kör, amit senki sem vesz észre. A mechanizmus egyszerű: visszainjektáljuk a validációs üzenetet a következő próbálkozás promptjába, így a modell pontosan tudja, mi ment félre, ahelyett, hogy másodszorra is vakon találgatna.
Ez a kényelem azonban határokat igényel. Korlátozd a próbálkozások számát, különben egy lehetetlen korlátozás – például egy külföldi számokra túl szigorú pattern – hívások sorozatába kerget. És figyeld az újrapróbálkozási arányt: ha a kinyeréseid negyede újrapróbálkozáson megy keresztül, a probléma a kezdeti promptban vagy a sémában rejlik, nem a modellben.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Kinyer és validál automatikus újrapróbálkozással."""
last_error = None
for attempt in range(max_retries):
input_text = prompt
if last_error:
input_text += (f"\n\nWARNING: Your previous response had "
f"this validation error: {last_error}\n"
f"Correct and try again.")
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
input=input_text,
text={"format": {"type": "json_schema",
"name": "data",
"schema": schema,
"strict": True}},
temperature=0.1
)
data = json.loads(response.output_text)
is_valid, error = validator(data)
if is_valid:
return data
last_error = error
raise ValueError(f"Failed after {max_retries} attempts: {last_error}")
Tesztpad naptármeghívókhoz
Készíts egy Pydantic sémát események kinyerésére – cím, dátum, idő, helyszín, résztvevők –, majd csatlakoztasd egy Strukturált Kimenet hívás mögé. Teszteld öt meghívót tartalmazó e-mailen, ügyelve arra, hogy legyen közöttük legalább egy, ahol az időt szövegesen írják le („csütörtök késő délelőtt“), és egy, ahol a helyszín implicit („mint szokott, a tárgyalóban“). Ezek azok az esetek, amelyek megtörik a validálást, és ezek dominálnak egy valós postafiókban.
Ezután add hozzá az automatikus újrapróbálkozást, és mérj meg két értéket: az első próbálkozásra elért sikerarányt és az újrapróbálkozás utáni arányt. A második megmutatja, mit ér a javítás, az első pedig azt, hogy át kell-e dolgoznod az utasításaidat, ahelyett, hogy egy második esélyre számítanál.
Főbb megállapítások
- A Strukturált Kimenet garantálja a szerkezetet, de nem a szemantikai érvényességet
- Használj két sémát: egyet az API-nak (szigorú), egyet a kliens validáláshoz
- A Pydantic (Python) és a Zod (TypeScript) a referenciaeszközök
- A visszajelzéssel kombinált újrapróbálkozási minta a validálási hibák többségét kijavítja
- Mindig validálj kliens oldalon, mielőtt elmented az adatokat