Структурированные выходные данные и парсинг

Структурированные выходные данные — это нативный механизм API, гарантирующий, что ответ Claude соответствует заданной JSON-схеме. Каноничный способ включения — параметр output_config: {"format": {"type": "json_schema", "schema": ...}} в messages.create (старый верхнеуровневый параметр output_format объявлен устаревшим во всём API). Это официальная замена старых трюков: предзаполнение реплики ассистента символом { больше не работает — на Fable 5 и всём семействе 4.6+ префиллы последнего хода ассистента возвращают HTTP 400. Помимо формата ответа, структурированные выходы включают и строгую валидацию параметров инструментов через strict: true в определении инструмента.

Как это работает

Вы описываете JSON-схему желаемого результата, и API гарантирует, что ответ модели ей соответствует. Рекомендуемый путь в SDK — хелпер client.messages.parse(), который сам валидирует ответ по схеме и возвращает типизированный объект. Для инструментов флаг strict: true в определении гарантирует, что параметры вызова всегда валидны по схеме. У схем есть ограничения: рекурсивные схемы не поддерживаются, числовые ограничения minimum/maximum недоступны, а для каждого объекта обязательно additionalProperties: false. Первый запрос с новой схемой оплачивает разовую компиляцию и отвечает медленнее, после чего схема кешируется на 24 часа — повторные запросы идут без этой надбавки.

Когда применять

Используйте структурированные выходы везде, где ответ модели читает программа, а не человек: извлечение полей из документов, классификация с фиксированным набором меток, генерация конфигураций, наполнение баз данных, интеграции с внешними системами. Комбинация со strict: true для инструментов — стандарт для продакшен-агентов: она устраняет целый класс ошибок парсинга параметров. Если вы мигрируете со старых моделей код с префиллами ассистента, структурированные выходы — прямая замена этого паттерна.

Типичные ошибки

Первая ошибка — по привычке использовать префилл ассистента для форсирования JSON: на Fable 5 и моделях 4.6+ такой запрос падает с 400. Вторая — использовать устаревший верхнеуровневый output_format вместо каноничного output_config.format. Третья — нарушать ограничения схем: рекурсия, minimum/maximum для чисел или пропущенный additionalProperties: false приведут к отказу. Четвёртая — не учитывать разовую задержку компиляции новой схемы: при бенчмарках первый запрос всегда медленнее, замеряйте на прогретом 24-часовом кеше. Наконец, ручной парсинг сырого текста вместо client.messages.parse() — это лишний код и лишние точки отказа, которые SDK уже закрывает.

Как это работает

Когда применять

Типичные ошибки

Связанные понятия

Полезные ресурсы