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

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

Вот пример того, как реализовать кеширование промптов с помощью Messages API, используя блок cache_control:

Shell

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 # остальная часть входных данных

JSON

{"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 минут слишком мало, Anthropic также предлагает продолжительность кеша 1 час.

Для получения дополнительной информации см. Продолжительность кеша 1 час.

Кеширование промптов кеширует полный префикс

Кеширование промптов ссылается на весь промпт — tools, system и messages (в таком порядке) до и включая блок, обозначенный cache_control.

---

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

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

Model	Base Input Tokens	5m Cache Writes	1h Cache Writes	Cache Hits & Refreshes	Output Tokens
Claude Opus 4.1	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Opus 4	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Sonnet 4	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.7	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.5 (deprecated)	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Haiku 3.5	$0.80 / MTok	$1 / MTok	$1.6 / MTok	$0.08 / MTok	$4 / MTok
Claude Opus 3 (deprecated)	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Haiku 3	$0.25 / MTok	$0.30 / MTok	$0.50 / MTok	$0.03 / MTok	$1.25 / MTok

Таблица выше отражает следующие множители ценообразования для кеширования промптов:

• Токены записи 5-минутного кеша стоят в 1,25 раза больше базовой цены входных токенов
• Токены записи 1-часового кеша стоят в 2 раза больше базовой цены входных токенов
• Токены чтения кеша стоят в 0,1 раза меньше базовой цены входных токенов

---

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

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

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

• 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 блоков перед вашей финальной контрольной точкой

Важное ограничение: Автоматическая проверка префиксов смотрит назад только примерно на 20 блоков содержимого от каждой явной контрольной точки. Если ваш промпт имеет более 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. Изменения на каждом уровне аннулируют этот уровень и все последующие уровни.

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

Что изменяется	Кеш инструментов	Системный кеш	Кеш сообщений	Влияние
Определения инструментов	✘	✘	✘	Изменение определений инструментов (имена, описания, параметры) аннулирует весь кеш
Переключатель веб-поиска	✓	✘	✘	Включение/отключение веб-поиска изменяет системный промпт
Переключатель цитат	✓	✘	✘	Включение/отключение цитат изменяет системный промпт
Выбор инструмента	✓	✓	✘	Изменения параметра tool_choice влияют только на блоки сообщений
Изображения	✓	✓	✘	Добавление/удаление изображений где-либо в промпте влияет на блоки сообщений
Параметры размышлений	✓	✓	✘	Изменения настроек расширенного размышления (включить/отключить, бюджет) влияют на блоки сообщений
Результаты не-инструментов, переданные в запросы расширенного размышления	✓	✓	✘	Когда результаты не-инструментов передаются в запросы при включенном расширенном размышлении, все ранее кешированные блоки размышлений удаляются из контекста, и любые сообщения в контексте, которые следуют за этими блоками размышлений, удаляются из кеша. Для получения дополнительной информации см. Кеширование с блоками размышлений.

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

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

Изменения в tool_choice или наличие/отсутствие изображений где-либо в промпте аннулируют кеш, требуя создания новой записи кеша. Для получения дополнительной информации об аннулировании кеша см. Что аннулирует кеш.

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

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

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

5-минутный и 1-часовой кеш ведут себя одинаково в отношении задержки. Вы обычно увидите улучшенное время до первого токена для длинных документов.

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

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

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

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

Если B и/или C больше A, они обязательно будут промахами кеша, потому что A — это самое высокое попадание в кеш.

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

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

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

---

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

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

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

Пример кеширования большого контекста

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "Вы — ИИ-ассистент, задача которого анализировать юридические документы."
        },
        {
            "type": "text",
            "text": "Вот полный текст сложного юридического соглашения: [Вставьте полный текст 50-страничного юридического соглашения здесь]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Каковы ключевые условия и положения в этом соглашении?"
        }
    ]
}'

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

Для первого запроса:

• input_tokens: Количество токенов только в пользовательском сообщении
• cache_creation_input_tokens: Количество токенов во всем системном сообщении, включая юридический документ
• cache_read_input_tokens: 0 (нет попадания в кеш при первом запросе)

Для последующих запросов в пределах времени жизни кеша:

• input_tokens: Количество токенов только в пользовательском сообщении
• cache_creation_input_tokens: 0 (нет создания нового кеша)
• cache_read_input_tokens: Количество токенов во всем кешированном системном сообщении

