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

A JSON mód korlátai és a hibakezelés

6. lecke 12 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Az érvényes nem egyenlő a helyessel
  2. Nincs garancia a sémára
  3. Kötelező kliensoldali validálás
  4. Három hiba, amivel találkozni fogsz
  5. Újrapróbálkozás visszacsatolással
  6. A jel a megközelítés váltására
  7. Főbb megállapítások

Az érvényes nem egyenlő a helyessel

A JSON mód szintaktikailag érvényes JSON-t garantál, de nem szemantikailag helyeset. Ez a különbség fejlesztés közben apróságnak tűnhet, de éles környezetben kritikussá válik. Az a JSON, amely hiba nélkül elemezhető, de váratlan kulcsokat tartalmaz, pontosan olyan hibát okoz, amelynek a nyomozása napokig tarthat, mivel a probléma fellépésekor nem dobódik kivétel.

Nincs garancia a sémára

A mechanizmus semmit sem tud a sémádról: sosem látta azt a struktúrát, amelyet a kódod elvár. A modell kihagyhat egy szükséges mezőt, hozzáadhat egy nem kértet, átnevezhet egy kulcsot – például firstName helyett first_name –, vagy megváltoztathat egy típust, ha "42"-t ad vissza szövegként, amikor számot (42) vártál. Egyik eset sem érvénytelen JSON.

# Ezt várod:
# {"name": "Alice", "age": 30, "city": "Paris"}

# De ezt kaphatod:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}

A JSON érvényes, de a struktúra nem egyezik azzal, amit a kódod elvár. Ez az alapvető különbség az egyedi strukturált kimenetekhez (Custom Structured Outputs) képest.

Kötelező kliensoldali validálás

Mivel a séma nincs garantálva, a validálás rád hárul. A minimális minta három lépést hajt végre sorrendben: megkísérli az elemzést, ellenőrzi, hogy a gyökér objektum-e (nem lista vagy skalár), majd ellenőrzi a kötelező kulcsok jelenlétét. Minden hiba esetén egy ValueError kivételt dob, amelynek üzenetét felhasználhatod a naplózásban.

import json
from typing import Optional

def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
    """JSON elemzése és a kötelező kulcsok ellenőrzése."""
    try:
        data = json.loads(raw_content)
    except json.JSONDecodeError as e:
        raise ValueError(f"Érvénytelen JSON: {e}")

    if not isinstance(data, dict):
        raise ValueError(f"JSON objektum várható, de {type(data).__name__} érkezett")

    missing = [k for k in required_keys if k not in data]
    if missing:
        raise ValueError(f"Hiányzó kulcsok: {missing}")

    return data

# Használat
try:
    result = parse_and_validate(
        response.choices[0].message.content,
        required_keys=["name", "category", "priority"]
    )
    process_ticket(result)
except ValueError as e:
    log_error(f"Érvénytelen kimenet: {e}")
    fallback_processing(raw_content)

A TypeScript verzió egy lépéssel tovább megy: a kulcsok jelenlétén túl ellenőrzi, hogy a visszaadott kategória szerepel-e az engedélyezett listában. Ez az ellenőrzés hiányzik leggyakrabban, pedig ez akadályozza meg, hogy egy „urgent_billing“ kategóriájú jegy észrevétlenül csússzon át a routingszűrőn.

interface TicketClassification {
  category: string;
  priority: string;
  sentiment: string;
  summary: string;
}

function validateTicket(raw: string): TicketClassification {
  const data = JSON.parse(raw);

  const requiredKeys = ["category", "priority", "sentiment", "summary"];
  const missing = requiredKeys.filter((k) => !(k in data));

  if (missing.length > 0) {
    throw new Error(`Hiányzó kulcsok: ${missing.join(", ")}`);
  }

  const validCategories = ["billing", "account", "technical", "feature_request", "other"];
  if (!validCategories.includes(data.category)) {
    throw new Error(`Érvénytelen kategória: ${data.category}`);
  }

  return data as TicketClassification;
}

Három hiba, amivel találkozni fogsz

Az első a csonka JSON. Ha a válasz eléri a max_tokens limitet, a rendszer félbehagyja a generálást, és az eredmény érvénytelenné válik – a záró kapcsos zárójel sosem érkezik meg. A tünetet már elemzés előtt észreveheted: a finish_reason értéke "length" lesz "stop" helyett.

response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages,
    response_format={"type": "json_object"},
    max_tokens=50  # Túl kicsi a teljes JSON-hoz
)

