Loading...
  • Разработка
  • Администрирование
  • Модели и цены
  • Клиентские SDK
  • Справочник API
Search...
⌘K
Log in
Кэширование промптов
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

Solutions

  • AI agents
  • Code modernization
  • Coding
  • Customer support
  • Education
  • Financial services
  • Government
  • Life sciences

Partners

  • Amazon Bedrock
  • Google Cloud's Vertex AI

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Company

  • Anthropic
  • Careers
  • Economic Futures
  • Research
  • News
  • Responsible Scaling Policy
  • Security and compliance
  • Transparency

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Help and security

  • Availability
  • Status
  • Support
  • Discord

Terms and policies

  • Privacy policy
  • Responsible disclosure policy
  • Terms of service: Commercial
  • Terms of service: Consumer
  • Usage policy
Разработка/Управление контекстом

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

Оптимизируйте использование API с помощью кэширования подсказок, которое позволяет возобновлять работу с определённых префиксов в ваших подсказках.

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

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Есть два способа включить кэширование подсказок:

  • Автоматическое кэширование: Добавьте одно поле cache_control на верхний уровень вашего запроса. Система автоматически применяет точку разрыва кэша к последнему кэшируемому блоку и перемещает её вперёд по мере роста разговоров. Лучше всего подходит для многоходовых разговоров, где растущая история сообщений должна кэшироваться автоматически.
  • Явные точки разрыва кэша: Поместите cache_control непосредственно на отдельные блоки контента для точного управления тем, что именно кэшируется.

Самый простой способ начать — это автоматическое кэширование:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

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


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

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

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

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

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

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

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

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

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

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


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

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

ModelBase Input Tokens5m Cache Writes1h Cache WritesCache Hits & RefreshesOutput Tokens
Claude Opus 4.7$5 / MTok$6.25 / MTok$10 / MTok$0.50 / MTok$25 / MTok
Claude Opus 4.6$5 / MTok$6.25 / MTok$10 / MTok$0.50 / MTok$25 / MTok
Claude Opus 4.5$5 / MTok$6.25 / MTok$10 / MTok$0.50 / MTok$25 / MTok
Claude Opus 4.1$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Opus 4 (deprecated)$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Sonnet 4.6$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 4.5$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 4 (deprecated)$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Haiku 4.5$1 / MTok$1.25 / MTok$2 / MTok$0.10 / MTok$5 / MTok
Claude Haiku 3.5 (retired, except on Bedrock and Vertex AI)$0.80 / MTok$1 / MTok$1.60 / MTok$0.08 / MTok$4 / MTok

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

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

Эти множители складываются с другими модификаторами ценообразования, такими как скидка Batch API и местоположение данных. Полные сведения см. в разделе ценообразование.


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

Кэширование подсказок (как автоматическое, так и явное) поддерживается на всех активных моделях Claude.


Автоматическое кэширование

Автоматическое кэширование — это самый простой способ включить кэширование подсказок. Вместо размещения cache_control на отдельных блоках контента добавьте одно поле cache_control на верхний уровень тела вашего запроса. Система автоматически применяет точку разрыва кэша к последнему кэшируемому блоку.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())

Как автоматическое кэширование работает в многоходовых разговорах

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

ЗапросКонтентПоведение кэша
Запрос 1Система
+ Пользователь(1) + Помощник(1)
+ Пользователь(2) ◀ кэш
Всё записано в кэш
Запрос 2Система
+ Пользователь(1) + Помощник(1)
+ Пользователь(2) + Помощник(2)
+ Пользователь(3) ◀ кэш
Система через Пользователь(2) читаются из кэша;
Помощник(2) + Пользователь(3) записаны в кэш
Запрос 3Система
+ Пользователь(1) + Помощник(1)
+ Пользователь(2) + Помощник(2)
+ Пользователь(3) + Помощник(3)
+ Пользователь(4) ◀ кэш
Система через Пользователь(3) читаются из кэша;
Помощник(3) + Пользователь(4) записаны в кэш

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

Поддержка TTL

По умолчанию автоматическое кэширование использует TTL в 5 минут. Вы можете указать TTL в 1 час за 2x базовую цену входных токенов:

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

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

