BroadRouter

Corriger le JSON invalide d’un LLM : causes, réparation, relance

Par l’équipe BroadNet Inference · 7 min de lecture · Publié · Mis à jour

Vérifiez d’abord finish_reason : une réponse coupée à max_tokens ne se répare pas sans risque, alors augmentez la limite et relancez la requête. Sinon, retirez les balises de code et le texte autour, décodez la première valeur JSON, puis corrigez seulement les erreurs sans ambiguïté, comme les virgules finales. Validez contre un schéma et, en cas d’échec, renvoyez l’erreur exacte une ou deux fois. La sortie structurée, là où elle existe, évite l’essentiel.

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 :

  1. Les réponses tronquées et vides lèvent une exception avant tout parsing : elles ne deviennent jamais des données.
  2. Les balises de code et les blocs de raisonnement sont retirés par deux expressions régulières.
  3. raw_decode est 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.
  4. 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_reason ne l’a pas signalé ; cela lève une exception. Les virgules placées juste avant } ou ] hors des chaînes sont supprimées.
  5. ast.literal_eval lit la sortie à la Python, avec apostrophes simples, True et None. 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.
  6. NaN et Infinity lèvent une exception, via parse_constant. Le module json de Python les accepte par défaut ; la RFC 8259 dit qu’ils « are not permitted » (traduction : « ne sont pas autorisés »), et JSON.parse en 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.

Questions fréquentes

Pourquoi mon LLM renvoie-t-il le JSON dans un bloc de code markdown ?

Les modèles de chat mettent généralement le code en forme pour des humains, et une balise de code est la façon dont les interfaces de chat l’affichent. Demandez « du JSON uniquement, sans balise de code », mais retirez quand même les balises dans votre code : la consigne réduit la fréquence, elle ne la supprime pas.

Comment corriger un JSONDecodeError sur une sortie de LLM ?

Regardez d’abord finish_reason. S’il vaut "length", la réponse a été coupée : augmentez max_tokens et renvoyez la requête. Sinon, retirez les balises de code et décodez la première valeur JSON avec raw_decode, qui ignore le texte qui suit. Corrigez les virgules finales, puis validez. Si cela échoue encore, redemandez en joignant l’erreur.

Faut-il utiliser une bibliothèque de réparation de JSON ?

Pour les logs et le débogage, oui. Pour des données sur lesquelles vous agissez, prudence. Des bibliothèques comme json_repair complètent les valeurs manquantes par défaut : une ville tronquée "Jed" revient sous la forme d’un "Jed" valide. Rejetez la sortie tronquée et renvoyez plutôt la requête.

Pourquoi la sortie JSON de mon LLM est-elle coupée ?

La réponse a atteint max_tokens. Sur les modèles de raisonnement comme DeepSeek V4.1 Flash, GLM 5.3 et Qwen3.8 27B, le raisonnement compte dans cette limite : une longue réflexion peut laisser trop peu de place. Augmentez la limite, réglez reasoning_effort sur low ou demandez moins de sortie par appel.

Le mode JSON garantit-il un JSON valide ?

Presque. Selon OpenAI, la sortie du mode JSON est du JSON valide « except for in some edge cases » (traduction : « sauf dans certains cas limites »), par exemple quand la limite de tokens est atteinte, et le mode n’impose pas votre schéma. La sortie structurée avec json_schema ajoute le respect du schéma là où le fournisseur l’impose. Validez dans tous les cas.

Quels modèles BroadNet prennent en charge la sortie structurée ?

La référence de l’API de BroadNet indique la sortie structurée pour GLM 5.3 et Qwen3.8 27B, vérifié le 15 novembre 2026. Elle ne l’indique pas pour DeepSeek V4.1 Flash ni pour Gemma 4 VL 26B : sur ces modèles, demandez le JSON dans le prompt, avec réparation et validation.

Lire en MarkdownDemander à ChatGPTDemander à ClaudeDemander à Perplexity