Prompt Caching и Batch API — экономика масштаба

Время: ~30 мин теории + 30 мин практики

Суть урока

Два механизма экономии на масштабе: Prompt Caching — как абонемент в спортзал (платишь один раз за вход, ходишь много раз), Batch API — как оптовый заказ на фабрике (дешевле за единицу, но ждёшь доставку до 24 часов). Отдельно каждый даёт 50-90% скидки. Вместе на кэшированных входных токенах экономия доходит до 95% от базовой цены (у Opus 5.5 и Fable 5.1 кэш ещё дешевле). Актуальные цены и версии: Актуальное сейчас.

Ключевые концепции

• Prompt Caching — кэширование повторяющихся частей промпта на серверах Anthropic
• cache_control — маркер {"type": "ephemeral"} который указывает что кэшировать
• TTL — время жизни кэша: 5 минут (стандарт, "5m") или 1 час ("1h", дороже при записи)
• Ценообразование кэша — запись 5m: 1.25x от базовой цены, запись 1h: 2x, чтение: 0.1x (экономия 90%; у Opus 5.5 чтение 0.05x, у Fable 5.1 — ещё дешевле)
• Batch API — пакетная отправка до 100 000 запросов (или 256 MB) с 50% скидкой
• Статусы батча — in_progress → ended (большинство завершается менее чем за 1 час, максимум 24 часа)

Теория

Часть 1: Prompt Caching

Как работает кэширование

Каждый раз когда ты отправляешь запрос к Claude, платишь за все токены: системный промпт, контекст, пример, пользовательское сообщение. Если системный промпт — 3000 токенов, и ты делаешь 1000 запросов в день, это 3 миллиона токенов только на повторяющийся контекст.

Prompt Caching сохраняет промпт на серверах Anthropic. Есть два TTL (время жизни кэша):

Первый запрос: платишь за запись в кэш (1.25x для 5m или 2x для 1h)
Запросы 2-N (в пределах TTL): платишь около 10% за чтение из кэша (у Opus 5.5 — 5%, у Fable 5.1 — ещё меньше) + полную цену за некэшированные токены

🎨 Образ: 5-минутный кэш — абонемент в кофейню на утро: второй кофе за 10% цены, но только пока ты в кофейне. 1-часовой — абонемент на целый день: дороже при покупке, зато хватает надолго.

Структура запроса с кэшированием

Способ 1: Автоматическое кэширование (top-level cache_control)

Самый простой — добавь cache_control на уровне запроса, и API сам определит что кэшировать:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    cache_control={"type": "ephemeral"},  # ← автоматическое кэширование
    system="Ты — специализированный ассистент для анализа договоров...",
    messages=[{"role": "user", "content": "Проанализируй этот договор: [текст]"}]
)

Способ 2: Explicit breakpoints (точечный контроль)

Для точного контроля ставь cache_control на конкретных блоках контента:

# Системный промпт — 2000+ токенов (длинный, повторяется)
SYSTEM_PROMPT = """
Ты — специализированный ассистент для анализа договоров аренды недвижимости.
Работаешь только на русском языке.

ПРАВИЛА АНАЛИЗА:
1. Всегда проверяй срок аренды, дату начала и окончания
2. Выделяй условия досрочного расторжения
3. Фиксируй штрафы и неустойки
4. Проверяй наличие индексации арендной платы
5. Отмечай ответственность сторон за ремонт
...ещё 1500 токенов правил и примеров...
"""

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}  # ← маркер на конкретном блоке
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Проанализируй этот договор: [текст договора]"
        }
    ]
)

# Проверяем что кэш работает
usage = response.usage
print(f"Входящих токенов: {usage.input_tokens}")
print(f"Токенов создано в кэш: {usage.cache_creation_input_tokens}")
print(f"Токенов прочитано из кэша: {usage.cache_read_input_tokens}")

Способ 3: 1-часовой TTL (для batch-задач и долгих задач с размышлением)

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    cache_control={
        "type": "ephemeral",
        "ttl": "1h"  # ← 1 час вместо 5 минут (запись дороже, чтение то же)
    },
    system="Длинный системный промпт...",
    messages=[{"role": "user", "content": "Запрос..."}]
)