Автоматическое кэширование совместимо с явными точками разрыва кэша. При совместном использовании автоматическая точка разрыва кэша использует один из 4 доступных слотов точек разрыва.

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

{
  "model": "claude-opus-4-7",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

Что остаётся неизменным

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

Граничные случаи

  • Если последний блок уже имеет явный cache_control с тем же TTL, автоматическое кэширование не имеет эффекта.
  • Если последний блок имеет явный cache_control с другим TTL, API возвращает ошибку 400.
  • Если уже существуют 4 явные точки разрыва на уровне блоков, API возвращает ошибку 400 (нет свободных слотов для автоматического кэширования).
  • Если последний блок не подходит в качестве цели автоматической точки разрыва кэша, система молча проходит назад, чтобы найти ближайший подходящий блок. Если ничего не найдено, кэширование пропускается.

Автоматическое кэширование доступно на Claude API и Azure AI Foundry (предварительная версия). Поддержка Amazon Bedrock и Google Vertex AI будет добавлена позже.


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

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

Структурирование вашей подсказки

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

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

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

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

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

  1. Записи в кэш происходят только в вашей точке разрыва. Отметив блок с помощью cache_control, вы записываете ровно одну запись в кэш: хеш префикса, заканчивающегося в этом блоке. Система не записывает записи для какой-либо более ранней позиции. Поскольку хеш кумулятивный, охватывающий всё вплоть до и включая точку разрыва, изменение любого блока в точке разрыва или до неё создаёт другой хеш при следующем запросе.

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

  3. Окно обратного просмотра составляет 20 блоков. Система проверяет максимум 20 позиций на точку разрыва, считая саму точку разрыва первой. Если система не найдёт соответствующую запись в этом окне, проверка останавливается (или возобновляется со следующей явной точки разрыва, если она есть).

Пример: Обратный просмотр в растущем разговоре

Вы добавляете новые блоки в каждый ход и устанавливаете cache_control на финальный блок каждого запроса:

  • Ход 1: 10 блоков, точка разрыва на блоке 10. Нет предыдущих записей в кэше. Система записывает запись на блоке 10.
  • Ход 2: 15 блоков, точка разрыва на блоке 15. На блоке 15 нет записи, поэтому система проходит назад к блоку 10 и находит запись из хода 1. Попадание в кэш на блоке 10; система обрабатывает только блоки 11–15 заново и записывает новую запись на блоке 15.
  • Ход 3: 35 блоков, точка разрыва на блоке 35. Система проверяет 20 позиций (блоки 35–16) и ничего не находит. Запись из хода 2 на блоке 15 находится на одну позицию вне окна, поэтому нет попадания в кэш. Добавление второй точки разрыва на блоке 15 запускает второе окно обратного просмотра там, которое находит запись из хода 2.

Распространённая ошибка: Точка разрыва на контенте, который изменяется в каждом запросе

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

  • Запрос 1: Запись в кэш на блоке 6. Хеш включает временную метку.
  • Запрос 2: Временная метка отличается, поэтому хеш префикса на блоке 6 отличается. Обратный просмотр проходит через блоки 5, 4, 3, 2 и 1, но система никогда не записывала запись ни в одной из этих позиций. Нет попадания в кэш. Вы платите за свежую запись в кэш при каждом запросе и никогда не получаете чтение.

Обратный просмотр не находит стабильный контент позади вашей точки разрыва и не кэширует его. Он находит записи, которые предыдущие запросы уже записали, а записи происходят только в точках разрыва. Переместите cache_control на блок 5, последний блок, который остаётся неизменным между запросами, и каждый последующий запрос будет читать кэшированный префикс. Автоматическое кэширование попадает в ту же ловушку: оно размещает точку разрыва на последнем кэшируемом блоке, который в этой структуре — это блок, который изменяется в каждом запросе, поэтому вместо этого используйте явную точку разрыва на блоке 5.

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

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

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

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

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

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

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

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

Добавление большего количества точек разрыва cache_control не увеличивает ваши затраты — вы всё равно платите одинаково в зависимости от того, какой контент фактически кэшируется и читается. Точки разрыва просто дают вам контроль над тем, какие разделы могут кэшироваться независимо.


Стратегии кэширования и рекомендации

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Что делает кэш недействительным

Изменения кэшированного контента могут сделать часть или весь кэш недействительным.

Как описано в разделе Структурирование вашей подсказки, кэш следует иерархии: tools → system → messages. Изменения на каждом уровне делают недействительным этот уровень и все последующие уровни.

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

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

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

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

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

Понимание разбивки токенов

Поле input_tokens представляет только токены, которые идут после последней точки разрыва кэша в вашем запросе — не все входные токены, которые вы отправили.

Для расчёта общего количества входных токенов:

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Пространственное объяснение:

  • cache_read_input_tokens = токены перед точкой разрыва уже кэшированы (чтения)
  • cache_creation_input_tokens = токены перед точкой разрыва кэшируются сейчас (записи)
  • input_tokens = токены после вашей последней точки разрыва (не подходят для кэша)

Пример: Если у вас есть запрос с 100 000 токенов кэшированного контента (прочитано из кэша), 0 токенов нового контента, кэшируемого, и 50 токенов в вашем сообщении пользователя (после точки разрыва кэша):

  • cache_read_input_tokens: 100 000
  • cache_creation_input_tokens: 0
  • input_tokens: 50
  • Всего обработано входных токенов: 100 050 токенов

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

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

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

Автоматическое кеширование наряду с другим содержимым: Хотя блоки размышления не могут быть явно отмечены с помощью 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],
Пользователь: [Text response, cache=True]
# Блок пользователя, не являющийся результатом инструмента, обозначает новый цикл помощника и все предыдущие блоки размышления удаляются из контекста
# Этот запрос обрабатывается так, как если бы блоки размышления никогда не были присутствующими

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

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

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

