A JSON mód korlátai és a hibakezelés
Ezen az oldalon
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