JSON Toolkit

JSON від LLM обірвався: спершу подивіться причину зупинки, а потім говоріть про лагодження

Головне: Модель повернула JSON, що урвався посеред значення, а парсер повідомляє лише номер стовпця. Закрити дужки — і розбір знову проходить, але кожен відсутній фрагмент тепер схований усередині даних. Стаття проводить межу між тим, що лагодження обрізання може чесно повернути, і тим, що треба запитувати заново.

Практика~5 хв читанняОпубліковано 2026-11-14Оновлено 2026-11-14
Закриття обрізаного JSON стеком після розбору з урахуванням рядків

Обрізання — це не синтаксична помилка, а брак даних. Синтаксис лагодиться, обрізання можна повернути лише частково. Тієї миті, коли інструмент закриває прогалину, решта прогалини перестає бути помилкою розбору й стає тим, про що ніхто не знає.

Як виглядає обрізання: одного номера стовпця замало

Модель пише JSON за вашою схемою, впирається в ліміт виводу, і текст просто закінчується. Передайте це модулю json на Python 3.11:

{"scores": {"clarity": 8, "depth": 7}, "items": [{"name": "a", "qty": 2}, {"name": "b", "qty"

json.loads видає Expecting ':' delimiter, col 94. Стовпець указує на ключ "qty" без значення, але справжня причина — документ не має кінця. Жадібний regex із дописаним "} не рятує; закриття стеком з урахуванням рядків (шостий розділ) розбирається, але в items лишаються 2 записи, а третій частковий зникає. Номер стовпця каже, де текст зупинився. Він ніколи не каже, скільки ви втратили.

Це перша справжня відмінність від звичайної помилки JSON. У зайвої коми є чіткий кінцевий стан: приберіть її, і документ цілий. У обрізання такого стану немає. Полагодьте — і це досі фрагмент.

Обрізання — не псування синтаксису: сліпа пляма лагоджувачів

Лагоджувачі на кшталт jsonrepair перетворюють синтаксично зламаний JSON на легальний: знімають markdown-обгортки, прибирають коми, міняють лапки. Там задум цілий, а лагодження — лише прибирання. Обрізаний вхід для того самого інструмента виглядає як зламаний JSON, тож він закриває відкритий рядок, масив і об'єкт та повертає щось розбирабельне. З-поміж 83 обрізаних звітів Claude інструмент «полагодив» 79, жорстко відмовили лише 4. Моніторинг помилок бачив частоту в двадцять разів нижчу за реальну.

Як виглядав результат? Відгук до питання 6 обривався на півслові, питань 7–9 не було, масив next_steps зник. Pydantic усе одно валідував, бо в next_steps було значення за замовчуванням [], а список не мав обмеження довжини. Кожен шар робив свою роботу. Продукт видав упевнений і хибний звіт.

Поставте лагодження синтаксису на шлях обрізання — і воно тихо перетвориться з прибирання на вигадування. Тож спершу межа: інструмент лагодження працює лише з брудом формату на повних відповідях; обрізана відповідь не повинна до нього доходити взагалі. Про бруд формату читайте в посібнику з лагодження JSON.

Перший крок завжди — причина зупинки

Усі великі API безкоштовно повідомляють у метаданих, чому генерація припинилася. Це ж найбільш ігнорований рядок коду в інтеграціях з LLM. Anthropic віддає stop_reason, чат-API OpenAI — finish_reason: max_tokens означає обрізання, end_turn або stop — що модель завершила сама.

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)

Коли обрізання стало явним винятком, у повтору з'являється умова спрацювання, а в моніторингу — джерело тривоги. Ті 83 звіти знайшлися заднім числом одним запитом за полем stop_reason у логах, які зберігалися завжди і ніколи не читалися. Gemini сигналізує length та incomplete у тому ж сенсі; підключаючи нового провайдера, звіряйтеся з таблицею відповідності, а не вгадуйте.

max_tokens — це огорожа, а не бюджет

Пряма причина зазвичай — ліміт, розрахований на попередню версію продукту: 1500 токенів, які з приходом довгих сесій ріжуть 39% довгих звітів. Підняти ліміт безкоштовно. Оплата йде за фактично згенеровані токени, тому 4096 на звіт у 1100 токенів коштує рівно стільки ж, скільки 1500. Ліміт потрібен, щоб спинити розгін генерації, а не щоб економити.

Рахуйте за даними: тиждень спостерігайте реальний розподіл, візьміть p99 і лишіть запас. Команда з того інциденту обрала 4096, бо після виправлення p99 був 2350. Другий напрям — зменшити сам вивід. Повторювані ключі в однорідних масивах з'їдають основну частину токенів; табличне кодування перед викликом (див. посібник із формату TOON) скорочує обсяг, що має вміститися в ліміт.

Порядок полів схеми визначає, що обріжеться

Моделі пишуть JSON згори вниз. Коли бюджет вичерпується, першим зникає те, що стоїть у кінці списку властивостей. Схема в порядку summary, per_question_feedback, scores, next_steps втрачає спершу scores — саме те, що користувач знімає скриншотом і порівнює щотижня. Виправлення — перестановка: короткі критичні поля вперед, довгі й відтворювані деталі потім, вільний текст у самому кінці.

Поведінка провайдерів також змінює наслідки того самого обрізання:

Провайдер Механізм структурованого виводу Поведінка при обрізанні
OpenAI response_format з strict: true Гарантія на рівні семплування, але найвужчий діалект; зазвичай відмовляється генерувати
Anthropic input_schema у tool use Гарантії на етапі декодування немає; може повернути незакриті дужки
Gemini responseSchema з MIME JSON На декодуванні примусово лише enum і тип; обрізання все ще можливе

«Структурований вивід увімкнено, валідація не потрібна» — омана. Чим слабша гарантія провайдера, тим потрібніша власна перевірка схеми й цикл повторів. Як зібрати такий контрактний тест, є в контрактних тестах JSON Schema.

Коли часткове відновлення справді потрібне: закриття стеком з урахуванням рядків

Бувають випадки, коли з фрагмента треба вичавити хоч щось: потоковий попередній перегляд, деградована відповідь, черга на ручну перевірку. Тоді закриття — остання сходинка драбини лагодження, і в неї дві умови. Перша: обхід дужок має враховувати рядки, стежачи за лапками й екрануванням посимвольно, інакше { усередині значення ламає стек. Друга: неповні пари «ключ-значення» треба видалити до закриття. Ключ "qty" без значення не можна закрити в {"qty"}; пара йде цілком.

def close_truncated(s: str) -> str:
    # 1) Обхід з урахуванням рядків; спершу закрити відкритий рядок
    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) Прибрати неповні пари та висячі двокрапку/кому
    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) Пересканувати стек і закрити за 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))

