Votre code appelle json.loads() sur la réponse d’un modèle et obtient JSONDecodeError: Expecting value: line 1 column 1. Ou bien le parsing passe, mais un champ est une chaîne là où vous attendiez un nombre. Cet article classe les causes selon ce que vous pouvez faire sans risque pour chacune, fournit une fonction Python testée qui ne répare que les cas sans ambiguïté, et montre une boucle de relance qui sait quand une relance ne servira à rien.
Le choix entre le mode JSON et json_schema est traité dans mode JSON ou json_schema. Ici, il s’agit de ce qu’il faut faire de la réponse que vous avez réellement reçue.
Pourquoi les LLM renvoient-ils du JSON invalide ?
Un modèle écrit du texte un token à la fois. Tant que le serveur ne contraint pas le décodage, rien ne l’empêche d’ajouter une phrase aimable ou de manquer de place. Les échecs courants :
| Ce que vous voyez | Cause | Réparable sans risque dans le code ? |
|---|---|---|
```json … ``` autour de l’objet |
Habitude de mise en forme du chat | Oui : retirer la balise |
| « Here is the JSON: » avant, « Let me know… » après | Même habitude | Oui : ne lire que la première valeur |
<think>...</think> avant l’objet |
Texte de raisonnement dans le champ content sur certains serveurs | Oui : retirer le bloc |
| Se termine au milieu d’une chaîne, accolades ouvertes | max_tokens atteint |
Non : renvoyer avec plus de place |
| Contenu vide | Le raisonnement a consommé tout le budget | Non : renvoyer avec plus de place |
{"a": 1,} |
Virgule finale ; JavaScript l’accepte, la RFC 8259 non | Oui : un seul sens possible |
{'a': True, 'b': None} |
Syntaxe Python | Oui : ast.literal_eval la lit sans risque |
NaN, Infinity |
Pas du JSON ; Python les accepte par défaut | Non : rejeter |
| JSON valide, mauvais types ou champs manquants | Schéma non imposé | Non : redemander avec l’erreur |
La ligne de partage, c’est l’ambiguïté. S’il n’y a qu’une seule chose que le modèle a pu vouloir dire, corrigez-la dans le code et journalisez-le. S’il faudrait deviner, rejetez la réponse.
Pourquoi ne pas réparer un JSON tronqué ?
Parce que la version réparée a l’air juste et ne l’est pas. Nous avons passé json_repair 0.64.9, une bibliothèque populaire sous licence MIT, sur une réponse coupée au milieu d’un mot :
'{"name": "Omar", "city": "Jed' -> {'name': 'Omar', 'city': 'Jed'}
Elle a renvoyé un JSON valide avec la ville « Jed ». Son README le dit franchement : elle « automatically completes missing values in JSON fields with reasonable defaults » (traduction : « complète automatiquement les valeurs manquantes des champs JSON avec des valeurs par défaut raisonnables »). C’est utile pour lire des logs. Pour des données que vous stockez ou sur lesquelles vous agissez, cela transforme un échec visible en échec silencieux.
Vérifiez finish_reason avant de parser. "length" signifie que la réponse a atteint max_tokens. Renvoyer la même requête avec la même limite échoue de la même façon : doublez la limite ou demandez moins par appel. Les modèles de raisonnement rendent ce cas plus fréquent : la référence de l’API de BroadNet indique que DeepSeek V4.1 Flash, GLM 5.3 et Qwen3.8 27B raisonnent avant de répondre, et que le raisonnement compte dans max_tokens. Avec une petite limite, la réponse peut revenir vide. Laissez 1 000 tokens ou plus, ou réglez reasoning_effort sur low ; l’article sur le budget de raisonnement donne les chiffres.
Une fonction de réparation qui ne corrige que les cas sûrs
Elle n’utilise que la bibliothèque standard. Elle renvoie la valeur parsée et la liste des réparations effectuées, pour que vous puissiez les compter.
import ast, json, re
class Truncated(Exception): pass
class NotJSON(Exception): pass
FENCE = re.compile(r"```(?:json|JSON)?\s*\n(.*?)```", re.S)
THINK = re.compile(r"<think>.*?</think>", re.S)
def _reject_constant(name): # NaN, Infinity: Python accepts them, JSON does not
raise NotJSON(f"non-standard constant {name}")
_decoder = json.JSONDecoder(parse_constant=_reject_constant)
def _first_value(s):
"""Decode the first JSON object or array in s, ignoring prose before and after it."""
for i, ch in enumerate(s):
if ch in "{[":
try:
return _decoder.raw_decode(s, i)[0]
except json.JSONDecodeError:
continue # a stray brace in prose; try the next one
raise NotJSON("no JSON object or array found")
def _scan(s):
"""Drop commas before } or ] outside strings; report brackets left open."""
out, stack, in_str, esc = [], [], False, False
for i, ch in enumerate(s):
if in_str:
if esc:
esc = False
elif ch == "\\":
esc = True
elif ch == '"':
in_str = False
elif ch == '"':
in_str = True
elif ch in "{[":
stack.append(ch)
elif ch in "}]" and stack:
stack.pop()
elif ch == ",":
rest = s[i + 1:].lstrip()
if rest[:1] in ("}", "]"):
continue # trailing comma: skip it
out.append(ch)
return "".join(out), len(stack) + (1 if in_str else 0)
def _python_literal(s):
"""Output in Python syntax: single quotes, True/False/None, trailing commas."""
start = min((i for i in (s.find("{"), s.find("[")) if i >= 0), default=-1)
end = max(s.rfind("}"), s.rfind("]"))
if start < 0 or end <= start:
raise NotJSON("no braces")
value = ast.literal_eval(s[start:end + 1]) # literals only; never runs code
if not isinstance(value, (dict, list)):
raise NotJSON("not an object or array")
json.dumps(value, allow_nan=False) # must round-trip as strict JSON
return value
def parse_llm_json(content, finish_reason=None):
"""Return (value, repairs). Raises Truncated or NotJSON."""
if finish_reason == "length":
raise Truncated("hit max_tokens; raise the limit or shorten the output")
if not content or not content.strip():
raise NotJSON("empty content (reasoning may have used the whole budget)")
repairs = []
s = content.strip().lstrip("\ufeff")
if THINK.search(s):
s = THINK.sub("", s).strip(); repairs.append("removed <think> block")
m = FENCE.search(s)
if m:
s = m.group(1).strip(); repairs.append("removed code fence")
try:
value = _decoder.decode(s)
return value, repairs
except json.JSONDecodeError:
pass
try:
value = _first_value(s); repairs.append("ignored text around JSON")
return value, repairs
except NotJSON:
pass
fixed, open_count = _scan(s)
if open_count:
raise NotJSON(f"incomplete JSON, {open_count} bracket(s) or string left open: treat as truncated")
if fixed != s:
try:
value = _first_value(fixed); repairs.append("removed trailing commas")
return value, repairs
except NotJSON:
pass
try:
value = _python_literal(s); repairs.append("parsed Python-style literal")
return value, repairs
except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError, NotJSON) as e:
raise NotJSON(f"unrepairable: {e}") from None
Le rôle de chaque étape :
- Les réponses tronquées et vides lèvent une exception avant tout parsing : elles ne deviennent jamais des données.
- Les balises de code et les blocs de raisonnement sont retirés par deux expressions régulières.
raw_decodeest l’outil clé. Selon la documentation Python, il décode un document « from a string that may have extraneous data at the end » (traduction : « à partir d’une chaîne qui peut contenir des données superflues à la fin ») et renvoie l’endroit où il s’est arrêté. En partant du premier{ou[, il saute le texte avant l’objet et ignore celui d’après. Si une accolade dans le texte ne se décode pas, il essaie la suivante.- Le balayage des accolades parcourt le texte en suivant les chaînes et les échappements. Des accolades restées ouvertes signifient que la réponse a été coupée, même si
finish_reasonne l’a pas signalé ; cela lève une exception. Les virgules placées juste avant}ou]hors des chaînes sont supprimées. ast.literal_evallit la sortie à la Python, avec apostrophes simples,TrueetNone. Il n’évalue que des littéraux et n’exécute jamais de code. Le résultat doit ensuite se sérialiser en JSON strict.NaNetInfinitylèvent une exception, viaparse_constant. Le modulejsonde Python les accepte par défaut ; la RFC 8259 dit qu’ils « are not permitted » (traduction : « ne sont pas autorisés »), etJSON.parseen JavaScript les rejette.
Nous l’avons exécutée sur 17 chaînes de test : JSON propre, JSON entre balises, clés et valeurs arabes entre balises, texte avant et après, un espace réservé {name} dans le texte avant l’objet, un bloc <think>, des virgules finales dans des objets et des tableaux, des virgules et des accolades à l’intérieur de chaînes, des guillemets échappés, un chemin Windows terminé par une barre oblique inverse, des littéraux Python, NaN, une réponse vide, une réponse coupée avec et sans finish_reason: "length", et deux objets à la suite. Tous se sont comportés comme l’indique le tableau ci-dessus. Un test a révélé un vrai bug : une première version basculait son indicateur d’échappement avant de chercher le guillemet fermant, si bien que "he said \"hi,]\"" perdait sa virgule. Testez votre propre code de réparation sur des guillemets échappés.
Deux limites à connaître. Face à deux objets à la suite, la fonction renvoie le premier ; si vous voulez plusieurs éléments, demandez un tableau JSON. Et une sortie Python entre apostrophes simples qui contient un guillemet double à l’intérieur d’une chaîne peut être mal lue par le balayage des accolades, puis rejetée. Rejeter est l’échec sûr.
Comment relancer quand la réparation échoue ?
La réparation s’occupe du format. La validation s’occupe du contenu : bons champs, bons types, valeurs plausibles. Cette boucle valide avec le paquet jsonschema et choisit la relance selon la cause :
import json, os
from jsonschema import Draft202012Validator
from openai import OpenAI
from llm_json import parse_llm_json, Truncated, NotJSON
client = OpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
api_key=os.environ["BROADNET_API_KEY"])
SCHEMA = {"type": "object", "additionalProperties": False,
"required": ["name", "city", "amount"],
"properties": {"name": {"type": "string", "minLength": 1},
"city": {"type": ["string", "null"]},
"amount": {"type": "number", "minimum": 0}}}
validator = Draft202012Validator(SCHEMA)
def extract(text, model="broadnet/qwen3.8-27b", max_tokens=1500, attempts=3, log=print):
messages = [{"role": "system", "content": "Extract name, city and amount. Reply with one JSON object only, no code fence. "
"Schema: " + json.dumps(SCHEMA)},
{"role": "user", "content": text}]
for attempt in range(1, attempts + 1):
r = client.chat.completions.create(model=model, messages=messages, max_tokens=max_tokens,
reasoning_effort="low", temperature=0)
c = r.choices[0]
try:
value, repairs = parse_llm_json(c.message.content, c.finish_reason)
errors = [f"{'/'.join(map(str, e.path)) or '(root)'}: {e.message}" for e in validator.iter_errors(value)]
if not errors:
log({"attempt": attempt, "repairs": repairs, "ok": True})
return value
problem = "The JSON does not match the schema: " + "; ".join(errors)
except Truncated:
log({"attempt": attempt, "ok": False, "why": "truncated"})
max_tokens *= 2 # same prompt, more room; a re-ask would be cut off too
continue
except NotJSON as e:
problem = f"That reply was not valid JSON ({e})."
log({"attempt": attempt, "ok": False, "why": problem})
messages += [{"role": "assistant", "content": c.message.content or ""},
{"role": "user", "content": problem + " Return the corrected JSON object only."}]
raise RuntimeError(f"no valid JSON after {attempts} attempts")
Les règles de cette boucle :
- Tronqué : renvoyer les mêmes messages avec une limite doublée. Ajouter un message « merci de corriger » rallongerait le prompt sans raccourcir la sortie.
- Pas du JSON, ou mauvaise forme : renvoyer l’erreur exacte. « amount: ‘1200’ is not of type ‘number’ » donne au modèle quelque chose de précis à corriger. Une simple relance répète souvent l’erreur.
- Plafonner à trois tentatives. Chaque relance renvoie toute la conversation en tokens d’entrée. Après trois, journalisez l’entrée et orientez-la ailleurs.
- Journaliser la liste des réparations. Une hausse du nombre de « removed code fence » après une modification du prompt vous dit que le prompt s’est dégradé, même si rien n’a échoué.
Nous avons exécuté cette boucle contre un serveur factice local qui rejouait des réponses scriptées. Une réponse entre balises, avec une virgule finale et "amount": "1200" sous forme de chaîne, a été réparée, a échoué à la validation, puis a été corrigée au deuxième appel une fois l’erreur renvoyée. Une réponse coupée avec finish_reason: "length" a été renvoyée avec max_tokens porté de 1 500 à 3 000 et a réussi. Le serveur factice enregistrait chaque requête, ce qui a confirmé le nombre de messages et la limite envoyés par la boucle. Un vrai modèle peut échouer autrement : exécutez-la sur 100 de vos propres entrées avant de vous fier aux chiffres.
La sortie structurée rend-elle tout cela inutile ?
Elle en supprime l’essentiel. Un serveur qui contraint le décodage à votre schéma ne peut émettre ni balise de code, ni virgule finale, ni champ manquant. vLLM, un serveur courant pour les modèles ouverts, le fait avec les backends xgrammar ou guidance. Deux échecs subsistent même alors : la troncature à max_tokens et les refus. OpenAI note que la sortie du mode JSON est valide « except for in some edge cases » (traduction : « sauf dans certains cas limites ») et que votre application « must detect and handle » (traduction : « doit détecter et gérer ») une sortie qui n’est pas un objet complet. Gardez donc la vérification de finish_reason et le validateur, même avec json_schema.
Ce que chaque approche évite :
| Approche | Balises et texte | Erreurs de syntaxe | Mauvaise forme | Troncature |
|---|---|---|---|---|
| Prompt seul (« réponds en JSON ») | Moins souvent | Moins souvent | Moins souvent | Non |
Mode JSON (json_object) |
Oui | Oui | Non | Non |
Sortie structurée (json_schema, imposée) |
Oui | Oui | Oui | Non |
Avec le mode JSON, OpenAI précise aussi que vous « must always instruct the model to produce JSON » (traduction : « devez toujours demander au modèle de produire du JSON ») dans un message ; sinon, il peut émettre des espaces jusqu’à atteindre la limite de tokens. Les autres serveurs compatibles OpenAI varient : testez le mode sur le modèle que vous livrez. Le test figure dans l’article sur la sortie structurée.
Pour vérifier une réponse à la main, collez-la dans le validateur de sortie JSON de LLM, ou construisez un schéma strict à partir d’un objet d’exemple avec le générateur de JSON Schema.
La place de BroadNet Inference
BroadRouter est le site de BroadNet. La référence de l’API de BroadNet indique la sortie structurée pour GLM 5.3 et Qwen3.8 27B seulement, sans nommer le paramètre de requête : testez donc json_schema sur le modèle avant de vous y fier. Sur DeepSeek V4.1 Flash et Gemma 4 VL 26B, demandez le JSON dans le prompt et appliquez la fonction de réparation et le validateur ci-dessus. Trois des quatre modèles raisonnent avant de répondre : prévoyez-le dans max_tokens. Pour l’extraction en masse, l’article sur le traitement par lots montre comment journaliser finish_reason élément par élément. Les prompts et les réponses ne sont pas conservés après chaque requête.
