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

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

Вот пример того, как реализовать кеширование промптов с помощью Messages API, используя блок 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-1-20250805",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Вы — ИИ-ассистент, задача которого анализировать литературные произведения. Ваша цель — предоставлять проницательные комментарии о темах, персонажах и стиле письма.\n"
      },
      {
        "type": "text",
        "text": "<полное содержание Гордости и предубеждения>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Проанализируйте основные темы в Гордости и предубеждении."
      }
    ]
  }'

# Вызовите модель снова с теми же входными данными до контрольной точки кеша
curl https://api.anthropic.com/v1/messages # остальная часть входных данных

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

В этом примере весь текст “Гордости и предубеждения” кешируется с использованием параметра cache_control. Это позволяет повторно использовать этот большой текст в нескольких вызовах API без повторной обработки каждый раз. Изменение только пользовательского сообщения позволяет задавать различные вопросы о книге, используя кешированное содержимое, что приводит к более быстрым ответам и повышенной эффективности.

​

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

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

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

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

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

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

​

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

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

​

Как реализовать кеширование промптов

​

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

Кеширование промптов в настоящее время поддерживается на:

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5 (устарел)
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (устарел)

​

Структурирование вашего промпта

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

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

​

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

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

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

​

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

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

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

​

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

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

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

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

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

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

​

Понимание затрат на контрольные точки кеша

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

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

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

​

Что может быть кешировано

Большинство блоков в запросе могут быть обозначены для кеширования с помощью cache_control. Это включает:

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

​

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

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

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

​

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

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

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

​

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

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

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

​

Кеширование с блоками размышлений

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

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

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

Паттерны аннулирования кеша:

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

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

Пример с использованием инструментов:

Запрос 1: Пользователь: "Какая погода в Париже?"
Ответ: [блок_размышления_1] + [блок использования инструмента 1]

Запрос 2: 
Пользователь: ["Какая погода в Париже?"], 
Ассистент: [блок_размышления_1] + [блок использования инструмента 1], 
Пользователь: [результат_инструмента_1, cache=True]
Ответ: [блок_размышления_2] + [текстовый блок 2]
# Запрос 2 кеширует содержимое своего запроса (не ответ)
# Кеш включает: пользовательское сообщение, блок_размышления_1, блок использования инструмента 1 и результат_инструмента_1

Запрос 3:
Пользователь: ["Какая погода в Париже?"], 
Ассистент: [блок_размышления_1] + [блок использования инструмента 1], 
Пользователь: [результат_инструмента_1, cache=True], 
Ассистент: [блок_размышления_2] + [текстовый блок 2], 
Пользователь: [Текстовый ответ, cache=True]
# Блок пользователя, не являющийся результатом инструмента, приводит к игнорированию всех блоков размышлений
# Этот запрос обрабатывается так, как если бы блоки размышлений никогда не присутствовали

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

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

​

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

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

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

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

​

Продолжительность кеша 1 час

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

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

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

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

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "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: Количество токенов при самом высоком 1-часовом блоке cache_control после A (или равно A, если таких нет).
3. Позиция C: Количество токенов при последнем блоке cache_control.

Вы будете платить за:

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

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

​

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

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

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

​

FAQ