Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Omejitve načina JSON in obravnava napak

Lekcija 6 od 12 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Veljavno ne pomeni pravilno
  2. Ni zagotovil za shemo
  3. Obvezno preverjanje na strani odjemalca
  4. Tri napake, na katere boš naletel
  5. Ponovni poskus z povratnimi informacijami
  6. Signal za spremembo pristopa
  7. Ključne ugotovitve

Veljavno ne pomeni pravilno

Način JSON zagotavlja sintaktično veljaven JSON, ne pa tudi semantično pravilnega JSON-a. Ta razlika se med razvojem morda zdi nepomembna, v proizvodnem okolju pa postane ključna. JSON, ki se brez napak razčleni, vendar vsebuje nepričakovane ključe, povzroča prav tisto vrsto hroščev, katerih iskanje traja dneve, saj ob nastanku težave ne sproži nobene izjeme.

Ni zagotovil za shemo

Mehanizem ne ve ničesar o tvoji shemi: nikoli ni videl strukture, ki jo tvoja koda pričakuje. Model lahko izpusti polje, ki ga potrebuješ, doda polje, ki ga nisi zahteval, preimenuje ključ – namesto first_name vrne firstName – ali spremeni tip, tako da vrne "42" kot niz, čeprav si pričakoval število 42. Nič od tega ni neveljaven JSON.

# Pričakuješ to:
# {"name": "Alice", "age": 30, "city": "Paris"}

# Lahko pa prejmeš:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}

JSON je veljaven, vendar se struktura ne ujema s tem, kar pričakuje tvoja koda. To je temeljna razlika v primerjavi s prilagojenimi strukturiranimi izpisi.

Obvezno preverjanje na strani odjemalca

Ker shema ni zagotovljena, je preverjanje tvoja odgovornost. Najosnovnejši vzorec zaporedoma opravi tri korake: poskusi razčleniti JSON, preveri, ali je koren objekt (in ne seznam ali skalar), nato pa preveri prisotnost zahtevanih ključev. Vsaka napaka sproži izjemo ValueError s sporočilom, ki ga lahko uporabiš v dnevnikih.

import json
from typing import Optional

def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
    """Razčleni JSON in preveri zahtevane ključe."""
    try:
        data = json.loads(raw_content)
    except json.JSONDecodeError as e:
        raise ValueError(f"Neveljaven JSON: {e}")

    if not isinstance(data, dict):
        raise ValueError(f"Pričakovan JSON objekt, prejet {type(data).__name__}")

    missing = [k for k in required_keys if k not in data]
    if missing:
        raise ValueError(f"Manjkajoči ključi: {missing}")

    return data

# Uporaba
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"Neveljaven izpis: {e}")
    fallback_processing(raw_content)

Različica v TypeScriptu gre korak dlje in poleg prisotnosti ključev preveri še, ali vrnjena kategorija spada na seznam dovoljenih vrednosti. To je preverjanje, ki najpogosteje manjka, prav ono pa prepreči, da bi se vstopnica, razvrščena kot "urgent_billing", tiho izmuznila skozi tvoje usmerjanje.

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(`Manjkajoči ključi: ${missing.join(", ")}`);
  }

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

  return data as TicketClassification;
}

Tri napake, na katere boš naletel

Prva je okrnjen JSON. Če odgovor doseže omejitev max_tokens, se tok podatkov prereže sredi pretoka in postane neveljaven – zaklepajoči oklepaj nikoli ne prispe. Simptom lahko opaziš še pred razčlenjevanjem: finish_reason ima vrednost "length" namesto "stop".

response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages,
    response_format={"type": "json_object"},
    max_tokens=50  # Premalo za popoln JSON
)

# response.choices[0].finish_reason bo "length" namesto "stop"
if response.choices[0].finish_reason == "length":
    print("Opozorilo: Okrnjen odgovor, povečaj max_tokens")

Vedno preveri finish_reason: če ima vrednost "length", je odgovor nepopoln, ne glede na to, kaj pravi preostala vsebina.

Druga napaka se nanaša na tipe. Starost lahko prispe kot niz, cena kot celo število, čeprav pričakuješ število s plavajočo vejico. Namesto da bi zaupal izpisu, obdaj dostop s pomožno funkcijo, ki poskusi pretvorbo in ob neuspehu vrne privzeto vrednost.

def safe_get_int(data: dict, key: str, default: int = 0) -> int:
    """Pridobi celo število, po potrebi s pretvorbo."""
    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

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

Tretja je preimenovanje ključev. Pri pozivu v francoščini lahko model zlahka spremeni phone v telephone ali name v nom. Preslikava sopomenk absorbira te variacije, ne da bi moral ponoviti klic.

def normalize_keys(data: dict, key_mapping: dict) -> dict:
    """Normaliziraj ključe z uporabo preslikave sopomenk."""
    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

# Preslikava sopomenk
mapping = {
    "name": ["name", "nom", "full_name", "fullName"],
    "email": ["email", "mail", "e-mail", "emailAddress"],
    "phone": ["phone", "telephone", "tel", "phoneNumber"],
}

normalized = normalize_keys(raw_data, mapping)

Ponovni poskus z povratnimi informacijami

Ko preverjanje kljub tvojim najboljšim prizadevanjem ne uspe, najboljši odziv ni ponoviti popolnoma enak klic, temveč modelu sporočiti, kaj je šlo narobe. Če njegov lasten odgovor skupaj s sporočilom o napaki vrneš v pogovor, mu daš kontekst, potreben za samopopravek, kar običajno uspe že ob drugem poskusu.

import json

def call_with_retry(client, messages, max_retries=3):
    """Klic s ponovnim poskusom in povratnimi informacijami o napakah."""
    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)  # Tvoja funkcija za preverjanje
            return data
        except (json.JSONDecodeError, ValueError) as e:
            if attempt < max_retries - 1:
                # Dodaj povratne informacije o napaki v kontekst
                messages.append({"role": "assistant", "content": raw})
                messages.append({
                    "role": "user",
                    "content": f"Tvoj odgovor je neveljaven: {e}. Popravi ga in vrni veljaven JSON."
                })
            else:
                raise RuntimeError(f"Neuspeh po {max_retries} poskusih: {e}")

Signal za spremembo pristopa

Če ugotoviš, da pišeš obsežno kodo za preverjanje, je to močan signal, da je čas za prehod na prilagojene strukturirane izpise. To potrjujejo trije tipični pragovi: ko moraš preverjati več kot pet polj, postane nadzorna funkcija daljša od samega klica; ko tipi postanejo kompleksni z gnezdenimi seznami ali naštevanji, ročno preverjanje postane neločljivo povezano z hrošči, ki jih uvaja; in za vsak kritičen proizvodni cevovod je delegiranje omejitev shemi preprosto varneje kot njihovo ročno rekonstruiranje.

Ključne ugotovitve

  • Način JSON zagotavlja veljaven JSON, ne pa veljavne sheme
  • Vedno preveri izpis na strani odjemalca: preveri zahtevane ključe, pravilne tipe in vrednosti znotraj meja
  • Preveri finish_reason, da zaznaš okrnjene odgovore
  • Implementiraj mehanizem za ponovne poskuse s povratnimi informacijami o napakah
  • Če postane preverjanje kompleksno, preidi na prilagojene strukturirane izpise