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

Кэширование промптов — это мощная функция, которая оптимизирует использование 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-sonnet-4-5",
    "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}

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

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

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

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

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

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

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

Цены

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

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

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

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

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

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

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

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

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

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

Три основных принципа:

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

2. Обратная последовательная проверка: Система проверяет попадания в кэш, работая в обратном направлении от вашей явной точки разрыва, проверяя каждый предыдущий блок в обратном порядке. Это гарантирует, что вы получите самое длинное возможное попадание в кэш.

3. Окно обратного просмотра в 20 блоков: Система проверяет только до 20 блоков перед каждой явной точкой разрыва cache_control. После проверки 20 блоков без совпадения она прекращает проверку и переходит к следующей явной точке разрыва (если она есть).

Пример: Понимание окна обратного просмотра

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Понимание затрат на точки разрыва кэша

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

• Записи в кэш: Когда новое содержимое записывается в кэш (на 25% больше, чем базовые входные токены для TTL 5 минут)
• Чтения из кэша: Когда используется кэшированное содержимое (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: Количество входных токенов, которые не были прочитаны из кэша или использованы для создания кэша (т.е. токены после последней точки разрыва кэша).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

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

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

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

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

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

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

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

Если вы испытываете неожиданное поведение:

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

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

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

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

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

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

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

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

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

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

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

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

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

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

• Точное совпадение: Попадания в кэш требуют 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: Количество токенов на самом высоком блоке cache_control на 1 час после A (или равно A, если их нет).
3. Позиция C: Количество токенов на последнем блоке cache_control.

Вам будет выставлен счёт за:

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

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

Примеры кэширования подсказок

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

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

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

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