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

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

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

This feature is not covered by Zero Data Retention (ZDR) arrangements. Data is retained according to the feature's standard retention policy.

API Message Batches

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

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

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

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

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

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

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

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

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

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

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

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

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

Vision
Tool use
Системные сообщения
Многооборотные разговоры
Любые бета-функции

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

Поскольку пакеты могут обрабатываться дольше 5 минут, рассмотрите возможность использования кэширования на 1 час с кэшированием подсказок для лучшего коэффициента попадания в кэш при обработке пакетов с общим контекстом.

Цены

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

Model	Batch input	Batch output
Claude Opus 4.6	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.5	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.1	$7.50 / MTok	$37.50 / MTok
Claude Opus 4	$7.50 / MTok	$37.50 / MTok
Claude Sonnet 4.6	$1.50 / MTok	$7.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

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

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

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

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

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

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

Протестируйте запросы вашего пакета с помощью API Messages

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

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

JSON

{
  "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 после завершения обработки всех запросов в пакете и готовности результатов. Вы можете отслеживать состояние вашего пакета, посетив Console или используя конечную точку получения.

Опрос завершения Message Batch

Для опроса Message Batch вам потребуется его id, который предоставляется в ответе при создании пакета или путем перечисления пакетов. Вы можете реализовать цикл опроса, который периодически проверяет статус пакета до завершения обработки:

Перечисление всех Message Batches

Вы можете перечислить все Message Batches в вашем Workspace, используя конечную точку списка. API поддерживает разбиение на страницы, автоматически получая дополнительные страницы по мере необходимости:

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

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

Тип результата	Описание
`succeeded`	Запрос был успешным. Включает результат сообщения.
`errored`	Запрос столкнулся с ошибкой и сообщение не было создано. Возможные ошибки включают недействительные запросы и внутренние ошибки сервера. Вам не будет выставлен счет за эти запросы.
`canceled`	Пользователь отменил пакет до того, как этот запрос мог быть отправлен модели. Вам не будет выставлен счет за эти запросы.
`expired`	Пакет достиг своего 24-часового истечения до того, как этот запрос мог быть отправлен модели. Вам не будет выставлен счет за эти запросы.

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

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

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

.jsonl file

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-6","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-opus-4-6","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 будет установлен на нашу стандартную форму ошибки.

Результаты пакета могут не совпадать с порядком ввода

Результаты пакета могут быть возвращены в любом порядке и могут не совпадать с порядком запросов при создании пакета. В приведенном выше примере результат для второго запроса пакета возвращается перед первым. Чтобы правильно сопоставить результаты с соответствующими запросами, всегда используйте поле custom_id.

Отмена Message Batch

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

Ответ будет показывать пакет в состоянии canceling:

JSON

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "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": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

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

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

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

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

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

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

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

Чтобы максимально использовать API Batches:

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

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

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

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

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

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

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

Часто задаваемые вопросы

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

import anthropic
import time

client = anthropic.Anthropic()

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | grep -o '"results_url":[[:space:]]*"[^"]*"' \
  | cut -d'"' -f4 \
  | while read -r url; do
    curl -s "$url" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | sed 's/}{/}\n{/g' \
      | while IFS= read -r line
    do
      result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
      custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
      error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')

      case "$result_type" in
        "succeeded")
          echo "Success! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request" ]; then
            # Request body must be fixed before re-sending request
            echo "Validation error: $custom_id"
          else
            # Request can be retried directly
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Write a summary of Pride and Prejudice."}
                ]
            }
        }
    ]
}'

API Message Batches

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

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

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

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

Цены

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

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

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

Опрос завершения Message Batch

Перечисление всех Message Batches

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

Отмена Message Batch

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

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

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

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

Часто задаваемые вопросы

Сколько времени занимает обработка пакета?

Доступен ли API Batches для всех моделей?

Могу ли я использовать API Message Batches с другими функциями API?

Как API Message Batches влияет на цены?

Могу ли я обновить пакет после его отправки?

Существуют ли ограничения скорости API Message Batches и взаимодействуют ли они с ограничениями скорости API Messages?

Как я обрабатываю ошибки в своих пакетных запросах?

Как API Message Batches обрабатывает конфиденциальность и разделение данных?

Могу ли я использовать кэширование подсказок в API Message Batches?