Расчет окупаемости кэширования промптов в Claude

Стоимость кэширования промптов до получения выгоды

Кэширование промптов позволяет Claude повторно использовать начальную часть промпта вместо повторного чтения при каждом вызове. Итоговая стоимость определяется двумя множителями к базовой цене входных токенов модели. По состоянию на август 2026 года, запись в кэш стоит 1.25x от базовой цены при времени жизни 5 минут или 2x при времени жизни 1 час. Чтение из кэша стоит 0.1x. Эти множители действуют для всех моделей, поэтому точка окупаемости не меняется при изменении цены за токен.

Суть заключается в обмене текущей надбавки на будущую скидку. Вы один раз доплачиваете за сохранение префикса. Каждый последующий запрос, начинающийся с идентичных байтов, оплачивает эту часть по цене в десять раз ниже стандартной. Если префикс не используется повторно в течение времени его жизни, вы переплачиваете 25 процентов без какой-либо выгоды.

Точка безубыточности в одной строке алгебры

Обозначим B как базовую стоимость ввода префикса без кэширования. Без кэширования N запросов стоят N умножить на B. При использовании 5-минутного кэша первый запрос записывает префикс по цене 1.25B, а остальные N минус 1 запросов считывают его по цене 0.1B. Приравняем эти значения и получим 0.9N = 1.15, откуда N = 1.28. Второй запрос уже обходится дешевле, чем работа без кэширования.

Повторим расчет для 1-часового кэша с двойной стоимостью записи: 0.9N = 1.9, откуда N = 2.11. Для долгосрочного кэша требуется два чтения до достижения точки безубыточности, поэтому он не является выбором по умолчанию.

На графике ниже приведен расчет стоимости для префикса объемом 20,000 токенов в Claude Opus 5, базовая ставка ввода для которого составляет $5 за миллион токенов по состоянию на август 2026 года. Умножьте каждое значение на 0.6 для модели со стоимостью $3 за миллион. Форма кривой при этом не меняется.

[
  {
    "requests": 1,
    "uncached_usd": "0.10",
    "cached_5m_usd": "0.125",
    "cached_1h_usd": "0.20"
  },
  {
    "requests": 2,
    "uncached_usd": "0.20",
    "cached_5m_usd": "0.135",
    "cached_1h_usd": "0.21"
  },
  {
    "requests": 3,
    "uncached_usd": "0.30",
    "cached_5m_usd": "0.145",
    "cached_1h_usd": "0.22"
  },
  {
    "requests": 5,
    "uncached_usd": "0.50",
    "cached_5m_usd": "0.165",
    "cached_1h_usd": "0.24"
  },
  {
    "requests": 10,
    "uncached_usd": "1.00",
    "cached_5m_usd": "0.215",
    "cached_1h_usd": "0.29"
  },
  {
    "requests": 20,
    "uncached_usd": "2.00",
    "cached_5m_usd": "0.315",
    "cached_1h_usd": "0.39"
  }
]

Одиночный запрос стоит $0.10 без кэширования и $0.125 с кэшированием, поэтому кэширование разового промпта является чистым убытком. На втором запросе 5-минутный кэш обходится в $0.135 против $0.20. 1-часовой кэш на этом этапе все еще проигрывает: $0.21 против тех же $0.20, и он становится выгоднее варианта без кэширования только на третьем запросе: $0.22 против $0.30. К моменту выполнения 20 запросов разница составляет $2.00 против $0.315.

Попадание в кэш (cache hit) также обновляет запись, поэтому в опубликованной таблице цен этот столбец называется «попадания и обновления в кэше». Таким образом, активная конечная точка поддерживает 5-минутную запись в актуальном состоянии бесконечно долго по цене чтения, а 1-часовой срок жизни оправдывает свою двойную стоимость записи только в том случае, если в вашем трафике есть реальные паузы.

Во что обходится низкий коэффициент попаданий

Реальный трафик приводит к промахам. Запрос, который не попадает в кэш, но при этом содержит точку останова, тарифицируется как запись. Поэтому корректный способ моделирования затрат — представить их как функцию от коэффициента попаданий (hit rate). На графике ниже это показано для 1000 запросов, каждый из которых содержит одинаковый префикс размером 20000 токенов.

