JSON Toolkit

Руководство по восстановлению JSON: как спасти сломанный вывод LLM и сохранить доверие

Главное: Вывод LLM, завёрнутый в markdown-ограждение, с завершающими запятыми и литералами Python, строгий парсер отвергает целиком — как и конфиги, отредактированные вручную без кавычек. Это руководство проводит настоящую границу между девятью классами ошибок, которые восстановитель исправляет, и четырьмя, которые не исправит никогда, объясняет, почему автомат состояний побеждает регулярные выражения, и даёт цепочку разбора, готовую к продакшену, с jsonrepair и json-repair.

Средний~6 мин чтенияОпубликовано 2026-11-08Обновлено 2026-11-08
Схема конвейера восстановления JSON: снятие ограждения, нормализация кавычек, балансировка скобок, финальная валидация

Строгий парсер не даёт сломанному вводу никакой скидки: одно сообщение об ошибке, один номер строки — и ни байта ваших данных. Восстановитель существует, чтобы превратить «полный провал» в «достаточно хорошо для запуска» — но то, что он дописывает, всегда лишь лучшее предположение о намерении, а не гарантия правильности.

Один: откуда берётся сломанный JSON

Восстановление — не магия, поэтому начните с входа. В реальных проектах нестандартный JSON приходит из трёх концентрированных источников:

  1. Вывод LLM. Языковые модели генерируют текст токен за токеном; они не запускают JSON-сериализатор. Даже по требованию «только JSON» модель завернёт ответ в ограждение ```json, добавит перед ним «Вот ваши данные», оставит завершающую запятую или упрётся в лимит токенов и остановится посреди объекта.
  2. Копирование из других языков. Объект JavaScript, напечатанный через console.log, несёт одинарные кавычки и ключи без кавычек; словарь Python печатается как True/False/None. Эти «похожие на JSON» строки взрываются при первом контакте с JSON.parse.
  3. Конфиги 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 никогда не попадает в логику восстановления, поэтому «отремонтировать хороший документ в плохой» невозможно.

Три: четыре вещи, которые восстановитель не исправит

Граница по другую сторону столь же явна. Не ждите исправления для:

  1. HTML-страниц ошибок или чистой прозы. Во вводе нет никакой JSON-структуры, и ни один инструмент не создаст данные из ничего.
  2. Синтаксически валидных, но неверных данных. Ключ с опечаткой, значение не на своём месте, число, сохранённое как строка, — это семантические проблемы, которые любой парсер, включая восстановители, молча пропускает.
  3. Данных, потерянных из-за обрыва. Автодополнение превратит {"items": [{"id": 1}, {"na в валидный JSON, но значение name не вернётся никогда. Вы получите «валидный, но неполный» объект. В продакшене проверяйте stopReason === "max_tokens", прежде чем решать: дополнить или повторить запрос.
  4. Дублирующихся ключей и неоднозначных структур. Какой из двух одинаковых ключей победит, зависит от реализации парсера. Ответственные восстановители предлагают 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 у источника, в порядке приоритета:

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