Как получить JSON от Claude API и проверить его по схеме

Короткий ответ: опишите контракт данных схемой, запросите структурированный результат поддерживаемым способом и всё равно валидируйте ответ в приложении. JSON полезен только тогда, когда код отличает корректный объект от отказа модели, незавершённой генерации и сетевой ошибки.

Когда этот подход подходит

Материал рассчитан на серверную интеграцию с Claude API. Перед внедрением проверьте, что нужная функция и модель доступны вашему аккаунту. Интерфейс Console и лимиты могут меняться, поэтому названия полей сверяйте с официальной документацией на дату разработки.

Пошаговая настройка

1. Сначала определите минимальную схему: обязательные поля, допустимые типы, перечисления и запрет неожиданных свойств там, где это важно.
2. Передайте схему через актуальный механизм Structured Outputs из документации Anthropic. Не заменяйте схему просьбой «ответь только JSON» — текстовая инструкция слабее машинного контракта.
3. После ответа проверьте stop_reason и тип содержимого, затем разберите JSON.
4. Прогоните объект через валидатор вашей платформы, например JSON Schema-валидатор. Ошибочный объект отправьте в журнал без персональных данных и обработайте как контролируемый сбой.

Ограничения и применимость

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

Как проверить результат

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

Чего не делать

• Не извлекайте JSON регулярным выражением из произвольного текста.
• Не делайте все поля обязательными без бизнес-причины.
• Не записывайте результат в базу до серверной валидации.

Практический вывод

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

Официальная документация: https://docs.anthropic.com/en/docs/build-with-claude/structured-outputs