Батчевая обработка

Когда нужно прогнать тысячи запросов и ответ не нужен «прямо сейчас» — есть режим дешевле.

Batch API — режим массовой асинхронной обработки: вы отправляете пачку запросов, провайдер выполняет их в фоне и отдаёт результаты позже, со скидкой (часто ~50%).

Когда это нужно

• Разметить/классифицировать большой датасет.
• Сгенерировать описания для тысяч товаров.
• Прогнать оффлайн-аналитику, отчёты, эмбеддинги.

Общий признак: ответ нужен не в реальном времени. Пользователь не ждёт у экрана. Тогда задержка (минуты-часы) приемлема в обмен на скидку и щедрые лимиты.

Чем batch отличается от обычных вызовов

Как это устроено (Claude)

Создаёте пачку запросов (у каждого свой custom_id), отправляете, периодически опрашиваете статус, забираете результаты по готовности.

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

batch = client.messages.batches.create(requests=[
    Request(custom_id="item-1", params=MessageCreateParamsNonStreaming(
        model="claude-haiku-4-5", max_tokens=64,
        messages=[{"role": "user", "content": "Тон: Отличный сервис!"}],
    )),
    Request(custom_id="item-2", params=MessageCreateParamsNonStreaming(
        model="claude-haiku-4-5", max_tokens=64,
        messages=[{"role": "user", "content": "Тон: Ужасное обслуживание."}],
    )),
])
print(batch.id, batch.processing_status)

# Позже: опрашиваем и забираем результаты
for result in client.messages.batches.results(batch.id):
    print(result.custom_id, result.result.type)

Жизненный цикл пачки

Пачка проходит через состояния: создана → обрабатывается → завершена. Вы не держите соединение открытым всё это время — отправили и периодически опрашиваете статус (или ждёте вебхук, если провайдер его поддерживает). Большинство пачек завершается в пределах часа, но провайдеры закладывают окно до суток. Результаты доступны ограниченный срок после готовности, поэтому забирайте их и сохраняйте у себя, а не полагайтесь на то, что они будут лежать на сервере провайдера вечно.

На что обращать внимание

• Связывайте запрос и ответ по custom_id — порядок результатов не гарантирован.
• Часть запросов в пачке может завершиться ошибкой — обрабатывайте каждый результат отдельно.
• Batch не подходит для интерактива: пользователю не покажешь ответ через час.
• В одной пачке работают все возможности обычного запроса: системный промпт, инструменты, кэш — поэтому общий контекст можно ещё и закэшировать.

Итог

• Batch — массовая асинхронная обработка со скидкой и отдельными лимитами.
• Подходит, когда ответ не нужен немедленно (разметка, генерация, аналитика).
• Запрос ↔ ответ связывают по custom_id; ошибки обрабатывают поштучно.