[
  {
    "hit_rate_percent": 0,
    "cost_5m_usd": "125.00",
    "cost_1h_usd": "200.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 25,
    "cost_5m_usd": "96.25",
    "cost_1h_usd": "152.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 50,
    "cost_5m_usd": "67.50",
    "cost_1h_usd": "105.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 75,
    "cost_5m_usd": "38.75",
    "cost_1h_usd": "57.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 90,
    "cost_5m_usd": "21.50",
    "cost_1h_usd": "29.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 95,
    "cost_5m_usd": "15.75",
    "cost_1h_usd": "19.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 99,
    "cost_5m_usd": "11.15",
    "cost_1h_usd": "11.90",
    "uncached_usd": "100.00"
  }
]

При коэффициенте попаданий 0 процентов вы платите $125.00 вместо $100.00, а кэш с временем жизни 1 час удваивает счет до $200.00. Решив уравнение 1.25 минус 1.15h = 1, получаем, что 5-минутный кэш начинает экономить средства при коэффициенте попаданий около 22 процентов, поэтому при 25 процентах значение уже составляет $96.25. Аналогичный расчет для двойной стоимости записи дает около 53 процентов для часового кэша, поэтому при 50-процентном коэффициенте попаданий затраты все еще составляют $105.00, что выше линии без кэширования. При 90 процентах оба значения достигают $21.50 и $29.00. При 99 процентах короткий кэш достигает $11.15, что близко к минимальному уровню, составляющему одну десятую от цены без кэширования.

Коэффициент попаданий — это показатель, который необходимо отслеживать, поскольку это единственный параметр, который вы контролируете после фиксации размера префикса.

Какие префиксы стоит использовать для точек останова

Запрос может содержать до четырех точек останова кэша, поэтому возникает вопрос, какие блоки их заслуживают. Кандидатами являются блоки, которые идентичны побайтово при разных вызовах и достаточно велики, чтобы это имело значение. В таблице ниже приведена стоимость четырех распространенных конфигураций для 1,000 запросов при 90-процентной частоте попаданий в 5-минутный кэш.

[
  {
    "label": "System prompt",
    "prefix_size_tokens": "2,000",
    "uncached_usd": "10.00",
    "cached_usd": "2.15",
    "saved_usd": "7.85"
  },
  {
    "label": "System plus tools",
    "prefix_size_tokens": "8,000",
    "uncached_usd": "40.00",
    "cached_usd": "8.60",
    "saved_usd": "31.40"
  },
  {
    "label": "Policy document",
    "prefix_size_tokens": "25,000",
    "uncached_usd": "125.00",
    "cached_usd": "26.88",
    "saved_usd": "98.12"
  },
  {
    "label": "Codebase context",
    "prefix_size_tokens": "120,000",
    "uncached_usd": "600.00",
    "cached_usd": "129.00",
    "saved_usd": "471.00"
  }
]

Системный промпт с простым токеном 2,000 экономит $7.85 на 1,000 запросов по сравнению с $10.00 без кэширования. При больших объемах это реальные деньги, но не это делает кэширование интересным. Добавьте определения инструментов, и вы получите 8,000 токенов и экономию в $31.40. Документ с политикой на 25,000 токенов, к которому обращается каждый запрос, экономит $98.12. Последняя строка — это то, что меняет архитектуру: 120,000 токенов контекста кодовой базы или транскрипта стоят $600.00 без кэширования и $129.00 с кэшированием, что дает экономию в $471.00.

Экономия масштабируется в зависимости от размера префикса и частоты попаданий, и больше ни от чего. Это меняет подход к тому, что вообще стоит включать в промпт: сколько на самом деле стоит миллион токенов Claude снижается до одной десятой от номинальной цены для всего, что вы отправляете более одного раза.

Как это выглядит в ежемесячном счете

На графике ниже используется префикс токенов 8,000 из примера выше, системный промпт и определения инструментов при частоте попаданий 90 процентов, с масштабированием до ежемесячных объемов запросов.

[
  {
    "label": "10k requests",
    "uncached_usd": "400.00",
    "cached_usd": "86.00",
    "saved_usd": "314.00"
  },
  {
    "label": "100k requests",
    "uncached_usd": "4,000.00",
    "cached_usd": "860.00",
    "saved_usd": "3,140.00"
  },
  {
    "label": "1M requests",
    "uncached_usd": "40,000.00",
    "cached_usd": "8,600.00",
    "saved_usd": "31,400.00"
  }
]

При 10,000 запросов в месяц экономия составляет $314.00 — это разница между $400.00 и $86.00. При 100,000 запросов экономия составляет $3,140.00. При миллионе запросов счет за входные токены без кэширования составит $40,000.00, а кэширование позволит сократить его на $31,400.00. Это касается только входных токенов. Выходные токены оплачиваются отдельно, и кэширование на них не влияет. Об этом стоит помнить, прежде чем обещать кому-либо снижение счета на 90 процентов. Кэширование является одним из методов, описанных в руководстве по контролю расходов на AI-агента на VPS.