Начиная с 5 февраля 2026 года, кеширование подсказок будет использовать изоляцию на уровне рабочей области вместо изоляции на уровне организации. Кеши будут изолированы для каждой рабочей области, обеспечивая разделение данных между рабочими областями в одной организации. Это изменение применяется к Claude API и Azure AI Foundry (предварительная версия); Amazon Bedrock и Google Vertex AI будут сохранять изоляцию кеша на уровне организации. Если вы используете несколько рабочих областей, проверьте вашу стратегию кеширования, чтобы учесть это изменение.

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

Для использования расширенного кеша включите ttl в определение cache_control следующим образом:

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

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

Output
{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "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 API определяет три места выставления счётов в вашей подсказке:

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

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

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

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

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


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

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

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

Хранение данных

Кэширование подсказок (как автоматическое, так и явное) имеет право на ZDR. Anthropic не хранит исходный текст ваших подсказок или ответов Claude.

Представления KV (ключ-значение) кэша и криптографические хэши кэшированного контента хранятся только в памяти и не сохраняются на диск. Кэшированные записи имеют минимальное время жизни 5 минут (стандартное) или 60 минут (расширенное), после чего они оперативно, хотя и не мгновенно, удаляются. Записи кэша изолированы между организациями.

Для соответствия ZDR по всем функциям см. API и хранение данных.


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

Was this page helpful?

  • Как работает кэширование подсказок
  • Ценообразование
  • Поддерживаемые модели
  • Автоматическое кэширование
  • Как автоматическое кэширование работает в многоходовых разговорах
  • Поддержка TTL
  • Комбинирование с кэшированием на уровне блоков
  • Что остаётся неизменным
  • Граничные случаи
  • Явные точки разрыва кэша
  • Структурирование вашей подсказки
  • Понимание затрат на точки разрыва кэша
  • Стратегии кэширования и рекомендации
  • Ограничения кэширования
  • Что может быть кэшировано
  • Что не может быть кэшировано
  • Что делает кэш недействительным
  • Отслеживание производительности кэша
  • Кеширование с блоками размышления
  • Хранение и совместное использование кеша
  • Лучшие практики для эффективного кеширования
  • Оптимизация для различных вариантов использования
  • Устранение неполадок при распространённых проблемах
  • Длительность кеша в 1 час
  • Когда использовать кеш на 1 час
  • Смешивание различных TTL
  • Примеры кэширования подсказок
  • Хранение данных
  • Часто задаваемые вопросы