Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

JSON-tilan rajoitukset ja virheenkäsittely

Oppitunti 6 / 12 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kelvollinen ei tarkoita oikeaa
  2. Ei takuita skeemasta
  3. Pakollinen asiakaspuolen validointi
  4. Kolme kohtaamaasi epäonnistumista
  5. Yritä uudelleen palautteen kanssa
  6. Signaali lähestymistavan muuttamiselle
  7. Keskeiset asiat

Kelvollinen ei tarkoita oikeaa

JSON-tila takaa syntaktisesti kelvollisen JSONin, ei semanttisesti oikeaa JSONia. Tämä ero saattaa vaikuttaa hienovaraiselta kehitysvaiheessa, mutta se muuttuu kriittiseksi tuotantoympäristössä. JSON, joka jäsentyy ilman virheitä mutta sisältää odottamattomia avaimia, aiheuttaa juuri sellaisia bugeja, joiden jäljittäminen vie päiviä, koska mikään poikkeus ei laukea, kun ongelma itse asiassa ilmenee.

Ei takuita skeemasta

Mekanismi ei tiedä mitään skeemastasi: se ei ole koskaan nähnyt rakennetta, jota koodisi odottaa. Malli saattaa jättää pois tarvitsemasi kentän, lisätä pyytämättömän kentän, nimetä avaimen uudelleen – firstName first_name:n sijaan – tai muuttaa tyyppiä palauttamalla "42" merkkijonona, kun odotit numeroa 42. Mikään tästä ei ole virheellistä JSONia.

# Odotat tätä:
# {"name": "Alice", "age": 30, "city": "Paris"}

# Mutta saatat vastaanottaa:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}

JSON on kelvollista, mutta rakenne ei vastaa sitä, mitä koodisi odottaa. Tämä on perustavanlaatuinen ero mukautettuihin jäsennettyihin tulosteisiin verrattuna.

Pakollinen asiakaspuolen validointi

Koska skeemaa ei taata, validointi on sinun vastuullasi. Minimimalli tekee kolme asiaa järjestyksessä: se yrittää jäsentää datan, varmistaa, että juuri on objekti (ei lista eikä skalaari), ja tarkistaa vaaditut avaimet. Jokainen epäonnistuminen nostaa ValueError-poikkeuksen viestillä, jota voit käyttää lokeissasi.

import json
from typing import Optional

def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
    """Jäsennä JSON ja varmista vaaditut avaimet."""
    try:
        data = json.loads(raw_content)
    except json.JSONDecodeError as e:
        raise ValueError(f"Virheellinen JSON: {e}")

    if not isinstance(data, dict):
        raise ValueError(f"Odotettiin JSON-objektia, vastaanotettiin {type(data).__name__}")

    missing = [k for k in required_keys if k not in data]
    if missing:
        raise ValueError(f"Puuttuvat avaimet: {missing}")

    return data

# Käyttö
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"Virheellinen tuloste: {e}")
    fallback_processing(raw_content)

TypeScript-versio menee askeleen pidemmälle tarkistamalla avainten olemassaolon lisäksi, että palautettu kategoria kuuluu sallittujen listalle. Tämä on useimmiten puuttuva tarkistus, ja se estää lipun, joka on luokiteltu arvoksi "urgent_billing", lipumasta hiljaa reitityksesi läpi.

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(`Puuttuvat avaimet: ${missing.join(", ")}`);
  }

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

  return data as TicketClassification;
}

Kolme kohtaamaasi epäonnistumista

Ensimmäinen on typistynyt JSON. Jos vastaus osuu max_tokens-rajaan, se katkeaa kesken virran ja muuttuu virheelliseksi – sulkeva aaltosulke ei koskaan saavu. Huomaat oireen jo ennen jäsentämistä: finish_reason on "length" eikä "stop".

response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages,
    response_format={"type": "json_object"},
    max_tokens=50  # Liian pieni täydelliselle JSONille
)

# response.choices[0].finish_reason on "length" eikä "stop"
if response.choices[0].finish_reason == "length":
    print("Varoitus: Typistynyt vastaus, kasvata max_tokens-arvoa")

Tarkista aina finish_reason: jos se on "length", vastaus on epätäydellinen riippumatta siitä, mitä muu sisältö sanoo.

Toinen epäonnistuminen koskee tyyppejä. Ikä saattaa saapua merkkijonona, hinta kokonaislukuna, kun odotit liukulukua. Älä luota tulosteeseen, vaan kääri pääsy apufunktioon, joka yrittää muunnosta ja palautuu oletusarvoon epäonnistuessaan.

def safe_get_int(data: dict, key: str, default: int = 0) -> int:
    """Pura kokonaisluku, muunna tarvittaessa."""
    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

# Käyttö
age = safe_get_int(data, "age", default=0)

Kolmas on avainten uudelleennimeäminen. Ranskankielisellä kehotteella malli saattaa helposti vaihtaa phone:n muotoon telephone tai name:n muotoon nom. Synonyymikartta absorboi nämä variaatiot ilman, että sinun tarvitsee yrittää puhelua uudelleen.

def normalize_keys(data: dict, key_mapping: dict) -> dict:
    """Normalisoi avaimet synonyymikartan avulla."""
    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

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

normalized = normalize_keys(raw_data, mapping)

Yritä uudelleen palautteen kanssa

Kun validointi epäonnistuu parhaista yrityksistäsi huolimatta, paras vaste ei ole yrittää samaa puhelua uudelleen: kerro mallille, mikä meni pieleen. Syöttämällä sen oman vastauksen takaisin keskusteluun yhdessä virheilmoituksen kanssa annat sille tarvittavan kontekstin itsensä korjaamiseen, yleensä toisella yrityksellä.

import json

def call_with_retry(client, messages, max_retries=3):
    """Soita uudelleen virhepalautteen kanssa."""
    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)  # Oma validointifunktiosi
            return data
        except (json.JSONDecodeError, ValueError) as e:
            if attempt < max_retries - 1:
                # Lisää virhepalaute kontekstiin
                messages.append({"role": "assistant", "content": raw})
                messages.append({
                    "role": "user",
                    "content": f"Vastauksesi on virheellinen: {e}. Korjaa se ja palauta kelvollinen JSON."
                })
            else:
                raise RuntimeError(f"Epäonnistui {max_retries} yrityksen jälkeen: {e}")

Signaali lähestymistavan muuttamiselle

Jos huomaat kirjoittavasi laajaa validointikoodia, se on vahva signaali siitä, että on aika siirtyä mukautettuihin jäsennettyihin tulosteisiin. Kolme tyypillistä kynnysarvoa vahvistavat tämän: yli viiden kentän validoinnissa ohjausfunktio muuttuu pidemmäksi kuin itse kutsu; kun tyypit monimutkaistuvat sisäkkäisillä listoilla tai enum-arvoilla, manuaalinen validointi erottamattomasti sekoittuu aiheuttamiinsa bugeihin; ja missä tahansa kriittisessä tuotantoputkessa rajoitteiden delegointi skeemalle on yksinkertaisesti turvallisempaa kuin niiden uudelleenrakentaminen käsin.

Keskeiset asiat

  • JSON-tila takaa kelvollisen JSONin, ei kelvollista skeemaa
  • Validoi tuloste aina asiakaspuolella: tarkista vaaditut avaimet, oikeat tyypit ja arvot sallituissa rajoissa
  • Tarkista finish_reason havaitaksesi typistyneet vastaukset
  • Toteuta uudelleenyritysmekanismi virhepalautteen kanssa
  • Jos validointi muuttuu monimutkaiseksi, siirry mukautettuihin jäsennettyihin tulosteisiin