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

«Prompt caching» (кэширование подсказок) оптимизирует использование 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 минуты после завершения этого ответа.

Цены

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

Model	Base tokens		Prompt caching
Name	Input	Output	5m writes	1h writes	Hits and refreshes
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / 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 / MTokfor prompts up to 100,000 tokens	$0.50 / MTok	$0.125 / MTok	$0.20 / MTok	$0.01 / MTok
	$0.50 / MTokfor prompts over 100,000 tokens	$2.50 / MTok	$0.625 / MTok	$1 / MTok	$0.05 / MTok
Additional models
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
Claude Haiku 3.5	$0.80 / MTok	$4 / MTok	$1 / MTok	$1.60 / MTok	$0.08 / MTok

^{1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.}

^{2 Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.}

^{All other models use the standard 0.1x multiplier.}

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

Кэширование подсказок (как автоматическое, так и явное) поддерживается всеми активными моделями 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 час по цене, в 2 раза превышающей базовую цену входных токенов:

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

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

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

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

{
  "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?" }]
}

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

Автоматическое кэширование использует ту же базовую инфраструктуру кэширования. Цены, минимальные пороги токенов, требования к порядку контекста и «lookback window» (окно обратного просмотра) размером 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. «Cache hit» (попадание в кэш) на блоке 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% от базовой цены входных токенов, или 2,5% для Claude Fable 5.1 и Claude Mythos 5.1, и 5% для Claude Opus 5.5 и Claude Sonnet 5.5)
• Обычные входные токены: за любой некэшированный контент

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

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

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

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

• 512 токенов для 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
• 2048 токенов для Claude Mythos Preview и Claude Opus 4.7
• 4096 токенов для Claude Opus 4.6 и Claude Opus 4.5
• 1024 токена для Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 (устарела), Claude Opus 4.1 (выведена из эксплуатации, кроме Bedrock и Google Cloud), Claude Opus 4 (выведена из эксплуатации, кроме Google Cloud) и Claude Sonnet 4 (выведена из эксплуатации, кроме Bedrock и Google Cloud)
• 4096 токенов для Claude Haiku 4.5
• 2048 токенов для Claude Haiku 3.5 (выведена из эксплуатации, кроме Google Cloud)

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

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

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

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

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

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

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

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

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

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

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

• Блоки «thinking» (размышлений) нельзя кэшировать напрямую с помощью 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 кэши также изолированы для каждого рабочего пространства внутри организации; Bedrock и Google Cloud используют только изоляцию на уровне организации.

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

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

Рекомендации по эффективному кэшированию

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

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

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

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

• Диалоговые агенты: снижайте затраты и «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 API определяет три позиции тарификации в вашей подсказке:

1. Позиция A: количество токенов в точке самого дальнего попадания в кэш (или 0, если попаданий нет).
2. Позиция B: количество токенов в самом дальнем блоке 1-часового cache_control после A (или равно A, если таких нет).
3. Позиция C: количество токенов в последнем блоке cache_control.

С вас будет взиматься плата за:

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

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

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

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

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

Укажите max_tokens: 0 в запросе. API загружает вашу подсказку в модель и записывает кэш в каждой breakpoint (точке останова) 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
• Extended thinking (расширенные размышления) (thinking.type: "enabled")
• Structured outputs (структурированные выходные данные) (output_config.format)
• tool_choice со значением {"type": "tool", ...} или {"type": "any"}

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

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

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

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

Чтобы помочь вам начать работу с prompt caching (кэшированием подсказок), в руководстве по кэшированию подсказок приведены подробные примеры и рекомендации.

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

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())

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

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

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

Сведения о соответствии требованиям ZDR для всех функций см. в разделе API и хранение данных.

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

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(/* ... */);