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

Кэширование промптов — это мощная функция, которая оптимизирует использование вашего 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, 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: Пользователь: "Какая погода в Париже?"
Ответ: [thinking_block_1] + [блок использования инструмента 1]

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

Запрос 3:
Пользователь: ["Какая погода в Париже?"], 
Ассистент: [thinking_block_1] + [блок использования инструмента 1], 
Пользователь: [tool_result_1, cache=True], 
Ассистент: [thinking_block_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