К содержимому
Блог

Структурированный JSON-ответ через tool use и проверку схемы

Структурированный JSON-ответ через tool use и проверку схемы

Структурированный JSON-ответ нужен, когда результат LLM читает программа, а не человек. Формулировка «верни только JSON» полезна для черновика, но не заменяет контракт. Надёжнее описать ожидаемый объект как инструмент, потребовать его вызов и проверить полученные данные у себя.

Коротко

  • Синтаксически корректный JSON ещё не означает, что объект годится для бизнес-операции.

  • Один принудительно выбранный инструмент задаёт модели форму ответа через input_schema.

  • После ответа проверяют типы, диапазоны, права и связи между полями.

  • Повтор возможен только с ограничением попыток и понятной причиной отказа.

Какие две проверки нужны JSON-ответу?

Первая проверка относится к форме: объект разбирается, нужные поля существуют, типы совпадают, лишние свойства не пролезли. Вторая относится к смыслу: дата допустима, сумма совпадает с позициями, категория доступна пользователю, а действие не нарушает состояние заказа. Модель не знает ваши текущие данные, если вы их ей не передали, поэтому вторую проверку нельзя переносить в промпт.

Частая ошибка состоит в том, что после JSON.parse объект сразу записывают в базу. Парсер подтверждает лишь грамматику. Ему всё равно, существует ли клиент, можно ли менять статус и не противоречит ли одно поле другому.

Как получить объект через tool use?

В Messages API Relay передаёт tools модели без собственного преобразования. Карточка показывает возможность tools, но не подтверждает протокол для конкретного ключа. Перед запросом получите персональный каталог через GET /api/models?allowed_for_key=...: у выбранной модели в usable_protocols должен быть anthropic_messages. Затем передайте один инструмент с JSON Schema. Когда нужен именно объект, настройка выбора инструмента должна требовать конкретное имя, а не оставлять модели возможность ответить обычным текстом. Формат запроса описан в документации Messages.

json
{
  "name": "record_ticket",
  "description": "Вернуть классификацию обращения пользователя по схеме.",
  "input_schema": {
    "type": "object",
    "properties": {
      "topic": {
        "type": "string",
        "enum": ["billing", "bug", "access", "other"]
      },
      "summary": {
        "type": "string",
        "maxLength": 280
      },
      "needs_operator": {
        "type": "boolean"
      }
    },
    "required": ["topic", "summary", "needs_operator"],
    "additionalProperties": false
  }
}

Такой контракт заметно уже свободного ответа. Но он не обещает бизнес-истину. После успешной проверки схемы поле topic ограничено перечислением, а решение о маршрутизации обращения всё равно принимает сервер после проверки контекста и прав.

Почему схему не стоит делать слишком большой?

Большая вложенная схема превращает извлечение в длинный экзамен. Уберите поля, которые можно вычислить сами, и разделите действия. Сначала извлеките данные документа. Потом отдельным шагом сопоставьте их с текущей записью. Это снижает количество противоречий и делает ошибку понятнее.

Полезны перечисления, ограничения длины и явные обязательные поля. Меньше пользы от красивых описаний вроде «корректная дата». Лучше задать формат и проверить его программно. Нулевое значение, неизвестная категория и отсутствие данных должны быть отдельными состояниями схемы, а не маскироваться строкой «не найдено».

Что делать после ответа модели?

Сначала извлеките блок вызова инструмента по его идентификатору. Затем прогоните объект через валидатор выбранного языка. Далее выполните бизнес-проверки, которые требуют вашей базы, прав или расчёта. Только успешный объект передаётся следующему шагу.

text
вызов модели → проверка JSON Schema → проверка правил приложения → действие

Если проверка правил не прошла, не пишите объект в хранилище. Сохраните безопасную причину, например «итог не равен сумме строк», и при необходимости дайте модели один шанс исправить объект. Модель должна видеть конкретное правило, но не чужие персональные данные и не внутренние сообщения базы.

Как ограничить повторную попытку?

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

Не повторяйте при отказе в доступе, недоступном сервисе или неизменяемом состоянии объекта. Эти причины не становятся верными от другого текста модели. Повтор в такой ситуации лишь создаёт новые запросы и запутывает журнал.

