Beperkingen van de JSON-modus en foutafhandeling
Op deze pagina
Geldig betekent niet correct
De JSON-modus garandeert syntactisch geldige JSON, geen semantisch correcte JSON. Dit onderscheid lijkt tijdens de ontwikkeling misschien subtiel, maar wordt cruciaal in productie. JSON die zonder fouten parseert maar onverwachte sleutels bevat, veroorzaakt precies dat soort bugs waarvan het dagen duurt om de oorzaak te vinden, omdat er geen uitzondering wordt gegenereerd op het moment dat het probleem zich voordoet.
Geen schemagaranties
Het mechanisme weet niets over uw schema: het heeft de structuur die uw code verwacht nooit gezien. Het model kan een veld weglaten dat u nodig heeft, een veld toevoegen dat u niet hebt gevraagd, een sleutel hernoemen—firstName in plaats van first_name—of een type wijzigen door "42" als string terug te geven terwijl u het getal 42 verwachtte. Niets hiervan is ongeldige JSON.
# U verwacht dit:
# {"name": "Alice", "age": 30, "city": "Paris"}
# Maar u kunt dit ontvangen:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
De JSON is geldig, maar de structuur komt niet overeen met wat uw code verwacht. Dit is het fundamentele verschil met Custom Structured Outputs.
Verplichte validatie aan de clientkant
Omdat het schema niet gegarandeerd is, ligt de validatie bij u. Het minimale patroon doet drie dingen op volgorde: het probeert te parseren, verifieert dat de root een object is (geen lijst of scalar) en controleert vervolgens op verplichte sleutels. Bij elke fout wordt een ValueError gegenereerd met een bericht dat u in uw logs kunt gebruiken.
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Parse JSON en verifieer verplichte sleutels."""
try:
data = json.loads(raw_content)
except json.JSONDecodeError as e:
raise ValueError(f"Ongeldige JSON: {e}")
if not isinstance(data, dict):
raise ValueError(f"JSON-object verwacht, {type(data).__name__} ontvangen")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Ontbrekende sleutels: {missing}")
return data
# Gebruik
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"Ongeldige uitvoer: {e}")
fallback_processing(raw_content)
De TypeScript-versie gaat een stap verder door niet alleen de aanwezigheid van sleutels te controleren, maar ook te verifiëren dat de teruggegeven categorie tot de toegestane lijst behoort. Dit is de controle die het vaakst ontbreekt, en juist deze voorkomt dat een ticket geclassificeerd als "urgent_billing" stilletjes door uw routering glipt.
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(`Ontbrekende sleutels: ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Ongeldige categorie: ${data.category}`);
}
return data as TicketClassification;
}
Drie fouten die u zult tegenkomen
De eerste is afgekapte JSON. Als het antwoord de max_tokens-limiet bereikt, wordt het midden in de stream afgebroken en ongeldig—de afsluitende haakje arriveert nooit. U kunt het symptoom herkennen nog voordat u parseert: finish_reason is gelijk aan "length" in plaats van "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # Te klein voor volledige JSON
)
# response.choices[0].finish_reason zal "length" zijn in plaats van "stop"
if response.choices[0].finish_reason == "length":
print("Waarschuwing: Afgekapt antwoord, verhoog max_tokens")
Controleer altijd finish_reason: als dit gelijk is aan "length", is het antwoord onvolledig, ongeacht wat de rest van de inhoud zegt.
De tweede fout betreft types. Een leeftijd kan als string binnenkomen, een prijs als integer terwijl u een float verwacht. Vertrouw niet blindelings op de uitvoer; kapsel de toegang in met een helper die conversie probeert en terugvalt op een standaardwaarde als dit mislukt.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Haal een integer op, met conversie indien nodig."""
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
# Gebruik
age = safe_get_int(data, "age", default=0)
De derde is het hernoemen van sleutels. Met een Franse prompt kan het model moeiteloos phone wijzigen in telephone, of name in nom. Een synoniemtoewijzing absorbeert deze variaties zonder dat u de oproep hoeft te herhalen.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Normaliseer sleutels met behulp van een synoniemtoewijzing."""
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
# Synoniemtoewijzing
mapping = {
"name": ["name", "nom", "full_name", "fullName"],
"email": ["email", "mail", "e-mail", "emailAddress"],
"phone": ["phone", "telephone", "tel", "phoneNumber"],
}
normalized = normalize_keys(raw_data, mapping)
Opnieuw proberen met feedback
Wanneer validatie ondanks uw beste inspanningen mislukt, is de beste reactie niet om exact dezelfde oproep te herhalen: vertel het model wat er misging. Door zijn eigen antwoord samen met het foutbericht terug in het gesprek te voeren, geeft u het de context die nodig is om zichzelf te corrigeren, meestal bij de tweede poging.
import json
def call_with_retry(client, messages, max_retries=3):
"""Oproep met opnieuw proberen en foutfeedback."""
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) # Uw validatiefunctie
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Voeg foutfeedback toe aan de context
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"Uw antwoord is ongeldig: {e}. Corrigeer dit en retourneer geldige JSON."
})
else:
raise RuntimeError(f"Mislukt na {max_retries} pogingen: {e}")
Het signaal om van aanpak te veranderen
Als u merkt dat u uitgebreide validatiecode schrijft, is dat een sterk signaal dat het tijd is om over te stappen op Custom Structured Outputs. Drie typische drempels bevestigen dit: bij meer dan vijf te valideren velden wordt de controlefunctie langer dan de oproep zelf; zodra types complex worden met geneste lijsten of enums, wordt handmatige validatie onlosmakelijk verbonden met de bugs die het introduceert; en voor elke kritieke productiepijplijn is het delegeren van beperkingen aan het schema simpelweg veiliger dan ze met de hand reconstrueren.
Belangrijkste punten
- De JSON-modus garandeert geldige JSON, geen geldig schema
- Valideer uitvoer altijd aan de clientkant: controleer op verplichte sleutels, correcte types en waarden binnen de grenzen
- Controleer
finish_reasonom afgekapte antwoorden op te sporen - Implementeer een mechanisme om opnieuw te proberen met foutfeedback
- Als validatie complex wordt, migreer dan naar Custom Structured Outputs