Prompt Caching в Claude API: экономим токены

Каждый запрос к Claude — платный. В input_tokens входит всё: system prompt, история, вопрос. Если делаешь 100 запросов с одним system prompt на 500 токенов — платишь за 50 000 токенов «впустую».

Prompt caching кешируе часть промпта на стороне Anthropic. Повторные запросы с тем же кешированным содержимым стоят 10% от обычной цены.

Как включить кеш

Меняем system со строки на список с cache_control:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Ты — Python-тьютор. Объясняешь просто...",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "Что такое list comprehension?"}]
)

Чтение метрик кеша

usage = response.usage
print(f"Обычные входящие токены:    {usage.input_tokens}")
print(f"Создан кеш (1.25x цена):   {usage.cache_creation_input_tokens}")
print(f"Прочитан кеш (0.1x цена):  {usage.cache_read_input_tokens}")

• Первый запрос — cache_creation_input_tokens > 0 (кеш создаётся, стоит 1.25x)
• Повторные запросы — cache_read_input_tokens > 0 (читается кеш, стоит 0.1x)

Батч-обработка — где кеш реально работает

texts = ["Текст 1", "Текст 2", "Текст 3", ...]

SYSTEM = [{"type": "text", "text": "Длинный system prompt...", "cache_control": {"type": "ephemeral"}}]

total_saved = 0
for text in texts:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        system=SYSTEM,
        messages=[{"role": "user", "content": text}]
    )
    # Начиная со второго запроса — кеш уже читается
    saved = response.usage.cache_read_input_tokens
    total_saved += saved

print(f"Сэкономлено токенов через кеш: {total_saved}")

Когда кеш создаётся, а когда читается

Что можно кешировать

• System prompt (самый частый случай)
• Длинные документы в начале messages
• Few-shot примеры

Минимальный размер для кеширования: 1024 токена (для claude-sonnet-4-6).

Подсчёт реальной экономии

def calc_cost(usage, model="sonnet"):
    rates = {"sonnet": (3.0, 15.0, 3.75, 0.3)}  # in, out, cache_create, cache_read per 1M
    r = rates[model]
    cost = (
        usage.input_tokens * r[0] +
        usage.output_tokens * r[1] +
        (usage.cache_creation_input_tokens or 0) * r[2] +
        (usage.cache_read_input_tokens or 0) * r[3]
    ) / 1_000_000
    return cost