Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Пакетная обработка — это мощный подход для эффективной обработки больших объемов запросов. Вместо обработки запросов один за другим с немедленными ответами, пакетная обработка позволяет вам отправлять несколько запросов вместе для асинхронной обработки. Этот паттерн особенно полезен, когда:
API Message Batches — это наша первая реализация этого паттерна.
API Message Batches — это мощный и экономичный способ асинхронной обработки больших объемов запросов Messages. Этот подход хорошо подходит для задач, которые не требуют немедленных ответов, при этом большинство пакетов завершаются менее чем за 1 час, снижая затраты на 50% и увеличивая пропускную способность.
Вы можете изучить справочник API напрямую, а также прочитать это руководство.
Когда вы отправляете запрос в API Message Batches:
Это особенно полезно для массовых операций, которые не требуют немедленных результатов, таких как:
Все активные модели поддерживают API Message Batches.
Любой запрос, который вы можете сделать к API Messages, может быть включен в пакет. Это включает:
Поскольку каждый запрос в пакете обрабатывается независимо, вы можете смешивать различные типы запросов в одном пакете.
Поскольку пакеты могут обрабатываться дольше 5 минут, рассмотрите возможность использования кэширования на 1 час с кэшированием подсказок для лучшей частоты попаданий в кэш при обработке пакетов с общим контекстом.
API Batches предлагает значительную экономию затрат. Все использование взимается по 50% от стандартных цен API.
| Model | Batch input | Batch output |
|---|---|---|
| Claude Opus 4.5 | $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 |
| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 3.7 (deprecated) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
| Claude Opus 3 (deprecated) | $7.50 / MTok | $37.50 / MTok |
| Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
Message Batch состоит из списка запросов на создание Message. Форма отдельного запроса состоит из:
custom_id для идентификации запроса Messagesparams со стандартными параметрами 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-sonnet-4-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-sonnet-4-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hi again, friend"}
]
}
}
]
}'В этом примере два отдельных запроса объединены в пакет для асинхронной обработки. Каждый запрос имеет уникальный custom_id и содержит стандартные параметры, которые вы использовали бы для вызова API Messages.
Протестируйте ваши запросы пакета с помощью API Messages
Валидация объекта params для каждого запроса сообщения выполняется асинхронно, и ошибки валидации возвращаются после завершения обработки всего пакета. Вы можете убедиться, что вы правильно строите свой ввод, предварительно проверив форму вашего запроса с помощью 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 Message Batch указывает на этап обработки пакета. Он начинается как in_progress, затем обновляется на ended после завершения обработки всех запросов в пакете и готовности результатов. Вы можете отслеживать состояние вашего пакета, посетив Console или используя конечную точку получения.
Для опроса Message Batch вам понадобится его id, который предоставляется в ответе при создании пакета или при перечислении пакетов. Вы можете реализовать цикл опроса, который периодически проверяет статус пакета до завершения обработки:
import anthropic
import time
client = anthropic.Anthropic()
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 в вашем Workspace, используя конечную точку списка. API поддерживает пагинацию, автоматически получая дополнительные страницы по мере необходимости:
import anthropic
client = anthropic.Anthropic()
# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(
limit=20
):
print(message_batch)После завершения обработки пакета каждый запрос Messages в пакете будет иметь результат. Существует 4 типа результатов:
| Тип результата | Описание |
|---|---|
succeeded | Запрос был успешным. Включает результат сообщения. |
errored | Запрос столкнулся с ошибкой и сообщение не было создано. Возможные ошибки включают недействительные запросы и внутренние ошибки сервера. Вам не будет выставлен счет за эти запросы. |
canceled | Пользователь отменил пакет до того, как этот запрос мог быть отправлен модели. Вам не будет выставлен счет за эти запросы. |
expired | Пакет достиг своего 24-часового истечения до того, как этот запрос мог быть отправлен модели. Вам не будет выставлен счет за эти запросы. |
Вы увидите обзор ваших результатов с помощью 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-sonnet-4-5-20250929","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-sonnet-4-5-20250929","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 будет установлен на нашу стандартную форму ошибки.
Результаты пакета могут не совпадать с порядком ввода
Результаты пакета могут быть возвращены в любом порядке и могут не совпадать с порядком запросов при создании пакета. В приведенном выше примере результат для второго запроса пакета возвращается перед первым. Чтобы правильно сопоставить результаты с соответствующими запросами, всегда используйте поле custom_id.
Вы можете отменить Message Batch, который в настоящее время обрабатывается, используя конечную точку отмены. Сразу после отмены processing_status пакета будет canceling. Вы можете использовать ту же технику опроса, описанную выше, чтобы дождаться завершения отмены. Отмененные пакеты заканчиваются со статусом ended и могут содержать частичные результаты для запросов, которые были обработаны до отмены.
import anthropic
client = anthropic.Anthropic()
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
}API Message Batches поддерживает кэширование подсказок, что позволяет потенциально снизить затраты и время обработки для пакетных запросов. Скидки на цены от кэширования подсказок и Message Batches могут складываться, обеспечивая еще большую экономию затрат при использовании обеих функций вместе. Однако, поскольку пакетные запросы обрабатываются асинхронно и параллельно, попадания в кэш предоставляются на основе наилучших усилий. Пользователи обычно испытывают коэффициент попадания в кэш в диапазоне от 30% до 98%, в зависимости от их моделей трафика.
Чтобы максимизировать вероятность попадания в кэш в ваших пакетных запросах:
cache_control в каждый запрос Message в вашем пакетеПример реализации кэширования подсказок в пакете:
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-sonnet-4-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."}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-sonnet-4-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."}
]
}
}
]
}'В этом примере оба запроса в пакете включают идентичные системные сообщения и полный текст Pride and Prejudice, отмеченный с помощью cache_control для увеличения вероятности попадания в кэш.
Чтобы максимально использовать API Batches:
custom_id для легкого сопоставления результатов с запросами, поскольку порядок не гарантирован.Если вы испытываете неожиданное поведение:
request_too_large.custom_id.created_at пакета (не времени обработки ended_at). Если прошло более 29 дней, результаты больше не будут доступны для просмотра.Обратите внимание, что отказ одного запроса в пакете не влияет на обработку других запросов.
Изоляция рабочей области: Пакеты изолированы в рабочей области, в которой они были созданы. Доступ к ним могут получить только ключи API, связанные с этой рабочей областью, или пользователи с разрешением на просмотр пакетов рабочей области в консоли.
Доступность результатов: Результаты пакета доступны в течение 29 дней после создания пакета, что позволяет достаточно времени для получения и обработки.