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

«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 5The best combination of speed and intelligence	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Haiku 4.5The fastest model with near-frontier intelligence	$1 / MTok	$5 / MTok	$1.25 / MTok	$2 / MTok	$0.10 / 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 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 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 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 доступных слотов для точек останова.

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

{
  "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)
• Обычные входные токены: за любой некэшированный контент

Добавление дополнительных точек останова 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 Fable 5 и Claude Mythos 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 (выведена из эксплуатации, кроме Bedrock и 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 blocks» (блоки размышлений) нельзя кэшировать напрямую с помощью 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+ блоки размышлений сохраняются по умолчанию, даже когда добавляется пользовательский контент, не являющийся результатом инструмента, поэтому кэш остаётся действительным
• На более ранних моделях Opus/Sonnet и всех моделях Haiku кэш становится недействительным при добавлении пользовательского контента, не являющегося результатом инструмента, что приводит к удалению всех предыдущих блоков размышлений из контекста
• Такое поведение кэширования проявляется даже без явных маркеров 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]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

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

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

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

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

• Точное совпадение: для попадания в кэш требуются на 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 минут.
• Когда важна "latency" (задержка), а ваши последующие подсказки могут отправляться позже чем через 5 минут.
• Когда вы хотите эффективнее использовать ограничение скорости, поскольку "cache hits" (попадания в кэш) не учитываются в вашем ограничении скорости.

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

Вы можете использовать управление кэшем с 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" (предварительный прогрев кэша) позволяет загрузить вашу "system prompt" (системную подсказку) или определения инструментов в "prompt cache" (кэш подсказок) до того, как пользователь отправит реальный запрос. Это устраняет дополнительную "latency" (задержку), вызванную "cache miss" (промахом кэша) при первом взаимодействии пользователя, и сокращает "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: 0 некоторые приложения использовали для достижения того же эффекта прогревочные вызовы с max_tokens: 1. Подход с max_tokens: 0 предпочтительнее: вывод не создаётся, поэтому не нужно отбрасывать однотокенный ответ, выходные токены не тарифицируются, а назначение запроса однозначно.

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

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

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

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.

Представления кэша "key-value" («ключ-значение»), или KV, и криптографические хеши закэшированного содержимого хранятся только в памяти и не сохраняются на постоянных носителях. Записи кэша имеют минимальное время жизни 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(/* ... */);