Руководство по восстановлению 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 принадлежат к этой школе, а мантра сообщества «восстановитель — это не поиск-и-замена» относится именно к этому.
Полный порядок конвейера восстановления (как раскрыт в реализации 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). Декодирование ограничено схемой, поэтому завершающая запятая просто не может быть сгенерирована. Строгий режим OpenAI падает примерно в 0,1% случаев — ценой жёстких требований вроде
additionalProperties: false. - JSON-режим (json_object). Гарантирует только синтаксическую валидность — не форму — и обрыв из-за лимита токенов всё равно случается.
- Явные инструкции. На эндпоинтах без JSON-режима формулировка «без ограждений, без комментариев, без завершающих запятых, выводи только объект» снижает частоту ошибок на 70–80%.
- Ниже temperature, выше лимит токенов. Первое уменьшает уход в прозу; второе уменьшает обрывы.
- Повторение с приложенной ошибкой. Когда валидация падает, добавьте сломанный вывод плюс «JSON-путь + сообщение об ошибке» к беседе и попросите снова. С точной ошибкой модели обычно исправляются сами.
На практике наслоение «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 в начале файла — всё это в стандартном списке восстановления; фигурные кавычки нормализуются в прямые. Прогоните результат через валидатор один раз — и готово.