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

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

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

• Автоматическое кэширование: добавьте одно поле 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 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 минуты после завершения этого ответа.



Цены

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



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

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

По умолчанию автоматическое кэширование использует 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. Окно обратного просмотра составляет 20 блоков. Система проверяет не более 20 позиций на точку останова, считая саму точку останова первой. Если система не находит соответствующую запись в этом окне, проверка останавливается (или возобновляется со следующей явной точки останова, если таковая имеется).

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

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

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

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

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

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

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

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



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

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

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



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

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

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

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



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



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

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

• 512 токенов для Claude Opus 5, Claude Fable 5 и Claude Mythos 5
• 2 048 токенов для Claude Mythos Preview и Claude Opus 4.7
• 4 096 токенов для Claude Opus 4.6 и Claude Opus 4.5
• 1 024 токена для Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1 (выведена из эксплуатации, кроме Bedrock и Google Cloud), Claude Opus 4 (выведена из эксплуатации, кроме Google Cloud) и Claude Sonnet 4 (выведена из эксплуатации, кроме Bedrock и Google Cloud)
• 4 096 токенов для Claude Haiku 4.5
• 2 048 токенов для 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, в ходах пользователя
• Использование инструментов и результаты инструментов: блоки контента в массиве 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 минут.
• Когда важна задержка, и ваши последующие подсказки могут быть отправлены позже, чем через 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 запросов, каждый из которых имеет разные попадания и промахи кэша. Каждый имеет разную рассчитанную цену, показанную в цветных блоках, в результате.



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

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



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

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

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



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

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

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

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



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