Кэширование подсказок

«Prompt caching» (кэширование подсказок) оптимизирует использование API, позволяя API возобновлять обработку с определённых префиксов в ваших подсказках. Это значительно сокращает время обработки и затраты для повторяющихся задач или подсказок с неизменными элементами.

Существует два способа включить кэширование подсказок:

• Автоматическое кэширование: добавьте одно поле cache_control на верхнем уровне вашего запроса. Система автоматически применяет «cache breakpoint» (точку останова кэша) к последнему кэшируемому блоку и перемещает её вперёд по мере роста разговора. Лучше всего подходит для многоходовых разговоров, где растущая история сообщений должна кэшироваться автоматически.
• Явные точки останова кэша: размещайте cache_control непосредственно в отдельных блоках контента для точного контроля над тем, что именно кэшируется.

Проще всего начать с автоматического кэширования:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

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

Как работает кэширование подсказок

Когда вы отправляете запрос с включённым кэшированием подсказок:

1. Система проверяет, был ли префикс подсказки до указанной точки останова кэша уже закэширован в результате недавнего запроса.
2. Если он найден, используется кэшированная версия, что сокращает время обработки и затраты.
3. В противном случае обрабатывается полная подсказка, а префикс кэшируется, как только начинается ответ.

Это особенно полезно для:

• Подсказок с большим количеством примеров
• Больших объёмов контекста или справочной информации
• Повторяющихся задач с неизменными инструкциями
• Длинных многоходовых разговоров

По умолчанию кэш имеет время жизни 5 минут. Кэш обновляется без дополнительной платы каждый раз, когда используется кэшированный контент.

Время жизни отсчитывается от начала запроса, который записывает или читает запись кэша, а не от конца его ответа. Время, затраченное на генерацию ответа, засчитывается в счёт времени жизни: если «streaming» (потоковая передача) ответа занимает 4 минуты, последующий запрос, повторно использующий тот же кэшированный префикс, должен начаться примерно в течение 1 минуты после завершения этого ответа.

Цены

Для кэширования подсказок действуют собственные цены. В следующей таблице показана цена за миллион токенов для каждой поддерживаемой модели:

Модель	Базовые токены		Кэширование промптов
Название	Ввод	Вывод	Записи в кэш на 5 мин	Запись в кэш на 1 ч	Попадания и обновления
Claude Fable 5.2For demanding reasoning and long-horizon agentic work	8 $ / MTok	40 $ / MTok	10 $ / MTok	16 $ / MTok	0,20 $ / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work	4 $ / MTok	20 $ / MTok	5 $ / MTok	8 $ / MTok	0,20 $ / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence	2 $ / MTok	10 $ / MTok	2,50 $ / MTok	4 $ / MTok	0,10 $ / MTok2
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing	0,10 $ / MTokдля промптов с числом токенов до 100 000	0,50 $ / MTok	0,125 $ / MTok	0,20 $ / MTok	0,01 $ / MTok
	0,50 $ / MTokдля промптов с числом токенов более 100 000	2,50 $ / MTok	0,625 $ / MTok	1 $ / MTok	0,05 $ / MTok
