JSON Toolkit

Структурований вивід LLM ламається: як насправді писати схему для strict-режиму

Головне: Якщо просто увімкнути strict для звичайної JSON Schema, швидше за все повернеться 400: усі поля обов'язкові, additionalProperties:false у кожному об'єкті, $ref та allOf відхиляються одразу. У цій статті — як пакетно переписати вільну схему у strict-сумісну, з nullable-об'єднаннями, жорсткими лімітами та чеклістом розбору refusal.

Середній~8 хв читанняОпубліковано 2026-11-19Оновлено 2026-11-19
Схема правил переписування JSON Schema для strict-режиму LLM

Головне: strict: true — це не перемикач «бути трохи серйознішим», а контракт, який приймає лише підмножину JSON Schema. Усі поля в required, additionalProperties: false у кожному об'єкті, $ref і allOf відхиляються одразу. Відправити непереписану схему в strict-режимі — значить отримати 400, а не надійніший вивід.

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

Що strict насправді змінює: замок на семплері у вигляді граматики

У звичайному режимі JSON, згенерований моделлю, лише «ймовірно» відповідає вашій схемі, і все тримається на рядку «виведи JSON» у промпті. В офіційних evals OpenAI модель gpt-4-0613 із лише промптом слідувала складним схемам у менш ніж 40% випадків; із увімкненим strict gpt-4o-2024-08-06 досягла 100% на тому самому наборі.

Механізм — обмежене декодування (constrained decoding): на першому запиті API компілює вашу схему у скінченний автомат, і на етапі декодування кожен токен має бути пропущений цим автоматом. Модель фізично не може видати токен, що порушує схему. Це не нагадування — це замок. Ціна складається з двох частин: перша компіляція нової схеми забирає додатковий час (зазвичай до 10 секунд, для складних схем — до хвилини) і додає близько 5-8% затримки першого токена; артефакти компіляції кешуються, тому наступні запити нічого не платять.

Чітко розділіть, що гарантується, а що ні: синтаксис і форма замкнені, семантика — ні. Модель як і раніше може впевнено записати 400 у estimate_hours або витягнути неправильну адресу електронної пошти. Форма — це підлога, а не стеля; якість семантики все одно тримає eval-набір. У 2026 році навіть найновіші моделі під навантаженням показують приблизно 0,4% залишкового рівня псування форми, тож цикл повторів залишається обов'язковим.

Три жорсткі правила: усе в required, заборона зайвих ключів, nullable замість optional

Strict mode висуває до схеми три вимоги переписування, і кожна суперечить звичній інтуїції JSON Schema:

  1. Кожне поле має бути в required. Strict не приймає поняття необов'язкового поля. Щоб виразити «опційність», лишіть поле у required, але оголосіть тип як nullable-об'єднання — "type": ["string", "null"] — і дозвольте моделі повертати null за відсутності. Це точна протилежність стандартної практики, де required містить лише справді необхідні поля.
  2. Кожен об'єкт мусить явно оголошувати additionalProperties: false. У звичайних схемах це часто залишають невстановленим (див. нашу статтю про поведінку additionalProperties у різних рантаймах), але в strict-режимі це умова допуску: без нього запит падає. Причина пряма — автомат може генерувати лише оголошені ключі, тож будь-який неоголошений ключ недосяжний за конструкцією.
  3. Пастка для Python: Pydantic викидає поля з дефолтами з required. Запис priority: str = "low" прибирає один елемент зі списку required згенерованої схеми, і strict відхиляє її. Або приберіть дефолт, або долайте масово скриптом нижче.

Усі три правила мають рекурсивно застосовуватися до кожного вкладеного об'єкта. Виправити верхній рівень, лишивши дочірні об'єкти недоторканими, — і ви все одно отримаєте 400. Мінімальний відповідний приклад:

{
  "type": "object",
  "properties": {
    "intent": { "type": "string", "enum": ["book", "cancel", "question", "other"] },
    "note": { "type": ["string", "null"] }
  },
  "required": ["intent", "note"],
  "additionalProperties": false
}

Ці конструкції падають одразу: заборонені та неозброєні ключові слова

Strict-режим підтримує лише підмножину JSON Schema. Поділіть ключові слова на два відра і працюйте з ними по-різному:

