Claude Platform Docs
СообщенияВозможности модели

Пакетная обработка

Асинхронно обрабатывайте большие объёмы запросов Messages с помощью Message Batches API, сокращая затраты на 50 процентов и увеличивая пропускную способность.

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

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

Message Batches API реализует этот шаблон.

Message Batches API

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

Помимо этого руководства, вы можете изучить справочник API напрямуюДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ПараметрПричина
stream: trueРезультаты пакета возвращаются одним файлом, а не потоком.
speed (Быстрый режим)Быстрый режим настраивает задержку синхронных запросов, что неприменимо к асинхронной пакетной обработке.
fallbacks (Серверный резервный вариант)Серверный резервный вариант не применяется к пакетам. Чтобы повторить отклонённые запросы, см. Отказы в Message Batches.
max_tokens: 0См. Ограничения пакетов.

Цены

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

МодельТокены при пакетной обработке
НазваниеВводВывод
Claude Fable 5.2For demanding reasoning and long-horizon agentic work
4 $ /
20 $ / MTok
Claude Opus 5.5For long-running agentic coding and knowledge work
2 $ / MTok
10 $ / MTok
Claude Sonnet 5.5The best combination of speed and intelligence
1 $ / MTok
5 $ / MTok
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing
0,05 $ / MTokдля промптов с числом токенов до 100 000
0,25 $ / MTok
0,25 $ / MTokдля промптов с числом токенов более 100 000
1,25 $ / MTok
4 $ / MTok
20 $ / MTok
5 $ / MTok
25 $ / MTok
5 $ / MTok
25 $ / MTok
5 $ / MTok
25 $ / MTok
5 $ / MTok
25 $ / MTok
2,50 $ / MTok
12,50 $ / MTok
2,50 $ / MTok
12,50 $ / MTok
2,50 $ / MTok
12,50 $ / MTok
2,50 $ / MTok
12,50 $ / MTok
2,50 $ / MTok
12,50 $ / MTok
Claude Opus 4.1
7,50 $ / MTok
37,50 $ / MTok
Claude Opus 4
7,50 $ / MTok
37,50 $ / MTok
1 $ / MTok
5 $ / MTok
1,50 $ / MTok
7,50 $ / MTok
1,50 $ / MTok
7,50 $ / MTok
Claude Sonnet 4
1,50 $ / MTok
7,50 $ / MTok
0,50 $ / MTok
2,50 $ / MTok

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

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

Пакет сообщений состоит из списка запросов на создание Message. Отдельный запрос включает:

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

Вы можете создать пакетДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape., передав этот список в параметр 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-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

В этом примере два отдельных запроса объединены в пакет для асинхронной обработки. Каждый запрос имеет уникальный custom_id и содержит стандартные параметры, которые вы использовали бы для вызова Messages API.

При первом создании пакета ответ имеет статус обработки in_progress.

Output
{
  "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Доступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. в пакете сообщений указывает, на каком этапе обработки находится пакет. Изначально оно имеет значение in_progress, затем обновляется до ended, когда все запросы в пакете завершили обработку и результаты готовы. Вы можете отслеживать состояние пакета в Console или с помощью эндпоинта получения.

Опрос завершения пакета сообщений

Чтобы опрашивать пакет сообщений, вам понадобится его 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)

Получение списка всех пакетов сообщений

Вы можете получить список всех пакетов сообщений в вашем рабочем пространстве с помощью эндпоинта спискаДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.. Результаты разбиваются на страницы. SDK загружает дополнительные страницы по мере необходимости:

client = anthropic.Anthropic()

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

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

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

Тип результатаОписание
succeededЗапрос выполнен успешно. Включает результат сообщения.
erroredПри выполнении запроса произошла ошибка, и сообщение не было создано. Возможные ошибки включают недопустимые запросы и внутренние ошибки сервера. Плата за такие запросы не взимается.
canceledПользователь отменил пакет до того, как этот запрос был отправлен модели. Плата за такие запросы не взимается.
expiredСрок действия пакета (24 часа) истёк до того, как этот запрос был отправлен модели. Плата за такие запросы не взимается.

Объект request_counts пакета подсчитывает запросы, которые всё ещё обрабатываются, и запросы с каждым типом результата.

Результаты пакета доступны для загрузки по свойству results_urlДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. в пакете сообщений, а также, если это разрешено правами вашей организации, в Console. Поскольку результаты могут быть большими, получайте результаты потокомДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape., а не загружайте их все сразу.

client = anthropic.Anthropic()

# Потоковое чтение файла результатов экономными по памяти частями, по одной за раз
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    outcome = result.result
    match outcome.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if outcome.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, представляющий результат одного запроса в пакете сообщений. Для каждого полученного потоком результата вы можете выполнять разные действия в зависимости от его custom_id и типа результата. Вот пример набора результатов:

.jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-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-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 будет иметь стандартную структуру ошибки.

Результаты пакета используют версию API запроса, который создал пакет.

Отмена пакета сообщений

Вы можете отменить пакет сообщений, который находится в процессе обработки, с помощью эндпоинта отменыДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.. Сразу после отмены 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:

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

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

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

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

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

Расширенный вывод доступен только в Message Batches API, но не в синхронном Messages API.

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

Одна генерация объёмом 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-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.
  • Убедитесь, что с момента created_at пакета (а не с момента окончания обработки ended_at) прошло менее 29 дней. По истечении 29 дней результаты больше не доступны для загрузки.
  • Убедитесь, что пакет не был отменён.

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

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

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

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

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

Доступность

Пакетная обработка
Требования к доступности Пакетная обработка одинаковы на всех поддерживаемых платформах.
API
  • Messages API
  • Managed Agents Не поддерживается
Модели
  • Все модели

Обработка данных

Обзор обработки данных

Применимые конечные точки

  • /v1/messages/batches
Нулевое хранение данныхНе допускается

Хранение 29 дней; требуется асинхронное хранилище. Подробнее

HIPAAНе допускается

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

Дальнейшие шаги

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

Снижайте затраты и задержку, кэшируя префиксы подсказок, общие для запросов в пакете.

Эта страница была полезной?