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

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

API пакетов сообщений — это наша первая реализация этого шаблона.

​

API пакетов сообщений

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

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

​

Как работает API пакетов сообщений

Когда вы отправляете запрос в API пакетов сообщений:

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

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

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

​

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

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

​

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

API пакетов сообщений в настоящее время поддерживает:

• 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)

​

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

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

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

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

​

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

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

​

Как использовать API пакетов сообщений

​

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

Пакет сообщений состоит из списка запросов на создание сообщения. Форма отдельного запроса включает:

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

Вы можете создать пакет, передав этот список в параметр 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 и содержит стандартные параметры, которые вы бы использовали для вызова API Messages.

Когда пакет только что создан, ответ будет иметь статус обработки 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 пакета сообщений указывает на стадию обработки пакета. Оно начинается как in_progress, затем обновляется до ended, когда все запросы в пакете завершили обработку и результаты готовы. Вы можете отслеживать состояние вашего пакета, посетив Консоль или используя конечную точку получения:

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 типа результатов:

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

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

#!/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-объект, представляющий результат одного запроса в пакете сообщений. Для каждого потокового результата вы можете выполнить различные действия в зависимости от его custom_id и типа результата. Вот пример набора результатов:

{"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 будет установлен в нашу стандартную форму ошибки.

​

Использование кэширования запросов с пакетами сообщений

API пакетов сообщений поддерживает кэширование запросов, позволяя потенциально снизить затраты и время обработки пакетных запросов. Скидки на ценообразование от кэширования запросов и пакетов сообщений могут складываться, обеспечивая еще большую экономию затрат при совместном использовании обеих функций. Однако, поскольку пакетные запросы обрабатываются асинхронно и параллельно, попадания в кэш предоставляются по принципу “лучших усилий”. Пользователи обычно испытывают частоту попаданий в кэш от 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, чтобы увеличить вероятность попаданий в кэш.

​

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

Чтобы получить максимальную отдачу от API пакетов:

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

​

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

При возникновении неожиданного поведения:

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

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

​

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

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

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

​

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