# response.choices[0].finish_reason értéke "length" lesz "stop" helyett
if response.choices[0].finish_reason == "length":
    print("Figyelmeztetés: Csonka válasz, növeld a max_tokens értékét")

Mindig ellenőrizd a finish_reason értékét: ha az "length", a válasz hiányos, függetlenül attól, mit mond a tartalom többi része.

A második hiba a típusokkal kapcsolatos. Az életkor szövegként érkezhet, az ár egész számként, amikor lebegőpontos számot vártál. A kimenetben való blind megbízás helyett érdemes egy segédfüggvénybe csomagolni a hozzáférést, amely megkísérli az átalakítást, és hiba esetén alapértelmezett értékre áll vissza.

def safe_get_int(data: dict, key: str, default: int = 0) -> int:
    """Egész szám kinyerése, szükség esetén konverzióval."""
    value = data.get(key)
    if value is None:
        return default
    if isinstance(value, int):
        return value
    if isinstance(value, float):
        return int(value)
    if isinstance(value, str):
        try:
            return int(value)
        except ValueError:
            return default
    return default

# Használat
age = safe_get_int(data, "age", default=0)

A harmadik hiba a kulcsok átnevezése. Francia nyelvű prompt esetén a modell könnyen átválthat a phone kulcsról a telephone-re, vagy a name-ről a nom-ra. Egy szinonimatérkép kezeli ezeket a variációkat anélkül, hogy újra kellene hívnod az API-t.

def normalize_keys(data: dict, key_mapping: dict) -> dict:
    """Kulcsok normalizálása szinonimatérkép alapján."""
    normalized = {}
    for standard_key, aliases in key_mapping.items():
        for alias in aliases:
            if alias in data:
                normalized[standard_key] = data[alias]
                break
    return normalized

# Szinonimatérkép
mapping = {
    "name": ["name", "nom", "full_name", "fullName"],
    "email": ["email", "mail", "e-mail", "emailAddress"],
    "phone": ["phone", "telephone", "tel", "phoneNumber"],
}

normalized = normalize_keys(raw_data, mapping)

Újrapróbálkozás visszacsatolással

Ha a validálás a legjobb szándékaid ellenére is sikertelen, a legjobb megoldás nem ugyanannak a hívásnak a megismétlése, hanem annak közlése a modellel, mi ment rosszul. Ha a saját válaszát visszacsatolod a beszélgetésbe a hibaüzenettel együtt, megadod neki a szükséges kontextust az önkorrekcióhoz, ami általában már a második próbálkozásra sikerül.

import json

def call_with_retry(client, messages, max_retries=3):
    """Hívás újrapróbálkozással és hibavisszacsatolással."""
    for attempt in range(max_retries):
        response = client.chat.complete(
            model="mistral-large-latest",
            messages=messages,
            response_format={"type": "json_object"},
            temperature=0
        )

        raw = response.choices[0].message.content
        try:
            data = json.loads(raw)
            validate_schema(data)  # A saját validáló függvényed
            return data
        except (json.JSONDecodeError, ValueError) as e:
            if attempt < max_retries - 1:
                # Hiba visszacsatolása a kontextusba
                messages.append({"role": "assistant", "content": raw})
                messages.append({
                    "role": "user",
                    "content": f"A válaszod érvénytelen: {e}. Javítsd ki, és adj vissza érvényes JSON-t."
                })
            else:
                raise RuntimeError(f"Sikertelen {max_retries} próbálkozás után: {e}")

A jel a megközelítés váltására

Ha azt veszed észre, hogy kiterjedt validáló kódot írsz, az erős jelzés arra, hogy ideje áttérni az egyedi strukturált kimenetekre (Custom Structured Outputs). Három tipikus küszöbérték erősíti meg ezt: ha ötnél több mezőt kell validálni, a vezérlő függvény hosszabb lesz, mint maga a hívás; ha a típusok összetetté válnak (beágyazott listák vagy enumok), a manuális validálás elválaszthatatlanná válik az általa okozott hibáktól; és bármely kritikus éles környezeti folyamat esetén egyszerűen biztonságosabb a korlátozásokat a sémára bízni, mint kézzel újraépíteni őket.

Főbb megállapítások

  • A JSON mód érvényes JSON-t garantál, de nem érvényes sémát
  • Mindig validáld a kimenetet kliensoldalon: ellenőrizd a kötelező kulcsokat, a helyes típusokat és az értékek határait
  • Ellenőrizd a finish_reason értékét a csonka válaszok észleléséhez
  • Implementálj egy újrapróbálkozási mechanizmust hibavisszacsatolással
  • Ha a validálás összetetté válik, térj át az egyedi strukturált kimenetekre