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

Кэширование промптов — это мощная функция, которая оптимизирует использование 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-20250514",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input

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

​

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

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

Примечание:

• Токены записи в 5-минутный кэш стоят в 1,25 раза больше базовой цены входных токенов
• Токены записи в 1-часовой кэш стоят в 2 раза больше базовой цены входных токенов
• Токены чтения из кэша стоят 0,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, вы можете определить до 4 точек кэширования, что позволяет кэшировать различные повторно используемые разделы отдельно. Для каждой точки система автоматически проверит наличие кэша в предыдущих позициях и использует самый длинный совпадающий префикс, если он найден.

​

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

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

• 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 минут.

​

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

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

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

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

​

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

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

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

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

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

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

​

Отслеживание производительности кэша

Отслеживайте производительность кэша с помощью этих полей ответа API, в разделе usage в ответе (или событии message_start при потоковой передаче):

• cache_creation_input_tokens: Количество токенов, записанных в кэш при создании новой записи.
• cache_read_input_tokens: Количество токенов, извлеченных из кэша для этого запроса.
• input_tokens: Количество входных токенов, которые не были прочитаны из кэша или использованы для создания кэша.

​

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

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

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

​

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

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

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

​

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

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

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

Обратите внимание, что изменения в tool_choice или наличие/отсутствие изображений в любом месте промпта приведут к аннулированию кэша, требуя создания новой записи кэша.

​

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

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

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

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

Шаблоны аннулирования кэша:

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

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

Запрос 1: Пользователь: "Какая погода в Париже?"
Ответ: [thinking_block_1] + [tool_use block 1]

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

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

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

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

​

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

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

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

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

​

1-часовая продолжительность кэша (бета)

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

Чтобы использовать расширенный кэш, добавьте extended-cache-ttl-2025-04-11 в качестве бета-заголовка к вашему запросу, а затем включите 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