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

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

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

Message Batches API

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

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

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

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

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

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

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

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

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

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

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

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

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

• Vision
• Tool use
• System messages
• Multi-turn conversations
• Любые бета-функции

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

Цены

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

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

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

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

• Уникального custom_id для идентификации запроса Messages. Должен быть от 1 до 64 символов и содержать только буквенно-цифровые символы, дефисы и подчеркивания (соответствующие ^[a-zA-Z0-9_-]{1,64}$).
• Объекта params со стандартными параметрами Messages API

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

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

В этом примере два отдельных запроса пакетируются вместе для асинхронной обработки. Каждый запрос имеет уникальный 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, или используя endpoint получения.

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

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

import time

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

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)

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

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

client = anthropic.Anthropic()

# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

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

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

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

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

client = anthropic.Anthropic()

# Stream results file in memory-efficient chunks, processing one at a time
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    match result.result.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if result.result.error.error.type == "invalid_request_error":
                # Request body must be fixed before re-sending request
                print(f"Validation error {result.custom_id}")
            else:
                # Request can be retried directly
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

Результаты находятся в формате .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-7","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-7","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 Batch

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

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

Ответ покажет пакет в состоянии canceling:

{
  "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%, в зависимости от их моделей трафика.

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

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

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

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                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.",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                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.",
                    }
                ],
            ),
        ),
    ]
)

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

Расширенный вывод (бета)

Заголовок бета-версии output-300k-2026-03-24 повышает лимит max_tokens до 300 000 для пакетных запросов, использующих Claude Opus 4.7, Claude Opus 4.6 или Claude Sonnet 4.6. Включите заголовок для создания выходных данных намного длиннее стандартного лимита (64k до 128k в зависимости от модели) за один ход.

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

Одна генерация с 300k токенами может занять более часа, поэтому планируйте отправку пакетов с учетом 24-часового окна обработки. Применяется стандартное ценообразование пакетов (50% от стандартных цен API).

from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas=["output-300k-2026-03-24"],
    requests=[
        Request(
            custom_id="long-form-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=300_000,
                messages=[
                    {
                        "role": "user",
                        "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
                    }
                ],
            ),
        ),
    ],
)

print(message_batch)

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

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

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

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

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

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

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

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

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

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

Хранение данных

Обработка пакетов хранит данные запроса и ответа в течение до 29 дней после создания пакета. Вы можете удалить пакет сообщений в любое время после обработки, используя конечную точку DELETE /v1/messages/batches/{batch_id}. Чтобы удалить пакет, находящийся в процессе обработки, сначала отмените его. Асинхронная обработка требует хранения на стороне сервера как входных, так и выходных данных до завершения пакета и получения результатов.

Для соответствия требованиям ZDR для всех функций см. API и хранение данных.

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