Obmedzenia režimu JSON a spracovanie chýb
Na tejto strane
Platné neznamená správne
Režim JSON zaručuje syntakticky platný JSON, nie však sémanticky správny JSON. Tento rozdiel sa môže počas vývoja zdať nepatrný, no v produkcii sa stáva kritickým. JSON, ktorý sa analyzuje bez chýb, ale obsahuje neočakávané kľúče, spôsobuje presne ten typ chyby, ktorého vystopovanie trvá dni, pretože sa pri jej vzniku nevyhodí žiadna výnimka.
Žiadne záruky schémy
Mechanizmus nič nevie o tvojej schéme: nikdy nevidel štruktúru, ktorú tvoj kód očakáva. Model môže vynechať pole, ktoré potrebuješ, pridať také, ktoré si nepožadoval, premenovať kľúč – napríklad firstName namiesto first_name – alebo zmeniť typ tým, že vráti "42" ako reťazec, keď si očakával číslo 42. Nič z toho nie je neplatný JSON.
# Očakávaš toto:
# {"name": "Alice", "age": 30, "city": "Paris"}
# Ale môžeš dostať:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
JSON je platný, ale štruktúra nezodpovedá tomu, čo tvoj kód očakáva. To je zásadný rozdiel oproti vlastným štruktúrovaným výstupom (Custom Structured Outputs).
Povinná validácia na strane klienta
Keďže schéma nie je zaručená, validácia zostáva na tebe. Minimálny vzor robí tri veci v poradí: pokúsi sa o analýzu, overí, či je koreň objekt (nie zoznam alebo skalár), a následne skontroluje povinné kľúče. Každé zlyhanie vyvolá výnimku ValueError so správou, ktorú môžeš použiť v logoch.
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Analyzuje JSON a overí povinné kľúče."""
try:
data = json.loads(raw_content)
except json.JSONDecodeError as e:
raise ValueError(f"Neplatný JSON: {e}")
if not isinstance(data, dict):
raise ValueError(f"Očakával sa JSON objekt, prijaté {type(data).__name__}")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Chýbajúce kľúče: {missing}")
return data
# Použitie
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"Neplatný výstup: {e}")
fallback_processing(raw_content)
Verzia v TypeScrite ide o krok ďalej tým, že okrem prítomnosti kľúčov overuje aj to, či vrátená kategória patrí do zoznamu povolených hodnôt. Toto je kontrola, ktorá najčastejšie chýba, a práve ona zabraňuje tomu, aby tiket klasifikovaný ako "urgent_billing" ticho prešiel cez tvoje smerovanie.
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(`Chýbajúce kľúče: ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Neplatná kategória: ${data.category}`);
}
return data as TicketClassification;
}
Tri zlyhania, na ktoré narazíš
Prvým je orezaný JSON. Ak odpoveď dosiahne limit max_tokens, bude prerušená uprostred toku a stane sa neplatnou – chýba jej uzatváracia zátvorka. Príznak spozoruješ ešte pred samotnou analýzou: finish_reason sa rovná "length" namiesto "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # Príliš malé na kompletný JSON
)
# response.choices[0].finish_reason bude "length" namiesto "stop"
if response.choices[0].finish_reason == "length":
print("Upozornenie: Orezaaná odpoveď, zvýšte max_tokens")
Vždy kontroluj finish_reason: ak sa rovná "length", odpoveď je neúplná, bez ohľadu na to, čo hovorí zvyšok obsahu.
Druhé zlyhanie sa týka typov. Vek môže prísť ako reťazec, cena ako celé číslo, keď očakávaš desatinné. Namiesto dôvery vo výstup obal prístup pomocnou funkciou, ktorá sa pokúsi o konverziu a v prípade zlyhania sa vráti k predvolenej hodnote.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Extrahuje celé číslo, v prípade potreby ho skonvertuje."""
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
# Použitie
age = safe_get_int(data, "age", default=0)
Tretím je premenovanie kľúčov. Pri francúzskom prompte môže model ľahko zmeniť phone na telephone alebo name na nom. Mapovanie synonym absorbuje tieto variácie bez potreby opakovať volanie.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Normalizuje kľúče pomocou mapovania synonym."""
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
# Mapovanie synonym
mapping = {
"name": ["name", "nom", "full_name", "fullName"],
"email": ["email", "mail", "e-mail", "emailAddress"],
"phone": ["phone", "telephone", "tel", "phoneNumber"],
}
normalized = normalize_keys(raw_data, mapping)
Opakovanie so spätnou väzbou
Keď validácia zlyhá napriek tvojej najlepšej snahe, najlepšou odpoveďou nie je opakovať presne to isté volanie: povedz modelu, čo sa pokazilo. Tým, že mu vrátiš jeho vlastnú odpoveď späť do konverzácie spolu so správou o chybe, poskytneš mu kontext potrebný na samokorekciu, čo sa zvyčajne podarí už pri druhom pokuse.
import json
def call_with_retry(client, messages, max_retries=3):
"""Volanie s opakovaním a spätnou väzbou o chybe."""
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) # Tvoja validačná funkcia
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Pridanie spätnej väzby o chybe do kontextu
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"Tvoja odpoveď je neplatná: {e}. Oprav ju a vráť platný JSON."
})
else:
raise RuntimeError(f"Zlyhanie po {max_retries} pokusoch: {e}")
Signál na zmenu prístupu
Ak sa pristihneš pri písaní rozsiahleho validačného kódu, je to silný signál, že je čas migrovať na vlastné štruktúrované výstupy (Custom Structured Outputs). Tri typické prahové hodnoty to potvrdzujú: pri viac ako piatich poliach na validáciu sa kontrolná funkcia stane dlhšou než samotné volanie; akonáhle sa typy stanú komplexnými s vnorenými zoznamami alebo enumami, manuálna validácia sa stane neoddeliteľnou od chýb, ktoré zavádza; a pre akúkoľvek kritickú produkčnú pipeline je delegovanie obmedzení na schému jednoducho bezpečnejšie než ich ručná rekonštrukcia.
Kľúčové poznatky
- Režim JSON zaručuje platný JSON, nie však platnú schému
- Vždy validuj výstup na strane klienta: skontroluj povinné kľúče, správne typy a hodnoty v rámci ohraničení
- Skontroluj
finish_reasonna detekciu orezaných odpovedí - Implementuj mechanizmus opakovania so spätnou väzbou o chybe
- Ak sa validácia stane komplexnou, migruj na vlastné štruktúrované výstupy (Custom Structured Outputs)