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

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

• Выходные данные JSON (output_config.format): Получайте ответ Claude в определённом формате JSON
• Строгое использование инструментов (strict: true): Гарантируйте проверку схемы для имён инструментов и входных данных

Вы можете использовать эти функции независимо или вместе в одном запросе.

Почему использовать структурированные выходные данные

Без структурированных выходных данных Claude может генерировать неправильно сформированные ответы JSON или недействительные входные данные инструментов, которые нарушают работу ваших приложений. Даже при тщательном написании подсказок вы можете столкнуться с:

• Ошибками анализа из-за неправильного синтаксиса JSON
• Отсутствующими обязательными полями
• Несогласованными типами данных
• Нарушениями схемы, требующими обработки ошибок и повторных попыток

Структурированные выходные данные гарантируют ответы, соответствующие схеме, через ограниченное декодирование:

• Всегда корректно: Больше нет ошибок JSON.parse()
• Безопасно по типам: Гарантированные типы полей и обязательные поля
• Надёжно: Повторные попытки не требуются для нарушений схемы

Выходные данные JSON

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

• Управлять форматом ответа Claude
• Извлекать данные из изображений или текста
• Генерировать структурированные отчёты
• Форматировать ответы API

Быстрый старт

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.",
        }
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },
)
print(response.content[0].text)

Формат ответа: Корректный JSON, соответствующий вашей схеме в response.content[0].text

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}

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

Работа с JSON выводом в SDK

SDK предоставляют вспомогательные функции, которые упрощают работу с JSON выводом, включая преобразование схемы, автоматическую валидацию и интеграцию с популярными библиотеками схем.

Использование встроенных определений схем

Вместо написания сырых JSON схем вы можете использовать знакомые инструменты определения схем на вашем языке:

• Python: модели Pydantic с client.messages.parse()
• TypeScript: схемы Zod с zodOutputFormat() или типизированные литералы JSON Schema с jsonSchemaOutputFormat()
• Java: простые классы Java с автоматическим выведением схемы через outputConfig(Class<T>)
• Ruby: классы Anthropic::BaseModel с output_config: {format: Model}
• PHP: классы, реализующие StructuredOutputModel с outputConfig: ['format' => MyClass::class]
• CLI, C#, Go: сырые JSON схемы, передаваемые через output_config

from pydantic import BaseModel
from anthropic import Anthropic


class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.",
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

Методы, специфичные для SDK

Каждый SDK предоставляет вспомогательные функции, которые упрощают работу со структурированными выводами. Полные детали см. на отдельных страницах SDK.

Как работает преобразование SDK

Python, TypeScript, Ruby и PHP SDK автоматически преобразуют схемы с неподдерживаемыми функциями:

1. Удалить неподдерживаемые ограничения (например, minimum, maximum, minLength, maxLength)
2. Обновить описания с информацией об ограничениях (например, "Должно быть не менее 100"), когда ограничение не поддерживается напрямую со структурированными выводами
3. Добавить additionalProperties: false ко всем объектам
4. Отфильтровать форматы строк только поддерживаемый список
5. Валидировать ответы против вашей исходной схемы (со всеми ограничениями)

Это означает, что Claude получает упрощенную схему, но ваш код по-прежнему применяет все ограничения через валидацию.

Пример: поле Pydantic с minimum: 100 становится простым целым числом в отправленной схеме, но SDK обновляет описание на "Должно быть не менее 100" и валидирует ответ против исходного ограничения.

Распространённые варианты использования

Строгое использование инструментов

Для обеспечения соответствия JSON Schema при использовании инструментов с грамматикой с ограничениями выборки см. Строгое использование инструментов.

Использование обеих функций вместе

JSON-выходы и строгое использование инструментов решают разные проблемы и работают вместе:

• JSON-выходы контролируют формат ответа Claude (что говорит Claude)
• Строгое использование инструментов проверяет параметры инструментов (как Claude вызывает ваши функции)

При совместном использовании Claude может вызывать инструменты с гарантированно корректными параметрами И возвращать структурированные JSON-ответы. Это полезно для агентских рабочих процессов, где вам нужны как надежные вызовы инструментов, так и структурированные финальные выходы.

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # JSON outputs: structured response format
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # Strict tool use: guaranteed tool parameters
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)

Важные соображения

Компиляция грамматики и кеширование

Структурированные выходы используют ограниченную выборку с скомпилированными артефактами грамматики. Это вводит некоторые характеристики производительности, о которых следует знать:

• Задержка первого запроса: При первом использовании определенной схемы возникает дополнительная задержка во время компиляции грамматики
• Автоматическое кеширование: Скомпилированные грамматики кешируются в течение 24 часов с момента последнего использования, что делает последующие запросы намного быстрее
• Инвалидация кеша: Кеш инвалидируется, если вы измените:
  • Структуру JSON-схемы
  • Набор инструментов в вашем запросе (при использовании как структурированных выходов, так и использования инструментов)
  • Изменение только полей name или description не инвалидирует кеш