Дополнительные модели
Claude Mythos 5.2	8 $ / MTok	40 $ / MTok	10 $ / MTok	16 $ / MTok	0,20 $ / MTok1
Claude Fable 5.1	10 $ / MTok	50 $ / MTok	12,50 $ / MTok	20 $ / MTok	0,25 $ / MTok1
Claude Mythos 5.1	10 $ / MTok	50 $ / MTok	12,50 $ / MTok	20 $ / MTok	0,25 $ / MTok1
Claude Fable 5	10 $ / MTok	50 $ / MTok	12,50 $ / MTok	20 $ / MTok	1 $ / MTok
Claude Mythos 5	10 $ / MTok	50 $ / MTok	12,50 $ / MTok	20 $ / MTok	1 $ / MTok
Claude Opus 5	5 $ / MTok	25 $ / MTok	6,25 $ / MTok	10 $ / MTok	0,50 $ / MTok
Claude Opus 4.8	5 $ / MTok	25 $ / MTok	6,25 $ / MTok	10 $ / MTok	0,50 $ / MTok
Claude Opus 4.7	5 $ / MTok	25 $ / MTok	6,25 $ / MTok	10 $ / MTok	0,50 $ / MTok
Claude Opus 4.6	5 $ / MTok	25 $ / MTok	6,25 $ / MTok	10 $ / MTok	0,50 $ / MTok
Claude Opus 4.5	5 $ / MTok	25 $ / MTok	6,25 $ / MTok	10 $ / MTok	0,50 $ / MTok
Claude Opus 4.1	15 $ / MTok	75 $ / MTok	18,75 $ / MTok	30 $ / MTok	1,50 $ / MTok
Claude Opus 4	15 $ / MTok	75 $ / MTok	18,75 $ / MTok	30 $ / MTok	1,50 $ / MTok
Claude Sonnet 5	2 $ / MTok	10 $ / MTok	2,50 $ / MTok	4 $ / MTok	0,20 $ / MTok
Claude Sonnet 4.6	3 $ / MTok	15 $ / MTok	3,75 $ / MTok	6 $ / MTok	0,30 $ / MTok
Claude Sonnet 4.5	3 $ / MTok	15 $ / MTok	3,75 $ / MTok	6 $ / MTok	0,30 $ / MTok
Claude Sonnet 4	3 $ / MTok	15 $ / MTok	3,75 $ / MTok	6 $ / MTok	0,30 $ / MTok
Claude Haiku 4.5	1 $ / MTok	5 $ / MTok	1,25 $ / MTok	2 $ / MTok	0,10 $ / MTok

^{1 Попадания в кэш и обновления кэша для моделей Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1 и Claude Mythos 5.1 оплачиваются по ставке 0,025x от базовой цены входных токенов.}

^{2 Попадания в кэш и обновления кэша для моделей Claude Opus 5.5 и Claude Sonnet 5.5 оплачиваются по ставке 0,05x от базовой цены входных токенов.}

^{Для всех остальных моделей действует стандартный множитель 0,1x.}

Поддерживаемые модели

Кэширование подсказок (как автоматическое, так и явное) поддерживается на всех активных моделях Claude.

Автоматическое кэширование

Автоматическое кэширование — самый простой способ включить кэширование подсказок. Вместо размещения cache_control в отдельных блоках контента добавьте одно поле cache_control на верхнем уровне тела запроса. Система автоматически применяет точку останова кэша к последнему кэшируемому блоку.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())

Как автоматическое кэширование работает в многоходовых разговорах

При автоматическом кэшировании точка кэша автоматически перемещается вперёд по мере роста разговора. Каждый новый запрос кэширует всё до последнего кэшируемого блока, а предыдущий контент читается из кэша.

Точка останова кэша автоматически перемещается к последнему кэшируемому блоку в каждом запросе, поэтому вам не нужно обновлять маркеры cache_control по мере роста разговора.

Поддержка TTL

По умолчанию автоматическое кэширование использует «time to live» (время жизни), или TTL, равное 5 минутам. Вы можете указать TTL 1 час по цене, вдвое превышающей базовую цену входных токенов:

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

Сочетание с кэшированием на уровне блоков

Автоматическое кэширование совместимо с явными точками останова кэша. При совместном использовании автоматическая точка останова кэша занимает один из 4 доступных слотов точек останова.

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

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

Что остаётся неизменным

Автоматическое кэширование использует ту же базовую инфраструктуру кэширования. Цены, минимальные пороги токенов, требования к порядку контекста и окно ретроспективного просмотра в 20 блоков применяются так же, как и для явных точек останова.

Граничные случаи

