Кэширование подсказок оптимизирует использование вашего API, позволяя возобновлять работу с определённых префиксов в ваших подсказках. Это значительно сокращает время обработки и затраты на повторяющиеся задачи или подсказки с согласованными элементами.
This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.
Есть два способа включить кэширование подсказок:
cache_control на верхний уровень вашего запроса. Система автоматически применяет точку разрыва кэша к последнему кэшируемому блоку и перемещает её вперёд по мере роста разговоров. Лучше всего подходит для многоходовых разговоров, где растущая история сообщений должна кэшироваться автоматически.cache_control непосредственно на отдельные блоки контента для точного управления тем, что именно кэшируется.Самый простой способ начать — это автоматическое кэширование:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
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())При автоматическом кэшировании система кэширует весь контент вплоть до и включая последний кэшируемый блок. При последующих запросах с тем же префиксом кэшированный контент автоматически переиспользуется.
Когда вы отправляете запрос с включённым кэшированием подсказок:
Это особенно полезно для:
По умолчанию кэш имеет время жизни 5 минут. Кэш обновляется без дополнительных затрат каждый раз при использовании кэшированного контента.
Если вы считаете, что 5 минут слишком мало, Anthropic также предлагает длительность кэша в 1 час за дополнительную плату.
Для получения дополнительной информации см. Длительность кэша в 1 час.
Кэширование подсказок кэширует полный префикс
Кэширование подсказок ссылается на всю подсказку — tools, system и messages (в этом порядке) вплоть до и включая блок, обозначенный с помощью cache_control.
Кэширование подсказок вводит новую структуру ценообразования. В таблице ниже показана цена за миллион токенов для каждой поддерживаемой модели:
| Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
|---|---|---|---|---|---|
| Claude Opus 4.7 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.6 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.1 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 (deprecated) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 4.6 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
| Claude Haiku 3.5 (retired, except on Bedrock and Vertex AI) | $0.80 / MTok | $1 / MTok | $1.60 / MTok | $0.08 / MTok | $4 / MTok |
Таблица выше отражает следующие множители ценообразования для кэширования подсказок:
Эти множители складываются с другими модификаторами ценообразования, такими как скидка Batch API и местоположение данных. Полные сведения см. в разделе ценообразование.
Кэширование подсказок (как автоматическое, так и явное) поддерживается на всех активных моделях Claude.
Автоматическое кэширование — это самый простой способ включить кэширование подсказок. Вместо размещения cache_control на отдельных блоках контента добавьте одно поле cache_control на верхний уровень тела вашего запроса. Система автоматически применяет точку разрыва кэша к последнему кэшируемому блоку.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
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())При автоматическом кэшировании точка кэша перемещается вперёд автоматически по мере роста разговоров. Каждый новый запрос кэширует всё вплоть до последнего кэшируемого блока, а предыдущий контент читается из кэша.
| Запрос | Контент | Поведение кэша |
|---|---|---|
| Запрос 1 | Система + Пользователь(1) + Помощник(1) + Пользователь(2) ◀ кэш | Всё записано в кэш |
| Запрос 2 | Система + Пользователь(1) + Помощник(1) + Пользователь(2) + Помощник(2) + Пользователь(3) ◀ кэш | Система через Пользователь(2) читаются из кэша; Помощник(2) + Пользователь(3) записаны в кэш |
| Запрос 3 | Система + Пользователь(1) + Помощник(1) + Пользователь(2) + Помощник(2) + Пользователь(3) + Помощник(3) + Пользователь(4) ◀ кэш | Система через Пользователь(3) читаются из кэша; Помощник(3) + Пользователь(4) записаны в кэш |
Точка разрыва кэша автоматически перемещается к последнему кэшируемому блоку в каждом запросе, поэтому вам не нужно обновлять маркеры cache_control по мере роста разговора.
По умолчанию автоматическое кэширование использует TTL в 5 минут. Вы можете указать TTL в 1 час за 2x базовую цену входных токенов:
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }Автоматическое кэширование совместимо с явными точками разрыва кэша. При совместном использовании автоматическая точка разрыва кэша использует один из 4 доступных слотов точек разрыва.
Это позволяет вам комбинировать оба подхода. Например, используйте явные точки разрыва для кэширования вашей системной подсказки и инструментов независимо, в то время как автоматическое кэширование обрабатывает разговор:
{
"model": "claude-opus-4-7",
"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.Автоматическое кэширование доступно на Claude API и Azure AI Foundry (предварительная версия). Поддержка Amazon Bedrock и Google Vertex AI будет добавлена позже.
Для большего контроля над кэшированием вы можете поместить cache_control непосредственно на отдельные блоки контента. Это полезно, когда вам нужно кэшировать разные разделы, которые изменяются с разной частотой, или когда вам нужен точный контроль над тем, что именно кэшируется.
Поместите статический контент (определения инструментов, системные инструкции, контекст, примеры) в начало вашей подсказки. Отметьте конец переиспользуемого контента для кэширования, используя параметр cache_control.
Префиксы кэша создаются в следующем порядке: tools, system, затем messages. Этот порядок образует иерархию, где каждый уровень строится на предыдущих.
Вы можете использовать только одну точку разрыва кэша в конце вашего статического контента, и система автоматически найдёт самый длинный префикс, который предыдущий запрос уже записал в кэш. Понимание того, как это работает, помогает вам оптимизировать вашу стратегию кэширования.
Три основных принципа:
Записи в кэш происходят только в вашей точке разрыва. Отметив блок с помощью cache_control, вы записываете ровно одну запись в кэш: хеш префикса, заканчивающегося в этом блоке. Система не записывает записи для какой-либо более ранней позиции. Поскольку хеш кумулятивный, охватывающий всё вплоть до и включая точку разрыва, изменение любого блока в точке разрыва или до неё создаёт другой хеш при следующем запросе.
Чтения из кэша ищут назад записи, которые предыдущие запросы записали. При каждом запросе система вычисляет хеш префикса в вашей точке разрыва и проверяет наличие соответствующей записи в кэше. Если её нет, она проходит назад блок за блоком, проверяя, соответствует ли хеш префикса в каждой более ранней позиции чему-то уже находящемуся в кэше. Она ищет предыдущие записи, а не стабильный контент.
Окно обратного просмотра составляет 20 блоков. Система проверяет максимум 20 позиций на точку разрыва, считая саму точку разрыва первой. Если система не найдёт соответствующую запись в этом окне, проверка останавливается (или возобновляется со следующей явной точки разрыва, если она есть).
Пример: Обратный просмотр в растущем разговоре
Вы добавляете новые блоки в каждый ход и устанавливаете cache_control на финальный блок каждого запроса:
Распространённая ошибка: Точка разрыва на контенте, который изменяется в каждом запросе
Ваша подсказка имеет большой статический системный контекст (блоки 1–5), за которым следует блок для каждого запроса, содержащий временную метку и сообщение пользователя (блок 6). Вы устанавливаете cache_control на блоке 6:
Обратный просмотр не находит стабильный контент позади вашей точки разрыва и не кэширует его. Он находит записи, которые предыдущие запросы уже записали, а записи происходят только в точках разрыва. Переместите cache_control на блок 5, последний блок, который остаётся неизменным между запросами, и каждый последующий запрос будет читать кэшированный префикс. Автоматическое кэширование попадает в ту же ловушку: оно размещает точку разрыва на последнем кэшируемом блоке, который в этой структуре — это блок, который изменяется в каждом запросе, поэтому вместо этого используйте явную точку разрыва на блоке 5.
Ключевой вывод: Поместите cache_control на последний блок, чей префикс идентичен между запросами, которые вы хотите поделить кэшем. В растущем разговоре финальный блок работает, пока каждый ход добавляет менее 20 блоков: более ранний контент никогда не изменяется, поэтому обратный просмотр следующего запроса находит предыдущую запись. Для подсказки с изменяющимся суффиксом (временные метки, контекст для каждого запроса, входящее сообщение) поместите точку разрыва в конце статического префикса, а не на изменяющийся блок.
Вы можете определить до 4 точек разрыва кэша, если вы хотите:
Важное ограничение: Обратный просмотр может найти только записи, которые предыдущие запросы уже записали. Если растущий разговор перемещает вашу точку разрыва на 20 или более блоков дальше последней записи, окно обратного просмотра её пропускает. Добавьте вторую точку разрыва ближе к этой позиции с самого начала, чтобы запись накапливалась там, прежде чем она вам понадобится.
Сами точки разрыва кэша не добавляют никаких затрат. Вы платите только за:
Добавление большего количества точек разрыва cache_control не увеличивает ваши затраты — вы всё равно платите одинаково в зависимости от того, какой контент фактически кэшируется и читается. Точки разрыва просто дают вам контроль над тем, какие разделы могут кэшироваться независимо.
Минимальная кэшируемая длина подсказки составляет:
Более короткие подсказки не могут быть кэшированы, даже если отмечены с помощью cache_control. Любые запросы на кэширование менее этого количества токенов будут обработаны без кэширования, и ошибка не будет возвращена. Чтобы проверить, была ли подсказка кэширована, проверьте поля использования ответа fields: если оба cache_creation_input_tokens и cache_read_input_tokens равны 0, подсказка не была кэширована (вероятно, потому что она не соответствовала минимальному требованию длины).
Если ваша подсказка немного не соответствует минимуму для используемой модели, расширение кэшированного контента для достижения порога часто стоит того. Чтения из кэша стоят значительно меньше, чем некэшированные входные токены, поэтому достижение минимума может снизить затраты для часто переиспользуемых подсказок.
Для одновременных запросов обратите внимание, что запись в кэш становится доступной только после начала первого ответа. Если вам нужны попадания в кэш для параллельных запросов, дождитесь первого ответа перед отправкой последующих запросов.
В настоящее время "ephemeral" — это единственный поддерживаемый тип кэша, который по умолчанию имеет время жизни 5 минут.
Большинство блоков в запросе могут быть кэшированы. Это включает:
toolssystemmessages.content, как для пользовательских, так и для помощника ходовmessages.content, в пользовательских ходахmessages.content, как для пользовательских, так и для помощника ходовКаждый из этих элементов может быть кэширован, либо автоматически, либо путём отметки с помощью cache_control.
Хотя большинство блоков запроса могут быть кэшированы, есть некоторые исключения:
Блоки мышления не могут быть кэшированы непосредственно с помощью cache_control. Однако блоки мышления МОГУТ быть кэшированы вместе с другим контентом, когда они появляются в предыдущих ходах помощника. При кэшировании таким образом они СЧИТАЮТСЯ входными токенами при чтении из кэша.
Подблоки контента (такие как цитирования) сами по себе не могут быть кэшированы непосредственно. Вместо этого кэшируйте блок верхнего уровня.
В случае цитирований блоки контента документа верхнего уровня, которые служат исходным материалом для цитирований, могут быть кэшированы. Это позволяет вам эффективно использовать кэширование подсказок с цитированиями путём кэширования документов, на которые будут ссылаться цитирования.
Пустые текстовые блоки не могут быть кэшированы.
Изменения кэшированного контента могут сделать часть или весь кэш недействительным.
Как описано в разделе Структурирование вашей подсказки, кэш следует иерархии: tools → system → messages. Изменения на каждом уровне делают недействительным этот уровень и все последующие уровни.
В таблице ниже показано, какие части кэша делаются недействительными различными типами изменений. ✘ указывает, что кэш делается недействительным, в то время как ✓ указывает, что кэш остаётся действительным.
| Что изменяется | Кэш инструментов | Кэш системы | Кэш сообщений | Влияние |
|---|---|---|---|---|
| Определения инструментов | ✘ | ✘ | ✘ | Изменение определений инструментов (имена, описания, параметры) делает весь кэш недействительным |
| Переключатель веб-поиска | ✓ | ✘ | ✘ | Включение/отключение веб-поиска изменяет системную подсказку |
| Переключатель цитирований | ✓ | ✘ | ✘ | Включение/отключение цитирований изменяет системную подсказку |
| Параметр скорости | ✓ | ✘ | ✘ | Переключение между speed: "fast" и стандартной скоростью делает кэши системы и сообщений недействительными |
| Выбор инструмента | ✓ | ✓ | ✘ | Изменения параметра tool_choice влияют только на блоки сообщений |
| Изображения | ✓ | ✓ | ✘ | Добавление/удаление изображений в любом месте подсказки влияет на блоки сообщений |
| Параметры мышления | ✓ | ✓ | ✘ | Изменения параметров расширенного мышления (включение/отключение, бюджет) влияют на блоки сообщений |
| Результаты, не являющиеся инструментами, переданные в запросы расширенного мышления | ✓ | ✓ | ✘ | Когда результаты, не являющиеся инструментами, передаются в запросы при включённом расширенном мышлении, все ранее кэшированные блоки мышления удаляются из контекста, и любые сообщения в контексте, которые следуют за этими блоками мышления, удаляются из кэша. Для получения дополнительной информации см. Кэширование с блоками мышления. |
Отслеживайте производительность кэша, используя эти поля ответа API, в usage в ответе (или событие message_start если потоковая передача):
cache_creation_input_tokens: Количество токенов, записанных в кэш при создании новой записи.cache_read_input_tokens: Количество токенов, полученных из кэша для этого запроса.input_tokens: Количество входных токенов, которые не были прочитаны из кэша или использованы для создания кэша (то есть токены после последней точки разрыва кэша).Понимание разбивки токенов
Поле input_tokens представляет только токены, которые идут после последней точки разрыва кэша в вашем запросе — не все входные токены, которые вы отправили.
Для расчёта общего количества входных токенов:
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokensПространственное объяснение:
cache_read_input_tokens = токены перед точкой разрыва уже кэшированы (чтения)cache_creation_input_tokens = токены перед точкой разрыва кэшируются сейчас (записи)input_tokens = токены после вашей последней точки разрыва (не подходят для кэша)Пример: Если у вас есть запрос с 100 000 токенов кэшированного контента (прочитано из кэша), 0 токенов нового контента, кэшируемого, и 50 токенов в вашем сообщении пользователя (после точки разрыва кэша):
cache_read_input_tokens: 100 000cache_creation_input_tokens: 0input_tokens: 50Это важно для понимания как затрат, так и ограничений скорости, так как input_tokens обычно будет намного меньше, чем ваш общий ввод при эффективном использовании кэширования.
При использовании расширенного размышления с кешированием подсказок блоки размышления имеют особое поведение:
Автоматическое кеширование наряду с другим содержимым: Хотя блоки размышления не могут быть явно отмечены с помощью cache_control, они кешируются как часть содержимого запроса при последующих вызовах API с результатами инструментов. Это обычно происходит при использовании инструментов, когда вы передаёте блоки размышления обратно для продолжения разговора.
Подсчёт входных токенов: Когда блоки размышления читаются из кеша, они считаются входными токенами в ваших метриках использования. Это важно для расчёта стоимости и планирования бюджета токенов.
Паттерны инвалидации кеша:
cache_controlДля получения дополнительной информации об инвалидации кеша см. Что инвалидирует кеш.
Пример с использованием инструмента:
Запрос 1: Пользователь: "Какая погода в Париже?"
Ответ: [thinking_block_1] + [tool_use block 1]
Запрос 2:
Пользователь: ["Какая погода в Париже?"],
Помощник: [thinking_block_1] + [tool_use block 1],
Пользователь: [tool_result_1, cache=True]
Ответ: [thinking_block_2] + [text block 2]
# Запрос 2 кеширует содержимое своего запроса (не ответ)
# Кеш включает: пользовательское сообщение, thinking_block_1, tool_use block 1 и tool_result_1
Запрос 3:
Пользователь: ["Какая погода в Париже?"],
Помощник: [thinking_block_1] + [tool_use block 1],
Пользователь: [tool_result_1, cache=True],
Помощник: [thinking_block_2] + [text block 2],
Пользователь: [Text response, cache=True]
# Блок пользователя, не являющийся результатом инструмента, обозначает новый цикл помощника и все предыдущие блоки размышления удаляются из контекста
# Этот запрос обрабатывается так, как если бы блоки размышления никогда не были присутствующимиКогда включен блок пользователя, не являющийся результатом инструмента, это обозначает новый цикл помощника и все предыдущие блоки размышления удаляются из контекста.
Для получения более подробной информации см. документацию по расширенному размышлению.
Начиная с 5 февраля 2026 года, кеширование подсказок будет использовать изоляцию на уровне рабочей области вместо изоляции на уровне организации. Кеши будут изолированы для каждой рабочей области, обеспечивая разделение данных между рабочими областями в одной организации. Это изменение применяется к Claude API и Azure AI Foundry (предварительная версия); Amazon Bedrock и Google Vertex AI будут сохранять изоляцию кеша на уровне организации. Если вы используете несколько рабочих областей, проверьте вашу стратегию кеширования, чтобы учесть это изменение.
Изоляция организации: Кеши изолированы между организациями. Разные организации никогда не совместно используют кеши, даже если они используют идентичные подсказки.
Точное совпадение: Попадания в кеш требуют 100% идентичных сегментов подсказок, включая весь текст и изображения до и включая блок, отмеченный управлением кешем.
Генерация выходных токенов: Кеширование подсказок не влияет на генерацию выходных токенов. Полученный вами ответ будет идентичен тому, что вы получили бы, если бы кеширование подсказок не использовалось.
Для оптимизации производительности кеширования подсказок:
Адаптируйте вашу стратегию кеширования подсказок к вашему сценарию:
Если вы испытываете неожиданное поведение:
cache_control находятся в одних и тех же местахtool_choice и использование изображений остаются согласованными между вызовамиcache_creation_input_tokens и cache_read_input_tokens будут 0tool_use имеют стабильный порядок, так как некоторые языки (например, Swift, Go) рандомизируют порядок ключей при преобразовании JSON, нарушая кешиИзменения в tool_choice или наличие/отсутствие изображений в любом месте подсказки инвалидируют кеш, требуя создания новой записи кеша. Для получения дополнительной информации об инвалидации кеша см. Что инвалидирует кеш.
Если вы считаете, что 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": 456,
"ephemeral_1h_input_tokens": 100
}
}
}Обратите внимание, что текущее поле cache_creation_input_tokens равно сумме значений в объекте cache_creation.
Если у вас есть подсказки, которые используются с регулярной периодичностью (то есть системные подсказки, которые используются чаще, чем каждые 5 минут), продолжайте использовать кеш на 5 минут, так как это будет продолжать обновляться без дополнительной платы.
Кеш на 1 час лучше всего использовать в следующих сценариях:
Кеш на 5 минут и 1 час ведут себя одинаково в отношении задержки. Вы обычно увидите улучшенное время до первого токена для длинных документов.
Вы можете использовать управление кешем на 1 час и 5 минут в одном запросе, но с важным ограничением: Записи кеша с более длительным TTL должны появляться перед более короткими TTL (то есть запись кеша на 1 час должна появляться перед любыми записями кеша на 5 минут).
При смешивании TTL API определяет три места выставления счётов в вашей подсказке:
A: Количество токенов при наивысшем попадании в кеш (или 0, если нет попаданий).B: Количество токенов при наивысшем блоке cache_control на 1 час после A (или равно A, если таких нет).C: Количество токенов при последнем блоке cache_control.Если B и/или C больше, чем A, они обязательно будут промахами кеша, потому что A является наивысшим попаданием в кеш.
Вам будет выставлен счёт за:
A.(B - A).(C - B).Вот 3 примера. Это изображает входные токены 3 запросов, каждый из которых имеет разные попадания в кеш и промахи кеша. Каждый имеет разный рассчитанный прайсинг, показанный в цветных полях, в результате.
Чтобы помочь вам начать работу с кэшированием подсказок, кулинарная книга по кэшированию подсказок содержит подробные примеры и лучшие практики.
Следующие фрагменты кода демонстрируют различные паттерны кэширования подсказок. Эти примеры показывают, как реализовать кэширование в различных сценариях, помогая вам понять практическое применение этой функции:
Кэширование подсказок (как автоматическое, так и явное) имеет право на ZDR. Anthropic не хранит исходный текст ваших подсказок или ответов Claude.
Представления KV (ключ-значение) кэша и криптографические хэши кэшированного контента хранятся только в памяти и не сохраняются на диск. Кэшированные записи имеют минимальное время жизни 5 минут (стандартное) или 60 минут (расширенное), после чего они оперативно, хотя и не мгновенно, удаляются. Записи кэша изолированы между организациями.
Для соответствия ZDR по всем функциям см. API и хранение данных.
Was this page helpful?