Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Beperkingen van de JSON-modus en foutafhandeling

Les 6 van 12 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Geldig betekent niet correct
  2. Geen schemagaranties
  3. Verplichte validatie aan de clientkant
  4. Drie fouten die u zult tegenkomen
  5. Opnieuw proberen met feedback
  6. Het signaal om van aanpak te veranderen
  7. Belangrijkste punten

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_reason om afgekapte antwoorden op te sporen
  • Implementeer een mechanisme om opnieuw te proberen met foutfeedback
  • Als validatie complex wordt, migreer dan naar Custom Structured Outputs