• Если последний блок уже имеет явный cache_control с тем же TTL, автоматическое кэширование ничего не делает.
• Если последний блок имеет явный cache_control с другим TTL, API возвращает ошибку 400.
• Если уже существуют 4 явные точки останова на уровне блоков, API возвращает ошибку 400 (не осталось слотов для автоматического кэширования).
• Если последний блок не подходит в качестве цели автоматической точки останова кэша, система незаметно движется назад, чтобы найти ближайший подходящий блок. Если такой блок не найден, кэширование пропускается.

Явные точки останова кэша

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

Структурирование подсказки

Размещайте статический контент (определения инструментов, системные инструкции, контекст, примеры) в начале подсказки. Отметьте конец повторно используемого контента для кэширования с помощью параметра cache_control.

Префиксы кэша создаются в следующем порядке: tools, system, затем messages. Этот порядок образует иерархию, в которой каждый уровень строится на основе предыдущих.

Как работает автоматическая проверка префиксов

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

Три основных принципа:

1. Записи в кэш происходят только в вашей точке останова. Пометка блока с помощью cache_control создаёт ровно одну запись в кэше: хэш префикса, заканчивающегося на этом блоке. Система не создаёт записей ни для какой более ранней позиции. Поскольку хэш кумулятивный и охватывает всё до точки останова включительно, изменение любого блока в точке останова или перед ней приводит к другому хэшу в следующем запросе.

2. Чтения из кэша ищут в обратном направлении записи, созданные предыдущими запросами. При каждом запросе система вычисляет хэш префикса в вашей точке останова и проверяет наличие соответствующей записи в кэше. Если её нет, система движется назад по одному блоку, проверяя, совпадает ли хэш префикса в каждой более ранней позиции с чем-либо, уже находящимся в кэше. Она ищет предыдущие записи, а не стабильный контент.

3. Окно ретроспективного просмотра составляет 20 блоков. Система проверяет не более 20 позиций для каждой точки останова, считая саму точку останова первой. Если система не находит совпадающей записи в этом окне, проверка прекращается (или возобновляется со следующей явной точки останова, если она есть). В Claude API последовательность подряд идущих блоков tool_use считается одной позицией, как и последовательность подряд идущих блоков tool_result, поэтому ход с множеством параллельных вызовов инструментов сам по себе не выталкивает запись предыдущего запроса за пределы окна.

Пример: ретроспективный просмотр в растущем разговоре

Вы добавляете новые блоки на каждом ходе и устанавливаете cache_control на последнем блоке каждого запроса:

• Ход 1: 10 блоков, точка останова на блоке 10. Предыдущих записей в кэше нет. Система создаёт запись на блоке 10.
• Ход 2: 15 блоков, точка останова на блоке 15. У блока 15 нет записи, поэтому система возвращается к блоку 10 и находит запись хода 1. Попадание в кэш на блоке 10. Система заново обрабатывает только блоки с 11 по 15 и создаёт новую запись на блоке 15.
• Ход 3: 35 блоков, точка останова на блоке 35. Система проверяет 20 позиций (блоки с 35 по 16) и ничего не находит. Запись хода 2 на блоке 15 находится на одну позицию за пределами окна, поэтому попадания в кэш нет. Добавление второй точки останова на блоке 15 запускает там второе окно ретроспективного просмотра, которое находит запись хода 2.

Распространённая ошибка: точка останова на контенте, который меняется с каждым запросом

Ваша подсказка содержит большой статический системный контекст (блоки с 1 по 5), за которым следует блок для конкретного запроса с меткой времени и сообщением пользователя (блок 6). Вы устанавливаете cache_control на блоке 6:

• Запрос 1: запись в кэш на блоке 6. Хэш включает метку времени.
• Запрос 2: метка времени отличается, поэтому хэш префикса на блоке 6 отличается. Ретроспективный просмотр проходит через блоки 5, 4, 3, 2 и 1, но система никогда не создавала записей ни в одной из этих позиций. Попадания в кэш нет. Вы платите за новую запись в кэш при каждом запросе и никогда не получаете чтения.