Модификация подсказки и стоимость токенов

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

• Количество входных токенов немного выше
• Внедренная подсказка стоит вам токены, как и любая другая системная подсказка
• Изменение параметра output_config.format инвалидирует любой кеш подсказок для этого потока разговора

Ограничения JSON Schema

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

Порядок свойств

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

Например, учитывая эту схему:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

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

1. name (обязательное, в порядке схемы)
2. email (обязательное, в порядке схемы)
3. notes (необязательное, в порядке схемы)
4. age (необязательное, в порядке схемы)

Это означает, что выходные данные могут выглядеть так:

{
  "name": "John Smith",
  "email": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

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

Недействительные выходы

Хотя структурированные выходы гарантируют соответствие схеме в большинстве случаев, есть сценарии, когда выходные данные могут не соответствовать вашей схеме:

Отказы (stop_reason: "refusal")

Claude сохраняет свои свойства безопасности и полезности даже при использовании структурированных выходов. Если Claude отказывает в запросе по соображениям безопасности:

• Ответ имеет stop_reason: "refusal"
• Вы получите код состояния 200
• Вам будут выставлены счета за сгенерированные токены
• Выходные данные могут не соответствовать вашей схеме, потому что сообщение об отказе имеет приоритет над ограничениями схемы

Достигнут лимит токенов (stop_reason: "max_tokens")

Если ответ обрезан из-за достижения лимита max_tokens:

• Ответ имеет stop_reason: "max_tokens"
• Выходные данные могут быть неполными и не соответствовать вашей схеме
• Повторите попытку с более высоким значением max_tokens, чтобы получить полный структурированный выход

Ограничения сложности схемы

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

Явные ограничения

Следующие ограничения применяются ко всем запросам с output_config.format или strict: true:

Дополнительные внутренние ограничения

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

Когда эти ограничения превышены, вы получите ошибку 400 с сообщением "Schema is too complex for compilation." Эти ошибки означают, что объединенная сложность ваших схем превышает то, что может быть эффективно скомпилировано, даже если каждое отдельное ограничение выше удовлетворено. В качестве последней защиты API также применяет тайм-аут компиляции 180 секунд. Схемы, которые проходят все явные проверки, но создают очень большие скомпилированные грамматики, могут превысить этот тайм-аут.

Советы по снижению сложности схемы

Если вы достигли ограничений сложности, попробуйте эти стратегии по порядку:

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

2. Уменьшите необязательные параметры. Сделайте параметры required где возможно. Каждый необязательный параметр примерно удваивает часть пространства состояний грамматики. Если параметр всегда имеет разумное значение по умолчанию, рассмотрите возможность сделать его обязательным и попросить Claude явно предоставить это значение по умолчанию.

3. Упростите вложенные структуры. Глубоко вложенные объекты с необязательными полями усложняют сложность. Где возможно, сплющивайте структуры.

4. Разделите на несколько запросов. Если у вас много строгих инструментов, рассмотрите возможность разделения их на отдельные запросы или подагентов.

Для постоянных проблем с действительными схемами свяжитесь с поддержкой с определением вашей схемы.

Хранение данных

Подсказки и ответы обрабатываются с ZDR при использовании структурированных выходов. Однако сама JSON-схема временно кешируется в течение до 24 часов с момента последнего использования в целях оптимизации. Никакие данные подсказок или ответов не сохраняются после ответа API.

Структурированные выходы имеют право на HIPAA, но PHI не должна включаться в определения JSON-схемы. API компилирует JSON-схемы в грамматики, которые кешируются отдельно от содержимого сообщений, и эти кешированные схемы не получают такую же защиту PHI, как подсказки и ответы. Не включайте PHI в имена свойств схемы, значения enum, значения const или регулярные выражения pattern. PHI должна появляться только в содержимом сообщений (подсказках и ответах), где она защищена гарантиями безопасности HIPAA.

Для соответствия ZDR и HIPAA во всех функциях см. API и хранение данных.

Совместимость функций

Работает с:

• Пакетная обработка: Обрабатывайте структурированные выходы в масштабе с 50% скидкой
• Подсчет токенов: Подсчитывайте токены без компиляции
• Потоковая передача: Потоковая передача структурированных выходов как обычных ответов
• Совместное использование: Используйте JSON-выходы (output_config.format) и строгое использование инструментов (strict: true) вместе в одном запросе

Несовместимо с:

• Цитирования: Цитирования требуют чередования блоков цитирования с текстом, что конфликтует с ограничениями строгой JSON-схемы. Возвращает ошибку 400, если цитирования включены с output_config.format.
• Предзаполнение сообщений: Несовместимо с JSON-выходами