Кеширование определений инструментов

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Получить текущую погоду в заданном месте",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Город и штат, например Сан-Франциско, Калифорния"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Единица температуры, либо цельсий, либо фаренгейт"
                    }
                },
                "required": ["location"]
            }
        },
        # много других инструментов
        {
            "name": "get_time",
            "description": "Получить текущее время в заданном часовом поясе",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "Имя часового пояса IANA, например America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Какая погода и время в Нью-Йорке?"
        }
    ]
}'

В этом примере мы демонстрируем кеширование определений инструментов.

Параметр cache_control размещается на финальном инструменте (get_time) для обозначения всех инструментов как части статического префикса.

Это означает, что все определения инструментов, включая get_weather и любые другие инструменты, определенные перед get_time, будут кешированы как единый префикс.

Этот подход полезен, когда у вас есть постоянный набор инструментов, которые вы хотите повторно использовать в нескольких запросах без повторной обработки каждый раз.

Для первого запроса:

• input_tokens: Количество токенов в пользовательском сообщении
• cache_creation_input_tokens: Количество токенов во всех определениях инструментов и системном промпте
• cache_read_input_tokens: 0 (нет попадания в кеш при первом запросе)

Для последующих запросов в пределах времени жизни кеша:

• input_tokens: Количество токенов в пользовательском сообщении
• cache_creation_input_tokens: 0 (нет создания нового кеша)
• cache_read_input_tokens: Количество токенов во всех кешированных определениях инструментов и системном промпте