Ретроспективный просмотр не находит стабильный контент позади вашей точки останова, чтобы закэшировать его. Он находит записи, которые предыдущие запросы уже создали, а записи происходят только в точках останова. Переместите cache_control на блок 5 — последний блок, который остаётся одинаковым во всех запросах, — и каждый последующий запрос будет читать кэшированный префикс. У автоматического кэширования та же проблема: оно помещает точку останова на последний кэшируемый блок, который в такой структуре меняется с каждым запросом, поэтому используйте вместо него явную точку останова на блоке 5.

Главный вывод: размещайте cache_control на последнем блоке, префикс которого идентичен во всех запросах, которые должны совместно использовать кэш. В растущем разговоре последний блок подходит, пока каждый ход добавляет менее 20 блоков: более ранний контент никогда не меняется, поэтому ретроспективный просмотр следующего запроса находит предыдущую запись. Для подсказки с изменяющимся суффиксом (метки времени, контекст конкретного запроса, входящее сообщение) размещайте точку останова в конце статического префикса, а не на изменяющемся блоке.

Когда использовать несколько точек останова

Вы можете определить до 4 точек останова кэша, если хотите:

• Кэшировать разные разделы, изменяющиеся с разной частотой (например, инструменты меняются редко, а контекст обновляется ежедневно)
• Иметь больший контроль над тем, что именно кэшируется
• Гарантировать попадание в кэш, когда растущий разговор смещает вашу точку останова на 20 или более блоков за последнюю запись в кэш

Понимание стоимости точек останова кэша

Сами точки останова кэша не добавляют никаких затрат. Плата взимается только за:

• Записи в кэш: когда новый контент записывается в кэш (на 25 процентов дороже базовых входных токенов для TTL 5 минут)
• Чтения из кэша: когда используется кэшированный контент (10 процентов от базовой цены входных токенов, с исключениями для отдельных моделей)
• Обычные входные токены: за любой некэшированный контент

Добавление дополнительных точек останова cache_control не увеличивает ваши затраты; вы по-прежнему платите ту же сумму в зависимости от того, какой контент фактически кэшируется и читается. Точки останова дают вам контроль над тем, какие разделы могут кэшироваться независимо.

Стратегии кэширования и соображения

Ограничения кэша

В Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Google managed) и Microsoft Foundry минимальная длина кэшируемой подсказки составляет:

• 512 токенов для Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, Claude Mythos 5 и Claude Haiku 5.5
• 2 048 токенов для Claude Mythos Preview и Claude Opus 4.7
• 4 096 токенов для Claude Opus 4.6 и Claude Opus 4.5
• 1 024 токена для Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 (устарела), Claude Opus 4.1 (выведена из эксплуатации, кроме Claude Models on Google Cloud (Google managed) и Bedrock), Claude Opus 4 (выведена из эксплуатации, кроме Claude Models on Google Cloud (Google managed)) и Claude Sonnet 4 (выведена из эксплуатации, кроме Claude Models on Google Cloud (Google managed) и Bedrock)
• 4 096 токенов для Claude Haiku 4.5

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

Более короткие подсказки не могут быть закэшированы, даже если они помечены cache_control. Любые запросы на кэширование меньшего количества токенов обрабатываются без кэширования, и ошибка не возвращается. Чтобы проверить, была ли подсказка закэширована, посмотрите на поля использования в ответе: если и cache_creation_input_tokens, и cache_read_input_tokens равны 0, подсказка не была закэширована (вероятно, потому что она не соответствовала требованию к минимальной длине).

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

Для параллельных запросов учитывайте, что запись в кэше становится доступной только после начала первого ответа. Если вам нужны попадания в кэш для параллельных запросов, дождитесь первого ответа, прежде чем отправлять последующие запросы.

В настоящее время ephemeral — единственный поддерживаемый тип кэша, который по умолчанию имеет время жизни 5 минут.

