Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Limitazzjonijiet tal-Modalità JSON u Ġestjoni tal-Iżbalji

Lezzjoni 6 / 12 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Validu Ma Jfissirx Korrett
  2. L-Ebda Garanzija ta’ Skema
  3. Validazzjoni Obbligatorja fuq in-Naħa tal-Klijent
  4. Tliet Fallimenti li Se Tiltaqa’ Magħhom
  5. Erġa’ Pprova b’Feedback
  6. Is-Sinjal biex Tibdel l-Approċċ
  7. Punti Ewlenin

Validu Ma Jfissirx Korrett

Il-Modalità JSON tiggarantixxi JSON sintattikament validu, mhux JSON semantikament korrett. Din id-distinzjoni tista’ tidher sottili waqt l-iżvilupp, iżda ssir kritika fil-produzzjoni. JSON li jiġi pparjat mingħajr żbalji iżda li fih ċwievet mhux mistennija joħloq eżattament dak it-tip ta’ bug li jieħu jiem biex issibuh, għax l-ebda eċċezzjoni ma tiġi attwata meta jseħħ il-problema attwali.

L-Ebda Garanzija ta’ Skema

Il-mekkaniżmu ma jaf xejn dwar l-iskema tiegħek: qatt ma ra l-istruttura li l-kodiċi tiegħek jistenna. Il-mudell jista’ jħalli barra kamp li għandek bżonn, iżid wieħed li ma talbtx, ibiddel isem ċavetta—firstName minflok first_name—jew ibiddel tip billi jirritorna "42" bħala string meta stennejt in-numru 42. L-ebda waħda minn dawn mhija JSON invalidu.

# Inti tistenna dan:
# {"name": "Alice", "age": 30, "city": "Paris"}

# Iżda tista' tirċievi:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}

Il-JSON huwa validu, iżda l-istruttura ma taqbilx ma’ dak li jistenna l-kodiċi tiegħek. Din hija d-differenza fundamentali mill-Outputs Strutturati Personalizzati.

Validazzjoni Obbligatorja fuq in-Naħa tal-Klijent

Peress li l-iskema mhijiex iggarantita, il-validazzjoni taqa’ fuqek. Il-mudell minimu jagħmel tliet affarijiet f’ordni: jipprova jipparja, jivverifika li r-root huwa oġġett (mhux lista jew skalar), imbagħad jiċċekkja għal ċwievet meħtieġa. Kull falliment iqajjem ValueError b’messaġġ li tista’ tuża fil-logs tiegħek.

import json
from typing import Optional

def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
    """Ipparja l-JSON u vverifika ċ-ċwievet meħtieġa."""
    try:
        data = json.loads(raw_content)
    except json.JSONDecodeError as e:
        raise ValueError(f"JSON invalidu: {e}")

    if not isinstance(data, dict):
        raise ValueError(f"Mistenni oġġett JSON, irċevut {type(data).__name__}")

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

    return data

# Użu
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"Output invalidu: {e}")
    fallback_processing(raw_content)

Il-verżjoni TypeScript tmur pass ‘il quddiem billi tivverifika, lil hinn mill-preżenza taċ-ċavetta, li l-kategorija rritornata tappartjeni għall-lista permessa. Din hija l-verifika li l-aktar tinħema, u dik li tipprevjeni li tikketta kklassifikata bħala "urgent_billing" tgħaddi silenzjużament mir-routing tiegħek.

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

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

  return data as TicketClassification;
}

Tliet Fallimenti li Se Tiltaqa’ Magħhom

L-ewwel huwa JSON imqatta’. Jekk ir-risposta tilħaq il-limitu max_tokens, tiġi maqtugħa f’nofs it-triq u ssir invalida—il-parentesi tal-għeluq qatt ma tasal. Tista’ tinduna bis-sintomu qabel anke tipparja: finish_reason huwa ugwali għal "length" minflok "stop".

response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages,
    response_format={"type": "json_object"},
    max_tokens=50  # Żgħir wisq għal JSON sħiħ
)