Как убедиться, что кэширование работает

Не полагайтесь только на архитектуру. Изучите блок использования (usage) в ответе. Каждый ответ Messages API сообщает количество записанных в кэш токенов, количество прочитанных из кэша токенов и количество новых токенов, которые пришлось обработать.

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=512,
    system=[
        {
            "type": "text",
            "text": POLICY_DOCUMENT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": question}],
)

u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)

Выполните запрос дважды с одним и тем же документом, но разными вопросами. Первый вызов покажет ненулевое значение cache_creation_input_tokens и нулевое cache_read_input_tokens. Второй вызов даст обратный результат, так как префикс будет найден. input_tokens учитывает только токены после последней контрольной точки, поэтому при корректной работе второго вызова это число будет небольшим — обычно это только новое сообщение пользователя. Оба вызова подлежат оплате, так как у Claude API нет бесплатного уровня, хотя для префикса в 20000 токенов стоимость пары запросов составит около четырнадцати центов.

Аналогичная проверка из командной строки для тела запроса, сохраненного в request.json:

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @request.json | jq '.usage'

При корректной работе второй вызов выведет примерно следующее:

{
  "input_tokens": 42,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 20143,
  "output_tokens": 187
}

Одна строка скажет вам правду. Если cache_read_input_tokens остается равным 0 при повторных вызовах, вы каждый раз оплачиваете запись с коэффициентом 1.25x и не получаете никакой выгоды.

Для времени жизни в 1 час контрольная точка имеет время жизни (TTL):

{
  "type": "text",
  "text": "your stable prefix",
  "cache_control": {"type": "ephemeral", "ttl": "1h"}
}

Также существует автоматическое кэширование: поле cache_control верхнего уровня в запросе, после которого API самостоятельно управляет контрольными точками по мере роста диалога. Оно занимает один из четырех доступных слотов для контрольных точек. Начните с него. Переходите к явным контрольным точкам, когда вам нужно точно определить границы кэшируемого сегмента.

Правило порядка, снижающее эффективность кэширования

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

Отсюда следует одно правило без исключений: всё, что меняется между вызовами, должно идти после всего, что остаётся неизменным.

Чаще всего проблему вызывает временная метка. Строка Current time: 2026-08-03T14:07:11Z в начале системного промпта гарантирует нулевой процент попаданий в кэш, так как хеш префикса будет разным при каждом вызове, и ни одна предыдущая запись не сможет совпасть. Переместите её в сообщение пользователя, в самый конец. Идентификатор сессии или nonce для каждого запроса ломают кэширование точно так же, и решение для них аналогично. Полученные документы, которые различаются в каждом запросе, также должны располагаться после кэшируемого блока, иначе они сдвигают все стабильные токены за границу, которая постоянно перемещается.

Второй источник проблем — установка точки прерывания (breakpoint) на блоке, который изменяется. Запись в кэш происходит в точке прерывания, поэтому, если этот блок каждый раз разный, ничего стабильного не сохраняется, а поиск находит только те записи, которые предыдущие запросы сохранили на своих собственных «плавающих» точках прерывания. Размещайте cache_control на последнем блоке, содержимое которого идентично во всех запросах.

Третий источник — изменение параметров, которые вы не воспринимаете как содержимое промпта. У другой модели — другой кэш. Изменение выбора инструментов аннулирует кэш начиная с системного уровня. Добавление или удаление инструмента аннулирует всё содержимое.

Минимальный префикс и «тихий» пропуск

Префикс, длина которого меньше минимально допустимой для модели, не кэшируется, при этом система не выдает никаких уведомлений. Нет ни ошибок, ни предупреждений. Запрос выполняется успешно, а оба счетчика показывают 0. По состоянию на август 2026 года установлены следующие минимальные значения:

• 512 токенов для Claude Opus 5 и Claude Fable 5
• 1 024 токена для Claude Sonnet 5 и Claude Opus 4.8
• 4 096 токенов для Claude Haiku 4.5

Если в запросе, который, по вашему мнению, должен кэшироваться, оба счетчика показывают 0, в первую очередь проверьте длину префикса. Именно поэтому самая дешевая модель не всегда является наиболее выгодной для задач с использованием кэширования. Для модели Haiku 4.5 требуется префикс в восемь раз длиннее, чем для Opus 5, чтобы кэширование вообще начало работать. Таким образом, системный промпт объемом 2 000 токенов будет кэшироваться одной моделью и «тихо» игнорироваться другой.

