Свободный текст удобен для человека, но плохо подходит как контракт между LLM и backend. Structured Outputs ограничивают ответ схемой: приложение заранее знает поля, типы и допустимые значения, а результат можно валидировать до выполнения бизнес-логики.
Когда нужен structured output
LLM вызывает следующий сервис или workflow.
Результат записывается в базу или очередь.
Нужно извлекать сущности, классификацию или параметры действия.
Ответ должен проходить машинную валидацию без regex-парсинга.
Формат является частью публичного или внутреннего API-контракта.
Схема как контракт
Опишите минимальную JSON Schema: required fields, типы, enum, ограничения массивов и вложенных объектов. Не просите модель возвращать поля «на всякий случай»: чем шире схема, тем больше поверхность для неоднозначности и последующих миграций.
Strict mode и обычный JSON mode
JSON mode обычно гарантирует синтаксически корректный JSON, но не соответствие вашей бизнес-схеме. Strict structured output должен проверять структуру относительно заданного schema contract. Даже при strict mode доменные ограничения — например существование user_id или допустимость статуса — остаются обязанностью приложения.
Validation pipeline
Сначала проверяйте JSON parse.
Затем валидируйте JSON Schema.
После схемы выполняйте доменные проверки и authorization.
Нормализуйте только явно разрешённые значения.
Не выполняйте side effect, пока весь pipeline не прошёл успешно.
Retries и repair
Если провайдер не гарантирует strict schema adherence, ограничьте число repair/retry попыток. В retry передавайте конкретную validation error, но не превращайте цикл в бесконечный self-correction. Для критичных действий лучше остановить workflow и запросить безопасный fallback.
Optional поля и null
Различайте поле отсутствует и поле равно null.
Не делайте все поля optional ради удобства модели.
Для union-типов задавайте небольшой закрытый набор вариантов.
Используйте enum для статусов и action types.
Храните schema version рядом с результатом.
Structured output и tool calling
Tool calling отвечает на вопрос «какой инструмент вызвать и с какими аргументами», а structured output — «в каком формате вернуть данные». Они могут использовать одну и ту же JSON Schema идею, но lifecycle разный: tool arguments приводят к действию, поэтому требуют дополнительных permission, idempotency и approval checks.
Schema versioning
Изменение required поля или enum может сломать downstream consumer. Версионируйте схемы так же, как API: добавляйте совместимые поля постепенно, измеряйте долю старых версий и только затем удаляйте deprecated контракт.
Observability
schema_validation_failure_rate
repair_attempts_per_request
fallback_rate
unknown_enum_rate
latency и token cost до/после retries
доля ответов каждой schema version
Безопасность
Schema validation не является authorization. Даже идеально валидный JSON может содержать опасное действие. Проверяйте права, лимиты, resource ownership и бизнес-инварианты отдельно от структуры ответа. Недоверенный пользовательский текст не должен менять schema или policy слоя приложения.
Короткий production checklist
Схема минимальна и versioned.
Есть JSON Schema validation и доменная validation.
Retries ограничены.
Side effects выполняются только после authorization.
Метрики validation/fallback собираются.
Есть тестовые cases для missing fields, enum, null, oversized arrays и malformed output.