Omezení režimu JSON a zpracování chyb
Na této stránce
Platné neznamená správné
Režim JSON zaručuje syntakticky platný JSON, nikoliv však sémanticky správný JSON. Tento rozdíl se může během vývoje zdát nepatrný, ale v produkčním prostředí je kritický. JSON, který se bez chyb načte, ale obsahuje neočekávané klíče, způsobuje přesně ten typ chyb, jejichž vystopování trvá dny, protože v okamžiku vzniku problému nedojde k vyvolání žádné výjimky.
Žádné záruky schématu
Mechanismus nic neví o vašem schématu: nikdy neviděl strukturu, kterou váš kód očekává. Model může vynechat pole, které potřebujete, přidat pole, o které jste nežádali, přejmenovat klíč – například firstName místo first_name – nebo změnit typ tím, že vrátí "42" jako řetězec, když jste očekávali číslo 42. Žádná z těchto situací není neplatný JSON.
# Očekáváte toto:
# {"name": "Alice", "age": 30, "city": "Paris"}
# Ale můžete obdržet:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
JSON je platný, ale struktura neodpovídá tomu, co váš kód očekává. To je zásadní rozdíl oproti vlastním strukturovaným výstupům (Custom Structured Outputs).
Povinná validace na straně klienta
Protože schéma není zaručeno, odpovědnost za validaci leží na vás. Minimální vzor provádí tři věci v pořadí: pokusí se o parsování, ověří, že kořenem je objekt (nikoliv seznam nebo skalár), a následně zkontroluje povinné klíče. Každé selhání vyvolá ValueError se zprávou, kterou můžete využít v logách.
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Načte JSON a ověří povinné klíč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čekáván JSON objekt, obdrženo {type(data).__name__}")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Chybějící klíče: {missing}")
return data
# Použití
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)
Verze v TypeScriptu jde o krok dál a kromě přítomnosti klíčů ověřuje, zda vrácená kategorie patří do seznamu povolených hodnot. Toto je kontrola, která nejčastěji chybí, a právě ona zabraňuje tomu, aby tiket klasifikovaný jako "urgent_billing" tiše proklouzl vaším směrováním.
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(`Chybějící klíče: ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Neplatná kategorie: ${data.category}`);
}
return data as TicketClassification;
}
Tři selhání, se kterými se setkáte
Prvním je oříznutý JSON. Pokud odpověď narazí na limit max_tokens, bude uprostřed přerušena a stane se neplatnou – chybí jí uzavírací složená závorka. Příznak poznáte ještě před parsováním: finish_reason má hodnotu "length" místo "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # Příliš malé pro úplný JSON
)
# response.choices[0].finish_reason bude "length" místo "stop"
if response.choices[0].finish_reason == "length":
print("Upozornění: Oříznutá odpověď, zvyšte max_tokens")
Vždy kontrolujte finish_reason: pokud má hodnotu "length", je odpověď neúplná, bez ohledu na to, co říká zbytek obsahu.
Druhé selhání se týká typů. Věk může přijít jako řetězec, cena jako celé číslo, když očekáváte desetinné. Místo důvěry ve výstup obalte přístup pomocnou funkcí, která se pokusí o konverzi a v případě selhání vrátí výchozí hodnotu.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Extrahuje celé číslo, v případě potřeby provede konverzi."""
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žití
age = safe_get_int(data, "age", default=0)
Třetím je přejmenování klíčů. Při francouzském promptu může model snadno zaměnit phone za telephone nebo name za nom. Mapování synonym tyto variace absorbuje, aniž byste museli volání opakovat.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Normalizuje klíče pomocí mapování 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
# Mapování 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)
Opakování s zpětnou vazbou
Když validace navzdory vašemu úsilí selže, nejlepší reakcí není opakovat přesně stejné volání: řekněte modelu, co se pokazilo. Tím, že jeho vlastní odpověď spolu se zprávou o chybě vrátíte zpět do konverzace, poskytnete mu kontext potřebný k nápravě, k čemuž obvykle dojde již při druhém pokusu.
import json
def call_with_retry(client, messages, max_retries=3):
"""Volání s opakováním a zpětnou vazbou o chybě."""
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) # Vaše validační funkce
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Přidání zpětné vazby o chybě do kontextu
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"Vaše odpověď je neplatná: {e}. Opravte ji a vraťte platný JSON."
})
else:
raise RuntimeError(f"Selhání po {max_retries} pokusech: {e}")
Signál ke změně přístupu
Pokud zjistíte, že píšete rozsáhlý validační kód, je to silný signál, že je čas migrovat na vlastní strukturované výstupy (Custom Structured Outputs). Tři typické prahové hodnoty to potvrzují: pokud máte více než pět polí k validaci, stane se kontrolní funkce delší než samotné volání; jakmile se typy stanou složitými s vnořenými seznamy nebo výčty, ruční validace se stane neoddělitelnou od chyb, které zavádí; a pro jakékoli kritické produkční pipeline je delegování omezení na schéma jednoduše bezpečnější než jejich ruční rekonstrukce.
Klíčové poznatky
- Režim JSON zaručuje platný JSON, nikoliv však platné schéma
- Vždy validujte výstup na straně klienta: kontrolujte povinné klíče, správné typy a hodnoty v povolených mezích
- Kontrolujte
finish_reasonpro detekci oříznutých odpovědí - Implementujte mechanismus opakování se zpětnou vazbou o chybě
- Pokud se validace stane složitou, migrujte na vlastní strukturované výstupy (Custom Structured Outputs)