Где Claude Code выполняет кэширование и где это невозможно

Claude Code кэширует собственный префикс. Системный промпт и определения инструментов находятся в начале каждого запроса и не меняются, поэтому они записываются один раз и считываются на протяжении всей сессии. Именно поэтому стоимость одного шага в длинной сессии значительно ниже, чем можно предположить исходя из размера контекста, что и отражается в счетчиках, описанных в том, как Claude Code отчитывается об использовании токенов.

Кэширование не поможет, если вы вносите изменения в начало контекста. История диалога работает только на добавление, поэтому обычные новые шаги расширяют уже закэшированный префикс. Редактирование файла, который был прочитан в начале сессии, изменяет содержимое в середине этого префикса, и каждый токен после внесенного изменения должен быть записан заново. Длительный простой приводит к тому же результату, так как срок действия записи истекает, и следующий шаг требует полной записи. Ни то, ни другое не является ошибкой. В обоих случаях правило префикса работает именно так, как описано.

Если вы пишете собственный клиент, применяйте структуру из первого запроса, а не адаптируйте её позже: формируйте вызов так, как это делает первое приложение Claude API на VPS, размещая стабильные блоки в начале, а изменяемые — в конце.

Режимы сбоев и их признаки

Каждый вызов — это запись. cache_creation_input_tokens принимает ненулевое значение при каждом запросе, тогда как cache_read_input_tokens остаётся равным 0. Что-то в точке останова или до неё меняется между вызовами. Выведите первые 200 символов собранного префикса для двух последовательных запросов и сравните их визуально.

Оба счётчика равны 0. Префикс короче минимально допустимого для модели, либо поле cache_control не дошло до API. Сначала подсчитайте количество токенов в префиксе, затем выведите в лог тело запроса, которое вы фактически отправили.

Чтение работает, затем прекращается. Серия попаданий, затем запись, затем снова попадания. Интервал между запросами превысил время жизни (TTL). Примите запись или перейдите на TTL 1 час, как только убедитесь, что частота попаданий превышает 53 процента.

Частота попаданий падает после развёртывания. Описание инструмента было отредактировано или модель была заменена. И то, и другое делает весь префикс невалидным. Ожидайте один дорогостоящий цикл записи после каждого развёртывания, затрагивающего промпт.

Счёт вырос после включения кэширования. Частота попаданий ниже точки окупаемости. При значении ниже примерно 22 процентов для 5-минутного кэша отправка префикса без кэширования обходится дешевле; то же самое верно для 1-часового кэша при частоте ниже 53 процентов.

FAQ

Сколько раз нужно повторно использовать промпт, чтобы кэширование стало выгодным?

Один раз при использовании 5-минутного кэша. Запись стоит 1.25x от базовой стоимости входных токенов, а чтение — 0.1x. N запросов без кэша стоят N, а N запросов с кэшем стоят 1.25 плюс 0.1 умножить на N минус 1. Точка окупаемости находится на N = 1.28, поэтому уже второй запрос оказывается выгоднее. При использовании 1-часового кэша стоимость записи составляет 2x, а точка окупаемости — N = 2.11, поэтому для выгоды требуется два чтения.

Почему значение cache_read_input_tokens всегда равно нулю?

Сначала проверьте длину префикса: если она меньше минимально допустимой для модели (на август 2026 года это 512 токенов для Claude Opus 5 и 4096 токенов для Claude Haiku 4.5), кэширование пропускается без уведомлений, и оба счетчика показывают 0. Если префикс достаточно длинный, поищите контент, который меняется между вызовами и находится в начале или до точки разделения, например, временную метку или идентификатор сессии в системном промпте. Если счетчики работали, но перестали, значит, интервал между запросами превысил время жизни кэша.

Меняет ли кэширование промптов ответы Claude?

Нет. Кэш хранит обработанную форму токенов, которые вы уже отправляли, и модель видит один и тот же промпт в обоих случаях. Это функция для оптимизации биллинга и задержек, а не изменение логики работы модели. Это также означает, что вы можете включить кэширование для уже работающего промпта без необходимости повторного запуска ваших тестов (evaluations).

Стоит ли платить за 1-часовой кэш?

Только если в вашем трафике есть паузы длиннее 5 минут, а коэффициент попаданий (hit rate) при этом будет составлять примерно 53 процента. Стоимость записи 2x в два раза выше, чем 1.25x, в случае промаха. 5-минутный кэш обновляется при каждом попадании, поэтому стабильный трафик поддерживает его активность по цене чтения, не требуя оплаты за более длительный срок хранения.