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.

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.