Structured Output
structured output — ответ модели по заданной схеме
Structured Output задаёт форму ответа модели: поля, типы и допустимые значения. Это помогает получать данные для программы, но не проверяет их смысл. Разберём ошибки, отказы и проверку результата.
Коротко
Structured Output задаёт формат ответа, который программа может проверить по схеме. Вместо свободного текста модель должна вернуть структуру, совместимую с поддерживаемой схемой. Это полезно для извлечения данных, классификации и передачи результата в код, но поле правильного типа всё ещё может содержать неверное значение.
Зачем нужна схема
Допустим, приложение извлекает данные из резюме. Оно ждёт такой объект:
{
"name": "Анна Смирнова",
"skills": ["Python", "SQL"],
"experience_years": 4,
"needs_review": false
}
В свободном режиме модель может переименовать skills в competencies, записать стаж строкой или добавить пояснение перед JSON. Схема заранее ограничивает набор допустимых форм.
Что может описывать схема
В зависимости от API поддерживаются:
- объекты и массивы;
- строки, числа, логические значения true/false и null;
- обязательные поля;
- enum — список допустимых значений;
- вложенные структуры;
- ограничения на дополнительные ключи;
- описания полей.
Провайдеры обычно поддерживают не весь JSON Schema, а определённое подмножество. Поддержка рекурсии, проверок формата и комбинаций условий различается. Схему проверяют при запуске и держат версионированной рядом с кодом.
Как ограничивается генерация
Один из способов — ограниченное декодирование (constrained decoding): на каждом шаге разрешаются только токены, которые ещё могут привести к структуре по схеме. Так модель не сможет закрыть массив не той скобкой или поставить строку там, где допустим только boolean.
Так ограничивается форма ответа, но не проверяется его достоверность. Если поле date описано просто как строка, в нём может оказаться несуществующая дата. Название поля само по себе не проверяет календарь; даже корректная дата может не совпасть с исходным документом. Если enum содержит approved, наличие этого значения не означает, что операция действительно одобрена.
Что проверяет приложение
входные данные
↓
запрос со схемой
↓
проверка статуса ответа
↓
парсинг и локальная валидация
↓
бизнес-правила и права доступа
↓
действие или ручная проверка
Локальная валидация всё равно полезна. Она защищает от несовместимости SDK, ошибок интеграции и изменений между версиями схемы.
Пример схемы
{
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": ["billing", "delivery", "other"]
},
"summary": {"type": "string"},
"needs_human": {"type": "boolean"}
},
"required": ["category", "summary", "needs_human"],
"additionalProperties": false
}
Такая схема стабилизирует ключи и типы. Она не проверяет, верно ли определена категория и не пропущена ли важная деталь обращения.
Structured Output и JSON Mode
JSON Mode ограничивает ответ синтаксисом JSON. Он подходит, когда структура гибкая или приложение само её проверяет.
Structured Output добавляет контракт полей и типов. Он удобнее, когда данные передаются между компонентами и формат известен заранее.
Оба режима требуют обработки:
- отказа модели;
- превышения лимита;
- сетевого сбоя;
- недоступной модели;
- семантически неверного значения;
- изменения версии контракта.
Structured Output и Function Calling
Схема ответа описывает данные, которые нужно вернуть пользователю или приложению. Function Calling описывает запрос модели к инструменту.
В обоих случаях аргументы могут быть структурированы, но полномочия различаются. Объект {"action":"delete"} не должен удалять данные только потому, что соответствует схеме. Приложение проверяет список разрешённых действий, права пользователя, область действия и необходимость подтверждения.
Когда режим особенно полезен
- извлечение полей из документов;
- классификация обращений;
- маршрутизация задач;
- построение карточек и таблиц;
- генерация параметров для внутреннего этапа;
- ответы API, которые читает другой сервис;
- многошаговый агент с узким набором состояний.
Для художественного текста строгая схема может только мешать. Там часто достаточно обычного ответа или лёгкого контейнера с несколькими полями.
Как проектировать хорошую схему
Понятные поля
score непонятен без шкалы. confidence_0_to_1 точнее, но уверенность модели всё равно не является измеренной вероятностью. Иногда лучше needs_review с понятным правилом.
Возможность оставить значение неизвестным
Если данных может не быть, это стоит выразить через null, отдельный статус или поле missing_information. Иначе схема будет требовать значение даже при отсутствии сведений, и модель может заполнить поле догадкой.
Данные отдельно от команд
Поле с извлечённым адресом и команда отправить посылку — разные уровни. Сначала данные проверяются, затем отдельный компонент решает, можно ли выполнять действие.
Версии схемы
Добавление обязательного поля может сломать старого клиента. Версия схемы, миграция и обратная совместимость нужны так же, как в обычном API.
Проверка на сложных примерах
Пустой документ, противоречивые сведения, несколько кандидатов, вредоносная инструкция внутри текста и обрыв ответа показывают, как приложение справляется с трудными случаями. На одном идеальном примере эти проблемы не видны.
Что схема не гарантирует
- фактическую точность;
- полноту извлечения;
- отсутствие смещения;
- безопасность содержимого строки;
- право пользователя на действие;
- одинаковое поведение после смены модели;
- совместимость с любой конструкцией JSON Schema.
Схема делает интеграцию надёжнее, но не превращает вероятностную модель в детерминированную базу данных. Когда результат должен запустить действие, нужны отдельные проверки — они разобраны в статье о вызове инструментов.
Например, помощник может вернуть параметры сцены для графа ComfyUI. До запуска приложение проверяет допустимые размеры, имена моделей и доступные узлы: корректная строка в JSON ещё не означает существующий checkpoint или разрешённый путь файла.
Частые ошибки
- Считать тип доказательством смысла. Целочисленное поле может содержать неверное число.
- Не предусмотреть
unknown. Модель вынуждена выбрать один из неподходящих вариантов. - Делать схему слишком сложной. Её труднее поддерживать и не каждый API её принимает.
- Сразу выполнять структурированную команду. Нужна авторизация и проверка области действия.
- Игнорировать статус завершения. Отказ и обрыв — нормальные ветки протокола.
- Менять схему без версии. Старые клиенты перестают понимать ответ.
Частые вопросы
Нужен ли разбор JSON, если схема уже применена? Да. SDK может вернуть готовый объект, но граница приложения всё равно должна проверять ожидаемую версию и обрабатывать ошибку.
Можно ли использовать Pydantic, Zod или типы языка? Да, если SDK умеет преобразовать их в поддерживаемую схему. Полезно посмотреть итоговый JSON Schema, потому что не все возможности библиотеки переносятся в API.
Что делать с очень динамической структурой?
Использовать более общий объект, пару key/value, JSON Mode или несколько простых схем по разным веткам. Огромный универсальный контракт часто хуже набора маленьких.
Схема устраняет выдуманные сведения? Нет. При успешном завершении строгий режим удерживает ответ в поддерживаемой форме, но выдуманное значение легко помещается в корректное поле. Отказ и обрыв обрабатываются отдельно.
Главное
Structured Output превращает желаемый формат в проверяемую схему и заметно упрощает интеграцию. Его сила — в полях и типах, а не в истинности. Надёжное приложение дополнительно проверяет завершение, локальную схему, бизнес-правила, права доступа и содержание значений.