Что выгодно кэшировать

Минимум для кэширования (зависит от модели; на октябрь 2026):

Меньше минимума — кэш молча не создаётся (ошибки нет). Проверяй: если cache_creation_input_tokens и cache_read_input_tokens оба = 0, кэширование не сработало.

Ценовая модель кэширования (на октябрь 2026)

Sonnet 5.5 (типичный выбор, $2/MTok input):

Все актуальные модели (на октябрь 2026):

Формула: запись 5m = 1.25x base, запись 1h = 2x base, чтение = 0.1x base (у Opus 5.5 — 0.05x, у Fable 5.1 — ещё меньше). Цены меняются от версии к версии, принцип остаётся: Актуальное сейчас.

На первом запросе платишь чуть больше за создание кэша. Уже на втором запросе в пределах TTL — экономия около 90% на кэшированных токенах.

Пример экономии

Сценарий (цены Sonnet 5.5 на октябрь 2026): 1000 запросов в день, системный промпт 3000 токенов, ответ 500 токенов. Запросы идут достаточно часто, чтобы каждые 5 минут кэш продлевался.

Без кэширования:
  Input: 1000 × 3000 = 3,000,000 токенов × $2/1M = $6.00/день
  Output: 1000 × 500 = 500,000 токенов × $10/1M = $5.00/день
  Итого: $11.00/день

С кэшированием (5-минутный TTL, одна сессия):
  Создание кэша (1 раз): 3000 × $2.50/1M = $0.0075
  Чтение кэша (999 раз): 999 × 3000 × $0.20/1M = $0.599
  Output (1000 раз): $5.00/день
  Итого: $5.61/день

Экономия: ~49%

Пример показывает метод расчёта. Подставь свои цифры из страницы Актуальное сейчас: экономия зависит от доли повторяющегося входа в общей стоимости.

Несколько точек кэширования (breakpoints)

🎨 Образ: Закладки в толстой книге — одна на введении, другая на середине, третья на финале. Не читаешь с начала каждый раз — прыгаешь сразу к нужному месту. Breakpoints — это закладки для API: он читает кэш с нужной точки, не пересчитывает всё с нуля.

Можно кэшировать несколько блоков в одном запросе. Максимум — 4 breakpoint'а (explicit cache_control):

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": BASE_RULES,           # Базовые правила (всегда)
            "cache_control": {"type": "ephemeral"}  # breakpoint 1
        },
        {
            "type": "text",
            "text": DOMAIN_KNOWLEDGE,     # Доменные знания (иногда меняется)
            "cache_control": {"type": "ephemeral"}  # breakpoint 2
        }
    ],
    messages=[{
        "role": "user",
        "content": user_question
    }]
)

Порядок проверки кэша: API проверяет кэш в порядке: tools → system → messages. Каждый breakpoint кэширует всё содержимое до него включительно (кумулятивно).

Что кэшировать, а что нет

Что инвалидирует кэш

Изменение любого из этих параметров «ломает» кэш — следующий запрос создаст новый:

• Определения tools
• Параметры thinking и effort (на части моделей)
• Переключение tool_choice
• Изменение изображений в промпте

Часть 2: Batch API

Когда нужен Batch API

🎨 Образ: Курьерская служба — можно вызвать такси прямо сейчас и заплатить в три раза дороже, а можно отдать 1000 посылок на следующий день и получить оптовую скидку 50%. Batch API — это оптовый курьер: не срочно, зато дёшево.

Batch API — для задач которые не требуют ответа прямо сейчас. Обрабатываешь пачку запросов, получаешь результаты через несколько часов, платишь вдвое меньше.

Идеальные сценарии:

• Классификация 5000 отзывов клиентов
• Генерация описаний для 2000 товаров
• Анализ 1000 резюме
• Перевод 3000 статей
• SEO-оптимизация 500 страниц
• Массовые evaluations (тысячи тест-кейсов)