Відро Ключові слова Поведінка в strict-режимі
Відхилено одразу посилання $ref / $defs, allOf, not, dependentRequired, dependentSchemas, if/then/else API повертає помилку; запит падає
Мовчазно не застосовується pattern, minLength, maxLength, format, minimum, maximum, multipleOf (fine-tuned моделі) Ні помилки, ні примусу — регулярні вирази перевіряйте самі в шарі застосунку

Підхід різний: перше відро треба переписати — розгорніть $ref інлайн і злийте allOf у properties. Друге відро може лишитися (деякі конфігурації їх приймають), але ніколи не вважайте його обороною. Покладатися на "pattern": "^v\\d+\\.\\d+\\.\\d+$" для гарантії формату версії — це бігти наосліп під strict; запускайте явну валідацію на кожній відповіді. Ще одне правило на самому верху: корінь схеми не може бути масивом чи «голим» об'єднанням типів — оберніть його в object.

Жорсткі ліміти: 5000 властивостей, 10 рівнів вкладеності, 120 000 символів

Навіть коли всі ключові слова сумісні, перевищення лімітів розміру все одно падає. Офіційні числа OpenAI:

  • щонайбільше 5000 властивостей об'єктів на всю схему, щонайбільше 10 рівнів вкладеності (у Anthropic ліміт вкладеності — приблизно 6 рівнів);
  • сумарна довжина рядків імен властивостей, імен визначень, значень enum і const — 120 000 символів;
  • щонайбільше 1000 значень enum сумарно; окремий строковий enum із понад 250 значеннями не може перевищувати 15 000 символів.

Ви рідко торкаєтеся цих лімітів, але «взяти весь словник компанії як enum» і «стиснути трирівневий граф об'єктів в один рівень» — два реальні провальні сценарії. Потрапили — розділяйте: розбийте гігантську схему на кілька викликів або сплюсуйте структуру. Корисний побічний ефект: ключі виводу йдуть у порядку ключів схеми, тож парсери, що залежать від фіксованого порядку, можуть вважати це фічею.

Скрипт, який пакетно переписує вільну схему в strict-вигляд

Ручне редагування пошарово гарантує пропуски. Рекурсивний скрипт нижче (патерн із гайду DevToolLab 2026) за один прохід додає «кожен об'єкт закрито, кожен ключ required»:

def make_strict(schema: dict) -> dict:
    """additionalProperties:false + кожен ключ required, на кожному рівні."""
    if isinstance(schema, dict):
        if schema.get("type") == "object" and "properties" in schema:
            schema["additionalProperties"] = False
            schema["required"] = list(schema["properties"].keys())
            for value in schema["properties"].values():
                make_strict(value)
        elif isinstance(schema, dict):
            for value in schema.values():
                make_strict(value)
    elif isinstance(schema, list):
        for item in schema:
            make_strict(item)
    return schema

Супутній робочий процес: спершу виведіть каркас схеми зі зразка JSON (сторінка інструменту /convert/schema на цьому сайті робить односторонній висновок Schema з JSON), візьміть каркас за точку відправлення, підтягніть його трьома strict-правилами і в кінці пройдіться make_strict як останнім страховою сіткою. Зверніть увагу: скрипт виправляє лише форму — nullable-об'єднання, enum і семантичні поля все одно вирішує людина; будь-яку схему з $ref спершу розгорніть інлайн.

Еквівалент для Anthropic: tool-as-schema

В Anthropic немає перемикача strict: true. Канонічний патерн 2026 року — прикріпити схему відповіді як input_schema інструменту і примусити модель викликати його через tool_choice:

await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  tools: [{ name: "emit", description: "Emit final summary", input_schema: schema }],
  tool_choice: { type: "tool", name: "emit" },
  messages,
});

Канал виклику інструментів сам валідує JSON, тож ефект еквівалентний strict-режиму. Різниця у деталях: ліміт вкладеності Anthropic — близько 6 рівнів, підтримується .nullable() замість .optional(); усі три постачальники (OpenAI, Anthropic, Gemini) приймають трохи різні підмножини схеми. Повторне використання однієї схеми без змін між постачальниками ненадійне — перевіряйте щоразу при зміні моделі.

Розберіть refusal, обрізання і таймаути до того, як говорити про повтори