Продолжение многоходового разговора

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...длинный системный промпт",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Привет, можете ли вы рассказать мне больше о солнечной системе?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Конечно! Солнечная система — это совокупность небесных тел, которые вращаются вокруг нашего Солнца. Она состоит из восьми планет, многочисленных лун, астероидов, комет и других объектов. Планеты, в порядке от ближайшей к самой дальней от Солнца: Меркурий, Венера, Земля, Марс, Юпитер, Сатурн, Уран и Нептун. Каждая планета имеет свои уникальные характеристики и особенности. Есть ли конкретный аспект солнечной системы, о котором вы хотели бы узнать больше?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Хорошо знать."
                },
                {
                    "type": "text",
                    "text": "Расскажите мне больше о Марсе.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

В этом примере мы демонстрируем, как использовать кеширование промптов в многоходовом разговоре.

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

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

Этот подход полезен для поддержания контекста в продолжающихся разговорах без повторной обработки той же информации.

Когда это настроено правильно, вы должны увидеть следующее в ответе использования каждого запроса:

• input_tokens: Количество токенов в новом пользовательском сообщении (будет минимальным)
• cache_creation_input_tokens: Количество токенов в новых ходах ассистента и пользователя
• cache_read_input_tokens: Количество токенов в разговоре до предыдущего хода

Объединение всего: Множественные контрольные точки кеша

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Поиск по базе знаний",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Поисковый запрос"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Получить конкретный документ по ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "ID документа"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "Вы — полезный исследовательский ассистент с доступом к базе знаний документов.\n\n# Инструкции\n- Всегда ищите соответствующие документы перед ответом\n- Предоставляйте цитаты для ваших источников\n- Будьте объективными и точными в ваших ответах\n- Если несколько документов содержат соответствующую информацию, синтезируйте их\n- Признавайте, когда информация недоступна в базе знаний",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Контекст базы знаний\n\nВот соответствующие документы для этого разговора:\n\n## Документ 1: Обзор солнечной системы\nСолнечная система состоит из Солнца и всех объектов, которые вращаются вокруг него...\n\n## Документ 2: Характеристики планет\nКаждая планета имеет уникальные особенности. Меркурий — самая маленькая планета...\n\n## Документ 3: Исследование Марса\nМарс был целью исследований в течение десятилетий...\n\n[Дополнительные документы...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Можете ли вы найти информацию о марсоходах?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "марсоходы"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Найдено 3 соответствующих документа: Документ 3 (Исследование Марса), Документ 7 (Технология роверов), Документ 9 (История миссий)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "Я нашел 3 соответствующих документа о марсоходах. Позвольте мне получить больше деталей из документа об исследовании Марса."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Да, пожалуйста, расскажите мне о ровере Perseverance конкретно.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

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

1. Кеш инструментов (контрольная точка кеша 1): Параметр cache_control на последнем определении инструмента кеширует все определения инструментов.

2. Кеш повторно используемых инструкций (контрольная точка кеша 2): Статические инструкции в системном промпте кешируются отдельно. Эти инструкции редко изменяются между запросами.

3. Кеш RAG контекста (контрольная точка кеша 3): Документы базы знаний кешируются независимо, позволяя обновлять RAG документы без аннулирования кеша инструментов или инструкций.

4. Кеш истории разговора (контрольная точка кеша 4): Ответ ассистента отмечен cache_control для включения инкрементального кеширования разговора по мере его развития.

Этот подход обеспечивает максимальную гибкость:

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

Для первого запроса:

• input_tokens: Токены в финальном пользовательском сообщении
• cache_creation_input_tokens: Токены во всех кешированных сегментах (инструменты + инструкции + RAG документы + история разговора)
• cache_read_input_tokens: 0 (нет попаданий в кеш)

Для последующих запросов только с новым пользовательским сообщением:

• input_tokens: Токены только в новом пользовательском сообщении
• cache_creation_input_tokens: Любые новые токены, добавленные в историю разговора
• cache_read_input_tokens: Все ранее кешированные токены (инструменты + инструкции + RAG документы + предыдущий разговор)

Этот паттерн особенно мощен для:

• RAG приложений с большими контекстами документов
• Агентных систем, которые используют множественные инструменты
• Длительных разговоров, которые нужно поддерживать в контексте
• Приложений, которые нужно оптимизировать различные части промпта независимо

---

FAQ

Нужны ли мне множественные контрольные точки кеша или достаточно одной в конце?

В большинстве случаев достаточно одной контрольной точки кеша в конце вашего статического содержимого. Система автоматически проверяет попадания в кеш на всех предыдущих границах блоков содержимого (до 20 блоков перед вашей контрольной точкой) и использует самый длинный совпадающий префикс.

Вам нужны множественные контрольные точки только если:

• У вас более 20 блоков содержимого перед желаемой точкой кеша
• Вы хотите кешировать разделы, которые обновляются с разной частотой, независимо
• Вам нужен явный контроль над тем, что кешируется для оптимизации затрат

Пример: Если у вас есть системные инструкции (редко изменяются) и RAG контекст (изменяется ежедневно), вы можете использовать две контрольные точки для их отдельного кеширования.

Добавляют ли контрольные точки кеша дополнительные затраты?

Нет, контрольные точки кеша сами по себе бесплатны. Вы платите только за:

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

Количество контрольных точек не влияет на ценообразование — важно только количество кешированного и прочитанного содержимого.

Каково время жизни кеша?

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

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

Сколько контрольных точек кеша я могу использовать?

Вы можете определить до 4 контрольных точек кеша (используя параметры cache_control) в вашем промпте.

Доступно ли кеширование промптов для всех моделей?

Нет, кеширование промптов в настоящее время доступно только для 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 в ваш API запрос.

Могу ли я использовать кеширование промптов с другими функциями API?

Да, кеширование промптов может использоваться вместе с другими функциями API, такими как использование инструментов и возможности зрения. Однако изменение наличия изображений в промпте или изменение настроек использования инструментов нарушит кеш.

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

Как кеширование промптов влияет на ценообразование?

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

Могу ли я вручную очистить кеш?

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

Как я могу отследить эффективность моей стратегии кеширования?

Вы можете отслеживать производительность кеша, используя поля cache_creation_input_tokens и cache_read_input_tokens в ответе API.

Что может нарушить кеш?

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

Как кеширование промптов обрабатывает конфиденциальность и разделение данных?

Кеширование промптов разработано с сильными мерами конфиденциальности и разделения данных:

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

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

3. Механизм кеширования разработан для поддержания целостности и конфиденциальности каждого уникального разговора или контекста.

4. Безопасно использовать cache_control где угодно в ваших промптах. Для экономической эффективности лучше исключать высоко вариативные части (например, произвольный ввод пользователя) из кеширования.

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

Могу ли я использовать кеширование промптов с Batches API?

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

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

• Соберите набор запросов сообщений, которые имеют общий префикс.
• Отправьте пакетный запрос только с одним запросом, который имеет этот общий префикс и 1-часовой блок кеша. Это будет записано в 1-часовой кеш.
• Как только это завершится, отправьте остальные запросы. Вам придется отслеживать задание, чтобы знать, когда оно завершится.

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

Почему я вижу ошибку `AttributeError: 'Beta' object has no attribute 'prompt_caching'` в Python?

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

Python

python client.beta.prompt_caching.messages.create(...)

Просто используйте:

Python

python client.messages.create(...)

Почему я вижу 'TypeError: Cannot read properties of undefined (reading 'messages')'?

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

TypeScript

client.beta.promptCaching.messages.create(...)

Просто используйте:

client.messages.create(...)