JSON від LLM обірвався: спершу подивіться причину зупинки, а потім говоріть про лагодження
Головне: Модель повернула 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 із запасом і вкладайтеся в запобігання розгону генерації.