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

Головне: 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:
- Кожне поле має бути в required. Strict не приймає поняття необов'язкового поля. Щоб виразити «опційність», лишіть поле у required, але оголосіть тип як nullable-об'єднання —
"type": ["string", "null"]— і дозвольте моделі повертати null за відсутності. Це точна протилежність стандартної практики, де required містить лише справді необхідні поля. - Кожен об'єкт мусить явно оголошувати additionalProperties: false. У звичайних схемах це часто залишають невстановленим (див. нашу статтю про поведінку additionalProperties у різних рантаймах), але в strict-режимі це умова допуску: без нього запит падає. Причина пряма — автомат може генерувати лише оголошені ключі, тож будь-який неоголошений ключ недосяжний за конструкцією.
- Пастка для 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 досі на місці, чи підтягнулися ліміти вкладеності та розміру. Постачальники приймають різні підмножини, тож перед повторним використанням схеми між моделями перевірте її одним мінімальним запитом.