Кэширование промптов

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

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

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

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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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."
      }
    ]
  }'

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

Как работает кэширование промптов

Когда вы отправляете запрос с включённым кэшированием промптов:

1. Система проверяет, был ли префикс промпта, вплоть до указанной точки кэширования, уже закэширован в результате недавнего запроса.
2. Если найден, используется кэшированная версия, что сокращает время обработки и затраты.
3. В противном случае обрабатывается полный промпт, и префикс кэшируется после начала ответа.

Это особенно полезно для:

• Промптов с большим количеством примеров
• Больших объёмов контекста или справочной информации
• Повторяющихся задач с постоянными инструкциями
• Длинных многоходовых разговоров

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

Ценообразование

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

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

Кэширование промптов (как автоматическое, так и явное) в настоящее время поддерживается на:

• Claude Opus 4.6
• Claude Opus 4.5
• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.6
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7 (устаревшая)
• Claude Haiku 4.5
• Claude Haiku 3.5 (устаревшая)
• Claude Haiku 3

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

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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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?"}
    ]
  }'

Как работает автоматическое кэширование в многоходовых разговорах

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

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

Поддержка TTL

По умолчанию автоматическое кэширование использует TTL 5 минут. Вы можете указать TTL 1 час по цене 2x от базовой цены входных токенов:

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

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

Автоматическое кэширование совместимо с явными точками кэширования. При совместном использовании автоматическая точка кэширования использует один из 4 доступных слотов точек кэширования.

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

{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [...]
}

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

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

Пример: Понимание окна просмотра назад

Рассмотрим разговор из 30 блоков контента, где вы устанавливаете cache_control только на блоке 30:

• Если вы отправляете блок 31 без изменений в предыдущих блоках: Система проверяет блок 30 (совпадение!). Вы получаете попадание в кэш на блоке 30, и только блок 31 требует обработки.

• Если вы изменяете блок 25 и отправляете блок 31: Система проверяет в обратном порядке от блока 30 → 29 → 28... → 25 (нет совпадения) → 24 (совпадение!). Поскольку блок 24 не изменился, вы получаете попадание в кэш на блоке 24, и только блоки 25-30 требуют повторной обработки.

• Если вы изменяете блок 5 и отправляете блок 31: Система проверяет в обратном порядке от блока 30 → 29 → 28... → 11 (проверка №20). После 20 проверок без совпадения она прекращает поиск. Поскольку блок 5 находится за пределами окна в 20 блоков, попадания в кэш не происходит, и все блоки требуют повторной обработки. Однако если бы вы установили явную точку cache_control на блоке 5, система продолжила бы проверку с этой точки: блок 5 (нет совпадения) → блок 4 (совпадение!). Это позволяет получить попадание в кэш на блоке 4, демонстрируя, почему следует размещать точки кэширования перед редактируемым контентом.

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

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

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

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

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

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

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

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

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

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

Минимальная длина кэшируемого промпта составляет:

• 4096 токенов для Claude Opus 4.6, Claude Opus 4.5
• 2048 токенов для Claude Sonnet 4.6
• 1024 токена для Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4 и Claude Sonnet 3.7 (устаревшая)
• 4096 токенов для Claude Haiku 4.5
• 2048 токенов для Claude Haiku 3.5 (устаревшая) и Claude Haiku 3

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

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

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

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

Большинство блоков в запросе можно кэшировать. Это включает:

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

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

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

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

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

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

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

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

Что инвалидирует кэш

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

Как описано в разделе Структурирование промпта, кэш следует иерархии: 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

Кэширование с блоками thinking

При использовании расширенного thinking с кэшированием промптов блоки thinking имеют особое поведение:

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

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

Паттерны инвалидации кэша:

• Кэш остаётся действительным, когда в качестве пользовательских сообщений предоставляются только результаты инструментов
• Кэш инвалидируется при добавлении пользовательского контента, не являющегося результатом инструмента, что приводит к удалению всех предыдущих блоков thinking
• Это поведение кэширования происходит даже без явных маркеров 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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

Когда включён блок пользователя, не являющийся результатом инструмента, он обозначает новый цикл ассистента, и все предыдущие блоки thinking удаляются из контекста.

Для получения более подробной информации см. документацию по расширенному thinking.

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

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

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

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

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

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

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

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

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

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

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

При возникновении неожиданного поведения:

• Убедитесь, что кэшированные разделы идентичны во всех вызовах. Для явных точек кэширования проверьте, что маркеры cache_control находятся в одних и тех же местах
• Убедитесь, что вызовы выполняются в течение времени жизни кэша (по умолчанию 5 минут)
• Убедитесь, что tool_choice и использование изображений остаются неизменными между вызовами
• Убедитесь, что вы кэшируете не менее минимального количества токенов
• Система автоматически проверяет попадания в кэш на предыдущих границах блоков контента (до ~20 блоков перед вашей точкой кэширования). Для промптов с более чем 20 блоками контента вам может потребоваться добавить дополнительные параметры cache_control раньше в промпте, чтобы обеспечить кэширование всего контента
• Убедитесь, что ключи в блоках контента tool_use имеют стабильный порядок, поскольку некоторые языки (например, Swift, Go) рандомизируют порядок ключей при преобразовании JSON, что нарушает кэши

Кэш на 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": 456,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

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

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

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

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

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

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

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

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

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

Примеры кэширования промптов

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

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

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

Кэширование запросов сохраняет KV (ключ-значение) кэш-представления и криптографические хэши кэшированного содержимого, но не хранит исходный текст запросов или ответов. Кэшированные записи имеют минимальное время жизни 5 минут (стандартное) или 60 минут (расширенное). Кэш-записи изолированы между организациями. Поскольку Anthropic не хранит исходный текст запросов или ответов, эта функция может подходить для клиентов, которым требуются обязательства по хранению данных типа ZDR.

Для получения информации о соответствии требованиям ZDR по всем функциям см. API и хранение данных.

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