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

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

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

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

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

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

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

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

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

Что можно включать в пакет

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

• Зрение (vision)
• Использование инструментов (tool use), включая все серверные инструменты (веб-поиск, веб-загрузка, выполнение кода, коннекторы MCP, advisor и поиск инструментов)
• Системные сообщения
• Многоходовые диалоги
• Расширенное мышление (extended thinking)
• Большинство бета-функций

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

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

Цены

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-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5",
                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 или используя эндпоинт получения.

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

client = anthropic.Anthropic()

# Автоматически загружает дополнительные страницы по мере необходимости.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

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

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

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

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

client = anthropic.Anthropic()

# Потоковая передача файла результатов экономными по памяти частями, обработка по одной за раз
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":
                # Тело запроса необходимо исправить перед повторной отправкой
                print(f"Validation error {result.custom_id}")
            else:
                # Запрос можно повторить напрямую
                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-5","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-5","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

Message Batches API поддерживает «prompt caching» (кэширование подсказок), что позволяет потенциально снизить затраты и время обработки пакетных запросов. Скидки от кэширования подсказок и Message Batches могут суммироваться, обеспечивая ещё большую экономию при совместном использовании обеих функций. Однако, поскольку пакетные запросы обрабатываются асинхронно и параллельно, попадания в кэш обеспечиваются по принципу «best effort». Пользователи обычно наблюдают частоту попаданий в кэш от 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-5",
                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-5",
                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, чтобы повысить вероятность попаданий в кэш.

Серверные инструменты и агентный цикл

Все серверные инструменты (веб-поиск, веб-загрузка, выполнение кода, коннекторы MCP, advisor и поиск инструментов) работают в пакетных запросах. Обработчик пакетов выполняет тот же серверный агентный цикл, что и синхронный Messages API.

Поскольку нет открытого соединения, которое нужно поддерживать, пакетный цикл выполняет больше итераций за ход, чем синхронный запрос, прежде чем вернуть stop_reason: "pause_turn". Если результат пакета возвращается с pause_turn, ход не завершился; вы можете продолжить его, отправив приостановленное содержимое ассистента в последующем запросе (пакетном или синхронном) точно так, как показано в паттерне продолжения pause_turn.

Обработчик пакетов дополнительно ограничивает web_search для каждой организации, чтобы высокопараллельная пакетная обработка не исчерпала ограничение скорости веб-поиска вашей организации. Пакет автоматически повторяет ограниченные запросы; вам не нужно обрабатывать это самостоятельно, но очень большие пакеты с веб-поиском могут выполняться дольше.

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

Бета-заголовок output-300k-2026-03-24 повышает предел max_tokens до 300 000 для пакетных запросов, использующих Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 или Claude Sonnet 4.6. Включите этот заголовок, чтобы генерировать выводы значительно длиннее стандартного лимита max_tokens в 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-5",
                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)

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

Чтобы получить максимум от Batches API:

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

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

При неожиданном поведении:

• Убедитесь, что общий размер пакетного запроса не превышает 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 и хранение данных.

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

Следующие шаги