РУКОВОДСТВО · ОБНОВЛЕНО 2026-09-15
Structured Output и JSON Schema в API нейросетей
Структурированный ответ упрощает передачу результата в программу, если схема узкая, валидатор обязателен, а смысл полей проверяется отдельно.
Передайте поддерживаемую JSON Schema, запретите лишние поля и валидируйте ответ на сервере. Structured Output повышает соблюдение формы, но не гарантирует правильность значений: суммы, даты, ссылки и решения нужно проверять предметными правилами.
1. Сделайте схему минимальной
Опишите только поля, которые реально использует следующий шаг. Укажите required, типы, enum и запрет дополнительных свойств, если маршрут это поддерживает. Не просите модель одновременно писать эссе и сложный объект. Понятные названия и описания полей снижают неоднозначность, а плоская структура обычно устойчивее глубоко вложенной.
2. Различайте режимы формата
Просьба «верни JSON» может дать синтаксически корректный объект произвольной формы. JSON mode обычно гарантирует допустимый JSON, а structured output связывает ответ со схемой в пределах поддерживаемого подмножества. Конкретные модели и endpoints отличаются, поэтому приложение проверяет возможность маршрута и не отправляет неизвестные ключевые слова схемы.
3. Валидируйте на границе сервера
Никогда не передавайте модельный объект сразу в базу или платёжный сервис. Сначала JSON parse, schema validation, ограничения длины и предметные проверки. Дата должна существовать, сумма попадать в диапазон, идентификатор — принадлежать пользователю. HTML и команды внутри строк остаются недоверенными данными даже при идеальной структуре.
4. Обработайте штатные исключения
Ответ может завершиться по лимиту, политике безопасности, timeout или сетевой ошибке. Отличайте refusal от сломанного JSON и не повторяйте каждый сбой бесконечно. Если обязательных данных нет во входе, правильный результат — явное null или статус needs_input, предусмотренный схемой. Логи содержат версию schema и model id.
5. Проверьте эволюцию контракта
Добавление required-поля способно сломать старого потребителя. Версионируйте схему, храните набор контрактных примеров и тестируйте старые случаи после смены модели. Метрики включают schema pass, предметную точность, retries, latency и цену принятого объекта. Ручная выборка нужна даже при стопроцентной синтаксической валидности.
Частые вопросы
Чем structured output отличается от JSON mode?
Первый стремится соблюдать заданную схему, второй может гарантировать только корректный JSON.
Можно доверять числам в валидном объекте?
Нет, форма не подтверждает источник и смысл значения.
Нужен ли серверный валидатор?
Да, модельный ответ всегда проверяется на границе приложения.
Что делать с отсутствующим значением?
Предусмотреть null или отдельный статус вместо выдуманного поля.
Все JSON Schema поддерживаются?
Обычно доступно подмножество, описанное конкретным провайдером и моделью.