- Вам нужно обработать большие объемы данных
- Немедленные ответы не требуются
- Вы хотите оптимизировать затраты
- Вы проводите крупномасштабные оценки или анализы
API Message Batches
API Message Batches — это мощный, экономически эффективный способ асинхронной обработки больших объемов запросов Messages. Этот подход хорошо подходит для задач, которые не требуют немедленных ответов, при этом большинство пакетов завершается менее чем за 1 час, снижая затраты на 50% и увеличивая пропускную способность. Вы можете изучить справочник API напрямую, в дополнение к этому руководству.Как работает API Message Batches
Когда вы отправляете запрос в API Message Batches:- Система создает новый Message Batch с предоставленными запросами Messages.
- Пакет затем обрабатывается асинхронно, при этом каждый запрос обрабатывается независимо.
- Вы можете опрашивать статус пакета и получать результаты, когда обработка завершена для всех запросов.
- Крупномасштабные оценки: Эффективная обработка тысяч тестовых случаев.
- Модерация контента: Асинхронный анализ больших объемов пользовательского контента.
- Анализ данных: Генерация инсайтов или резюме для больших наборов данных.
- Массовая генерация контента: Создание больших объемов текста для различных целей (например, описания товаров, резюме статей).
Ограничения пакетов
- Message Batch ограничен либо 100,000 запросов Message, либо 256 МБ по размеру, в зависимости от того, что достигается первым.
- Мы обрабатываем каждый пакет как можно быстрее, при этом большинство пакетов завершается в течение 1 часа. Вы сможете получить доступ к результатам пакета, когда все сообщения будут завершены или через 24 часа, в зависимости от того, что наступит раньше. Пакеты истекут, если обработка не завершится в течение 24 часов.
- Результаты пакетов доступны в течение 29 дней после создания. После этого вы все еще можете просматривать пакет, но его результаты больше не будут доступны для загрузки.
- Пакеты привязаны к Рабочему пространству. Вы можете просматривать все пакеты — и их результаты — которые были созданы в рабочем пространстве, к которому принадлежит ваш API ключ.
- Ограничения скорости применяются как к HTTP-запросам Batches API, так и к количеству запросов в пакете, ожидающих обработки. См. Ограничения скорости API Message Batches. Кроме того, мы можем замедлить обработку в зависимости от текущего спроса и объема ваших запросов. В этом случае вы можете увидеть больше запросов, истекающих через 24 часа.
- Из-за высокой пропускной способности и параллельной обработки пакеты могут немного превысить настроенный лимит расходов вашего рабочего пространства.
Поддерживаемые модели
Все активные модели поддерживают API Message Batches.Что можно обрабатывать пакетами
Любой запрос, который вы можете сделать к Messages API, может быть включен в пакет. Это включает:- Зрение
- Использование инструментов
- Системные сообщения
- Многоходовые разговоры
- Любые бета-функции
Поскольку пакеты могут обрабатываться дольше 5 минут, рассмотрите использование 1-часовой продолжительности кэша с кэшированием промптов для лучших показателей попадания в кэш при обработке пакетов с общим контекстом.
Ценообразование
Batches API предлагает значительную экономию затрат. Все использование тарифицируется по 50% от стандартных цен API.| Model | Batch input | Batch output |
|---|---|---|
| Claude Opus 4.1 | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 3.7 (deprecated) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
| Claude Opus 3 (deprecated) | $7.50 / MTok | $37.50 / MTok |
| Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
Как использовать API Message Batches
Подготовка и создание вашего пакета
Message Batch состоит из списка запросов для создания Message. Форма отдельного запроса включает:- Уникальный
custom_idдля идентификации запроса Messages - Объект
paramsсо стандартными параметрами Messages API
requests:
custom_id и содержит стандартные параметры, которые вы бы использовали для вызова Messages API.
Протестируйте ваши пакетные запросы с Messages APIВалидация объекта
params для каждого запроса сообщения выполняется асинхронно, и ошибки валидации возвращаются, когда обработка всего пакета завершена. Вы можете убедиться, что правильно строите ваш ввод, проверив форму запроса с Messages API сначала.in_progress.
JSON
Отслеживание вашего пакета
Полеprocessing_status Message Batch указывает на стадию обработки, на которой находится пакет. Оно начинается как in_progress, затем обновляется до ended, когда все запросы в пакете завершили обработку, и результаты готовы. Вы можете отслеживать состояние вашего пакета, посетив Консоль, или используя конечную точку получения:
Получение результатов пакета
После завершения обработки пакета каждый запрос Messages в пакете будет иметь результат. Существует 4 типа результатов:| Тип результата | Описание |
|---|---|
succeeded | Запрос был успешным. Включает результат сообщения. |
errored | Запрос столкнулся с ошибкой, и сообщение не было создано. Возможные ошибки включают недействительные запросы и внутренние ошибки сервера. Вы не будете оплачивать эти запросы. |
canceled | Пользователь отменил пакет до того, как этот запрос мог быть отправлен модели. Вы не будете оплачивать эти запросы. |
expired | Пакет достиг своего 24-часового истечения до того, как этот запрос мог быть отправлен модели. Вы не будете оплачивать эти запросы. |
request_counts пакета, который показывает, сколько запросов достигло каждого из этих четырех состояний.
Результаты пакета доступны для загрузки по свойству results_url на Message Batch, и если разрешения организации позволяют, в Консоли. Из-за потенциально большого размера результатов рекомендуется стримить результаты обратно, а не загружать их все сразу.
.jsonl, где каждая строка является действительным JSON-объектом, представляющим результат одного запроса в Message Batch. Для каждого стримингового результата вы можете делать что-то разное в зависимости от его custom_id и типа результата. Вот пример набора результатов:
.jsonl file
result.error будет установлен в нашу стандартную форму ошибки.
Результаты пакета могут не соответствовать порядку вводаРезультаты пакета могут возвращаться в любом порядке и могут не соответствовать порядку запросов при создании пакета. В приведенном выше примере результат для второго пакетного запроса возвращается перед первым. Чтобы правильно сопоставить результаты с соответствующими запросами, всегда используйте поле
custom_id.Использование кэширования промптов с Message Batches
API Message Batches поддерживает кэширование промптов, позволяя потенциально снизить затраты и время обработки для пакетных запросов. Скидки на ценообразование от кэширования промптов и Message Batches могут складываться, обеспечивая еще большую экономию затрат при совместном использовании обеих функций. Однако, поскольку пакетные запросы обрабатываются асинхронно и параллельно, попадания в кэш предоставляются по принципу наилучших усилий. Пользователи обычно испытывают показатели попадания в кэш от 30% до 98%, в зависимости от их паттернов трафика. Чтобы максимизировать вероятность попаданий в кэш в ваших пакетных запросах:- Включите идентичные блоки
cache_controlв каждый запрос Message в вашем пакете - Поддерживайте постоянный поток запросов, чтобы предотвратить истечение записей кэша после их 5-минутного времени жизни
- Структурируйте ваши запросы так, чтобы разделить как можно больше кэшированного контента
cache_control для увеличения вероятности попаданий в кэш.
Лучшие практики для эффективной пакетной обработки
Чтобы получить максимум от Batches API:- Регулярно отслеживайте статус обработки пакета и реализуйте соответствующую логику повторных попыток для неудачных запросов.
- Используйте значимые значения
custom_idдля легкого сопоставления результатов с запросами, поскольку порядок не гарантируется. - Рассмотрите разбиение очень больших наборов данных на несколько пакетов для лучшей управляемости.
- Выполните пробный запуск одной формы запроса с Messages API, чтобы избежать ошибок валидации.
Устранение неполадок распространенных проблем
Если вы испытываете неожиданное поведение:- Убедитесь, что общий размер пакетного запроса не превышает 256 МБ. Если размер запроса слишком большой, вы можете получить ошибку 413
request_too_large. - Проверьте, что вы используете поддерживаемые модели для всех запросов в пакете.
- Убедитесь, что каждый запрос в пакете имеет уникальный
custom_id. - Убедитесь, что прошло менее 29 дней с момента
created_atпакета (неended_atобработки). Если прошло более 29 дней, результаты больше не будут доступны для просмотра. - Подтвердите, что пакет не был отменен.
Хранение пакетов и конфиденциальность
- Изоляция рабочего пространства: Пакеты изолированы в рамках рабочего пространства, в котором они созданы. К ним могут получить доступ только API ключи, связанные с этим рабочим пространством, или пользователи с разрешением на просмотр пакетов рабочего пространства в Консоли.
- Доступность результатов: Результаты пакетов доступны в течение 29 дней после создания пакета, предоставляя достаточно времени для получения и обработки.
FAQ
Сколько времени требуется для обработки пакета?
Сколько времени требуется для обработки пакета?
Пакеты могут занимать до 24 часов для обработки, но многие завершатся раньше. Фактическое время обработки зависит от размера пакета, текущего спроса и объема ваших запросов. Возможно, что пакет истечет и не завершится в течение 24 часов.
Доступен ли Batches API для всех моделей?
Доступен ли Batches API для всех моделей?
См. выше список поддерживаемых моделей.
Могу ли я использовать API Message Batches с другими функциями API?
Могу ли я использовать API Message Batches с другими функциями API?
Да, API Message Batches поддерживает все функции, доступные в Messages API, включая бета-функции. Однако стриминг не поддерживается для пакетных запросов.
Как API Message Batches влияет на ценообразование?
Как API Message Batches влияет на ценообразование?
API Message Batches предлагает скидку 50% на все использование по сравнению со стандартными ценами API. Это применяется к входным токенам, выходным токенам и любым специальным токенам. Для получения дополнительной информации о ценообразовании посетите нашу страницу ценообразования.
Могу ли я обновить пакет после его отправки?
Могу ли я обновить пакет после его отправки?
Нет, после отправки пакета его нельзя изменить. Если вам нужно внести изменения, вы должны отменить текущий пакет и отправить новый. Обратите внимание, что отмена может не вступить в силу немедленно.
Есть ли ограничения скорости API Message Batches и взаимодействуют ли они с ограничениями скорости Messages API?
Есть ли ограничения скорости API Message Batches и взаимодействуют ли они с ограничениями скорости Messages API?
API Message Batches имеет ограничения скорости на основе HTTP-запросов в дополнение к ограничениям на количество запросов, нуждающихся в обработке. См. Ограничения скорости API Message Batches. Использование Batches API не влияет на ограничения скорости в Messages API.
Как обрабатывать ошибки в моих пакетных запросах?
Как обрабатывать ошибки в моих пакетных запросах?
Когда вы получаете результаты, каждый запрос будет иметь поле
result, указывающее, был ли он succeeded, errored, canceled или expired. Для результатов errored будет предоставлена дополнительная информация об ошибке. Просмотрите объект ответа об ошибке в справочнике API.Как API Message Batches обрабатывает конфиденциальность и разделение данных?
Как API Message Batches обрабатывает конфиденциальность и разделение данных?
API Message Batches разработан с сильными мерами конфиденциальности и разделения данных:
- Пакеты и их результаты изолированы в рамках рабочего пространства, в котором они были созданы. Это означает, что к ним могут получить доступ только API ключи из того же рабочего пространства.
- Каждый запрос в пакете обрабатывается независимо, без утечки данных между запросами.
- Результаты доступны только в течение ограниченного времени (29 дней) и следуют нашей политике хранения данных.
- Загрузка результатов пакетов в Консоли может быть отключена на уровне организации или на основе рабочего пространства.
Могу ли я использовать кэширование промптов в API Message Batches?
Могу ли я использовать кэширование промптов в API Message Batches?
Да, возможно использовать кэширование промптов с API Message Batches. Однако, поскольку асинхронные пакетные запросы могут обрабатываться параллельно и в любом порядке, попадания в кэш предоставляются по принципу наилучших усилий.