Кэширование подсказок

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

Как работает кэширование подсказок

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

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

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

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

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

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

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

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

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

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

В этом примере весь текст «Гордости и предубеждения» кэшируется с помощью параметра 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 (устарела)

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

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

В этом примере весь текст «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: Количество входных токенов, которые не были прочитаны из кэша или использованы для создания кэша (т.е. токены после последней точки разрыва кэша).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Длительность кэша в 1 час

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

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

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

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

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

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

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

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