Кэширование промптов
Повторно считывайте неизменный префикс за долю стоимости входных токенов — что кешировать, что не стоит и как проверить результат.
Кэширование промптов сохраняет префикс вашего запроса, чтобы последующие вызовы с тем же префиксом оплачивались по сниженной ставке за входные токены. Для запросов с большим неизменным вступлением — системным промптом, схемами инструментов или документом, по которому задаются вопросы, — это изменение даёт наибольшую отдачу.
Что хорошо подходит для кэширования
| Подходит | Почему |
|---|---|
| Системные промпты | Побайтово идентично при каждом вызове в рамках сессии |
| Определения инструментов / функций | Не меняются на протяжении всего запуска агента и часто занимают большой объём |
| Документ, по которому неоднократно задают вопросы | Одна загрузка, много вопросов |
| Примеры для обучения по нескольким образцам | Не меняется и часто имеет большой объём |
| Не подходит | Почему |
|---|---|
| Последнее сообщение пользователя | Каждый раз отличается — попаданий в кэш не будет |
| Любой контент с отметкой времени или идентификатором запроса в начале | Один изменившийся байт в начале префикса делает недействительным всё, что идёт после него |
| Короткие промпты | Их длина меньше минимальной для кэширования, поэтому выгоды нет |
Пометка префикса
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [{
"type": "text",
"text": "<long stable instructions...>",
"cache_control": {"type": "ephemeral"}
}],
"messages": [{"role": "user", "content": "Question that changes every call"}]
}Всё содержимое до помеченного блока включительно становится кэшируемым префиксом. Порядок важен: размещайте неизменное содержимое в начале, а меняющееся — в конце.
Проверка работы
Проверьте usage объект. При попадании в кэш токены учитываются в cache-read, а не как обычные входные токены. Если при повторных вызовах cache-read остаётся нулевым, ваш префикс на самом деле не идентичен — частой причиной бывает отметка времени, идентификатор сессии или недетерминированный порядок ключей JSON во вступлении.
json.dumps(obj) без sort_keys=True может менять порядок ключей между запусками, что меняет байты и незаметно лишает вас всех попаданий в кеш.Где это особенно важно
Агентные инструменты повторно отправляют один и тот же системный промпт и одни и те же схемы инструментов на каждом шаге. В сессии из 50 шагов без кеширования вы платите за эту вводную часть 50 раз, а с кешированием — примерно один раз.