Руководство Claude по кэшированию промптов

​

В одном предложении

​

Зачем это нужно — обратите внимание на коэффициенты

• TTL 5 мин: достаточно всего 2 повторных использований одного и того же префикса, чтобы окупить затраты (1.25 + 0.1 = 1.35, что дешевле 2.0 для двух запросов без кэша).
• TTL 1 час: 3 повторных использования для выхода на окупаемость (2 + 0.2 = 2.2, что дешевле 3.0).

​

Когда подходит

• Один и тот же длинный системный prompt, вызываемый многократно (агенты, чат-боты)
• Многоэтапные диалоги (каждая предыдущая реплика становится повторно используемым префиксом)
• Пакетная обработка одного документа (например, 50 вопросов к одному договору)
• RAG, где неизменные извлеченные фрагменты формируют префикс

​

Когда не подходит

• Каждый prompt отличается с самого первого символа
• Весь объём слишком мал и не достигает минимального порога для модели (см. ниже)
• Чат-клиенты, которые заново собирают прикрепленные файлы на каждой реплике (см. «Изображения и файлы тоже кэшируются» ниже)

​

Три обязательных требования

​

1. Явный маркер cache_control

# ❌ Wrong: plain string is never cached
"content": "a long passage..."

# ✅ Right: content block + cache_control
"content": [
    {
        "type": "text",
        "text": "a long passage...",
        "cache_control": {"type": "ephemeral"},
    },
    {"type": "text", "text": "the question"},
]

​

2. Длина должна превышать минимальное значение для модели

​

3. Префикс должен побайтно совпадать

# ❌ Wrong: question first means the prefix changes every turn; never hits
content = [
    {"type": "text", "text": "Please answer this question: " + question},  # volatile
    {"type": "text", "text": long_doc, "cache_control": {"type": "ephemeral"}},
]

# ✅ Right: long stable content first with marker, question after
content = [
    {"type": "text", "text": long_doc, "cache_control": {"type": "ephemeral"}},  # stable
    {"type": "text", "text": question},                                            # volatile
]

​

Минимальный запускаемый пример

import json, os, requests

URL = "https://api.apiyi.com/v1/messages"
KEY = os.environ["APIYI_API_KEY"]
HEADERS = {
    "content-type": "application/json",
    "x-api-key": KEY,
    "anthropic-version": "2023-06-01",
}

# Must be long enough. Sonnet 4.6 needs >= 1,024 tokens (~770+ English words).
LONG_TEXT = open("long_document.txt").read()


def ask(question: str, label: str):
    payload = {
        "model": "claude-sonnet-4-6",
        "max_tokens": 256,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": LONG_TEXT, "cache_control": {"type": "ephemeral"}},
                {"type": "text", "text": question},
            ],
        }],
    }
    r = requests.post(URL, headers=HEADERS, data=json.dumps(payload), timeout=120)
    u = r.json().get("usage", {})
    print(f"[{label}] input={u.get('input_tokens')} "
          f"write={u.get('cache_creation_input_tokens')} "
          f"read={u.get('cache_read_input_tokens')}")


ask("Summarize the main idea", "1st")  # expect write>0, read=0
ask("Give 3 keywords",        "2nd")    # expect write=0, read>0

[1st] input=35 write=6512 read=0
[2nd] input=22 write=0    read=6512

​

Как определить попадание в кэш — три поля usage

​

Самые распространенные ошибки

​

Изображения и файлы тоже кэшируются — но в сценариях с вложениями попадания в кэш менее стабильны

​

В чём различия между двумя сценариями

​

Восстановление частоты попадания в кэш в сценариях с вложениями

1. Размещайте вложения первыми и в фиксированном порядке — это самый большой и стабильный контент, поэтому ему самое место в префиксе
2. Кодируйте каждое вложение один раз и повторно используйте ту же строку base64; не считывайте и не кодируйте файл заново на каждой реплике (повторное кодирование не гарантирует получение идентичных байтов)
3. Не меняйте порядок блоков контента между репликами, особенно избегайте вариантов вроде «на этой реплике изображение первое, на следующей — последнее»
4. Размещайте cache_control после вложений, чтобы они попали внутрь кэшируемого префикса
5. Избегайте добавления или удаления вложений в середине диалога — добавление или удаление даже одного изображения делает недействительным весь префикс после него

​

Продвинутое: многоходовые диалоги

# When constructing the Nth turn's request
messages[-1]["content"][-1]["cache_control"] = {"type": "ephemeral"}

• Не более 4 cache_control точек разрыва на запрос.
• Окно поиска префикса у каждой точки разрыва — не более 20 блоков контента назад; все, что старше, не будет учитываться при попадании в кэш. Иными словами, в очень длинных диалогах отметка только последнего хода не покроет всю предыдущую историю.

​

Об APIYI и кэшировании

1. При первом запросе, usage.cache_creation_input_tokens > 0 (запись выполнена).
2. Через несколько секунд отправьте тот же префикс еще раз — вы должны увидеть usage.cache_read_input_tokens > 0 (попадание).
3. На панели тарификации будут отдельно указаны cache writes и cache reads с теми же официальными коэффициентами (1.25× / 2× / 0.1×).

​

Итоги

​

Связанные ссылки

• Родительская страница: Claude API Basics
• Руководства по настройке клиента: Claude Code integration · Cherry Studio integration
• Получение / управление token: https://api.apiyi.com/token
• Официальная документация Anthropic: platform.claude.com/docs/en/build-with-claude/prompt-caching