# response.choices[0].finish_reason ikun "length" minflok "stop"
if response.choices[0].finish_reason == "length":
    print("Twissija: Risposta maqtugħa, żid max_tokens")

Dejjem iċċekkja finish_reason: jekk huwa ugwali għal "length", ir-risposta mhix kompluta, irrispettivament minn dak li jgħid il-bqija tal-kontenut.

It-tieni falliment jikkonċerna t-tipi. Età tista’ tasal bħala string, prezz bħala integer meta stennejt float. Minflok ma tifda l-output, ilbes l-aċċess f’helper li jipprova konverżjoni u jerġa’ lura għal valur default jekk ifalli.

def safe_get_int(data: dict, key: str, default: int = 0) -> int:
    """Estrai integer, b'konverżjoni jekk meħtieġ."""
    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

# Użu
age = safe_get_int(data, "age", default=0)

It-tielet huwa l-bidla fl-ismijiet taċ-ċwievet. B’prompt bil-Franċiż, il-mudell jista’ faċilment ibiddel phone għal telephone, jew name għal nom. Mappatura ta’ sinonimi tassorbi dawn il-varjazzjonijiet mingħajr ma teħtieġ li terġa’ ssejjaħ.

def normalize_keys(data: dict, key_mapping: dict) -> dict:
    """Normalizza ċ-ċwievet billi tuża mappatura ta' sinonimi."""
    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

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

normalized = normalize_keys(raw_data, mapping)

Erġa’ Pprova b’Feedback

Meta l-validazzjoni tfalli minkejja l-aħjar sforzi tiegħek, l-aħjar risposta mhix li terġa’ ssir l-istess sejħa eżatta: huwa li tgħid lill-mudell x’mar ħażin. Billi tgħaddi r-risposta tiegħu stess lura fil-konversjoni flimkien mal-messaġġ ta’ żball, tagħtih il-kuntest meħtieġ biex jikkoreġi lilu nnifsu, ġeneralment sat-tieni tentattiv.

import json

def call_with_retry(client, messages, max_retries=3):
    """Sejħa b'tentattiv mill-ġdid u feedback ta' żball."""
    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)  # Il-funzjoni ta' validazzjoni tiegħek
            return data
        except (json.JSONDecodeError, ValueError) as e:
            if attempt < max_retries - 1:
                # Żid feedback ta' żball fil-kuntest
                messages.append({"role": "assistant", "content": raw})
                messages.append({
                    "role": "user",
                    "content": f"Ir-risposta tiegħek hija invalida: {e}. Ikkoreġiha u rritorna JSON validu."
                })
            else:
                raise RuntimeError(f"Falla wara {max_retries} tentattivi: {e}")

Is-Sinjal biex Tibdel l-Approċċ

Jekk issib ruħek tikteb kodiċi ta’ validazzjoni estensiv, dan huwa sinjal qawwi li wasal iż-żmien biex timmigra lejn Outputs Strutturati Personalizzati. Tliet limiti tipiċi jikkonfermaw dan: lil hinn minn ħames campi biex tivvalida, il-funzjoni ta’ kontroll issir itwal mis-sejħa nnifisha; ladarba t-tipi jsiru kumplessi b’listi mbejjta jew enums, il-validazzjoni manwali ssir inseparabbli mill-bugs li tintroduċi; u għal kwalunkwe pipeline kritika tal-produzzjoni, id-delega tar-restrizzjonijiet lill-iskema hija sempliċiment aktar sikura milli terġa’ tibnihom bl-idejn.

Punti Ewlenin

  • Il-Modalità JSON tiggarantixxi JSON validu, mhux skema valida
  • Dejjem ivvalida l-output fuq in-naħa tal-klijent: iċċekkja għal ċwievet meħtieġa, tipi korretti, u valuri fil-limiti
  • Iċċekkja finish_reason biex tiskopri risposti maqtugħin
  • Implimenta mekkaniżmu ta’ tentattiv mill-ġdid b’feedback ta’ żball
  • Jekk il-validazzjoni ssir kumplessa, immigra lejn Outputs Strutturati Personalizzati