Lähe põhisisu juurde
Eesti— Vali keel
Menüü

JSON-režiimi piirangud ja veahaldus

Õppetund 6 / 12 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Kehtiv ei tähenda õiget
  2. Skeemi garantiid puuduvad
  3. Kohustuslik kliendipoolne valideerimine
  4. Kolm tõrget, millega kohtud
  5. Korda veasisendiga
  6. Märk lähenemisviisi muutmiseks
  7. Peamised punktid

Kehtiv ei tähenda õiget

JSON-režiim garanteerib süntaktiliselt kehtiva JSON-i, mitte semantiliselt korrektset JSON-i. See eristus võib arenduse käigus tunduda peene nüansina, kuid muutub tootmiskeskkonnas kriitiliseks. JSON, mis parsitakse vigadeta, kuid sisaldab ootamatuid võtmeid, tekitab just selliseid vigu, mille jälitamine võtab päevi, sest probleemi tegeliku ilmnemise hetkel ühtegi erindit ei teki.

Skeemi garantiid puuduvad

Mehhanism ei tea sinu skeemist midagi: ta pole kunagi näinud struktuuri, mida sinu kood eeldab. Mudel võib jätta välja välja vajaliku välja, lisada mittesoovitud välja, nimetada võtme ümber – näiteks firstName asemel first_name – või muuta tüüpi, tagastades "42" stringina, kui ootasid arvu 42. Mitte ükski neist juhtumitest ei ole kehtetu JSON.

# Sa eeldad seda:
# {"name": "Alice", "age": 30, "city": "Paris"}

# Aga võid saada:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}

JSON on kehtiv, kuid struktuur ei vasta sellele, mida sinu kood ootab. See on fundamentaalne erinevus kohandatud struktureeritud väljunditega võrreldes.

Kohustuslik kliendipoolne valideerimine

Kuna skeem ei ole garanteeritud, langeb valideerimine sinu õlgadele. Minimaalne muster teeb järjest kolm asja: püüab parsida, kontrollib, et juur on objekt (mitte loend või skalaar), ja seejärel kontrollib nõutavate võtmete olemasolu. Iga tõrge tõstab ValueErrori sõnumiga, mida saad oma logides kasutada.

import json
from typing import Optional

def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
    """Parsi JSON ja kontrolli nõutavaid võtmeid."""
    try:
        data = json.loads(raw_content)
    except json.JSONDecodeError as e:
        raise ValueError(f"Kehtetu JSON: {e}")

    if not isinstance(data, dict):
        raise ValueError(f"Oodati JSON-objekti, saadi {type(data).__name__}")

    missing = [k for k in required_keys if k not in data]
    if missing:
        raise ValueError(f"Puuduvad võtmed: {missing}")

    return data

# Kasutus
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"Kehtetu väljund: {e}")
    fallback_processing(raw_content)

TypeScripti versioon astub sammu edasi, kontrollides võtmete olemasolu kõrval ka seda, kas tagastatud kategooria kuulub lubatud loendisse. Just see kontroll jääb kõige sagedamini tegemata ja just see hoiab ära olukorra, kus pilet kategooriaga "urgent_billing" vaikselt sinu suunamisest läbi libiseb.

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(`Puuduvad võtmed: ${missing.join(", ")}`);
  }

  const validCategories = ["billing", "account", "technical", "feature_request", "other"];
  if (!validCategories.includes(data.category)) {
    throw new Error(`Kehtetu kategooria: ${data.category}`);
  }

  return data as TicketClassification;
}

Kolm tõrget, millega kohtud

Esimene on lühendatud JSON. Kui vastus jõuab max_tokens piiranguni, katkestatakse see keskelt ja muutub kehtetuks – sulgev sulg ei jõua kunagi kohale. Sümptomi saad tuvastada juba enne parsimist: finish_reason on võrdne väärtusega "length" asemel "stop".

response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages,
    response_format={"type": "json_object"},
    max_tokens=50  # Liiga väike täieliku JSON-i jaoks
)