На вводі з початку статті це повертає {"scores": {...}, "items": [{"name": "a", "qty": 2}, {"name": "b"}]} на Python 3.11 зі стандартною бібліотекою. Розбір проходить, третій запис губиться. На боці локальних моделей тим самим займаються спеціалізовані бібліотеки на кшталт partial-json-parser: закрити стеком, відрізати за повнотою.

Головне — розкриття. Функція закриття зобов'язана повідомляти, на якій сходинці отримано результат; усе, що вийшло зі сходинки truncation, — частковий результат, і це треба позначати: запросити відсутній фрагмент, повторити з більшим лімітом або сказати користувачеві, що дані неповні. Вдавати, ніби нічого не сталося, — це вигадування галюцинацій детермінованим кодом.

Полагодити чи повторити: таблиця меж

Форма вводу Правильна дія Чому
Обгортки, зайві коми, одинарні лапки Інструмент лагодження Задум цілий, брудний лише синтаксис
Обрив посеред рядка Повтор або часткове відновлення з розкриттям Самого значення бракує
Обрив посеред структури Часткове відновлення з розкриттям Завершені поля виживають, часткові пари йдуть
Розбирається, але виглядає хибно Перевірка бізнес-логікою Це не обрізання, але часто йде поруч

Одна фінансова команда виміряла ціну. Довгі рахунки обрізалися, закриття дужок давало валідний JSON, відсутнє поле total отримувало значення за замовчуванням 0, і система з 98,2% відповідності формату видавала близько 200 хибних рахунків на місяць. Після того як обрізання почали вважати жорсткою деградацією і додали перевірку тотожності (total == сума позицій), частка грошових помилок упала з 0,8% до 0,02%, а відповідність формату зросла лише до 99,1%. Три місяці оптимізації «відповідності формату» били по хибній метриці. Пройти парсер — не те саме, що пройти бізнес.