Что можно кэшировать

Большинство блоков в запросе можно кэшировать. Сюда входят:

• Инструменты: определения инструментов в массиве tools
• Системные сообщения: блоки контента в массиве system
• Текстовые сообщения: блоки контента в массиве messages.content как для ходов пользователя, так и для ходов ассистента
• Изображения и документы: блоки контента в массиве messages.content в ходах пользователя
• Использование инструментов и результаты инструментов: блоки контента в массиве messages.content как в ходах пользователя, так и в ходах ассистента

Каждый из этих элементов можно кэшировать либо автоматически, либо пометив его с помощью cache_control.

Что нельзя кэшировать

Хотя большинство блоков запроса можно кэшировать, есть некоторые исключения:

• Блоки размышлений нельзя кэшировать напрямую с помощью cache_control. Однако блоки размышлений МОГУТ кэшироваться вместе с другим контентом, когда они появляются в предыдущих ходах ассистента. При таком кэшировании они УЧИТЫВАЮТСЯ как входные токены при чтении из кэша.

• Блоки подконтента (например, цитаты) сами по себе нельзя кэшировать напрямую. Вместо этого кэшируйте блок верхнего уровня.

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

• Пустые текстовые блоки нельзя кэшировать.

Что делает кэш недействительным

Изменения кэшированного контента могут сделать недействительной часть кэша или весь кэш.

Как описано в разделе Структурирование подсказки, кэш следует иерархии: tools → system → messages. Изменения на каждом уровне делают недействительными этот уровень и все последующие.

В следующей таблице показано, какие части кэша становятся недействительными при различных типах изменений. ✘ означает, что кэш становится недействительным, а ✓ — что кэш остаётся действительным.

На моделях, поддерживающих изменение инструментов посреди разговора, бета-заголовок inline-tools-2026-09-15 позволяет добавить инструмент или изменить определение инструмента посреди разговора без редактирования tools. Отправьте определение в блоке tool_addition в системном сообщении посреди разговора и оставьте tools точно таким, каким вы отправили его в первый раз. Кэшированный префикс по-прежнему совпадает, поэтому как новые входные данные обрабатывается только добавленное сообщение. Единственное исключение — массив tools без неотложенных инструментов: в этом случае первый инструмент, определённый таким способом, обходится в один полный промах кэша в этом запросе. См. Определение инструментов в сообщении.

Отслеживание производительности кэша

Отслеживайте производительность кэша с помощью следующих полей ответа API в usage в ответе (или в событии message_start при потоковой передаче):

• cache_creation_input_tokens: количество токенов, записанных в кэш при создании новой записи
• cache_read_input_tokens: количество токенов, полученных из кэша для этого запроса
• input_tokens: количество входных токенов, которые не были прочитаны из кэша и не использовались для создания кэша (то есть токены после последней точки останова кэша)

Кэширование с блоками размышлений

При использовании размышлений вместе с кэшированием подсказок блоки размышлений ведут себя особым образом:

Автоматическое кэширование вместе с другим контентом: хотя блоки размышлений нельзя явно пометить с помощью cache_control, они кэшируются как часть контента запроса, когда вы выполняете последующие вызовы API с результатами инструментов. Обычно это происходит при использовании инструментов, когда вы передаёте блоки размышлений обратно, чтобы продолжить разговор.

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

Закономерности аннулирования кэша:

• Кэш остаётся действительным, когда в качестве сообщений пользователя передаются только результаты инструментов.
• На Opus 4.5+, Sonnet 4.6+ и Haiku 5.5 блоки размышлений по умолчанию сохраняются даже при добавлении пользовательского контента, не являющегося результатом инструмента, поэтому кэш остаётся действительным.
• На более ранних моделях Opus/Sonnet и моделях Haiku вплоть до Claude Haiku 4.5 кэш становится недействительным при добавлении пользовательского контента, не являющегося результатом инструмента, что приводит к удалению всех предыдущих блоков размышлений из контекста.
• Такое поведение кэширования проявляется даже без явных маркеров cache_control.

