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 належать до цієї школи, а заклик спільноти «відновлювач — це не 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 у джерелі, у порядку пріоритету:

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