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

Validálás JSON Schema és Zod segítségével

11. lecke 16 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Validálás JSON Schema és Zod segítségével
  2. Miért kell validálni az átvétel után?
  3. Python validálás jsonschema segítségével
  4. Validálás Pydantic segítségével
  5. Validálás Zod segítségével (TypeScript/Node.js)
  6. Mintázat: újrapróbálkozás javítással
  7. Tesztpad naptármeghívókhoz
  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 (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 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.

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