Limitazioni della Modalità JSON e Gestione degli Errori
In questa pagina
Valido Non Significa Corretto
La Modalità JSON garantisce un JSON sintatticamente valido, non un JSON semanticamente corretto. Questa distinzione può sembrare sottile durante lo sviluppo, ma diventa critica in produzione. Un JSON che viene analizzato senza errori ma contiene chiavi inaspettate genera esattamente quel tipo di bug che richiede giorni per essere individuato, poiché nessuna eccezione viene sollevata nel momento in cui si verifica il problema.
Nessuna Garanzia sullo Schema
Il meccanismo non sa nulla del tuo schema: non ha mai visto la struttura che il tuo codice si aspetta. Il modello potrebbe omettere un campo necessario, aggiungerne uno non richiesto, rinominare una chiave—firstName invece di first_name—o cambiare un tipo restituendo "42" come stringa quando ti aspettavi il numero 42. Nulla di tutto questo costituisce un JSON non valido.
# Ti aspetti questo:
# {"name": "Alice", "age": 30, "city": "Paris"}
# Ma potresti ricevere:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
Il JSON è valido, ma la struttura non corrisponde a ciò che il tuo codice si aspetta. Questa è la differenza fondamentale rispetto agli Output Strutturati Personalizzati.
Validazione Obbligatoria Lato Client
Poiché lo schema non è garantito, la validazione ricade su di te. Il pattern minimo esegue tre operazioni in ordine: tenta l’analisi, verifica che la radice sia un oggetto (non una lista o uno scalare), quindi controlla la presenza delle chiavi richieste. Ogni fallimento solleva un ValueError con un messaggio utilizzabile nei tuoi log.
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Analizza il JSON e verifica le chiavi richieste."""
try:
data = json.loads(raw_content)
except json.JSONDecodeError as e:
raise ValueError(f"JSON non valido: {e}")
if not isinstance(data, dict):
raise ValueError(f"Atteso oggetto JSON, ricevuto {type(data).__name__}")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Chiavi mancanti: {missing}")
return data
# Utilizzo
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 non valido: {e}")
fallback_processing(raw_content)
La versione TypeScript fa un passo ulteriore verificando, oltre alla presenza delle chiavi, che la categoria restituita appartenga all’elenco consentito. Questo è il controllo che manca più spesso e quello che impedisce a un ticket classificato come "urgent_billing" di scivolare silenziosamente attraverso il tuo routing.
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(`Chiavi mancanti: ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Categoria non valida: ${data.category}`);
}
return data as TicketClassification;
}
Tre Fallimenti Che Incontrerai
Il primo è il JSON troncato. Se la risposta raggiunge il limite max_tokens, viene interrotta a metà flusso e diventa non valida: la parentesi graffa di chiusura non arriva mai. Puoi individuare il sintomo prima ancora di analizzare: finish_reason è uguale a "length" invece di "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # Troppo piccolo per un JSON completo
)
# response.choices[0].finish_reason sarà "length" invece di "stop"
if response.choices[0].finish_reason == "length":
print("Attenzione: Risposta troncata, aumenta max_tokens")
Controlla sempre finish_reason: se è uguale a "length", la risposta è incompleta, indipendentemente da ciò che dice il resto del contenuto.
Il secondo fallimento riguarda i tipi. Un’età potrebbe arrivare come stringa, un prezzo come intero quando ti aspetti un float. Invece di fidarti dell’output, avvolgi l’accesso in una funzione helper che tenta la conversione e ripiega su un valore predefinito in caso di fallimento.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Estrae un intero, con conversione se necessario."""
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
# Utilizzo
age = safe_get_int(data, "age", default=0)
Il terzo è la rinomina delle chiavi. Con un prompt in francese, il modello potrebbe facilmente cambiare phone in telephone, o name in nom. Una mappatura di sinonimi assorbe queste variazioni senza costringerti a ritentare la chiamata.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Normalizza le chiavi usando una mappatura di 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 dei 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)
Ritenta con Feedback
Quando la validazione fallisce nonostante i tuoi migliori sforzi, la risposta migliore non è ritentare la stessa identica chiamata: è dire al modello cosa è andato storto. Reinserendo la sua stessa risposta nella conversazione insieme al messaggio di errore, gli fornisci il contesto necessario per autocorreggersi, solitamente al secondo tentativo.
import json
def call_with_retry(client, messages, max_retries=3):
"""Chiama con ritento e feedback sull'errore."""
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) # La tua funzione di validazione
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Aggiungi feedback sull'errore al contesto
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"La tua risposta non è valida: {e}. Correggila e restituisci un JSON valido."
})
else:
raise RuntimeError(f"Fallito dopo {max_retries} tentativi: {e}")
Il Segnale per Cambiare Approccio
Se ti ritrovi a scrivere codice di validazione esteso, è un forte segnale che è il momento di migrare agli Output Strutturati Personalizzati. Tre soglie tipiche lo confermano: oltre cinque campi da validare, la funzione di controllo diventa più lunga della chiamata stessa; una volta che i tipi diventano complessi con liste nidificate o enum, la validazione manuale diventa inseparabile dai bug che introduce; e per qualsiasi pipeline di produzione critica, delegare i vincoli allo schema è semplicemente più sicuro che ricostruirli a mano.
Punti chiave
- La Modalità JSON garantisce un JSON valido, non uno schema valido
- Sempre valida l’output lato client: controlla le chiavi richieste, i tipi corretti e i valori entro i limiti
- Controlla
finish_reasonper rilevare risposte troncata - Implementa un meccanismo di ritento con feedback sugli errori
- Se la validazione diventa complessa, migra agli Output Strutturati Personalizzati