Что можно отправлять в батче: любой запрос из Messages API — Vision, tool use, system messages, multi-turn, режим размышления (thinking), любые beta-фичи. Исключение: fast mode в батче недоступен. Каждый запрос обрабатывается независимо, можно миксовать разные типы в одном батче.

Совет: для батчей с общим системным промптом используй 1-часовой кэш ("ttl": "1h") — батч обычно длится дольше 5 минут, и 5-минутный кэш протухнет.

Отправка батча

import anthropic

client = anthropic.Anthropic()

# Подготовка запросов. Haiku 4.5 может быть выведен из API не раньше 15.10.2026:
# перед запуском сверься со страницей model deprecations и подставь актуальную дешёвую модель
requests = []
products = load_products_from_db()  # твои 1000 товаров

for i, product in enumerate(products):
    requests.append({
        "custom_id": f"product-{product['id']}",  # твой ID для матчинга
        "params": {
            "model": "claude-haiku-4-5-20251001",  # Haiku для батчей — дешевле
            "max_tokens": 500,
            "messages": [{
                "role": "user",
                "content": f"""Напиши SEO-описание для товара:
Название: {product['name']}
Категория: {product['category']}
Характеристики: {product['specs']}

Описание должно быть 100-150 слов, содержать ключевые слова."""
            }]
        }
    })

# Отправляем батч
batch = client.messages.batches.create(requests=requests)

print(f"Батч создан: {batch.id}")
print(f"Статус: {batch.processing_status}")  # in_progress
print(f"Запросов в батче: {batch.request_counts.processing}")

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

import time

batch_id = batch.id

# Ждём завершения (polling)
while True:
    batch_status = client.messages.batches.retrieve(batch_id)
    
    if batch_status.processing_status == "ended":
        print("Батч завершён!")
        print(f"Успешно: {batch_status.request_counts.succeeded}")
        print(f"Ошибок: {batch_status.request_counts.errored}")
        break
    
    print(f"Обработано: {batch_status.request_counts.processing} запросов...")
    time.sleep(60)  # проверяем раз в минуту

# Получаем результаты
results = {}
for result in client.messages.batches.results(batch_id):
    if result.result.type == "succeeded":
        results[result.custom_id] = "".join(b.text for b in result.result.message.content if b.type == "text")
    else:
        results[result.custom_id] = None
        print(f"Ошибка для {result.custom_id}: {result.result.error}")

# Сохраняем в базу
save_descriptions_to_db(results)

Статусы батча

in_progress  → запросы обрабатываются
ending       → завершение (некоторые ещё идут)
ended        → всё готово, результаты доступны

Внутри каждого запроса:
  succeeded   → OK, есть результат
  errored     → ошибка (rate limit, invalid request)
  expired     → запрос не обработан за 24 часа
  canceled    → батч отменён вручную

🎨 Образ: Polling статуса батча — как трекинг посылки на сайте почты: заходишь раз в минуту, смотришь «в пути» или «доставлено», не ждёшь звонка курьера.

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

Отмена батча

# Если передумал — отменяй пока не поздно
client.messages.batches.cancel(batch_id)

Отменённые и не обработанные запросы не тарифицируются.

Ценообразование Batch API

Всё по 50% от стандартных цен — и input, и output:

Batch API + beta header output-300k-2026-03-24: до 300 000 output токенов на запрос для Opus 5.5, Sonnet 5.5 и ряда предыдущих моделей (обычный лимит синхронного запроса — 128k у Fable 5.1, Opus 5.5 и Sonnet 5.5, 64k у Haiku 4.5). Один такой ответ может генерироваться больше часа, поэтому закладывай окно в 24 часа.

Комбинация: Batch + Caching = максимальная экономия

# Общий системный промпт — кэшируется с 1-часовым TTL (батч > 5 мин!)
ANALYSIS_SYSTEM = """[4500+ токенов правил анализа: для Haiku 4.5 минимум для кэша 4096 токенов]"""

