Кэширование промптов

Кэширование промптов позволяет помечать стабильные префиксы запроса — системные промпты, описания инструментов, большие документы, few-shot примеры — чтобы Claude переиспользовал внутреннее состояние между вызовами. Чтение из кэша стоит примерно 0.1× цены обычных input-токенов, поэтому в чат-системах, агентских циклах и Q&A по документам кэширование обязательно с первого дня. Помечается блок через cache_control: {"type": "ephemeral"} (TTL 5 минут) или {"ttl": "1h"}; проверяется по usage.cache_read_input_tokens в ответе.

Как это работает

Кэш работает по точному совпадению префикса: изменение любого байта инвалидирует всё, что идёт после него. Запрос рендерится в порядке tools → system → messages — поэтому стабильное кладите в начало, переменное в конец. Breakpoint-ов cache_control может быть максимум четыре. Новый и самый простой вариант — cache_control верхнего уровня в messages.create(): он автоматически кэширует последний кэшируемый блок без ручной расстановки breakpoint-ов. Минимальный кэшируемый префикс зависит от модели: 4096 токенов на Opus 4.8 и Haiku 4.5, 2048 на Fable 5 и Sonnet 4.6 — более короткие префиксы молча не кэшируются, без ошибки. Экономика: чтение ~0.1× цены input, запись 1.25× для 5-минутного TTL и 2× для часового.

Когда применять

Включайте кэширование с первого запроса в любом сценарии с повторяющимся контекстом: многоходовые чаты, агентские циклы с одинаковым набором инструментов, Q&A по одному документу. Запись за 1.25× окупается уже при паре повторных вызовов внутри окна TTL. Часовой TTL (запись 2×) берите для редких, но регулярных вызовов — например, cron-задача раз в 20 минут, которая не удерживает 5-минутный кэш. Логируйте usage каждого вызова с первого дня: cache_read_input_tokens — единственный честный индикатор того, что кэш реально работает.

Типичные ошибки

Главный класс проблем — тихие инвалидаторы: timestamp или UUID в системном промпте (каждый вызов — новый префикс), несортированный JSON (ключи меняют порядок между рендерами), меняющийся от запроса к запросу набор инструментов, переключение модели посреди сессии. Вторая ловушка — префикс короче минимума модели: кэш просто не создаётся, ошибки нет. Третья — вера в кэш без верификации: если не смотреть usage.cache_read_input_tokens, можно месяцами платить полную цену. Наконец, переменные данные перед стабильными в промпте ломают префикс — соблюдайте порядок tools → system → messages.

Как это работает

Когда применять

Типичные ошибки

Связанные понятия

Полезные ресурсы