Если вы запустили Claude в продакшене в 2026 году и не включили prompt caching, вы почти наверняка переплачиваете, нередко на порядок. Кеширование промптов от Anthropic даёт самый сильный рычаг на счёт за Claude API. В отличие от большинства «трюков оптимизации» оно прозрачное, детерминированное и входит в официальный SDK. В этом посте разберём, что такое prompt caching на самом деле, математику цены, паттерны, где кеш окупается, и грабли, на которые команды наступают в первый месяц после внедрения.
Что такое prompt caching
Prompt caching позволяет пометить префиксные части запроса как кешируемые. На первом вызове Anthropic сохраняет у себя внутреннее представление этого префикса. Любой следующий вызов в пределах короткого TTL (по умолчанию 5 минут, продлевается при каждом попадании) получает тот же префикс из кеша, и модели не нужно кодировать его заново.
Включается кеш добавлением точки cache_control в content-блок. Все блоки до неё и включая её становятся частью ключа кеша. На запрос допускается до четырёх breakpoint'ов, поэтому кеш можно строить по уровням: сначала стабильный system prompt, затем стабильные описания инструментов, затем подвижная история диалога.
Кеш привязан к организации и к точному содержимому префикса. Если изменить хотя бы один токен в кешируемом префиксе, запись инвалидируется. Так и должно быть: устаревший контекст вы не получите. Но это же главная причина, по которой hit rate выходит ниже ожидаемого.
Математика цены
Кеширование бесплатным не бывает. Один и тот же входной токен Anthropic тарифицирует по трём ставкам:
- Обычный input: 1.0× от цены входа модели.
- Cache write: 1.25× от цены входа (наценка 25% за заполнение кеша).
- Cache read: 0.1× от цены входа (10% от прайса при попадании).
Точка безубыточности для любого кешируемого префикса: одно чтение по 0.1× плюс запись по 1.25× обходят два «холодных» вызова по 1.0× после двух переиспользований. Начиная с третьего попадания каждый вызов на этом префиксе практически бесплатен по сравнению с некешируемой базой.
Возьмём system prompt на 20 000 токенов на Sonnet 4.6 при примерно $3 за 1M входных токенов:
- Холодный вызов: 20 000 × $3 / 1M = $0.060 за вызов.
- Cache write: 20 000 × $0.50 / 1M = $0.01 (один раз на TTL).
- Cache read: 20 000 × $0.05 / 1M = $0.001 за вызов.
Десять чтений из кеша в окне 5 минут стоят $0.075 + 9 × $0.006 = $0.129, а те же десять вызовов без кеша обходятся в 10 × $0.060 = $0.600. Получается сокращение на 78% при десяти переиспользованиях. С ростом плотности повторов потолок асимптотически приближается к теоретическим 90%.
Где кеширование реально окупается
В продакшене стабильно окупаются четыре паттерна:
- Длинные system prompt. Всё, что тянет больше пары тысяч токенов (подробные персоны, правила форматирования, brand voice, гайдлайны), стоит кешировать. System prompt по определению одинаков во всех запросах.
- RAG со стабильной базой знаний. Если в промпт зашит фиксированный корпус документов (документация продукта, политики, схемы), кешируйте его. Переменные запросы пользователей идут после breakpoint'а.
- Tool definitions у агентов. JSON-схемы функций и инструментов у нетривиального агента легко переваливают за 10K токенов, а между вызовами почти не меняются. Кешируйте.
- Многошаговые ассистенты с длинной историей. Кешируйте всё до последнего полностью стабильного хода. Каждое новое сообщение пользователя удлиняет префикс, а предыдущая история переиспользуется.
Код: Python и TypeScript через codexkey
codexkey отдаёт Claude через OpenAI-совместимый эндпоинт, и prompt caching проходит насквозь прозрачно: без дополнительной настройки, проприетарных заголовков и переписывания кода. cache_control выставляется точно так же, как в нативном API Anthropic.
from openai import OpenAI
client = OpenAI(
api_key="YOUR_CODEXKEY_KEY",
base_url="https://api.codexkey.ru/v1",
)
SYSTEM_PROMPT = open("system_prompt.txt").read() # ~20K токенов
response = client.chat.completions.create(
model="claude-sonnet-5",
messages=[
{
"role": "system",
"content": [
{
"type": "text",
"text": SYSTEM_PROMPT,
"cache_control": {"type": "ephemeral"},
}
],
},
{"role": "user", "content": "Сделай саммари последнего отчёта по продажам."},
],
)
usage = response.usage
print(usage.cache_creation_input_tokens, usage.cache_read_input_tokens)
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.CODEXKEY_KEY,
baseURL: "https://api.codexkey.ru/v1",
});
const response = await client.chat.completions.create({
model: "claude-sonnet-5",
messages: [
{
role: "system",
content: [
{
type: "text",
text: SYSTEM_PROMPT,
cache_control: { type: "ephemeral" },
},
],
},
{ role: "user", content: "Сделай саммари последнего отчёта по продажам." },
],
});
console.log(response.usage);
В объекте usage отдельно приходят cache_creation_input_tokens и cache_read_input_tokens. По ним и проверяется, что кеш действительно срабатывает, так что логируйте их в проде с первого дня.
Реальные цифры из прода
Клиент с внутренним support-агентом на шлюзе codexkey перешёл с system prompt на 22 000 токенов без кеша на тот же промпт за одним breakpoint'ом cache_control. Пока кеша не было, один только system-сегмент стоил около $1 980 в месяц при ~30 вызовах в час. После внедрения префикс в среднем попадал в кеш 14 раз за окно в 5 минут, и та же строка расходов упала до $215 в месяц. Это сокращение на 89% без изменений в ответах модели и в качестве. Описания инструментов за вторым breakpoint'ом срезали ещё примерно $140 в месяц. В сумме счёт агента за Claude снизился с примерно $2 400 в месяц до менее $400.
Такое соотношение типично. Любая нагрузка со стабильным префиксом и хотя бы несколькими вызовами в окне 5 минут даёт 70-90% экономии на input сразу после правильной настройки кеша.
Грабли
Несколько вещей ловят команды при первом раскате:
- TTL в 5 минут скользит, а не фиксирован. Каждое попадание его продлевает. Но если трафик замолчал на полные 5 минут, следующий вызов снова платит 1.25× за запись. На редких нагрузках это тихо съедает экономию, поэтому измеряйте распределение интервалов между запросами.
- Четыре breakpoint'а: жёсткий лимит. Расставляйте их по уровням: system, затем tools, затем статичный контекст, затем недавняя история. Не тратьте breakpoint'ы на части, которые всегда меняются вместе.
- Любое изменение префикса инвалидирует кеш. Одна правка в system prompt, даже пробел, обнуляет запись. Относитесь к кешируемым префиксам как к неизменяемым build-артефактам и версионируйте их явно.
- Минимальный размер блока. Совсем мелкие кешируемые блоки (меньше ~1K токенов на большинстве моделей) не кешируются вовсе, SDK молча их пропускает. Кешировать тривиальный контент незачем.
Когда кешировать не стоит
Кеш плохо подходит в нескольких случаях:
- Одиночные вызовы. Если промпт не будет переиспользован в течение 5 минут, вы зря платите наценку 1.25× за запись.
- Короткие промпты. Ниже минимума на блок кеширование ничего не делает.
- Сильно вариативный system prompt. Когда в то, что выглядит как system prompt, подставляются персональные данные, каждый вызов превращается в холодную запись. Вынесите переменную часть за breakpoint или кешируйте только стабильную «оболочку» и смиритесь с тем, что персонализированный слой оплачивается полностью.
codexkey и кеширование
codexkey пробрасывает prompt caching на Anthropic прозрачно: те же breakpoint'ы, тот же TTL, тот же учёт в usage ответа. Включать какой-то проприетарный «режим кеширования» не нужно, а наши множители write и read в точности совпадают с тарифами Anthropic. Если вы уже кешируете напрямую в Anthropic, смена base_url на https://api.codexkey.ru/v1 сохранит всю нынешнюю экономию.
Если кеширование ещё не включено, включите его на этой неделе. Это самое выгодное изменение, которое вы внесёте в свою нагрузку на Claude за весь год.