# response.choices[0].finish_reason on "length" asemel "stop"
if response.choices[0].finish_reason == "length":
    print("Hoiatus: Lühendatud vastus, suurenda max_tokens")

Kontrolli alati finish_reasoni: kui see on võrdne "length", on vastus mittetäielik, sõltumata sellest, mida ülejäänud sisu ütleb.

Teine tõrge puudutab tüüpe. Vanus võib saabuda stringina, hind täisarvuna, kui ootad ujukomaarvu. Väljundisse usaldamise asemel mähista juurdepääs abifunktsiooni, mis püüab teisendada ja ebaõnnestumisel kasutab vaikimisi väärtust.

def safe_get_int(data: dict, key: str, default: int = 0) -> int:
    """Ekstrakti täisarv, vajadusel teisendades."""
    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

# Kasutus
age = safe_get_int(data, "age", default=0)

Kolmas on võtmete ümbernimetamine. Prantsuskeelse vihjega võib mudel hõlpsasti muuta phone väärtuseks telephone või name väärtuseks nom. Sünonüümide kaardistus neelab need variatsioonid ilma, et peaksid kutset uuesti proovima.

def normalize_keys(data: dict, key_mapping: dict) -> dict:
    """Normaliseeri võtmed, kasutades sünonüümide kaardistust."""
    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

# Sünonüümide kaardistus
mapping = {
    "name": ["name", "nom", "full_name", "fullName"],
    "email": ["email", "mail", "e-mail", "emailAddress"],
    "phone": ["phone", "telephone", "tel", "phoneNumber"],
}

normalized = normalize_keys(raw_data, mapping)

Korda veasisendiga

Kui valideerimine hoolimata sinu parimatest pingutustest ebaõnnestub, ei ole parim lahendus sama kutset uuesti teha: tuleb mudelile öelda, mis valesti läks. Sisestades tema enda vastuse koos veateatega tagasi vestluskonteksti, annad talle vajaliku info enesekorrigeerimiseks, mis õnnestub tavaliselt juba teisel katsel.

import json

def call_with_retry(client, messages, max_retries=3):
    """Kutsu koos korduse ja veasisendiga."""
    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)  # Sinu valideerimisfunktsioon
            return data
        except (json.JSONDecodeError, ValueError) as e:
            if attempt < max_retries - 1:
                # Lisa veasisend konteksti
                messages.append({"role": "assistant", "content": raw})
                messages.append({
                    "role": "user",
                    "content": f"Sinu vastus on kehtetu: {e}. Paranda see ja tagasta kehtiv JSON."
                })
            else:
                raise RuntimeError(f"Ebaõnnestus pärast {max_retries} katset: {e}")

Märk lähenemisviisi muutmiseks

Kui tabad end kirjutamast ulatuslikku valideerimiskoodi, on see tugev signaal, et on aeg üle minna kohandatud struktureeritud väljunditele. Kolm tüüpilist lävendit kinnitavad seda: kui valideeritavaid välju on rohkem kui viis, muutub juhtimisfunktsioon pikemaks kui enda kutse; kui tüübid muutuvad keerukaks, sisaldades pesastatud loendeid või loendeid (enums), muutub käsitsi valideerimine lahutamatuks vigadest, mida see tekitab; ja iga kriitilise tootmistorustiku puhul on piirangute delegeerimine skeemile lihtsalt ohutum kui nende käsitsi rekonstrueerimine.

Peamised punktid

  • JSON-režiim garanteerib kehtiva JSON-i, mitte kehtivat skeemi
  • Valideeri väljundit alati kliendipoolselt: kontrolli nõutavaid võtmeid, õigeid tüüpe ja väärtusi lubatud piirides
  • Kontrolli finish_reasoni, et tuvastada lühendatud vastuseid
  • Rakenda kordusmehhanism veasisendiga
  • Kui valideerimine muutub keerukaks, mine üle kohandatud struktureeritud väljunditele