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

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

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

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

Самый простой способ начать — автоматическое кэширование:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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 минут. Кэш обновляется без дополнительной платы каждый раз, когда используется кэшированное содержимое.

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

Цены

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

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

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

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

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

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

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

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

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

Явные контрольные точки кэша

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

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

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

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

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

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

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

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

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

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

Пример: обратный просмотр в растущем диалоге

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

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

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

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

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

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

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

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

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

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

Понимание стоимости контрольных точек кэша

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

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

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

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

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

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

• 512 токенов для Claude Fable 5.1, Claude Mythos 5.1, 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. Любые запросы на кэширование меньшего количества токенов будут обработаны без кэширования, и ошибка не возвращается. Чтобы проверить, была ли подсказка кэширована, проверьте поля usage в ответе: если и cache_creation_input_tokens, и cache_read_input_tokens равны 0, подсказка не была кэширована (вероятно, потому что она не соответствовала требованию минимальной длины).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Отслеживайте производительность кэша с помощью следующих полей ответа 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 на AWS и Microsoft Foundry; Bedrock и Google Cloud используют только изоляцию на уровне организации.

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

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

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

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

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

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

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

• Диалоговые агенты: снижайте затраты и задержку для продолжительных диалогов, особенно с длинными инструкциями или загруженными документами.
• Помощники по программированию: улучшайте автодополнение и ответы на вопросы по кодовой базе, сохраняя в подсказке соответствующие разделы или сводную версию кодовой базы.
• Обработка больших документов: включайте в подсказку полный объёмный материал, включая изображения, без увеличения задержки ответа.
• Подробные наборы инструкций: передавайте обширные списки инструкций, процедур и примеров для тонкой настройки ответов 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 минут.
• Когда вы хотите улучшить использование вашего ограничения скорости, поскольку попадания в кэш не вычитаются из вашего ограничения скорости.

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

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

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

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

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

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

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

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

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

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

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

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

client = anthropic.Anthropic()

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

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

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

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