Подробнее об аннулировании кэша см. Что делает кэш недействительным.

Пример с использованием инструментов:

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)

На более ранних моделях Opus/Sonnet и моделях Haiku вплоть до Claude Haiku 4.5 в этот момент все предыдущие блоки размышлений удаляются из контекста. На Opus 4.5+, Sonnet 4.6+ и Haiku 5.5 предыдущие блоки размышлений по умолчанию сохраняются и остаются частью кэшированного префикса.

Более подробную информацию см. в разделе Размышления и кэширование подсказок.

Хранение и совместное использование кэша

• Изоляция организаций и рабочих пространств: кэши изолированы между организациями. Разные организации никогда не используют кэши совместно, даже если применяют идентичные подсказки. В Claude API, Claude Platform on AWS и Microsoft Foundry кэши также изолированы по рабочим пространствам внутри организации; Claude Models on Google Cloud (Google managed) и Bedrock используют только изоляцию на уровне организации.

• Точное совпадение: для попадания в кэш требуются на 100 процентов идентичные сегменты подсказки, включая весь текст и изображения вплоть до блока с управлением кэшем включительно.

• Генерация выходных токенов: кэширование подсказок никак не влияет на генерацию выходных токенов. Полученный ответ идентичен тому, который вы получили бы без использования кэширования подсказок.

Лучшие практики эффективного кэширования

Чтобы оптимизировать производительность кэширования подсказок:

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

Оптимизация для различных сценариев использования

Адаптируйте стратегию кэширования подсказок к вашему сценарию:

• Разговорные агенты: снижайте затраты и «latency» (задержку) для продолжительных разговоров, особенно с длинными инструкциями или загруженными документами.
• Помощники по программированию: улучшайте автодополнение и ответы на вопросы по кодовой базе, сохраняя в подсказке соответствующие разделы или краткую версию кодовой базы.
• Обработка больших документов: включайте в подсказку полный объёмный материал, в том числе изображения, без увеличения задержки ответа.
• Подробные наборы инструкций: передавайте обширные списки инструкций, процедур и примеров для точной настройки ответов Claude. Разработчики часто включают в подсказку один-два примера, но с кэшированием подсказок можно добиться ещё лучшей производительности, включив более 20 разнообразных примеров высококачественных ответов.
• Агентное использование инструментов: повышайте производительность в сценариях с множественными вызовами инструментов и итеративными изменениями кода, где каждый шаг обычно требует нового вызова API.
• Книги, статьи, документация, расшифровки подкастов и другой объёмный контент: сделайте любую базу знаний интерактивной, встроив весь документ (документы) в подсказку и позволив пользователям задавать по нему вопросы.

Устранение распространённых проблем

Если вы столкнулись с неожиданным поведением:

• Убедитесь, что кэшируемые разделы идентичны во всех вызовах. Для явных точек останова проверьте, что маркеры cache_control находятся в одних и тех же местах.
• Проверьте, что вызовы выполняются в пределах времени жизни кэша (по умолчанию 5 минут).
• Убедитесь, что tool_choice, использование изображений, конфигурация размышлений и output_config.effort остаются неизменными между вызовами.
• Проверьте, что вы кэшируете как минимум минимальное количество токенов для вашей модели и платформы (см. Ограничения кэша).
• Убедитесь, что ваша точка останова находится на блоке, который остаётся идентичным во всех запросах. Записи в кэш происходят только в точке останова, и если этот блок меняется (метки времени, контекст конкретного запроса, входящее сообщение), хэш префикса никогда не совпадёт. Ретроспективный просмотр не находит стабильный контент позади точки останова; он находит только записи, которые более ранние запросы создали в своих собственных точках останова.
• Проверьте, что ключи в блоках контента tool_use имеют стабильный порядок, поскольку некоторые языки (например, Swift, Go) перемешивают порядок ключей при преобразовании в JSON, что нарушает работу кэша.
• Используйте диагностику кэша, чтобы API сравнивал последовательные запросы и сообщал, какая часть подсказки разошлась.

