JSON Mode : limites et gestion des erreurs
Šiame puslapyje
Valide ne signifie pas correct
Le mode JSON garantit un JSON syntaxiquement valide, mais pas un JSON sémantiquement correct. Cette distinction peut sembler subtile lors du développement, mais elle devient critique en production. Un JSON qui s’analyse sans erreur mais contient des clés inattendues crée exactement le genre de bug qui prend des jours à traquer, car aucune exception ne se déclenche au moment où le problème survient réellement.
Aucune garantie de schéma
Le mécanisme ne connaît rien de votre schéma : il n’a jamais vu la structure que votre code attend. Le modèle peut omettre un champ dont vous avez besoin, en ajouter un que vous n’avez pas demandé, renommer une clé — firstName au lieu de first_name — ou changer un type en renvoyant "42" comme chaîne alors que vous attendiez le nombre 42. Rien de tout cela n’est un JSON invalide.
# Vous attendez ceci :
# {"name": "Alice", "age": 30, "city": "Paris"}
# Mais vous pourriez recevoir :
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
Le JSON est valide, mais la structure ne correspond pas à ce que votre code attend. C’est la différence fondamentale avec les sorties structurées personnalisées (Custom Structured Outputs).
Validation obligatoire côté client
Puisque le schéma n’est pas garanti, la validation vous incombe. Le motif minimal fait trois choses dans l’ordre : il tente l’analyse, vérifie que la racine est un objet (et non une liste ou un scalaire), puis contrôle la présence des clés requises. Chaque échec lève une ValueError avec un message que vous pouvez utiliser dans vos journaux.
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Analyse le JSON et vérifie les clés requises."""
try:
data = json.loads(raw_content)
except json.JSONDecodeError as e:
raise ValueError(f"JSON invalide : {e}")
if not isinstance(data, dict):
raise ValueError(f"Objet JSON attendu, reçu {type(data).__name__}")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Clés manquantes : {missing}")
return data
# Utilisation
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"Sortie invalide : {e}")
fallback_processing(raw_content)
La version TypeScript va plus loin en vérifiant, au-delà de la présence des clés, que la catégorie retournée appartient bien à la liste autorisée. C’est la vérification la plus souvent oubliée, et celle qui empêche un ticket classé "urgent_billing" de glisser silencieusement à travers votre routage.
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(`Clés manquantes : ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Catégorie invalide : ${data.category}`);
}
return data as TicketClassification;
}
Trois échecs que vous rencontrerez
Le premier est le JSON tronqué. Si la réponse atteint la limite max_tokens, elle est coupée en plein flux et devient invalide — l’accolade fermante n’arrive jamais. Vous pouvez repérer le symptôme avant même l’analyse : finish_reason vaut "length" au lieu de "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # Trop petit pour un JSON complet
)
# response.choices[0].finish_reason sera "length" au lieu de "stop"
if response.choices[0].finish_reason == "length":
print("Avertissement : Réponse tronquée, augmentez max_tokens")
Vérifiez toujours finish_reason : s’il vaut "length", la réponse est incomplète, quoi que dise le reste du contenu.
Le deuxième échec concerne les types. Un âge peut arriver sous forme de chaîne, un prix comme entier alors que vous attendez un flottant. Plutôt que de faire confiance à la sortie, encapsulez l’accès dans une fonction auxiliaire qui tente la conversion et revient à une valeur par défaut en cas d’échec.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Extrait un entier, avec conversion si nécessaire."""
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
# Utilisation
age = safe_get_int(data, "age", default=0)
Le troisième est le renommage des clés. Avec une invite en français, le modèle peut facilement changer phone en telephone, ou name en nom. Une cartographie de synonymes absorbe ces variations sans vous obliger à relancer l’appel.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Normalise les clés grâce à une cartographie de synonymes."""
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
# Cartographie de synonymes
mapping = {
"name": ["name", "nom", "full_name", "fullName"],
"email": ["email", "mail", "e-mail", "emailAddress"],
"phone": ["phone", "telephone", "tel", "phoneNumber"],
}
normalized = normalize_keys(raw_data, mapping)
Nouvelle tentative avec rétroaction
Lorsque la validation échoue malgré vos meilleurs efforts, la meilleure réponse n’est pas de relancer exactement le même appel : c’est de dire au modèle ce qui s’est mal passé. En renvoyant sa propre réponse dans la conversation accompagnée du message d’erreur, vous lui donnez le contexte nécessaire pour s’autocorriger, généralement dès la deuxième tentative.
import json
def call_with_retry(client, messages, max_retries=3):
"""Appel avec nouvelle tentative et rétroaction d'erreur."""
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) # Votre fonction de validation
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Ajout de la rétroaction d'erreur au contexte
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"Votre réponse est invalide : {e}. Corrigez-la et renvoyez un JSON valide."
})
else:
raise RuntimeError(f"Échec après {max_retries} tentatives : {e}")
Le signal pour changer d’approche
Si vous vous retrouvez à écrire du code de validation extensif, c’est un signal fort qu’il est temps de migrer vers les sorties structurées personnalisées (Custom Structured Outputs). Trois seuils typiques le confirment : au-delà de cinq champs à valider, la fonction de contrôle devient plus longue que l’appel lui-même ; dès que les types se complexifient avec des listes imbriquées ou des énumérations, la validation manuelle devient inséparable des bugs qu’elle introduit ; et pour tout pipeline de production critique, déléguer les contraintes au schéma est simplement plus sûr que de les reconstruire à la main.
Svarbiausi punktai
- Le mode JSON garantit un JSON valide, pas un schéma valide
- Validez toujours la sortie côté client : vérifiez les clés requises, les types corrects et les valeurs dans les limites
- Vérifiez
finish_reasonpour détecter les réponses tronquées - Mettez en place un mécanisme de nouvelle tentative avec rétroaction d’erreur
- Si la validation devient complexe, migrez vers les sorties structurées personnalisées