Если в каждом запросе ты гонишь один и тот же большой кусок — инструкцию боту, каталог товаров, правила возврата — платить за него полную цену каждый раз глупо. Prompt caching позволяет закэшировать этот префикс: первый раз платишь чуть дороже (запись ~1.25×), а дальше читаешь из кэша почти бесплатно (~0.1× от цены входа).
Главное правило: кэш — это префикс
Запрос склеивается в фиксированном порядке: tools → system → messages. Кэш работает по совпадению с начала. Любое изменение в префиксе сбрасывает кэш для всего, что идёт после. Поэтому стабильное (инструкция бота, каталог) — в начало, изменчивое (вопрос клиента) — в конец.
Ставишь cache_control на последний стабильный блок:
resp = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
system=[
{
"type": "text",
"text": BIG_INSTRUKCIYA_I_KATALOG,
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "Где мой заказ 4821?"}],
)
Как проверить, что сработало
Смотри в usage ответа:
"usage": {
"input_tokens": 18,
"cache_creation_input_tokens": 2360,
"cache_read_input_tokens": 0
}
Первый запрос пишет кэш — растёт cache_creation_input_tokens. На втором с тем же префиксом должно появиться cache_read_input_tokens > 0 — значит, читаем из кэша и экономим.
Важно
Если cache_read_input_tokens упорно ноль — в префиксе что-то меняется на каждом запросе. Частые виновники: дата/время или datetime.now() в system, случайный id, несортированный JSON. Вынеси изменчивое в конец messages.
Кэш живёт около 5 минут и привязан к модели — сменил модель, и первый запрос снова пишет кэш заново.