Посібник з відновлення JSON: як врятувати зіпсований вивід LLM і не втратити довіру
Головне: Вивід LLM, обгорнутий у markdown-огорожу, з завершальними комами та Python-літералами, суворий парсер відхиляє повністю — як і конфіги з ручним редагуванням без лапок. Розбираємо межу між дев'ятьма класами помилок, які відновлювач справді виправляє, і чотирма, які не виправить ніколи, пояснюємо, чому автомат станів перемагає регулярні вирази, і даємо готовий ланцюжок парсингу з jsonrepair та json-repair.

Суворий парсер не дає зіпсованому вводу жодного послаблення: одне повідомлення про помилку, один номер рядка — і жодного байта ваших даних. Відновлювач існує, щоб перетворити «повний провал» на «досить добре, щоб запуститися» — але те, що він дописує, завжди лише найкраща здогадка про намір, ані гарантія правильності.
Один: звідки береться зіпсований JSON
Відновлення — не магія, тому почніть із вводу. У реальних проєктах нестандартний JSON походить із трьох концентрованих джерел:
- Вивід LLM. Мовні моделі генерують текст токен за токеном; вони не запускають JSON-серіалізатор. Навіть із вимогою «тільки JSON» модель обгорне відповідь у
```jsonогорожу, додасть перед нею «Ось ваші дані», залишить завершальну кому або впреться в ліміт токенів і зупиниться посеред об'єкта. - Копіювання з інших мов. Об'єкт JavaScript, надрукований через
console.log, несе одинарні лапки та ключі без лапок; словник Python друкується якTrue/False/None. Ці «схожі на JSON» рядки вибухають при першому контакті зJSON.parse. - Конфіги JSON5/JSONC. Файли на кшталт tsconfig законно дозволяють коментарі та завершальні коми. Вставте такий файл у суворий парсер — він відхилить увесь файл.
Три джерела потребують різного поводження, але відновлювачі покривають усі — за умови, що помилка є в їхньому оголошеному списку виправних.
Два: дев'ять класів помилок, які відновлювач справді виправляє
Поєднавши документацію бібліотеки jsonrepair зі списками можливостей, опублікованими постачальниками інструментів, автоматично виправні помилки поділяються на дев'ять класів:
| Клас | Зіпсований ввід | Після відновлення |
|---|---|---|
| Завершальна кома | [1, 2, 3,] |
[1, 2, 3] |
| Одинарні / фігурні лапки | {'a': 'b'}、{"a": "b"} |
{"a": "b"} |
| Ключі без лапок | {name: 'Ada'} |
{"name": "Ada"} |
| Коментарі | {"a": 1 /* примітка */} |
{"a": 1} |
| Python-літерали | {"ok": True, "v": None} |
{"ok": true, "v": null} |
| Markdown-огорожі | ```json {...} ``` |
{...} |
| Пропущені коми | [1 2] |
[1, 2] |
| Незакриті дужки / лапки | {"a": [1, 2 |
{"a": [1, 2]} |
| JSONP / конкатенація рядків | cb({...})、"x" + "y" |
{...}、"xy" |
Спільне для цих дев'яти: дані повністю на місці; неправильний лише синтаксис. Відновлювач підправляє пунктуацію та обгортки, не торкаючись жодного значення. Кілька деталей варті окремої уваги:
- Числа з нуля на початку стають рядками.
007відновлюється до"007", а не7, щоб не втратити розряди. Якщо поле й справді текстовий код — це правильно; якщо це справжнє число, рішення за вами. - Голі слова стають рядками.
NaNнеможливо відновити в число — одні реалізації видають"NaN", іншіnull. Поведінка відрізняється між бібліотеками; протестуйте свою перед підключенням до конвеєра. - Валідний вхід проходить без змін. Кожен серйозний відновлювач спершу запускає швидкий шлях суворого парсингу. Валідний JSON ніколи не потрапляє в логіку відновлення, тож «відремонтувати хороший документ у поганий» неможливо.
Три: чотири речі, які відновлювач не виправить
Межа з другого боку так само явна. Не чекайте виправлення для:
- HTML-сторінок помилок чи чистої прози. У вводі немає жодної JSON-структури, і жоден інструмент не створить дані з нічого.
- Синтаксично валідних, але хибних даних. Ключ із одруківкою, значення не на своєму місці, число, збережене як рядок — це семантичні проблеми, які кожен парсер, включно з відновлювачами, радісно пропускає.
- Даних, втрачених через обрив. Автодоповнення перетворить
{"items": [{"id": 1}, {"naна валідний JSON, але значенняnameне повернеться ніколи. Ви отримаєте «валідний, але неповний» об'єкт. У продакшені перевіряйтеstopReason === "max_tokens", перш ніж вирішувати: доповнювати чи повторювати запит. - Дубльованих ключів та неоднозначних структур. Який із двох однакових ключів переможе, залежить від реалізації парсера. Відповідальні відновлювачі пропонують strict-режим, який викидає помилку, а не мовчки обирає один.
Одне речення підсумовує межу довіри: відновлення — це найкраща здогадка, а не гарантія коректності. Пропустити неперевірений результат відновлення далі по конвеєру означає обміняти гучну синтаксичну помилку на тиху помилку даних.
Чотири: дві школи реалізації — один URL закриває суперечку
Відновлювачі бувають двох типів, і розрив проявляється на конкретному типі вводу.
Школа regex-заміни застосовує глобальний пошук-і-заміну до зіпсованих патернів. Розгляньте такий ввід:
{"url": "http://example.com", 'note': 'fine'}
Regex, що перетворює одинарні лапки на подвійні, зачепить і вміст URL; regex, що вилучає всі // як коментарі, розріже http:// навпіл. Усередині рядка й зовні структури символи виглядають однаково — regex не розрізнить їх.
Школа посимвольного автомата станів відстежує стан парсингу: усередині рядка в подвійних лапках, у рядку в одинарних, у рядковому коментарі, у блочному коментарі чи в очікуванні значення. Побачивши ', він спершу питає «чи я в рядку?» і лише тоді вирішує, конвертувати лапку чи пропустити. http://example.com сидить усередині рядка в подвійних лапках, тож автомат знає: // тут — дані, а не коментар, і зберігає їх. jsonrepair та json-healer належать до цієї школи, а заклик спільноти «відновлювач — це не find-and-replace» стосується саме цього.
Повний порядок конвеєра відновлення (за опублікованою реалізацією devkits) також вартий погляду: зняти огорожі → нормалізувати фігурні лапки → витягнути перший збалансований блок → вилучити коментарі → обгорнути голі ключі лапками → прибрати завершальні коми → конвертувати літерали → повторно серіалізувати через JSON.stringify. Ця фінальна ресеріалізація — ключовий крок: що б не робили попередні стадії, вихід генерується заново з розпарсеного результату, тож будь-який суворий парсер його прийме.
П'ять: підключення в коді — послідовний ланцюжок парсингу
Коли ви вбудовуєте відновлення в код, порядок важливіший за вибір бібліотеки. За патернами, опублікованими json2toon та aijsonmedic, послідовність має бути такою: перевірка обриву → витягнення JSON-діапазону → суворий parse → відновлення як fallback → валідація за схемою.
import { jsonrepair } from "jsonrepair";
export function parseModelJson(text, stopReason) {
if (stopReason === "max_tokens") {
// Відновлений обірваний вивід усе одно неповний — повторіть запит
throw new Error("Truncated output: retry with a higher max_tokens");
}
// Витягніть JSON-діапазон: LLM може додати балачки до і після
const start = text.search(/[[{]/);
const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
try {
return JSON.parse(candidate); // швидкий шлях для валідного вводу
} catch {
return JSON.parse(jsonrepair(candidate)); // відновлення як fallback
}
}
На боці Python пакет json-repair (понад 4 700 зірок) пропонує loads(), який повертає об'єкт напряму:
from json_repair import repair_json
import json
broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}
Два інженерні деталі:
- Вирівнюйте стеки. Якщо відновлення виконують і фронтенд, і бекенд, обирайте реалізації зі спільною семантикою — Python json-repair та його TypeScript-порт
@yarmu/json-repair, або jsonmend, чия Python- і JS-версії проходять той самий корпус узгодженості з 485 кейсів. Інакше той самий вивід відновиться в A на клієнті та B на сервері, і налагодження стане пекельним. - Увімкніть журнал відновлення.
@yarmu/json-repairзlogging: trueповертає масив кожної операції відновлення. Різкий стрибок кількості відновлень зазвичай означає, що змінилися промпт чи версія моделі — це сигнал раніше за будь-який звіт про помилки.
Ще один крок після відновлення не підлягає обговоренню: валідація за схемою. Синтаксично валідне не означає придатне. Відсутні поля, неправильні типи та несподівані ключі ловить схема. Підхід контрактного тестування застосовується тут напряму; дивіться наш гайд про контрактне тестування JSON Schema.
Шість: чекліст профілактики — найдешевше відновлення те, яке не потрібне
Відновлення — це запасний парашут. Справжня перемога — менше зіпсованого JSON у джерелі, у порядку пріоритету:
- Structured Outputs (режим json_schema). Декодування обмежене схемою, тож завершальна кома просто не може бути згенерована. Strict-режим OpenAI падає приблизно в 0,1% випадків, ціною жорстких вимог на кшталт
additionalProperties: false. - JSON-режим (json_object). Гарантіює лише синтаксичну валідність — не форму — і обрив через ліміт токенів усе одно трапляється.
- Явні інструкції. На ендпоінтах без JSON-режиму формулювання «без огорож, без коментарів, без завершальних ком, виводь лише об'єкт» знижує частоту помилок на 70–80%.
- Нижча temperature, вищий ліміт токенів. Перше зменшує дрейф у прозу; друге зменшує обриви.
- Повторення з долученою помилкою. Коли валідація падає, додайте зіпсований вивід плюс «JSON path + повідомлення про помилку» до розмови й попросіть ще раз. Моделі зазвичай виправляються самі, маючи точну помилку.
На практиці нашарування «structured outputs + відновлення-fallback + валідація за схемою» покриває практично кожен сценарій.
Сім: розподіл праці — конвертація діалекту не є відновленням
У наборі інструментів цього сайту є два пункти призначення, які покривають різні сегменти конвеєра:
- Проблеми діалекту (коментарі, одинарні лапки, завершальні коми) прямують до конвертера JSON5. Конвертація JSON5 ↔ стандартний JSON покриває рівно ці три класи з явною семантикою без здогадок. Якщо увесь ввід — файл JSONC/JSON5, конвертація передбачуваніша за відновлення. Про компроміси самих діалектів дивіться гайд JSON5 і JSONC.
- Після відновлення прогоніть результат через JSON-парсер для валідації та форматування, з помилками, прив'язаними до рядка і колонки, — це підтверджує, що суворий парсер справді приймає вихід.
- Проблеми бібліотечного класу (Python-літерали, автодоповнення обриву, JSONP-обгортки, markdown-огорожі) поки що вимагають кодового jsonrepair / json-repair — еквівалентного ремонту одним кліком у браузері немає, бо ці відновлення передбачають вгадування наміру, і локальна бібліотека — безпечніший дім для цього, ніж універсальний конвертер.
Якщо у вас на руках не зіпсовані дані, а повідомлення про помилку, почніть із гайду про виправлення помилок парсингу JSON, щоб перекласти повідомлення в координати, і вже тоді вирішуйте: редагувати вручну чи відновлювати.
FAQ
Чи псує відновлення JSON мої дані?
Для дев'яти виправних класів змінюються лише пунктуація та обгортки — значення недоторкані, а //, коми та фігурні дужки всередині рядків автомат станів розпізнає і зберігає. Але автодоповнення обриву дає неповні об'єкти, числа з нуля на початку стають рядками, а поводження з NaN різниться між бібліотеками. Перевірка ключових полів після відновлення — обов'язкова дія.
Які стосунки між відновленням і валідацією?
Валідація каже, де ввід незаконний; відновлення дає вам законний документ. Надійний робочий процес робить обидва: спершу відновлення, потім валідація — схема ловить типи та обов'язкові поля, синтаксична перевірка підтверджує, що суворий парсер приймає результат. Відновлювати без валідації — обміняти гучну синтаксичну помилку на тиху помилку даних.
LLM завжди обгортає вивід у ```json огорожу — що робити?
Короткостроково — витягуйте: беріть текст від першого { чи [ до останнього } чи ] і парсіть його; відновлювач зі зняттям огорож також зжере ціле повідомлення. Довгостроково — використовуйте structured outputs або явну інструкцію «без markdown-огорож», щоб огорожа взагалі не генерувалася.
jsonrepair чи json-repair — що обрати?
Для JavaScript беріть npm-пакет jsonrepair (він підтримує потоковий transform); для Python — json-repair із PyPI. Якщо відновлення йде на обох кінцях, оберіть семантично вирівняну пару — скажімо, json-repair плюс його TS-порт — щоб той самий ввід відновлювався однаково з обох боків.
Чи впораються відновлювачі з кирилицею та фігурними лапками?
Так. Типографські лапки, народжені кириличними розкладками («»), повноширинні пробіли та BOM на початку файлу — все це в стандартному списку відновлення; фігурні лапки нормалізуються до прямих. Прогоніть результат через валідатор один раз — і готово.