Длительность кэша 1 час

Если 5 минут для вас слишком мало, Anthropic также предлагает длительность кэша 1 час за дополнительную плату.

Чтобы использовать расширенный кэш, включите ttl в определение cache_control, например так:

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

Ответ содержит подробную информацию о кэше, например:

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

Поле cache_creation_input_tokens равно сумме значений в объекте cache_creation.

Если вы видите записи ephemeral_5m_input_tokens, которые не запрашивали, при использовании серверных инструментов, таких как веб-поиск, см. Результаты серверных инструментов кэшируются автоматически.

Когда использовать кэш на 1 час

Если вы используете подсказку с регулярной периодичностью (например, системную подсказку, которую вы отправляете чаще, чем раз в 5 минут), продолжайте использовать 5-минутный кэш, поскольку он будет и дальше обновляться без дополнительной платы.

Кэш на 1 час лучше всего использовать в следующих сценариях:

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

Смешивание разных TTL

Вы можете использовать в одном запросе элементы управления кэшем как на 1 час, так и на 5 минут, но с важным ограничением: записи кэша с более длинным TTL должны располагаться перед записями с более коротким TTL (то есть запись кэша на 1 час должна располагаться перед любыми записями кэша на 5 минут).

При смешивании TTL Claude API определяет в вашей подсказке три позиции для выставления счёта:

1. Позиция A: количество токенов на последнем в вашей подсказке попадании в кэш (или 0, если попаданий нет).
   • Попадание в запись, закэшированную с TTL 5 минут, не засчитывается, если блок cache_control с TTL 1 час, расположенный в подсказке дальше этой записи, является промахом кэша.
   • Запрос, который читает запись, закэшированную с TTL 5 минут, заново начинает отсчёт её 5-минутного времени жизни, даже если на этот раз запрос задаёт "ttl": "1h".
2. Позиция B: количество токенов на последнем после A блоке cache_control с TTL 1 час (или равно A, если таких нет).
3. Позиция C: количество токенов на последнем блоке cache_control.

С вас взимается плата за:

1. Токены чтения из кэша для A.
2. Токены записи в кэш на 1 час для (B - A).
3. Токены записи в кэш на 5 минут для (C - B).

Ниже приведены три примера запросов, у каждого из которых разные попадания и промахи кэша. У каждого получается разная расчётная стоимость, показанная в блоках.

Предварительный прогрев кэша

«Cache pre-warming» (предварительный прогрев кэша) позволяет загрузить вашу системную подсказку или определения инструментов в кэш подсказок до того, как пользователь инициирует реальный запрос. Это может уменьшить штраф к «latency» (задержке) из-за промаха кэша при первом взаимодействии пользователя, снижая «time-to-first-token» (время до первого токена), или TTFT, для приложений, чувствительных к задержке.

Как это работает

Установите max_tokens: 0 в вашем запросе. API считывает вашу подсказку в модель и записывает кэш в каждой точке останова cache_control, после чего немедленно возвращает ответ, не генерируя никакого вывода. Ответ содержит пустой массив content, stop_reason: "max_tokens" и полностью заполненный блок usage.

Размещайте точку останова cache_control на последнем блоке, который является общим с последующим запросом (обычно это ваша системная подсказка или определения инструментов), а не на сообщении-заглушке пользователя. В противном случае запись кэша будет привязана к заглушке, и последующий запрос в неё не попадёт. Также используйте ту же конфигурацию размышлений и output_config.effort, что и в последующих запросах: эти значения встраиваются в подсказку (см. Что делает кэш недействительным), поэтому прогрев с другой конфигурацией может записать запись, в которую ваш реальный трафик никогда не попадёт. Это означает использование явной точки останова кэша, а не автоматического кэширования, поскольку автоматическое кэширование размещает точку останова на последнем блоке, которым здесь является заглушка. Сообщение-заглушка пользователя может быть любой строкой с непробельным содержимым (в примерах здесь используется "warmup"); его содержимое считывается в модель, но ответ на него не даётся.

