Ierobežojumi un kļūdu apstrāde JSON režīmā
Šajā lapā
Derīgs nenozīmē pareizs
JSON režīms garantē sintaktiski derīgu JSON, nevis semantiski pareizu JSON. Šī atšķirība izstrādes laikā var šķist smalka, taču ražošanas vidē tā kļūst kritiska. JSON, kas tiek parsēts bez kļūdām, bet satur negaidītus atslēgvārdus, rada tieši tāda veida kļūdas, kuru atrašana prasa dienas, jo brīdī, kad problēma faktiski rodas, netiek izraisīts neviens izņēmums.
Nav shēmas garantiju
Mehānisms nezina neko par tavu shēmu: tas nekad nav redzējis struktūru, ko sagaida tavs kods. Modelis var izlaist lauku, kas tev ir nepieciešams, pievienot tādu, ko neesi pieprasījis, pārdēvēt atslēgvārdu – piemēram, firstName vietā izmantot first_name – vai mainīt datu tipu, atgriežot "42" kā virkni, lai gan gaidīji skaitli 42. Neviens no šiem gadījumiem nav nedderīgs JSON.
# Tu sagaidi šo:
# {"name": "Alice", "age": 30, "city": "Paris"}
# Bet tu vari saņemt:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
JSON ir derīgs, taču struktūra neatbilst tam, ko sagaida tavs kods. Šī ir fundamentālā atšķirība no pielāgotām strukturētām izvades formām (Custom Structured Outputs).
Obligāta klienta puses validācija
Tā kā shēma nav garantēta, validācija ir tava atbildība. Minimālā pieeja veic trīs darbības secībā: tā mēģina veikt parsēšanu, pārbauda, vai sakne ir objekts (nevis saraksts vai skalārs lielums), un pēc tam pārbauda obligāto atslēgvārdu esamību. Katra kļūda izraisa ValueError ar ziņojumu, ko vari izmantot savos žurnālos.
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Parsē JSON un pārbauda obligātās atslēgas."""
try:
data = json.loads(raw_content)
except json.JSONDecodeError as e:
raise ValueError(f"Nederīgs JSON: {e}")
if not isinstance(data, dict):
raise ValueError(f"Tika sagaidīts JSON objekts, saņemts {type(data).__name__}")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Trūkst atslēgu: {missing}")
return data
# Lietošana
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"Nederīga izvade: {e}")
fallback_processing(raw_content)
TypeScript versija iet soli tālāk, pārbaudot ne tikai atslēgu esamību, bet arī to, vai atgrieztā kategorija pieder atļauto sarakstam. Šī ir pārbaude, kas visbiežāk tiek izlaista, un tieši tā novērš situācijas, kad biļete, kas klasificēta kā "urgent_billing", klusi izslīd cauri tavai maršrutēšanai.
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(`Trūkst atslēgu: ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Nederīga kategorija: ${data.category}`);
}
return data as TicketClassification;
}
Trīs kļūmes, ar kurām saskarsies
Pirmā ir apgriezts JSON. Ja atbilde sasniedz max_tokens limitu, tā tiek pārtraukta plūsmas vidū un kļūst nederīga – noslēdzošā iekava nekad netiek sasniegta. Simptomu vari pamanīt pat pirms parsēšanas: finish_reason ir vienāds ar "length" nevis "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # Par mazu pilnīgam JSON
)
# response.choices[0].finish_reason būs "length" nevis "stop"
if response.choices[0].finish_reason == "length":
print("Brīdinājums: Apgriezta atbilde, palielini max_tokens")
Vienmēr pārbaudi finish_reason: ja tas ir vienāds ar "length", atbilde ir nepilnīga, neatkarīgi no tā, ko saka pārējais saturs.
Otrā kļūme attiecas uz datu tipiem. Vecums var ierasties kā virkne, cena kā vesels skaitlis, lai gan gaidīji peldošo komatu. Tā vietā, lai uzticētos izvadei, aptver piekļuvi palīgfunkcijā, kas mēģina veikt konvertēšanu un kļūmes gadījumā atgriež noklusējuma vērtību.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Iegūst veselu skaitli, veicot konvertēšanu, ja nepieciešams."""
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
# Lietošana
age = safe_get_int(data, "age", default=0)
Trešā ir atslēgvārdu pārdēvēšana. Izmantojot franču valodas uzvedni, modelis var viegli nomainīt phone uz telephone vai name uz nom. Sinonīmu kartēšana absorbē šīs variācijas, nepieprasot tev atkārtot izsaukumu.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Normalizē atslēgas, izmantojot sinonīmu kartēšanu."""
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
# Sinonīmu kartēšana
mapping = {
"name": ["name", "nom", "full_name", "fullName"],
"email": ["email", "mail", "e-mail", "emailAddress"],
"phone": ["phone", "telephone", "tel", "phoneNumber"],
}
normalized = normalize_keys(raw_data, mapping)
Atkārtošana ar atgriezenisko saiti
Kad validācija neizdodas, neskatoties uz taviem labākajiem centieniem, labākā reakcija nav atkārtot tieši to pašu izsaukumu: tev jāpastāsta modelim, kas gāja greizi. Ievadot tā paša atbildi atpakaļ sarunā kopā ar kļūdas ziņojumu, tu nodrocini tam kontekstu, kas nepieciešams paškorrekcijai, parasti jau otrajā mēģinājumā.
import json
def call_with_retry(client, messages, max_retries=3):
"""Izsauc ar atkārtošanu un kļūdu atgriezenisko saiti."""
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) # Tava validācijas funkcija
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Pievieno kļūdas atgriezenisko saiti kontekstam
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"Tava atbilde ir nederīga: {e}. Labo to un atgriez derīgu JSON."
})
else:
raise RuntimeError(f"Neizdevās pēc {max_retries} mēģinājumiem: {e}")
Signāls pieejas maiņai
Ja konstatē, ka raksti plašu validācijas kodu, tas ir spēcīgs signāls, ka ir laiks pāriet uz pielāgotām strukturētām izvades formām (Custom Structured Outputs). Trīs tipiski sliekšņi to apstiprina: pārsniedzot piecus laukus, kas jāvalidē, kontroles funkcija kļūst garāka par pašu izsaukumu; tiklīdz tipi kļūst sarežģīti ar ligzdotiem sarakstiem vai enumerācijām, manuāla validācija kļūst neatdalāma no kļūdām, ko tā ievieš; un jebkurai kritiskai ražošanas cauruļvadam ierobežojumu deleģēšana shēmai ir vienkārši drošāka nekā to rekonstruēšana ar rokām.
Galvenās atziņas
- JSON režīms garantē derīgu JSON, nevis derīgu shēmu
- Vienmēr validē izvadi klienta pusē: pārbaudi obligātās atslēgas, pareizos datu tipus un vērtības noteiktajās robežās
- Pārbaudi
finish_reason, lai noteiktu apgrieztas atbildes - Ievies atkārtošanas mehānismu ar kļūdu atgriezenisko saiti
- Ja validācija kļūst sarežģīta, pārej uz pielāgotām strukturētām izvades formām