JSON Toolkit

Le JSON d'un LLM est tronqué : regardez d'abord la raison d'arrêt, ensuite la réparation

L’essentiel : Le modèle renvoie un JSON coupé au milieu, et le parseur ne vous donne qu'un numéro de colonne. Refermer les accolades le rend de nouveau analysable, mais chaque champ manquant disparaît dans les données. Cet article trace la frontière entre ce qu'une réparation de troncature peut honnêtement récupérer et ce qui doit être relancé : filtrage par stop_reason, dimensionnement du plafond, ordre des champs du schéma.

Pratique~5 min de lecturePublié le 2026-11-14Mis à jour le 2026-11-14
Fermeture par pile d'un JSON tronqué après un balayage conscient des chaînes

Une troncature n'est pas une faute de syntaxe, c'est une donnée manquante. La syntaxe se répare, une troncature ne se récupère qu'en partie. À l'instant où un outil referme la brèche, le reste de la brèche cesse d'être une erreur d'analyse et devient quelque chose que personne ne voit.

À quoi ressemble une troncature : un numéro de colonne ne suffit pas

Le modèle écrit du JSON selon votre schéma, atteint le plafond de sortie et le texte s'arrête net. Donnez ceci au module json de Python 3.11 :

{"scores": {"clarity": 8, "depth": 7}, "items": [{"name": "a", "qty": 2}, {"name": "b", "qty"

json.loads lève Expecting ':' delimiter, col 94. La colonne pointe la clé "qty" sans valeur, mais la cause réelle est que le document n'a pas de fin. Le refermer avec une regex gourmande ajoutant "} échoue ; une fermeture par pile consciente des chaînes (section six) analyse correctement, mais items ne contient plus que 2 entrées et le troisième enregistrement partiel a disparu. Le numéro de colonne dit où le texte s'est arrêté. Il ne dit jamais combien vous avez perdu.

C'est la première vraie différence avec une erreur JSON ordinaire. Une virgule finale a un état final bien défini : supprimez-la et le document est entier. Une troncature n'a pas cet état final. Réparez-la et vous avez toujours un fragment.

Troncature n'est pas dégât de syntaxe : l'angle mort des outils de réparation

Les réparateurs comme jsonrepair transforment du JSON cassé en JSON légal : retirer les balises markdown, les virgules finales, convertir les guillemets simples. L'intention y est intacte, la réparation n'est qu'un nettoyage. Une entrée tronquée ressemble au même JSON cassé pour le même outil : il ferme la chaîne, le tableau, l'objet ouverts et rend quelque chose d'analysable. Sur 83 rapports Claude tronqués, l'outil en a « réparé » 79, seuls 4 ont échoué franchement. La surveillance d'erreurs voyait un taux vingt fois inférieur à la réalité.

Le résultat ressemblait à quoi ? Le retour de la question 6 s'arrêtait au milieu d'une phrase, les questions 7 à 9 n'existaient plus, le tableau next_steps avait disparu. Pydantic validait quand même, car next_steps avait [] par défaut et la liste de retours n'avait aucune contrainte de longueur. Chaque couche faisait son travail. Le produit livrait un rapport confiant et faux.

Placez la réparation de syntaxe sur un chemin de troncature et elle glisse silencieusement du nettoyage à la fabrication. La frontière vient donc en premier : un réparateur ne doit traiter que les salissures de forme d'une réponse complète ; une réponse coupée ne doit jamais l'atteindre. Pour les salissures de forme, voyez le guide de réparation JSON.

La première étape est toujours la raison d'arrêt

Toutes les API majeures indiquent pourquoi la génération s'est arrêtée, dans les métadonnées, gratuitement. C'est aussi la ligne de code la plus ignorée des intégrations LLM. Anthropic expose stop_reason, l'API chat d'OpenAI expose finish_reason : max_tokens signifie tronqué, end_turn ou stop signifie que le modèle a terminé seul.

resp = client.messages.create(model=MODEL, max_tokens=4096, ...)
if resp.stop_reason != "end_turn":
    raise TruncatedOutput(
        f"stop_reason={resp.stop_reason}, "
        f"output_tokens={resp.usage.output_tokens}"
    )
data = json.loads(resp.content[0].text)

Une fois la troncature transformée en exception explicite, la relance a un déclencheur et la surveillance une source d'alerte. Ces 83 rapports ont été retrouvés après coup avec une seule requête sur le champ stop_reason de journaux stockés depuis toujours et jamais lus. Gemini signale length et incomplete dans le même esprit ; pour un nouveau fournisseur, vérifiez la table de correspondance avant de supposer.

max_tokens est un garde-fou, pas un budget

La cause directe est souvent un plafond dimensionné pour une ancienne version du produit : une limite de 1500 jetons qui coupe 39 % des rapports longs dès l'arrivée des sessions longues. Augmenter le plafond ne coûte rien. La facturation suit les jetons réellement générés : un plafond de 4096 sur un rapport de 1100 jetons revient exactement au même qu'un plafond de 1500. Le plafond sert à arrêter une génération folle, pas à économiser.

Dimensionnez à partir des données : observez une semaine de distribution réelle, prenez le p99, laissez de la marge. L'équipe de l'incident a choisi 4096 parce que son p99 était de 2350 après correction. L'autre levier est de réduire la sortie elle-même. Les clés répétées des tableaux homogènes absorbent l'essentiel des jetons ; les remplacer par un encodage tabulaire avant l'appel (voir le guide du format TOON) réduit le volume à faire tenir sous le plafond.

L'ordre des champs du schéma décide de ce qui sera coupé

Les modèles écrivent le JSON de haut en bas. Quand le budget s'épuise, ce qui est en fin de liste disparaît d'abord. Un schéma ordonné summary, per_question_feedback, scores, next_steps perd d'abord les scores — précisément la partie que les utilisateurs capturent et comparent chaque semaine. La correction est un réordonnancement, pas une refonte : champs courts et critiques devant, détails longs régénérables ensuite, texte libre en dernier.

Le comportement des fournisseurs change aussi la conséquence d'une même troncature :

Fournisseur Mécanisme de sortie structurée Comportement en cas de troncature
OpenAI response_format avec strict: true Garantie au niveau de l'échantillonnage, dialecte le plus étroit ; refuse souvent de générer
Anthropic input_schema en tool use Aucune garantie au décodage ; peut renvoyer des accolades non fermées
Gemini responseSchema et type MIME JSON Seuls les enum et types sont contraints au décodage ; troncature toujours possible

« Sortie structurée activée, donc pas de validation » est donc une illusion. Plus la garantie du fournisseur est lâche, plus vous avez besoin de votre propre validation de schéma et d'une boucle de relance. La construction de ce test de contrat est traitée dans test de contrat JSON Schema.

Quand il faut vraiment une récupération partielle : fermeture par pile consciente des chaînes

Certains cas obligent à tirer quelque chose du fragment : aperçus en streaming, réponses dégradées, files de relecture humaine. La fermeture y est le dernier barreau de l'échelle de réparation et doit remplir deux conditions. D'abord, le balayage des accolades doit être conscient des chaînes : suivez l'état des guillemets et des échappements caractère par caractère, sinon une accolade dans une valeur casse la pile. Ensuite, supprimez les paires clé-valeur incomplètes avant de fermer. Une clé "qty" sans valeur ne peut pas donner {"qty"} ; la paire entière doit partir.

def close_truncated(s: str) -> str:
    # 1) Balayage conscient des chaînes, fermer la chaîne ouverte
    out, in_str, esc = [], False, False
    for ch in s:
        out.append(ch)
        if esc: esc = False; continue
        if ch == '\\' and in_str: esc = True; continue
        if ch == '"': in_str = not in_str
    text = ''.join(out) + ('"' if in_str else '')
    # 2) Retirer les paires partielles et deux-points ou virgule pendants
    text = re.sub(r',\s*"[^"]*"\s*$', '', text)
    text = re.sub(r'[{,]\s*"[^"]*"\s*:\s*$', '}', text)
    text = re.sub(r':\s*$', '', text)
    text = re.sub(r',\s*$', '', text)
    # 3) Rebalayer la pile et fermer en LIFO
    stack, in_str, esc = [], False, False
    for ch in text:
        if esc: esc = False; continue
        if ch == '\\' and in_str: esc = True; continue
        if ch == '"': in_str = not in_str; continue
        if not in_str:
            if ch in '{[': stack.append(ch)
            elif ch in '}]' and stack: stack.pop()
    return text + ''.join('}' if c == '{' else ']' for c in reversed(stack))

Sur l'entrée du début, ce code renvoie {"scores": {...}, "items": [{"name": "a", "qty": 2}, {"name": "b"}]} avec Python 3.11 et la bibliothèque standard seule. Cela s'analyse, et le troisième enregistrement est perdu. Côté modèles locaux, des bibliothèques dédiées comme partial-json-parser font le même travail : fermer par pile, élaguer par complétude.

L'essentiel est la divulgation. La fonction de fermeture doit dire à quel barreau le résultat a été obtenu ; tout ce qui sort du barreau truncation est un résultat partiel et doit être étiqueté comme tel : redemander la portée manquante, relancer avec un plafond plus grand, ou dire à l'utilisateur que ses données sont incomplètes. Faire semblant que rien ne s'est passé, c'est fabriquer des hallucinations avec du code déterministe.

Réparer ou relancer : une table de frontière

Forme de l'entrée Action correcte Pourquoi
Balises, virgules finales, guillemets simples Réparateur L'intention est complète, seule la syntaxe est sale
Coupé au milieu d'une chaîne Relance, ou récupération partielle + divulgation La valeur elle-même manque
Coupé au milieu d'une structure Récupération partielle + divulgation Les champs terminés survivent, les paires partielles doivent partir
S'analyse mais semble faux Validation métier Ce n'est pas la troncature, mais cela arrive souvent ensemble

Une équipe financière a chiffré le coût. Des factures longues étaient tronquées, la fermeture produisait du JSON valide, le champ total manquant prenait la valeur par défaut 0, et un système à 98,2 % de conformité de format produisait environ 200 factures fausses par mois. Après avoir traité la troncature comme une dégradation dure et ajouté un contrôle d'identité (total == somme des lignes), le taux d'erreur monétaire est passé de 0,8 % à 0,02 % tandis que la conformité de format ne montait qu'à 99,1 %. Trois mois d'optimisation sur « la conformité de format » visaient la mauvaise métrique. Passer le parseur n'est pas passer le métier.

La liste de quatre points : filtrer sur la raison d'arrêt avant d'analyser ; dimensionner le plafond sur le p99 et non comme un budget ; placer les champs critiques du schéma devant ; ne laisser au réparateur que les salissures de forme des réponses complètes. Faites les quatre et la troncature redevient, d'une corruption silencieuse, un échec bruyant et relançable.

Peut-on simplement refermer les accolades et utiliser le résultat

Non. Refermer ne rend que la légalité syntaxique ; les données restent un fragment avec une phrase coupée, des enregistrements finaux perdus et des valeurs par défaut à la place des vraies. Marquez la sortie comme partielle, déclenchez une relance ou une dégradation, et journalisez le taux de récupération.

Comment distinguer une troncature d'une vraie erreur de syntaxe

Lisez la raison d'arrêt dans les métadonnées : max_tokens, length ou incomplete signifie troncature ; end_turn ou stop avec un échec d'analyse signifie un vrai dégât de syntaxe. Sans métadonnées, regardez la fin : coupé dans un guillemet ou une accolade avec la structure externe non fermée, c'est presque toujours une troncature.

Pourquoi une troncature réparée est-elle plus dangereuse qu'un échec bruyant

Un réparateur optimise « ça s'analyse », et une troncature refermée s'analyse, donc la surveillance reste muette et la validation en aval passe grâce aux valeurs par défaut. C'est ainsi que 83 rapports n'ont produit que 4 erreurs. L'outil n'a pas la notion d'intention et ne peut pas savoir ce qui manque, donc la troncature doit être interceptée en amont.

Augmenter max_tokens coûte-t-il plus cher

Non. La facturation suit les jetons réellement générés ; le plafond n'est qu'un garde-fou. Un plafond de 4096 sur une sortie de 1100 jetons coûte exactement comme un plafond de 1500. Réglez-le sur le p99 réel avec de la marge et investissez plutôt dans la prévention des générations folles.

Références

Outils associés

Articles liés

Guide de réparation JSON : sauver les sorties LLM cassées sans perdre la confiance

Les sorties LLM enveloppées de balises markdown, truffées de virgules finales et de littéraux Python, sont rejetées par tout parseur strict — tout comme les configs éditées à la main sans guillemets. Ce guide trace la vraie frontière entre neuf classes d'erreurs réparables et quatre irréparables, explique pourquoi une machine à états bat les regex, et fournit une chaîne d'analyse prête pour la production avec jsonrepair et json-repair.

Intermédiaire~6 min de lectureMis à jour le 2026-11-08

Guide du format TOON : alléger le JSON avant de le donner à un LLM

Quand vous transmettez un tableau uniforme à un grand modèle de langage en JSON, les noms de clés répétés et les crochets consomment des tokens. TOON déclare la structure une seule fois grâce aux objets indentés et aux tableaux tabulaires, puis déroule les données ligne par ligne. Les benchmarks officiels montrent environ 40 % de tokens en moins avec une meilleure précision d'analyse. Ce guide couvre la syntaxe, les limites réelles des économies, les cas où il ne faut pas convertir, et l'intégration d'encode et de decode.

Intermédiaire~6 min de lectureMis à jour le 2026-11-10

Tests de contrat JSON Schema : soudez vos règles de validation dans la CI

Un schéma ne s'achève pas à l'écriture — c'est là que commence la dégradation. Une coquille assoupit silencieusement la validation, un refactoring casse toutes les fixtures. Ce guide présente un dispositif de test de contrat exploitable : fixtures positifs, négatifs et instantanés, lint du schéma lui-même, compilation unique réutilisée, et quatre portes de CI qui transforment la casse du contrat en build rouge.

Intermédiaire~8 min de lectureMis à jour le 2026-11-05