Пакетная обработка — это мощный подход для эффективной обработки больших объемов запросов. Вместо обработки запросов по одному с немедленными ответами, пакетная обработка позволяет отправлять несколько запросов вместе для асинхронной обработки. Этот паттерн особенно полезен, когда:
  • Вам нужно обработать большие объемы данных
  • Немедленные ответы не требуются
  • Вы хотите оптимизировать затраты
  • Вы проводите крупномасштабные оценки или анализы
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 дней после создания. После этого вы все еще можете просматривать пакет, но его результаты больше не будут доступны для загрузки.
  • Пакеты привязаны к Workspace. Вы можете просматривать все пакеты — и их результаты — которые были созданы в рамках Workspace, к которому принадлежит ваш API-ключ.
  • Ограничения скорости применяются как к HTTP-запросам Batches API, так и к количеству запросов в пакете, ожидающих обработки. См. Ограничения скорости API Message Batches. Кроме того, мы можем замедлить обработку в зависимости от текущего спроса и объема ваших запросов. В этом случае вы можете увидеть больше запросов, истекающих через 24 часа.
  • Из-за высокой пропускной способности и параллельной обработки пакеты могут немного превысить настроенный лимит расходов вашего Workspace.

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

API Message Batches в настоящее время поддерживает:
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (claude-3-5-sonnet-20240620 и claude-3-5-sonnet-20241022)
  • Claude Haiku 3.5 (claude-3-5-haiku-20241022)
  • Claude Haiku 3 (claude-3-haiku-20240307)
  • Claude Opus 3 (claude-3-opus-20240229)

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

Любой запрос, который вы можете сделать к Messages API, может быть включен в пакет. Это включает:
  • Зрение
  • Использование инструментов
  • Системные сообщения
  • Многоходовые разговоры
  • Любые бета-функции
Поскольку каждый запрос в пакете обрабатывается независимо, вы можете смешивать различные типы запросов в одном пакете.
Поскольку пакеты могут обрабатываться дольше 5 минут, рассмотрите использование 1-часовой длительности кэша с кэшированием промптов для лучших показателей попаданий в кэш при обработке пакетов с общим контекстом.

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

Batches API предлагает значительную экономию затрат. Все использование тарифицируется по 50% от стандартных цен API.
ModelBatch inputBatch output
Claude Opus 4.1$7.50 / MTok$37.50 / MTok
Claude Opus 4$7.50 / MTok$37.50 / MTok
Claude Sonnet 4$1.50 / MTok$7.50 / MTok
Claude Sonnet 3.7$1.50 / MTok$7.50 / MTok
Claude Sonnet 3.5 (deprecated)$1.50 / MTok$7.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: 
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-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'
В этом примере два отдельных запроса объединены в пакет для асинхронной обработки. Каждый запрос имеет уникальный custom_id и содержит стандартные параметры, которые вы бы использовали для вызова Messages API.
Протестируйте ваши пакетные запросы с Messages APIВалидация объекта params для каждого запроса сообщения выполняется асинхронно, и ошибки валидации возвращаются, когда обработка всего пакета завершена. Вы можете убедиться, что правильно строите ваш ввод, проверив форму вашего запроса с Messages API сначала.
Когда пакет впервые создается, ответ будет иметь статус обработки 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, или используя конечную точку получения: 
curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
 --header "x-api-key: $ANTHROPIC_API_KEY" \
 --header "anthropic-version: 2023-06-01" \
 | sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 processing status is \2/'
Вы можете опрашивать эту конечную точку, чтобы знать, когда обработка завершена.

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

После завершения обработки пакета каждый запрос Messages в пакете будет иметь результат. Существует 4 типа результатов:
Тип результатаОписание
succeededЗапрос был успешным. Включает результат сообщения.
erroredЗапрос столкнулся с ошибкой, и сообщение не было создано. Возможные ошибки включают недействительные запросы и внутренние ошибки сервера. Вы не будете оплачивать эти запросы.
canceledПользователь отменил пакет до того, как этот запрос мог быть отправлен модели. Вы не будете оплачивать эти запросы.
expiredПакет достиг своего 24-часового истечения до того, как этот запрос мог быть отправлен модели. Вы не будете оплачивать эти запросы.
Вы увидите обзор ваших результатов с request_counts пакета, который показывает, сколько запросов достигло каждого из этих четырех состояний. Результаты пакета доступны для загрузки по свойству results_url на Message Batch, и если разрешения организации позволяют, в Console. Из-за потенциально большого размера результатов рекомендуется стримить результаты обратно, а не загружать их все сразу. 
#!/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
Результаты будут в формате .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-20250514","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-20250514","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 Batches

API Message Batches поддерживает кэширование промптов, позволяя потенциально снизить затраты и время обработки для пакетных запросов. Скидки на ценообразование от кэширования промптов и Message Batches могут складываться, обеспечивая еще большую экономию затрат при совместном использовании обеих функций. Однако, поскольку пакетные запросы обрабатываются асинхронно и параллельно, попадания в кэш предоставляются на основе наилучших усилий. Пользователи обычно испытывают показатели попаданий в кэш от 30% до 98%, в зависимости от их паттернов трафика. Чтобы максимизировать вероятность попаданий в кэш в ваших пакетных запросах:
  1. Включите идентичные блоки cache_control в каждый запрос Message в вашем пакете
  2. Поддерживайте постоянный поток запросов, чтобы предотвратить истечение записей кэша после их 5-минутного времени жизни
  3. Структурируйте ваши запросы так, чтобы делиться как можно большим количеством кэшированного контента
Пример реализации кэширования промптов в пакете: 
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-20250514",
                "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-20250514",
                "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."}
                ]
            }
        }
    ]
}'
В этом примере оба запроса в пакете включают идентичные системные сообщения и полный текст “Гордости и предубеждения”, помеченный cache_control для увеличения вероятности попаданий в кэш.

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

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

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

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

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

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

​
FAQ