В системах с критичными действиями полезно разделить извлечение и подтверждение. Модель может подготовить объект «изменить адрес», но клиент показывает его человеку, а сервер подтверждает операцию только после явного действия пользователя. Принципы безопасного исполнения собраны в статье о защите вызовов инструментов.

Чем этот подход отличается от проверки JSON?

Проверка JSON отвечает на вопрос «можно ли доверить этот объект следующему коду?». Tool use отвечает на более ранний вопрос «как попросить модель вернуть объект определённой формы?». В рабочем контуре нужны оба шага. Подробности про валидацию, схемы и невалидные ответы есть в материале о проверке JSON-ответа LLM.

Если ваш клиент использует Chat Completions, он получит вызов в поле tool_calls, а не блок tool_use. Контракт схемы и серверная проверка от этого не меняются. Подходящие варианты протокола и модели смотрите в разделе о протоколах.

Как измерять качество результата?

Соберите набор реальных входов с ожидаемыми объектами. Отдельно посчитайте долю объектов, прошедших проверку формы, и долю объектов, прошедших бизнес-правила. Если вторая метрика хуже первой, проблема не в JSON. Часто ей оказываются неполная инструкция, неясные категории или данные, которых не было во входе.

Храните причины отказов отдельными кодами. Тогда через неделю видно не абстрактное «модель ошибается», а конкретный перекос: поле слишком свободное, пользовательский текст двусмыслен или проверка запрещает допустимый случай.

Как менять схему без тихой поломки?

Схема ответа тоже контракт. Добавление обязательного поля, переименование перечисления или смена значения null может сломать потребителя, который давно работает в фоне. Версионируйте контракт на границе приложения и оставляйте миграционный период, если результат читают несколько сервисов.

Полезно разделять объект, который вернула модель, и внутреннюю модель домена. Первый бывает неполным и требует проверки. Вторая содержит нормализованные значения, идентификаторы из вашей базы и вычисляемые поля. Такой разрыв не даёт модели подменить серверный источник истины красивой строкой.

Для каждого изменения схемы добавляйте входы из старого набора тестов. Если новая категория похожа на старую, проверьте оба варианта. Проверка формы должна сказать, какое поле не прошло. Сообщение «некорректный объект» не поможет ни модели при разрешённом повторе, ни разработчику при разборе.

Где заканчивается роль модели?

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

Схема уменьшает число технических сюрпризов, но не даёт полномочий. Если объект запускает действие, добавьте явное подтверждение пользователя и журнал решения. В асинхронной очереди сохраняйте проверенный объект, версию схемы и результат бизнес-валидации вместо одного исходного текста модели.

Как сделать ошибку понятной для следующего шага?

Проверка полезна тогда, когда её результат можно разобрать. Вместо сообщения «объект неверный» верните код причины и имя поля, если это не раскрывает чувствительные данные. Например, unknown_category, date_out_of_range или total_mismatch позволяют выбрать следующий ход: уточнить вопрос, предложить безопасный вариант или передать задачу человеку.

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

Временная проблема внешнего сервиса тоже не превращается в ошибку JSON. Она требует отдельного статуса, времени следующей попытки и ограничения повторов. Если эти случаи слиты в один текстовый отказ, очередь начинает переотправлять неподходящие задачи, а оператор не понимает, что именно произошло.

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

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

Гарантирует ли tool use правильность данных?

Нет. Он помогает получить объект в ожидаемой форме, но не проверяет смысл полей по правилам вашего продукта. Сервер всё равно валидирует права, диапазоны, связи между полями и текущее состояние записи. Эти проверки выполняются после ответа модели.

Нужно ли хранить текстовую версию JSON?

Обычно нет. Храните нормализованный объект, идентификатор запроса и результат проверки. Исходный пользовательский текст сохраняйте только если это допускают правила обработки данных и он действительно нужен для разбора ошибки. Секреты и лишние персональные данные в журнал не копируют.

Когда достаточно обычной просьбы вернуть JSON?

Для одноразового внутреннего эксперимента, где человек смотрит результат перед использованием. Как только JSON попадает в автоматический процесс, введите схему и серверную проверку. Стоимость ошибки в таком процессе почти всегда выше нескольких строк валидатора.

Создать аккаунт

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.