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

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

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

Суть заключается в обмене текущей наценки на будущую скидку. Вы один раз доплачиваете за сохранение префикса. Каждый последующий запрос, начинающийся с точно таких же байтов, оплачивает эту часть по цене в 10 раз ниже стандартной. Если префикс не используется повторно в течение времени его жизни, вы просто переплачиваете 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 процентов для 1-часового кэша, поэтому при 50-процентном коэффициенте попаданий стоимость всё ещё составляет $105.00, что выше линии без кэширования. При 90 процентах значения достигают $21.50 и $29.00. При 99 процентах короткий кэш достигает $11.15, что близко к нижней границе, составляющей одну десятую от цены без кэширования.

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

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

Запрос может содержать до четырех точек останова кэша, поэтому возникает вопрос, какие блоки их заслуживают. Кандидатами являются блоки, которые идентичны побайтово при разных вызовах и достаточно велики, чтобы это имело значение. В таблице ниже приведена стоимость четырех распространенных конфигураций при 1000 запросов с коэффициентом попадания 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 на 1000 запросов по сравнению с $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 учитывает только токены после последней точки останова (breakpoint), поэтому при корректном втором вызове это число будет небольшим — обычно это только новое сообщение пользователя.

Аналогичная проверка из командной строки для тела запроса, сохранённого в 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 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 всегда равно нулю?

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

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

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

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

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