Limitările modului JSON și gestionarea erorilor
Pe această pagină
Valid nu înseamnă corect
Modul JSON garantează un JSON sintactic valid, nu un JSON corect din punct de vedere semantic. Această distincție poate părea subtilă în timpul dezvoltării, dar devine critică în producție. Un JSON care se parsează fără erori, dar conține chei neașteptate, generează exact acel tip de bug care necesită zile pentru a fi depistat, deoarece nicio excepție nu este declanșată în momentul în care apare problema.
Nicio garanție privind schema
Mecanismul nu știe nimic despre schema dumneavoastră: nu a văzut niciodată structura pe care codul dumneavoastră o așteaptă. Modelul poate omite un câmp de care aveți nevoie, poate adăuga unul pe care nu l-ați solicitat, poate redenumi o cheie—firstName în loc de first_name—sau poate schimba un tip, returnând "42" ca șir de caractere când vă așteptați la numărul 42. Niciuna dintre aceste situații nu constituie un JSON invalid.
# Vă așteptați la acest lucru:
# {"name": "Alice", "age": 30, "city": "Paris"}
# Dar puteți primi:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
JSON-ul este valid, dar structura nu corespunde cu ceea ce se așteaptă codul dumneavoastră. Aceasta este diferența fundamentală față de ieșirile structurate personalizate (Custom Structured Outputs).
Validare obligatorie la nivel de client
Deoarece schema nu este garantată, validarea vă revine dumneavoastră. Modelul minim face trei lucruri în ordine: încearcă parsarea, verifică dacă rădăcina este un obiect (nu o listă sau un scalar), apoi verifică prezența cheilor obligatorii. Fiecare eșec declanșează o ValueError cu un mesaj pe care îl puteți utiliza în jurnalele dumneavoastră (logs).
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Parsează JSON și verifică cheile obligatorii."""
try:
data = json.loads(raw_content)
except json.JSONDecodeError as e:
raise ValueError(f"JSON invalid: {e}")
if not isinstance(data, dict):
raise ValueError(f"Se aștepta un obiect JSON, s-a primit {type(data).__name__}")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Chei lipsă: {missing}")
return data
# Utilizare
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"Ieșire invalidă: {e}")
fallback_processing(raw_content)
Versiunea TypeScript merge un pas mai departe, verificând, dincolo de prezența cheilor, dacă categoria returnată aparține listei de valori permise. Aceasta este verificarea care lipsește cel mai adesea și cea care împiedică un tichet clasificat ca "urgent_billing" să se strecoare silențios prin sistemul dumneavoastră de rutare.
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(`Chei lipsă: ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Categorie invalidă: ${data.category}`);
}
return data as TicketClassification;
}
Trei tipuri de eșecuri pe care le veți întâlni
Primul este JSON-ul trunchiat. Dacă răspunsul atinge limita max_tokens, acesta este întrerupt în mijlocul fluxului și devine invalid—acolada de închidere nu mai ajunge niciodată. Puteți identifica simptomul chiar înainte de a parsea: finish_reason este egal cu "length" în loc de "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # Prea mic pentru un JSON complet
)
# response.choices[0].finish_reason va fi "length" în loc de "stop"
if response.choices[0].finish_reason == "length":
print("Avertisment: Răspuns trunchiat, măriți max_tokens")
Verificați întotdeauna finish_reason: dacă este egal cu "length", răspunsul este incomplet, indiferent de ceea ce spune restul conținutului.
Al doilea eșec privește tipurile de date. O vârstă poate sosi ca șir de caractere, un preț ca întreg când vă așteptați la un număr zecimal (float). În loc să aveți încredere oarbă în ieșire, încapsulați accesul într-o funcție auxiliară care încearcă conversia și revine la o valoare implicită dacă aceasta eșuează.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Extrage un întreg, cu conversie dacă este necesar."""
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
# Utilizare
age = safe_get_int(data, "age", default=0)
Al treilea este redenumirea cheilor. Cu un prompt în limba franceză, modelul poate trece ușor de la phone la telephone, sau de la name la nom. O mapare de sinonime absoarbe aceste variații fără a vă obliga să reîncercați apelul.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Normalizează cheile folosind o mapare de sinonime."""
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
# Mapare de sinonime
mapping = {
"name": ["name", "nom", "full_name", "fullName"],
"email": ["email", "mail", "e-mail", "emailAddress"],
"phone": ["phone", "telephone", "tel", "phoneNumber"],
}
normalized = normalize_keys(raw_data, mapping)
Reîncercare cu feedback
Când validarea eșuează în ciuda tuturor eforturilor dumneavoastră, cel mai bun răspuns nu este să reîncercați exact același apel: este să spuneți modelului ce nu a funcționat. Prin reintroducerea propriului său răspuns în conversație, împreună cu mesajul de eroare, îi oferiți contextul necesar pentru a se autocorecta, de obicei încă de la a doua încercare.
import json
def call_with_retry(client, messages, max_retries=3):
"""Apel cu reîncercare și feedback de eroare."""
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) # Funcția dumneavoastră de validare
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Adăugați feedback-ul de eroare în context
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"Răspunsul dumneavoastră este invalid: {e}. Corectați-l și returnați un JSON valid."
})
else:
raise RuntimeError(f"Eșec după {max_retries} încercări: {e}")
Semnalul pentru a schimba abordarea
Dacă vă surprindeți scriind cod extensiv de validare, acesta este un semnal puternic că este timpul să migrați către ieșiri structurate personalizate (Custom Structured Outputs). Trei praguri tipice confirmă acest lucru: dincolo de cinci câmpuri de validat, funcția de control devine mai lungă decât apelul însuși; odată ce tipurile devin complexe, cu liste imbricate sau enumerații, validarea manuală devine inseparabilă de bug-urile pe care le introduce; iar pentru orice pipeline critic de producție, delegarea constrângerilor către schemă este pur și simplu mai sigură decât reconstruirea lor manuală.
Puncte cheie
- Modul JSON garantează un JSON valid, nu o schemă validă
- Validați întotdeauna ieșirea la nivel de client: verificați cheile obligatorii, tipurile corecte și valorile încadrate în limite
- Verificați
finish_reasonpentru a detecta răspunsurile trunchiate - Implementați un mecanism de reîncercare cu feedback de eroare
- Dacă validarea devine complexă, migrați către ieșiri structurate personalizate (Custom Structured Outputs)