requests = []
for doc in documents:  # 5000 документов
    requests.append({
        "custom_id": f"doc-{doc['id']}",
        "params": {
            "model": "claude-haiku-4-5-20251001",
            "max_tokens": 300,
            "system": [
                {
                    "type": "text",
                    "text": ANALYSIS_SYSTEM,
                    "cache_control": {
                        "type": "ephemeral",
                        "ttl": "1h"  # ← 1 час! Батч длится дольше 5 минут
                    }
                }
            ],
            "messages": [{"role": "user", "content": doc['text']}]
        }
    })

batch = client.messages.batches.create(requests=requests)

Почему "1h" а не "5m"? Батч обрабатывается асинхронно. Если он длится 20 минут, 5-минутный кэш протухнет после первых запросов, и остальные 4500 документов заплатят полную цену. 1-часовой кэш дороже при записи (2x), но дешевле суммарно.

Иллюстрация на условных $100 (реальная экономия зависит от доли повторяющегося входа):

🎨 Образ: Два типа экономии в магазине. Prompt Caching — карта постоянного покупателя: второй кофе дешевле. Batch API — оптовый заказ: берёшь 1000 штук, получаешь оптовую цену. Берёшь оба — максимальная скидка.

Практика

Задание: Batch-обработка с кэшированием

1. Подготовь список из 10 коротких текстов (отзывы, описания, что угодно):

   texts = [
       "Отличный сервис, всем рекомендую!",
       "Доставка задержалась на 3 дня, неприятно.",
       # ... ещё 8 текстов
   ]

2. Создай батч для классификации тональности (позитив/негатив/нейтрально):

   SENTIMENT_PROMPT = """
   Классифицируй тональность текста.
   Ответь только одним словом: позитив, негатив или нейтрально.
   Не добавляй пояснений.
   """  # ~50 токенов — минимум не достигнут, добавь больше правил и примеров

3. Добавь cache_control к системному промпту (расширь его добавив примеры: для Sonnet 5.5 нужно от 512 токенов, для Haiku 4.5 — от 4096)

4. Отправь батч и запусти polling-цикл проверки статуса

5. После завершения: вывести custom_id + результат для каждого текста

6. Проверь usage в ответах — видны ли cache_read_input_tokens?

Цель: пройти полный цикл Batch API и увидеть экономию в реальных числах.

Дополнительные платные фичи API (на октябрь 2026)

Помимо токенов модели, у Claude API есть отдельно тарифицируемые сервисы:

Fast mode (research preview) для Opus 5.5: заметно быстрее, но вдвое дороже — $8/MTok input и $40/MTok output против $4 и $20 в обычном режиме. Не работает с Batch API. Используй когда скорость критичнее цены.

🎨 Образ: Web Search — как платный поисковик для Claude. Code Execution — как песочница где Claude может реально запустить Python и увидеть результат (а не угадывать). Managed Agents — арендованный сервер для агента, платишь по часам как за такси с включённым счётчиком.

Инструменты и ресурсы

• Prompt Caching docs — platform.claude.com/docs: prompt caching
• Batch API docs — platform.claude.com/docs: batch processing
• Pricing — platform.claude.com/docs: pricing
• API Console — platform.claude.com
• Python SDK — pip install anthropic (Batch API входит в SDK)
• Лимиты Batch API — до 100 000 запросов или 256 MB; результаты хранятся 29 дней
• Beta header output-300k-2026-03-24 — до 300k output токенов в Batch для Opus 5.5, Sonnet 5.5 и ряда предыдущих моделей
• Актуальные цены и версии — Актуальное сейчас

Ключевые выводы

Prompt Caching окупается уже на втором запросе. Два TTL: 5 минут (default, запись +25%) и 1 час (запись +100%) — чтение обычно 0.1x (−90%), у Opus 5.5 и Fable 5.1 ещё дешевле. Минимум для кэша зависит от модели: от 512 до 4096 токенов. Если промпт короче — кэш молча не создаётся. Batch API — до 100 000 запросов за раз, 50% скидка. Большинство батчей завершается < 1 часа. Для батчей используй 1-часовой кэш ("ttl": "1h") — 5-минутный протухнет раньше чем батч закончится. Комбинируй оба метода для массовых задач: экономия 90-95% от базовой цены.

Следующий урок

→ Loop и Scheduled Tasks — когда что использовать