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

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

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

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

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

client = anthropic.Anthropic()

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



Цены

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



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

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



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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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-4-8",
  "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, Vertex AI и Microsoft Foundry (бета) минимальная длина кэшируемой подсказки составляет:

• 512 токенов для 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 4.6, Claude Sonnet 4.5, Claude Opus 4.1 (устарела), Claude Opus 4 (выведена из эксплуатации, кроме Vertex AI) и Claude Sonnet 4 (выведена из эксплуатации, кроме Bedrock и Vertex AI)
• 4 096 токенов для Claude Haiku 4.5
• 2 048 токенов для Claude Haiku 3.5 (выведена из эксплуатации, кроме Vertex AI)

Доступность моделей зависит от платформы, как и минимум для недавно выпущенных моделей: на Amazon Bedrock минимальная длина кэшируемой подсказки для Claude Fable 5 и Claude Mythos 5 составляет 1 024 токена.

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

total_input_tokens = cache_read_input_tokens + cache_creation_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+ предыдущие блоки мышления сохраняются по умолчанию и остаются частью кэшированного префикса.

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



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

• Изоляция по организациям и рабочим пространствам: кэши изолированы между организациями. Разные организации никогда не используют общие кэши, даже если они используют идентичные подсказки. Начиная с 5 февраля 2026 года кэши также изолированы по рабочим пространствам внутри организации в Claude API, Claude Platform на AWS и Microsoft Foundry (бета); Bedrock и Vertex AI продолжают использовать только изоляцию на уровне организации.

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

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



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

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

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



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

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

• Разговорные агенты: снижайте затраты и задержку для длительных разговоров, особенно с длинными инструкциями или загруженными документами.
• Помощники по программированию: улучшайте автодополнение и вопросы-ответы по кодовой базе, сохраняя соответствующие разделы или сокращённую версию кодовой базы в подсказке.
• Обработка больших документов: включайте полный длинный материал, в том числе изображения, в вашу подсказку без увеличения задержки ответа.
• Подробные наборы инструкций: делитесь обширными списками инструкций, процедур и примеров для тонкой настройки ответов Claude. Разработчики часто включают один-два примера в подсказку, но с кэшированием подсказок вы можете получить ещё лучшую производительность, включив 20+ разнообразных примеров высококачественных ответов.
• Агентное использование инструментов: повышайте производительность для сценариев, включающих множественные вызовы инструментов и итеративные изменения кода, где каждый шаг обычно требует нового вызова API.
• Общение с книгами, статьями, документацией, транскриптами подкастов и другим длинным контентом: оживите любую базу знаний, встроив весь документ (или документы) в подсказку и позволив пользователям задавать вопросы.



Устранение распространённых проблем

Если вы наблюдаете неожиданное поведение:

• Убедитесь, что кэшируемые разделы идентичны между вызовами. Для явных точек разрыва проверьте, что маркеры cache_control находятся в одних и тех же местах
• Проверьте, что вызовы выполняются в пределах времени жизни кэша (по умолчанию 5 минут)
• Убедитесь, что tool_choice и использование изображений остаются согласованными между вызовами
• Проверьте, что вы кэшируете как минимум минимальное количество токенов для вашей модели и платформы (см. Ограничения кэша)
• Убедитесь, что ваша точка разрыва находится на блоке, который остаётся идентичным между запросами. Записи в кэш происходят только в точке разрыва, и если этот блок меняется (временные метки, контекст для каждого запроса, входящее сообщение), хэш префикса никогда не совпадает. Просмотр назад не находит стабильный контент за точкой разрыва; он находит только записи, которые более ранние запросы записали в своих собственных точках разрыва
• Убедитесь, что ключи в ваших блоках контента tool_use имеют стабильный порядок, поскольку некоторые языки (например, Swift, Go) рандомизируют порядок ключей при преобразовании в JSON, что нарушает кэши
• Используйте диагностику кэша, чтобы API сравнил последовательные запросы и сообщил, какая часть подсказки разошлась



Кэш с временем жизни 1 час

Если 5 минут для вас слишком мало, Anthropic также предлагает кэш с временем жизни 1 час за дополнительную плату.

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

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

Ответ будет включать подробную информацию о кэше, например:

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

Обратите внимание, что текущее поле cache_creation_input_tokens равно сумме значений в объекте cache_creation.

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



Когда использовать 1-часовой кэш

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

1-часовой кэш лучше всего использовать в следующих сценариях:

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



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

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

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

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

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

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

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



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

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



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

Установите max_tokens: 0 в вашем запросе. API считывает вашу подсказку в модель и записывает кэш в любой точке разрыва cache_control, затем немедленно возвращается без генерации какого-либо вывода. Ответ имеет пустой массив content, stop_reason: "max_tokens" и полностью заполненный блок usage.

Разместите точку разрыва cache_control на последнем блоке, который является общим с последующим запросом (обычно это ваша системная подсказка или определения инструментов), а не на сообщении-заполнителе пользователя. В противном случае запись кэша привязывается к заполнителю, и последующий запрос не попадёт в неё. Это означает использование явной точки разрыва кэша, а не автоматического кэширования, поскольку автоматическое кэширование размещает точку разрыва на последнем блоке, которым здесь является заполнитель. Сообщение-заполнитель пользователя может быть любой строкой с непробельным содержимым (в примерах здесь используется "warmup"); его содержимое считывается в модель, но на него никогда не даётся ответ.

client = anthropic.Anthropic()

# Запустите это до прихода пользователей, чтобы прогреть общий кэш системной подсказки.
prewarm = client.messages.create(
    model="claude-opus-4-8",
    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-4-8",
  "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-4-8",
        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-4-8",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# Прогрейте кэш до поступления пользовательского трафика.
prewarm_cache()

# Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет закэширован.
response = respond("How do I implement a binary search tree?")
print(response.content[0].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 и хранение данных.



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