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

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

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, может быть включен в пакет. Это включает:

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

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

​

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

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

​

Как использовать 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.

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

Вы увидите обзор ваших результатов с 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 и типа результата. Вот пример набора результатов:

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

​

Использование кэширования промптов с 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