Руководство по контекстному кэшу Claude

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

export API_KEY="ваш API-ключ"

В примерах этого руководства используется claude-sonnet-5. Сведения о поддержке контекстного кэша другими моделями см. в описании моделей на платформе.

Сценарии использования

Если в нескольких запросах многократно передаётся один и тот же большой фрагмент контента, можно кэшировать его стабильный префикс, например:

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

Контекстный кэш подходит для запросов, в которых «начальный контент остаётся неизменным, а последний вопрос постоянно меняется».

Claude Messages API

Кэш на 5 минут

Добавьте cache_control в content block, который требуется кэшировать:

curl "https://api.apimart.ai/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Здесь размещается длинный префикс для многократного использования……",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Ответьте на вопрос на основе приведённого выше контента."
      }
    ]
  }'

system должен быть массивом content block. В строковую форму system нельзя добавить cache_control.

Если ttl не указан, по умолчанию срок действия кэша составляет 5 минут.

Кэш на 1 час

Чтобы использовать кэш на 1 час, добавьте заголовок запроса anthropic-beta и задайте для ttl значение 1h:

curl "https://api.apimart.ai/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Здесь размещается длинный префикс для многократного использования……",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Ответьте на вопрос на основе приведённого выше контента."
      }
    ]
  }'

Поддерживаемые значения TTL:

TTL	Значение
`5m`	кэширование на 5 минут; это значение используется, если `ttl` не указан
`1h`	кэширование на 1 час; также требуется соответствующий заголовок запроса `anthropic-beta`

Поля использования в ответе

Claude Messages API раздельно возвращает в usage токены обычного ввода, записи в кэш и чтения из кэша:

{
  "usage": {
    "input_tokens": 23,
    "cache_creation_input_tokens": 2619,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 2619,
      "ephemeral_1h_input_tokens": 0
    },
    "output_tokens": 24
  }
}

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

input_tokens
+ cache_creation_input_tokens
+ cache_read_input_tokens

Эти три значения не пересекаются. При первом запросе обычно возвращается cache_creation_input_tokens > 0. При повторной отправке того же стабильного префикса должно возвращаться cache_read_input_tokens > 0.

OpenAI-совместимый API

Пример запроса

При использовании кэша через /v1/chat/completions формат cache_control почти не отличается от Claude Messages API:

curl "https://api.apimart.ai/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "Здесь размещается длинный префикс для многократного использования……",
            "cache_control": {
              "type": "ephemeral"
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "Ответьте на вопрос на основе приведённого выше контента."
      }
    ]
  }'

Кэш на 1 час

OpenAI-совместимый формат также поддерживает кэширование на 1 час. Добавьте в запрос заголовок anthropic-beta и задайте ttl: "1h" в cache_control:

-H "anthropic-beta: extended-cache-ttl-2025-04-11"

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

`content` должен быть массивом

В OpenAI-совместимом формате cache_control должен находиться в конкретном content block. Его нельзя добавить к сообщению, в котором контент задан строкой.

{
  "role": "system",
  "content": "Здесь размещается длинный префикс……",
  "cache_control": {
    "type": "ephemeral"
  }
}

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

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "Здесь размещается длинный префикс……",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

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

Кэширование content block пользователя или ассистента

cache_control также можно добавить к content block в сообщении user или assistant, чтобы кэшировать длинный документ или префикс многошагового диалога:

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Здесь размещается длинный документ для многократного использования……",
      "cache_control": {
        "type": "ephemeral"
      }
    },
    {
      "type": "text",
      "text": "Кратко изложите три ключевых положения приведённого выше документа."
    }
  ]
}

Разделите стабильный контент и текущий вопрос на разные content block и добавьте cache_control только к стабильному content block.

Поля использования в ответе

В OpenAI-совместимом формате для данных об использовании кэша применяются другие поля:

{
  "usage": {
    "prompt_tokens": 1942,
    "completion_tokens": 22,
    "prompt_tokens_details": {
      "cached_tokens": 1921,
      "cache_write_tokens": 0
    },
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

Соответствие полей:

Значение	Claude Messages API	OpenAI-совместимый API
Общий ввод	сумма трёх полей ввода	`prompt_tokens`
Чтение из кэша	`cache_read_input_tokens`	`prompt_tokens_details.cached_tokens`
Общее поле записи в кэш	`cache_creation_input_tokens`	`prompt_tokens_details.cache_write_tokens` (заполняется только при отсутствии детализации по TTL)
Запись в 5-минутный кэш	`cache_creation.ephemeral_5m_input_tokens`	`claude_cache_creation_5_m_tokens`
Запись в 1-часовой кэш	`cache_creation.ephemeral_1h_input_tokens`	`claude_cache_creation_1_h_tokens`
Вывод	`output_tokens`	`completion_tokens`

Если prompt_tokens_details.cache_write_tokens равен 0, также проверьте claude_cache_creation_5_m_tokens и claude_cache_creation_1_h_tokens. При наличии полей с детализацией по TTL объём записи в кэш возвращается в соответствующем поле.

В именах claude_cache_creation_5_m_tokens и claude_cache_creation_1_h_tokens цифры и единицы разделены символами подчёркивания. Используйте имена полей в точности так, как они возвращены в ответе.

OpenAI-совместимый интерфейс может вернуть потоковый SSE-ответ, даже если stream: true не был явно передан. Клиент должен поддерживать разбор chat.completion.chunk; сведения об использовании находятся в последнем блоке данных, содержащем usage.

Условия попадания в кэш

Префикс достигает минимальной длины

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

Префикс полностью совпадает на уровне байтов

Текст, пробелы, переводы строк и порядок content block в префиксе кэша должны совпадать. Не добавляйте в стабильный префикс отметки времени, случайные ID, счётчики запросов или другой динамический контент.

Запрос не вызывает отказ модели

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

Срок действия кэша не истёк

Срок действия кэша составляет 5 минут или 1 час и отсчитывается от последнего обращения. Попадание в кэш обновляет срок действия.

Тарифицируемое использование

Использование кэша делится на три категории:

Использование	Когда возникает
Запись в кэш	при первоначальном создании кэша
Чтение из кэша	когда последующий запрос попадает в кэш
Обычный ввод	ввод за пределами префикса кэша

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

Минимальный воспроизводимый пример

Следующий скрипт создаёт достаточно длинный стабильный префикс и дважды подряд отправляет один и тот же запрос. Во втором ответе должно возвращаться cache_read_input_tokens > 0.

python3 - <<'PY' > /tmp/claude-cache-request.json
import json

paragraph = (
    "Кэширование промпта сохраняет префикс запроса, чтобы последующие запросы "
    "могли повторно использовать побайтово идентичный префикс без повторной обработки. "
)

system_text = (
    "Вы — помощник по работе с документацией. Ниже приведены справочные материалы.\n\n"
    + paragraph * 40
)

print(json.dumps({
    "model": "claude-sonnet-5",
    "max_tokens": 32,
    "system": [{
        "type": "text",
        "text": system_text,
        "cache_control": {"type": "ephemeral"}
    }],
    "messages": [{
        "role": "user",
        "content": "Одним предложением укажите, что должно оставаться неизменным."
    }]
}))
PY

for request_number in 1 2; do
  echo "Запрос ${request_number}"
  curl -s "https://api.apimart.ai/v1/messages" \
    -H "x-api-key: $API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    --data @/tmp/claude-cache-request.json \
  | python3 -c "import json, sys; print(json.load(sys.stdin)['usage'])"
done

Ожидаемый результат:

Запрос 1: cache_creation_input_tokens > 0, cache_read_input_tokens = 0
Запрос 2: cache_creation_input_tokens = 0, cache_read_input_tokens > 0

Контрольный список для диагностики

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

равен ли stop_reason значению refusal
достигает ли префикс кэша минимального количества токенов, требуемого моделью
полностью ли совпадает стабильный префикс в двух запросах на уровне байтов
является ли content массивом в OpenAI-совместимом формате
находится ли cache_control в конкретном content block
заданы ли для 1-часового кэша одновременно ttl: "1h" и соответствующий заголовок запроса anthropic-beta
не истёк ли TTL кэша
используются ли поля данных о кэше, соответствующие текущему интерфейсу

Обзор

Текстовая серия

Серия изображений

Видеосерия

Аудиосерия

Серия модерации

Управление загрузками

Управление задачами

Управление аккаунтом

Руководство по контекстному кэшу Claude

Сценарии использования

Claude Messages API

Кэш на 5 минут

Кэш на 1 час

Поля использования в ответе

OpenAI-совместимый API

Пример запроса

Кэш на 1 час

`content` должен быть массивом

Кэширование content block пользователя или ассистента

Поля использования в ответе

Условия попадания в кэш

Префикс достигает минимальной длины

Префикс полностью совпадает на уровне байтов

Запрос не вызывает отказ модели

Срок действия кэша не истёк

Тарифицируемое использование

Минимальный воспроизводимый пример

Контрольный список для диагностики

​Сценарии использования

​Claude Messages API

​Кэш на 5 минут

​Кэш на 1 час

​Поля использования в ответе

​OpenAI-совместимый API

​Пример запроса

​Кэш на 1 час

​content должен быть массивом

​Кэширование content block пользователя или ассистента

​Поля использования в ответе

​Условия попадания в кэш

​Префикс достигает минимальной длины

​Префикс полностью совпадает на уровне байтов

​Запрос не вызывает отказ модели

​Срок действия кэша не истёк

​Тарифицируемое использование

​Минимальный воспроизводимый пример

​Контрольный список для диагностики

Сценарии использования

Claude Messages API

Кэш на 5 минут

Кэш на 1 час

Поля использования в ответе

OpenAI-совместимый API

Пример запроса

Кэш на 1 час

`content` должен быть массивом

Кэширование content block пользователя или ассистента

Поля использования в ответе

Условия попадания в кэш

Префикс достигает минимальной длины

Префикс полностью совпадает на уровне байтов

Запрос не вызывает отказ модели

Срок действия кэша не истёк

Тарифицируемое использование

Минимальный воспроизводимый пример

Контрольный список для диагностики