client = anthropic.Anthropic()

# Вызовите это до прихода пользователей, чтобы прогреть общий кэш системной подсказки.
prewarm = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)  # []
print(prewarm.usage)

API возвращает пустой массив content:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}

Типичный шаблон использования

Выполняйте запрос прогрева при запуске приложения (или по расписанию), а затем отправляйте реальные пользовательские запросы после завершения прогрева:

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-5-5",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# Прогрейте кэш до поступления пользовательского трафика.
prewarm_cache()

# Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет в кэше.
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.text)

Имейте в виду, что TTL кэша по-прежнему действует. Для кэша по умолчанию на 5 минут отправляйте новый запрос прогрева как минимум каждые 5 минут, чтобы поддерживать кэш прогретым. При более длительных перерывах между пользовательскими запросами используйте вместо этого длительность кэша 1 час.

Ограничения

Запрос с max_tokens: 0 отклоняется с ошибкой invalid_request_error, если задан любой из следующих параметров, поскольку каждый из них подразумевает вывод, который невозможно получить при нулевом бюджете токенов:

• stream: true
• Расширенные размышления (thinking.type: "enabled")
• Структурированные выводы (output_config.format)
• tool_choice со значением {"type": "tool", ...} или {"type": "any"}

max_tokens: 0 также отклоняется внутри запроса Message Batches. Прогрев нацелен на время до первого токена, которое неприменимо к пакетной обработке, а запись кэша, сделанная во время пакетной обработки, скорее всего, истечёт до выполнения последующего запроса.

Замена обходного решения с max_tokens=1

Некоторые приложения отправляют запросы с max_tokens: 1 для прогрева кэша. Отдавайте предпочтение max_tokens: 0, если запрос это допускает: вывод не создаётся, поэтому не нужно отбрасывать однотокенный ответ, выходные токены не тарифицируются, а назначение запроса однозначно.

Примеры кэширования подсказок

Чтобы помочь вам начать работу с кэшированием подсказок, рецепт кэширования подсказок в Claude Cookbook содержит подробные примеры и лучшие практики.

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents.",
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?",
        }
    ],
)
print(response.usage.model_dump_json())

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": { "location": { "type": "string" } },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": { "timezone": { "type": "string" } },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        # ...длинный разговор до этого момента
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ],
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Good to know."},
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"},
                },
            ],
        },
    ],
)
print(response.usage.model_dump_json())

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"}
                },
                "required": ["query"],
            },
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {"type": "string", "description": "Document ID"}
                },
                "required": ["doc_id"],
            },
            "cache_control": {"type": "ephemeral"},
        },
    ],
    system=[
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"},
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"},
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
                }
            ],
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
    ],
)
print(response.usage.model_dump_json())

Хранение данных

Кэширование подсказок (как автоматическое, так и явное) соответствует требованиям ZDR. Anthropic не хранит необработанный текст ваших подсказок или ответов Claude.

Представления «KV (key-value) cache» (кэша ключ-значение) и криптографические хэши закэшированного содержимого хранятся только в памяти и не сохраняются на постоянных носителях. Закэшированные записи имеют минимальное время жизни 5 минут (стандартное) или 1 час (расширенное), после чего они удаляются оперативно, хотя и не мгновенно. Записи кэша изолированы между организациями, а в Claude API, Claude Platform on AWS и Microsoft Foundry — также между рабочими пространствами внутри организации.

Часто задаваемые вопросы

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

client.beta.prompt_caching.messages.create(**params)

client.messages.create(**params)

client.beta.promptCaching.messages.create(/* ... */);

client.messages.create(/* ... */);

Доступность