Чек-ліст із чотирьох пунктів: перевіряйте причину зупинки до розбору; задавайте ліміт за p99, а не як бюджет; ставте критичні поля схеми вперед; давайте лагоджувачу лише бруд формату повних відповідей. Виконайте всі чотири — і обрізання повернеться з тихого псування даних у гучний і повторюваний збій.

Можна просто закрити дужки й використати результат

Ні. Закриття гарантує лише синтаксичну легальність, дані лишаються фрагментом: фраза обривається, останні записи втрачені, замість реальних значень стоять значення за замовчуванням. Позначайте вивід як частковий, запускайте повтор або деградацію і логуйте частку відновлення.

Як відрізнити обрізання від справжньої синтаксичної помилки

Дивіться причину зупинки в метаданих: max_tokens, length або incomplete — обрізання; end_turn чи stop при збої розбору — справжнє псування синтаксису. Без метаданих дивіться на кінець: обрив усередині лапок або дужок із незакритою зовнішньою структурою майже завжди обрізання.

Чому полагоджене обрізання небезпечніше за гучний збій

Лагоджувач оптимізує «щоб розбиралося», а закрите обрізання розбирається, тож моніторинг мовчить, а подальша валідація проходить завдяки значенням за замовчуванням. Так 83 обрізані звіти дали лише 4 помилки. В інструмента немає поняття задуму, він не знає, чого бракує, тому обрізання треба перехоплювати вище за потоком.

Чи підняття max_tokens коштує дорожче

Ні. Оплата йде за фактично згенеровані токени, ліміт — лише огорожа. 4096 при 1100 згенерованих токенах коштує рівно як 1500. Ставте за реальним p99 із запасом і вкладайтеся в запобігання розгону генерації.

Джерела

Відповідні інструменти

Схожі статті

Посібник з відновлення JSON: як врятувати зіпсований вивід LLM і не втратити довіру

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

Середній~6 хв читанняОновлено 2026-11-08

Гід з формату TOON: полегшіть JSON перед передачею LLM

Коли ви передаєте однорідний масив мовній моделі у форматі JSON, повторювані назви ключів і дужки з'їдають токени. TOON оголошує структуру лише один раз через індексовані об'єкти та табличні масиви, а дані вивантажує рядок за рядком. Офіційні бенчмарки показують близько 40% менше токенів із вищою точністю парсингу. Цей гід охоплює синтаксис, коли економія працює, коли конвертувати не варто та як з'єднати encode і decode.

Середній~6 хв читанняОновлено 2026-11-10

Контрактне тестування JSON Schema: вбудуйте правила валідації в CI

Схема не завершується написанням — саме звідти починається деградація. Одна одруківка тихо послаблює валідацію, один рефакторинг ламає всі фікстури. Тут розібрано робочий набір контрактного тестування: позитивні, негативні та снапшот-фікстури, лінт самої схеми, одноразову компіляцію з повторним використанням і четверо воріт CI, що перетворюють поломку контракту на червону збірку.

Середній~8 хв читанняОновлено 2026-11-05