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

• Вам нужно обработать большие объемы данных
• Немедленные ответы не требуются
• Вы хотите оптимизировать затраты
• Вы проводите крупномасштабные оценки или анализы

API Message Batches — это наша первая реализация этого паттерна.

API Message Batches

API Message Batches — это мощный, экономически эффективный способ асинхронной обработки больших объемов запросов Messages. Этот подход хорошо подходит для задач, которые не требуют немедленных ответов, при этом большинство пакетов завершается менее чем за 1 час, снижая затраты на 50% и увеличивая пропускную способность.

Вы можете изучить справочник API напрямую, в дополнение к этому руководству.

Как работает API Message Batches

Когда вы отправляете запрос в API Message Batches:

1. Система создает новый Message Batch с предоставленными запросами Messages.
2. Пакет затем обрабатывается асинхронно, при этом каждый запрос обрабатывается независимо.
3. Вы можете опрашивать статус пакета и получать результаты, когда обработка завершена для всех запросов.

Это особенно полезно для массовых операций, которые не требуют немедленных результатов, таких как:

• Крупномасштабные оценки: Эффективная обработка тысяч тестовых случаев.
• Модерация контента: Асинхронный анализ больших объемов пользовательского контента.
• Анализ данных: Генерация инсайтов или резюме для больших наборов данных.
• Массовая генерация контента: Создание больших объемов текста для различных целей (например, описания товаров, резюме статей).

Ограничения пакетов

• Message Batch ограничен либо 100,000 запросов Message, либо 256 МБ по размеру, в зависимости от того, что достигается первым.
• Мы обрабатываем каждый пакет как можно быстрее, при этом большинство пакетов завершается в течение 1 часа. Вы сможете получить доступ к результатам пакета, когда все сообщения будут завершены или через 24 часа, в зависимости от того, что наступит раньше. Пакеты истекут, если обработка не завершится в течение 24 часов.
• Результаты пакетов доступны в течение 29 дней после создания. После этого вы все еще можете просматривать пакет, но его результаты больше не будут доступны для загрузки.
• Пакеты привязаны к Рабочему пространству. Вы можете просматривать все пакеты — и их результаты — которые были созданы в рабочем пространстве, к которому принадлежит ваш API ключ.
• Ограничения скорости применяются как к HTTP-запросам Batches API, так и к количеству запросов в пакете, ожидающих обработки. См. Ограничения скорости API Message Batches. Кроме того, мы можем замедлить обработку в зависимости от текущего спроса и объема ваших запросов. В этом случае вы можете увидеть больше запросов, истекающих через 24 часа.
• Из-за высокой пропускной способности и параллельной обработки пакеты могут немного превысить настроенный лимит расходов вашего рабочего пространства.

Поддерживаемые модели

Все активные модели поддерживают API Message Batches.

Что можно обрабатывать пакетами

Любой запрос, который вы можете сделать к Messages API, может быть включен в пакет. Это включает:

• Зрение
• Использование инструментов
• Системные сообщения
• Многоходовые разговоры
• Любые бета-функции

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

Ценообразование

Batches API предлагает значительную экономию затрат. Все использование тарифицируется по 50% от стандартных цен API.

Как использовать API Message Batches

Подготовка и создание вашего пакета

Message Batch состоит из списка запросов для создания Message. Форма отдельного запроса включает:

• Уникальный custom_id для идентификации запроса Messages
• Объект params со стандартными параметрами Messages API

Вы можете создать пакет, передав этот список в параметр requests:

В этом примере два отдельных запроса объединены в пакет для асинхронной обработки. Каждый запрос имеет уникальный custom_id и содержит стандартные параметры, которые вы бы использовали для вызова Messages API.

Когда пакет впервые создается, ответ будет иметь статус обработки in_progress.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

Отслеживание вашего пакета

