Механика кэша, ценовые уровни, длительности TTL и минимальные пороги токенов меняются по мере того, как Anthropic обновляет платформу. Не полагайтесь на какие-либо конкретные числа из сторонних руководств. Всегда сверяйтесь с официальной документацией по кэшированию промптов и страницей Модели и цены на предмет актуальных значений.
Экономика кэширования промптов
Каждый раз, когда вы вызываете API Claude, вы платите за каждый входной токен, который отправляете, — включая ваш системный промпт, определения инструментов и любой контекст, который вы впрыскиваете. Если вы делаете множество вызовов с одним и тем же большим префиксом, вы платите за обработку этого префикса с нуля каждый раз.
Кэширование промптов меняет это. Вы помечаете стабильную часть промпта как кэшируемую. Первый вызов обрабатывает её и сохраняет. Последующие вызовы, попадающие в кэш, пропускают эту обработку — и платят за эти токены долю обычной ставки.
Экономия не косметическая. Для приложений с большими, стабильными системными промптами или тяжёлым контекстом кэширование может изменить экономику функции с «слишком дорого, чтобы выкатывать» на «по сути бесплатно в эксплуатации».
Ментальная модель: стабильный префикс, изменчивый суффикс
Думайте о каждом вызове API как о двух частях:
Стабильный префикс — содержимое, которое не меняется между вызовами. Именно здесь применяется кэширование. Примеры:
- Ваш системный промпт
- Определения инструментов
- Большой справочный документ или кодовая база, которые вы впрыскиваете при каждом вызове
- Длинный блок few-shot-примеров
Изменчивый суффикс — содержимое, которое меняется от вызова к вызову. Здесь кэширование не применяется. Примеры:
- Текущее сообщение пользователя
- Данные в реальном времени, которые вы впрыскиваете на каждый запрос
- История разговора, растущая с каждым ходом
Правило простое: структурируйте промпты так, чтобы стабильное содержимое шло первым, а изменяющееся — последним. Точки разрыва кэша позиционны — всё до помеченной точки разрыва пригодно для кэширования; всё после — нет.
Если вы поместите динамическое содержимое перед статическим, вы сломаете кэш, потому что префикс меняется на каждом запросе.
Как работает модель затрат
Кэширование промптов вводит трёхстороннее разделение в том, как тарифицируются входные токены:
| Тип токена | Когда возникает | Стоимость относительно обычного входа |
|---|---|---|
| Запись в кэш | Первый вызов или после истечения кэша | Выше обычного входа |
| Чтение из кэша | Последующие вызовы, попадающие в кэш | Намного ниже обычного входа |
| Обычный вход | Токены после последней точки разрыва кэша | Обычная ставка |
Точные множители — на официальной странице цен, и они колеблются — проверяйте их напрямую. Что не меняется, так это структура: записи стоят дороже обычного, чтения — намного дешевле. Точка окупаемости — когда вы сделали достаточно кэшированных вызовов, чтобы отбить накладные расходы на запись, — наступает быстро для любого промпта со значительным стабильным содержимым.
Задержка следует тому же паттерну. Чтения из кэша пропускают полную обработку кэшированной части, что ощутимо снижает время до первого токена на вызовах с большими префиксами.
Когда кэширование промптов помогает
Кэширование окупается, когда истинны оба условия:
- У вас есть значительный стабильный префикс (существует минимальный порог токенов, ниже которого кэширование недоступно — точное число по модели смотрите в актуальной документации).
- Этот префикс переиспользуется достаточно часто, чтобы попадать в кэш чаще, чем изредка.
Сценарии, где кэширование — естественный выбор:
- Вопросы и ответы по документу — один и тот же большой документ впрыскивается для множества вопросов пользователей.
- Ассистенты для кодинга — большая кодовая база или дерево файлов включается в каждый запрос.
- Агентные циклы — один и тот же системный промпт и определения инструментов отправляются на каждом шаге многошагового рабочего процесса.
- Разговорные агенты с длинными инструкциями — детальная персона, набор правил или база знаний, которые никогда не меняются от вызова к вызову.
- Пакетная обработка — множество входных данных прогоняется по одному и тому же шаблону.
Когда кэширование промптов не помогает
Кэширование бесполезно, когда:
- Ваши промпты короткие (ниже минимального кэшируемого порога токенов).
- Ваш префикс меняется на каждом вызове — впрыскивание метки времени, контекста под конкретного пользователя или любой персонализации в «стабильную» часть инвалидирует кэш.
- Вы делаете нечастые вызовы с длинными промежутками между ними. Кэшированное содержимое истекает после TTL (длительности, которую вы можете настроить в пределах, поддерживаемых API). Если ваш трафик разрежен, вы будете в основном платить за записи при немногих чтениях.
- Ваш префикс мал по сравнению с динамическим содержимым каждого вызова. Экономия масштабируется с размером того, что кэшируется.
Как структурировать промпты под кэширование
Единственное структурное требование — порядок: стабильное содержимое должно идти перед изменчивым.
На практике:
[Системный промпт — инструкции, персона, правила]
[Определения инструментов — если статичны]
[Большие впрыснутые документы или контекст — если они одинаковы между вызовами]
--------- точка разрыва кэша здесь ---------
[Динамическое содержимое каждого вызова — сообщение пользователя, найденные фрагменты под этот запрос]
Вы помечаете точку разрыва полем cache_control на последнем блоке, который хотите включить в кэш. Всё до этого маркера пригодно для кэширования; всё после — обычный вход.
В одном запросе можно разместить до четырёх явных точек разрыва. Это полезно, когда разные части вашего промпта меняются с разной частотой — например, определения инструментов меняются редко, история разговора меняется каждый ход. У каждой секции может быть своя точка разрыва.
Правила инвалидации кэша
Кэш чувствителен к порядку. Любое изменение кэшированного блока или любого блока, идущего перед ним в промпте, инвалидирует кэш в этой точке разрыва и во всех последующих.
Изменения определений инструментов инвалидируют все кэши. Изменения системного промпта инвалидируют кэши системы и сообщений. Изменения посреди разговора затрагивают только кэш сообщений.
Практический вывод: если вы впрыскиваете что-либо, что меняется на каждом запросе, абсолютно убедитесь, что оно живёт после последней точки разрыва кэша, а не до или внутри неё.
Предварительный прогрев и мониторинг
Вы можете предварительно прогреть кэш до прихода пользовательского трафика, отправив запрос с max_tokens: 0 — это записывает кэш без генерации вывода. Полезно для пакетных задач или для предварительной оплаты стоимости записи в часы низкой нагрузки.
Поле usage в ответе API сообщает вам, сколько токенов было прочитано из кэша (cache_read_input_tokens), записано в кэш (cache_creation_input_tokens) и затарифицировано как обычный вход. Отслеживайте их, чтобы убедиться, что ваше кэширование действительно срабатывает, и измерить достигаемую экономию.
Используйте Калькулятор стоимости, чтобы смоделировать ожидаемую экономию, прежде чем закладываться на архитектуру с кэшированием.
Итог
Кэширование промптов — не микрооптимизация. Для любого приложения, которое многократно отправляет один и тот же большой префикс, это структурное экономическое решение. Модель для размышлений о нём проста: стабильное содержимое идёт первым, изменчивое — последним, точка разрыва ставится на границе.
Если вы строите на API и ещё не смотрели в сторону кэширования, проверьте текущие промпты на крупные стабильные секции. Если они есть, включить кэширование обычно несложно, а экономия реальна.