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

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    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'."}],
)
print(response.usage.model_dump_json())

# Call the model again with the same inputs up to the cache checkpoint
response = client.messages.create(.....)
print(response.usage.model_dump_json())

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.messages.create({
  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'."
    }
  ]
});
console.log(response.usage);

// Call the model again with the same inputs up to the cache checkpoint
const new_response = await client.messages.create(...)
console.log(new_response.usage);

import java.util.List;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.TextBlockParam;

public class PromptCachingExample {

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
                .model(Model.CLAUDE_OPUS_4_20250514)
                .maxTokens(1024)
                .systemOfTextBlockParams(List.of(
                        TextBlockParam.builder()
 .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")
 .build(),
                        TextBlockParam.builder()
 .text("<the entire contents of 'Pride and Prejudice'>")
 .cacheControl(CacheControlEphemeral.builder().build())
 .build()
                ))
                .addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
                .build();

        Message message = client.messages().create(params);
        System.out.println(message.usage());
    }
}

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

Цены

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

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

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

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

• 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 блоков

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

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

• 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

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

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

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

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

Запрос 3:
Пользователь: ["Какая погода в Париже?"],
Ассистент: [thinking_block_1] + [tool_use блок 1],
Пользователь: [tool_result_1, cache=True],
Ассистент: [thinking_block_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 минут.
• Когда вы хотите улучшить использование вашего ограничения скорости, так как попадания в кэш не вычитаются из вашего ограничения скорости.

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

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

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

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

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