Коли strict-режим видає вам недійсне, причин лише три, і кожна вимагає різної реакції:

  • Refusal: модель відмовила у виконанні (небезпечний запит тощо). Поле refusal у відповіді істинне — читати JSON у цей момент безглуздо; передайте людині або перепишіть запит.
  • Обрізання: finish_reason дорівнює length — max_tokens не вистачило, вивід фізично неповний. Обмеження схеми не врятує обрізаний вивід; підніміть бюджет або стисніть структуру. Ідентифікація та часткове відновлення — у нашій статті про діагностику та ремонт обрізаного JSON.
  • Псування форми: коли постачальник не повністю підтримує підмножину, поганий JSON все одно може дійти. Не повторюйте просто «спробуй ще раз» — додайте точний текст помилки валідації назад у промпт: «severity має бути low/medium/high/critical; ви вивели urgent; виправте та виведіть знову». Повтори з контекстом помилки скорочують середню кількість повторів із 3 до приблизно 1,5.

Поставте жорстку стелю повторів (скажімо, два), а за її перевищенням — деградуйте до меншої моделі для виправлення або до людської черги. Не дозволяйте одному поганому виводу паралізувати весь конвеєр.

Чекліст перед випуском

Перевірка Критерій проходження
required Кожне поле кожного об'єкта є в required
additionalProperties Явне false на кожному об'єкті, до найглибшого рівня
Опційна семантика Змодельована об'єднаннями ["string", "null"]; без голого optional
Заборонені ключові слова Немає $ref / allOf / if-then-else / dependentRequired
Неозброєні ключові слова pattern і format перевіряються вдруге в шарі застосунку
Розмір ≤5000 властивостей, ≤10 рівнів, ≤120 000 символів рядків
Розбір refusal / length / помилка парсингу обробляються окремими шляхами
Повтори З оригінальним текстом помилки, стеля 2, потім деградація
Семантика Evals або польові твердження поза схемою

Після проходження цього чеклісту надійність форми фактично замкнена. Семантику та еволюцію контракту — версіювання схем і змусити зламану схему спочатку червоніти в CI — дивіться у статті зварювання схемних контрактів у CI.

FAQ

Чи гарантує strict-режим правильність значень полів?

Ні. Він лише замик синтаксис і форму на етапі декодування: кожен ключ на місці, типи правильні, enum легальні. Про семантичну правильність він нічого не каже — модель може вивести добре сформовані, але хибні дані. Семантичний шар тримають eval-набори або польові твердження.

Чому опційні поля теж ідуть у required?

Автомат strict-режиму вимагає, щоб кожна оголошена властивість була досяжною; пропущений елемент required падає на валідації. Опційність змодельована об'єднанням ["string", "null"]: поле завжди з'являється, значення може бути null, а нижній код трактує null як відсутність.

Чи є pattern і minLength повністю марними?

Під fine-tuned моделями та в більшості strict-конфігурацій вони не застосовуються. Вони не дають помилки — і саме тому небезпечні: ви думаєте, що маєте оборону, а її немає. Відповіді, що залежать від цих обмежень, валідуйте явно через ajv або jsonschema після отримання.

Чи сповільнює strict-режим відповіді?

Лише перший запит із новою схемою платить за компіляцію (зазвичай до 10 секунд, до хвилини для складних). Після кешування артефактів наступні запити бачать лише близько 5-8% зростання затримки першого токена. У стабільному стані це непомітно; реальна ціна виникає лише при частих змінах схеми.

Що перевіряти повторно після зміни версії моделі?

Три речі: чи змінилася підтримувана підмножина схеми у цій версії, чи поля refusal і finish_reason досі на місці, чи підтягнулися ліміти вкладеності та розміру. Постачальники приймають різні підмножини, тож перед повторним використанням схеми між моделями перевірте її одним мінімальним запитом.

Джерела

Схожі статті

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

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

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

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

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

Практика~5 хв читанняОновлено 2026-11-14

Без additionalProperties перевірка схеми нічого не перевіряє

Успішна перевірка не означає чисті дані. Pydantic типово ігнорує невідомі поля, Zod їх вилучає, Ajv пропускає — вигадані параметри й одруківки проходять тихо. Стаття показує три форми мовчазного прийняття та дає повні рецепти: закривати об'єкти, контролювати приведення типів, підтягувати кожен рівень вкладеності.

Intermediate~8 хв читанняОновлено 2026-11-02