Перейти к содержимому

Структурированные ответы: как задать контракт данных

Когда результат модели читает программа, ей нужны определённые поля: категория тикета, срок из договора, аргументы команды. Структурированный ответ (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 не гарантирует смысловой корректности значений.

Обработчик ответа проходит несколько проверок до выполнения действия:

  1. Убедитесь, что запрос успешно завершён, ответ полон и его можно разобрать.
  2. Проверьте схему: типы, обязательные поля, лишние поля и допустимые значения.
  3. Сверьте смысл: цитату с документом, сумму с исходными числами, идентификатор с нужным проектом. Проверьте зависимости между полями.
  4. Проверьте права текущего пользователя и допустимость действия. Получите подтверждение там, где оно требуется правилами процесса.

Например, значение project_id может пройти проверку типа и существовать в базе. Обработчик всё равно должен установить, что пользователь имеет доступ к этому проекту. Для чтения и записи могут требоваться разные права. Схема не заменяет границы доступа.

Возвращайте модели понятные ошибки проверки без секретов и лишних данных. Разделяйте «дата не существует» и «нет права изменить запись»: во втором случае исправление формата не поможет.

Обработайте отказ, обрыв и повтор отдельно

Заголовок раздела «Обработайте отказ, обрыв и повтор отдельно»

Отказ модели и достижение лимита генерации требуют отдельных веток обработки. Например, Claude документирует состояния refusal и max_tokens, при которых результат может не соответствовать заданной схеме. Проверяйте статус завершения до чтения бизнес-полей, даже если библиотека умеет автоматически разбирать ответ. Эти исключения перечислены в описании структурированных ответов.

Для исправимой ошибки задайте предел повторов и общий срок обработки. При повторе передайте конкретную причину: «поле date не соответствует календарной дате». Недоступный источник, отказ доступа и противоречие документов требуют своего решения; повтор той же генерации не устраняет причину.

Потерянный ответ инструмента ещё не означает, что действие не выполнено. Перед повторной записью проверьте состояние операции или используйте идемпотентность (idempotency): повтор одного запроса не создаёт дополнительный внешний эффект. Для создания тикета это может быть сохранённый идентификатор операции, который обработчик использует для поиска уже созданной записи. Подробности восстановления разобраны в главе «Фоновые агенты».

Проверяйте контракт на отрицательных примерах

Заголовок раздела «Проверяйте контракт на отрицательных примерах»

Включите в эвал (eval), проверку на задаче с известными критериями, случаи с отсутствующим сроком, противоречием источников и выдуманной цитатой. Добавьте ответ с правильным типом, но неверным значением, лишнее поле, отказ, обрыв и повтор после потери ответа инструмента.

Оценивайте отдельно соответствие схеме, точность извлечённых значений и соблюдение разрешений. Иначе высокая доля разбираемых ответов скроет выдуманные факты. После изменения схемы повторите проверки её потребителей: отчёта, обработчика, хранилища и старых сохранённых результатов.

Автор учебника: Шахматов Алексей