Поле processing_status Message Batch указывает на стадию обработки, на которой находится пакет. Оно начинается как in_progress, затем обновляется до ended, когда все запросы в пакете завершили обработку, и результаты готовы. Вы можете отслеживать состояние вашего пакета, посетив Консоль, или используя конечную точку получения:

Вы можете опрашивать эту конечную точку, чтобы знать, когда обработка завершена.

Получение результатов пакета

После завершения обработки пакета каждый запрос Messages в пакете будет иметь результат. Существует 4 типа результатов:

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

Результаты пакета доступны для загрузки по свойству results_url на Message Batch, и если разрешения организации позволяют, в Консоли. Из-за потенциально большого размера результатов рекомендуется стримить результаты обратно, а не загружать их все сразу.

Результаты будут в формате .jsonl, где каждая строка является действительным JSON-объектом, представляющим результат одного запроса в Message Batch. Для каждого стримингового результата вы можете делать что-то разное в зависимости от его custom_id и типа результата. Вот пример набора результатов:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Если ваш результат имеет ошибку, его result.error будет установлен в нашу стандартную форму ошибки.

Использование кэширования промптов с Message Batches

API Message Batches поддерживает кэширование промптов, позволяя потенциально снизить затраты и время обработки для пакетных запросов. Скидки на ценообразование от кэширования промптов и Message Batches могут складываться, обеспечивая еще большую экономию затрат при совместном использовании обеих функций. Однако, поскольку пакетные запросы обрабатываются асинхронно и параллельно, попадания в кэш предоставляются по принципу наилучших усилий. Пользователи обычно испытывают показатели попадания в кэш от 30% до 98%, в зависимости от их паттернов трафика.

Чтобы максимизировать вероятность попаданий в кэш в ваших пакетных запросах:

1. Включите идентичные блоки cache_control в каждый запрос Message в вашем пакете
2. Поддерживайте постоянный поток запросов, чтобы предотвратить истечение записей кэша после их 5-минутного времени жизни
3. Структурируйте ваши запросы так, чтобы разделить как можно больше кэшированного контента

Пример реализации кэширования промптов в пакете:

В этом примере оба запроса в пакете включают идентичные системные сообщения и полный текст "Гордости и предубеждения", помеченный cache_control для увеличения вероятности попаданий в кэш.

Лучшие практики для эффективной пакетной обработки

Чтобы получить максимум от Batches API:

• Регулярно отслеживайте статус обработки пакета и реализуйте соответствующую логику повторных попыток для неудачных запросов.
• Используйте значимые значения custom_id для легкого сопоставления результатов с запросами, поскольку порядок не гарантируется.
• Рассмотрите разбиение очень больших наборов данных на несколько пакетов для лучшей управляемости.
• Выполните пробный запуск одной формы запроса с Messages API, чтобы избежать ошибок валидации.

Устранение неполадок распространенных проблем

Если вы испытываете неожиданное поведение:

• Убедитесь, что общий размер пакетного запроса не превышает 256 МБ. Если размер запроса слишком большой, вы можете получить ошибку 413 request_too_large.
• Проверьте, что вы используете поддерживаемые модели для всех запросов в пакете.
• Убедитесь, что каждый запрос в пакете имеет уникальный custom_id.
• Убедитесь, что прошло менее 29 дней с момента created_at пакета (не ended_at обработки). Если прошло более 29 дней, результаты больше не будут доступны для просмотра.
• Подтвердите, что пакет не был отменен.

Обратите внимание, что сбой одного запроса в пакете не влияет на обработку других запросов.

Хранение пакетов и конфиденциальность

• Изоляция рабочего пространства: Пакеты изолированы в рамках рабочего пространства, в котором они созданы. К ним могут получить доступ только API ключи, связанные с этим рабочим пространством, или пользователи с разрешением на просмотр пакетов рабочего пространства в Консоли.

• Доступность результатов: Результаты пакетов доступны в течение 29 дней после создания пакета, предоставляя достаточно времени для получения и обработки.

FAQ