Структурированные ответы: как задать контракт данных
Когда результат модели читает программа, ей нужны определённые поля: категория тикета, срок из договора, аргументы команды. Структурированный ответ (structured output) ограничивает форму результата заданной схемой. Такой контракт данных (data contract) позволяет автоматически разобрать данные и обнаружить часть ошибок до следующего действия.
Схема не подтверждает факты и не выдаёт разрешений. Модель может вернуть существующую категорию, которая не подходит тикету, или правильно оформленный идентификатор чужого проекта. Между генерацией и действием остаётся проверка приложения или человека.
Выберите контракт для ответа или инструмента
Заголовок раздела «Выберите контракт для ответа или инструмента»У большой языковой модели (large language model, LLM) есть два разных места для ограничений. Итоговый ответ можно привести к нужной структуре для отчёта или обработки. При вызове инструмента (tool calling) схему задают для аргументов действия: например, какой тикет прочитать и какие поля вернуть.
Просьба в промпте «верни только JSON» описывает желаемый формат. Строгий режим генерации использует технические ограничения провайдера. В документации Claude отдельно описаны JSON outputs для ответа и strict tool use для вызовов инструментов. Поддержка зависит от модели и способа подключения; проверьте её в своём харнесе (agent harness), программе, которая организует работу модели и инструментов.
Протокол подключения инструментов MCP (Model Context Protocol) задаёт другой слой контракта: inputSchema описывает вход сервера, outputSchema может описывать его ответ, а structuredContent передаёт структурированные данные. Эти поля сами по себе не включают строгую генерацию у модели. Требования к проверке входа и результата описаны в спецификации инструментов MCP.
Опишите поля и отсутствие данных
Заголовок раздела «Опишите поля и отсутствие данных»Схема JSON (JSON Schema) описывает типы, обязательность и допустимые значения полей. Перечисление поля в properties не делает его обязательным: это задаёт required. Запрет дополнительных полей задаётся через additionalProperties: false. Отсутствующее поле отличается от поля со значением null, то есть явно указанным отсутствием значения. Эти правила разобраны в справочнике JSON Schema.
Ниже учебный контракт для извлечения срока из документа. Все четыре поля обязательны; допустимость их сочетаний проверяет приложение.
| Поле | Допустимое значение | Что проверить после генерации |
|---|---|---|
status |
found, not_found или conflict |
Найден один срок, срок отсутствует или источники противоречат друг другу |
date |
Строка вида YYYY-MM-DD либо null |
Дата существует в календаре; при отсутствии однозначного срока передано null |
source |
Идентификатор документа и пункт либо null |
Источник доступен читателю и содержит указанный пункт |
quote |
Цитата либо null |
Цитата присутствует в указанной версии документа и подтверждает срок |
Для found нужны дата и подтверждающий фрагмент. При not_found дата отсутствует, но статус означает, что обработка документа завершена. При conflict приложение направляет случай человеку. Обрыв запроса не должен превращаться в not_found: это разные исходы.
Провайдеры поддерживают подмножества схемы. Не переносите сложную схему между моделями без проверки; ограничения, которые не обеспечивает генерация, оставьте в проверке приложения. Документация Gemini отдельно предупреждает: корректный JSON не гарантирует смысловой корректности значений.
Проверьте форму, факты и полномочия
Заголовок раздела «Проверьте форму, факты и полномочия»Обработчик ответа проходит несколько проверок до выполнения действия:
- Убедитесь, что запрос успешно завершён, ответ полон и его можно разобрать.
- Проверьте схему: типы, обязательные поля, лишние поля и допустимые значения.
- Сверьте смысл: цитату с документом, сумму с исходными числами, идентификатор с нужным проектом. Проверьте зависимости между полями.
- Проверьте права текущего пользователя и допустимость действия. Получите подтверждение там, где оно требуется правилами процесса.
Например, значение project_id может пройти проверку типа и существовать в базе. Обработчик всё равно должен установить, что пользователь имеет доступ к этому проекту. Для чтения и записи могут требоваться разные права. Схема не заменяет границы доступа.
Возвращайте модели понятные ошибки проверки без секретов и лишних данных. Разделяйте «дата не существует» и «нет права изменить запись»: во втором случае исправление формата не поможет.
Обработайте отказ, обрыв и повтор отдельно
Заголовок раздела «Обработайте отказ, обрыв и повтор отдельно»Отказ модели и достижение лимита генерации требуют отдельных веток обработки. Например, Claude документирует состояния refusal и max_tokens, при которых результат может не соответствовать заданной схеме. Проверяйте статус завершения до чтения бизнес-полей, даже если библиотека умеет автоматически разбирать ответ. Эти исключения перечислены в описании структурированных ответов.
Для исправимой ошибки задайте предел повторов и общий срок обработки. При повторе передайте конкретную причину: «поле date не соответствует календарной дате». Недоступный источник, отказ доступа и противоречие документов требуют своего решения; повтор той же генерации не устраняет причину.
Потерянный ответ инструмента ещё не означает, что действие не выполнено. Перед повторной записью проверьте состояние операции или используйте идемпотентность (idempotency): повтор одного запроса не создаёт дополнительный внешний эффект. Для создания тикета это может быть сохранённый идентификатор операции, который обработчик использует для поиска уже созданной записи. Подробности восстановления разобраны в главе «Фоновые агенты».
Проверяйте контракт на отрицательных примерах
Заголовок раздела «Проверяйте контракт на отрицательных примерах»Включите в эвал (eval), проверку на задаче с известными критериями, случаи с отсутствующим сроком, противоречием источников и выдуманной цитатой. Добавьте ответ с правильным типом, но неверным значением, лишнее поле, отказ, обрыв и повтор после потери ответа инструмента.
Оценивайте отдельно соответствие схеме, точность извлечённых значений и соблюдение разрешений. Иначе высокая доля разбираемых ответов скроет выдуманные факты. После изменения схемы повторите проверки её потребителей: отчёта, обработчика, хранилища и старых сохранённых результатов.
Что дальше
Заголовок раздела «Что дальше»- Инструменты и их вызов: как проверенный запрос становится действием.
- Эвалы на задачах команды: как измерять точность и устойчивость контракта.
- Безопасность и приватность: где проверять доступ и подтверждения.