Cache read коштує лише 10% від базової ціни input-токенів. І це не якась маркетингова знижка з зірочкою — це стандартний тариф Anthropic. На типовому продакшн-навантаженні з системним промптом 10 000 токенів і 50 000 запитів на день це означає скорочення input-витрат у 5–10 разів.
Реальний кейс зі знайомої команди: support-бот, що працює з продуктовою документацією на 50 000 токенів, економить понад $4 000 на місяць при правильному налаштуванні кешу. Команда, що витрачає $30k/міс на Claude API, після впровадження кешування + batch API + маршрутизації моделей зазвичай виходить на 20–30% від попередньої вартості. Тобто $60–100k економії на рік. Це той випадок, коли два дні роботи окуповуються вже наступного тижня.
Як працює prompt caching: модель префіксу
Коли ви надсилаєте запит до Claude API, сервер кодує весь промпт з нуля: tools, system, messages — саме в такому порядку. Prompt caching додає опціональну поведінку: ви позначаєте content block спеціальним маркером cache_control, і Anthropic зберігає закодований стан усього від початку запиту до цього блоку включно.
Наступний запит, що починається з тих самих байтів, читає готовий стан з кешу замість повного перерахунку. Ключ кешу — це точний хеш байтів закешованої частини плюс версія моделі. Один зайвий пробіл, оновлений timestamp, переставлені ключі в JSON — і кеш промахується. Так, аж настільки крихко.
6 правил, що визначають cache hit rate
- Префікс має бути ідентичним до байту. Будь-яка різниця нижче breakpoint скидає кеш.
- Кеш зберігається до 4 breakpoints на запит. Сервер автоматично шукає найдовший збіг серед попередніх 20 блоків.
- TTL оновлюється на кожному hit. Активна розмова тримає кеш гарячим без додаткових write-витрат.
- Tool definitions входять у префікс. Додавання нового tool інвалідовує кеш для всіх запитів з tools.
- Порядок ключів у JSON має значення. Деякі мови (Go, Swift) рандомізують порядок ключів — і це тихо ламає кеш.
- Мінімум токенів — інакше тиша. Якщо префікс коротший за поріг, запит проходить, але кешу не буде. Жодної помилки не повертається — і це найпідступніший сценарій.
Мінімальна довжина для кешування (травень 2026)
Якщо ваш префікс коротший за наведений нижче поріг для конкретної моделі, cache_control ігнорується мовчки. cache_creation_input_tokens у відповіді буде 0, і ви тихо платите повну ціну input-токенів.
| Модель | Мінімум токенів для кешування |
|---|
| Claude Opus 4.7, Opus 4.6, Opus 4.5, Haiku 4.5 | 4 096 |
| Claude Sonnet 4.6, Haiku 3.5 | 2 048 |
| Claude Sonnet 4.5, Opus 4.1, Sonnet 4, Sonnet 3.7 | 1 024 |
Це, до речі, найчастіша причина скарг «caching не працює»: розробник додає cache_control до системного промпту на 1 800 токенів і чекає знижки на Opus 4.7 — але префікс не дотягує до 4 096 токенів і кеш не створюється взагалі. І ніхто про це не повідомить — лише рахунок наприкінці місяця.
5-хвилинний TTL vs 1-годинний: що обрати
Anthropic пропонує два режими TTL з різною вартістю запису:
- 5-хвилинний (за замовчуванням): запис коштує 1.25× від базової ціни input-токенів. Підходить для активних чатів і безперервних навантажень.
- 1-годинний (опціональний): запис коштує 2× від базової ціни. Окуповується вже після двох cache reads в межах години.
Cache read в обох випадках коштує однаково — 10% від базової ціни. TTL оновлюється на кожному cache hit, тому активна сесія не платить за повторні writes. Простими словами: якщо до вашого префіксу хоча б раз на 5 хвилин надходить запит, кеш живе вічно (ну, у межах сесії).
Коли точно потрібен 1-годинний TTL у 2026
- Крон-агенти, що запускаються рідше ніж кожні 5 хвилин. Раніше їх ідеально влаштовував 60-хвилинний TTL — тепер кожен запуск робить cache write.
- Batch-пайплайни з нерівномірним навантаженням. Якщо між пакетами проходить 10–30 хвилин, 5-хвилинний кеш просто не доживає.
- Чати з довгими ідлами. Користувацькі сесії з паузами 10+ хвилин платять write premium на кожному другому повідомленні.
- Документ-аналіз з пов'язаними питаннями. Користувач завантажує PDF, ставить питання, читає відповідь 8 хвилин, ставить наступне — 5-хвилинний кеш цього не переживе.
Базовий приклад: prompt caching на Python
Спочатку — встановіть SDK свіжої версії: pip install anthropic>=0.40.0. Ось простий приклад з системним промптом, який кешується:
from anthropic import Anthropic
client = Anthropic()
DOCS = open("product_manual.md").read() # ~50k tokens
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
system=[
{
"type": "text",
"text": "Ти консультант з продуктом Acme. Відповідай стисло й точно.",
},
{
"type": "text",
"text": DOCS,
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{"role": "user", "content": "Як скинути пароль адміністратора?"}
],
)
print(response.usage)
# Перший запит: cache_creation_input_tokens=51234, cache_read_input_tokens=0
# Наступний: cache_creation_input_tokens=0, cache_read_input_tokens=51234
Зверніть увагу на одну деталь, яку часто пропускають: cache_control ставиться на останній блок, який ви хочете закешувати. Кешується все до цього блоку включно — і system prompt, і tool definitions, якщо вони є.
Розширений шаблон: 1-година + 5 хвилин в одному запиті
Для продакшн-агентів типовий шаблон — кешувати статичний префікс на 1 годину і історію розмови на 5 хвилин. Anthropic вимагає, щоб довший TTL ішов до коротшого (саме в такому порядку, не навпаки):
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=2048,
tools=TOOLS, # стабільний список — частина префіксу
system=[
{
"type": "text",
"text": SYSTEM_INSTRUCTIONS + KNOWLEDGE_BASE,
"cache_control": {"type": "ephemeral", "ttl": "1h"},
},
],
messages=[
*conversation_history[:-1],
{
**conversation_history[-1],
"content": [
{
"type": "text",
"text": conversation_history[-1]["content"],
"cache_control": {"type": "ephemeral"}, # 5 хв
}
],
},
],
)
Що тут відбувається на рівні білінгу:
- Перший запит у сесії: одна 1-годинна write (2× ціни) + одна 5-хвилинна write (1.25× ціни).
- Кожен наступний запит у тій самій сесії: cache read префіксу (10%) + 5-хвилинна write на новому повідомленні. Історія розмови читається з кешу.
- Через годину 1-годинний кеш вмирає — наступний запит знову платить 2×, але це раз на годину, а не раз на 5 хвилин.
Pre-warming: тримати кеш гарячим
Якщо ваші запити приходять нерегулярно, але в межах однієї моделі, простий cron-job, що пінгує кеш кожні 4 хвилини, тримає його живим без write-витрат:
def warm_cache():
client.messages.create(
model="claude-opus-4-7",
max_tokens=1,
system=[{"type": "text", "text": SYSTEM_PROMPT,
"cache_control": {"type": "ephemeral"}}],
messages=[{"role": "user", "content": "."}],
)
# Запускайте кожні 4 хвилини у вашому планувальнику
Один read-запит коштує близько 10% від ціни input-токенів і скидає TTL. Для системного промпту 50k токенів на Opus 4.7 це приблизно $0.075 за пінг — або $27 на місяць, якщо тримати кеш живим 24/7. Часто це окуповується вже на десятому реальному запиті. Так, я знаю, $27 здається дрібницею — але для команд, де реальні запити приходять «коли як», це різниця між нормальним hit rate і його повною відсутністю.
5 анти-патернів, що знищують hit rate
1. Динамічні timestamps у системному промпті
Рядок на кшталт "Поточна дата й час: 2026-05-03T14:32:15Z" у системному промпті інвалідовує кеш на кожному запиті. Або винесіть timestamp у user message, або обріжте до дня ("Сьогодні: 2026-05-03") — тоді кеш живе 24 години.
2. Персоналізовані префікси
«Ти допомагаєш {user.name} з компанії {user.company}» у кешованому system prompt означає cache miss для кожного нового користувача. Винесіть персоналізацію в перший user message або тримайте окремий per-user кеш з 1-годинним TTL.
3. Нестабільний whitespace
Якщо ви будуєте промпт через шаблони і десь потрапляє зайвий пробіл або переноса рядка, hit rate може впасти до 20% без видимої причини. Нормалізуйте агресивно: стрипайте, об'єднуйте пробіли, фіксуйте порядок секцій. Це банально, але саме на цьому я особисто згорів двічі.
4. Рандомізований порядок ключів у JSON
Go і Swift за замовчуванням не зберігають порядок ключів при серіалізації. Якщо ви відправляєте tool_use блоки, що формуються через стандартну JSON-серіалізацію цих мов, кеш може ламатися без видимої причини. Рішення — використовувати ordered serializer або сортувати ключі.
5. Часта зміна списку tools
Tool definitions йдуть першими в префіксі. Додаєте новий tool — кеш інвалідовано для всіх agent-запитів, навіть якщо новий tool не використовується. Розгортайте tools батчами, не по одному.
Як виміряти cache hit rate
Anthropic повертає три ключові поля в response.usage:
cache_creation_input_tokens — записано в кеш у цьому запиті (платите 1.25× або 2×).cache_read_input_tokens — прочитано з кешу (платите 10%).input_tokens — звичайні токени, що не кешуються (платите 100%).
Простий wrapper для логування hit rate у production:
import logging
def call_with_metrics(client, **kwargs):
resp = client.messages.create(**kwargs)
u = resp.usage
total_input = u.input_tokens + u.cache_creation_input_tokens + u.cache_read_input_tokens
hit_rate = u.cache_read_input_tokens / total_input if total_input else 0
logging.info(
"claude_call",
extra={
"model": kwargs.get("model"),
"cache_read": u.cache_read_input_tokens,
"cache_write": u.cache_creation_input_tokens,
"uncached_input": u.input_tokens,
"hit_rate": round(hit_rate, 3),
},
)
return resp
Якщо hit rate стабільно нижче 50% — у 90% випадків винна одна з трьох речей: префікс під мінімальним порогом, нестабільний фрагмент (timestamp / id) у кешованому тексті або переставлені повідомлення між turns. Перевіряйте саме в такому порядку — це швидше за всі інші гіпотези разом узяті.
Workspace-level ізоляція кешу (зміна 5 лютого 2026)
З 5 лютого 2026 року Claude API і Azure AI Foundry (preview) перейшли на workspace-level ізоляцію кешу замість organization-level. Це означає: якщо ваша команда використовує кілька workspaces в одній організації, кожен з них має власний кеш — навіть якщо промпти ідентичні до байту.
Що це змінює на практиці:
- Не намагайтеся «ділити» гарячий кеш між dev/staging/prod workspaces — це не працює.
- Якщо у вас було 3 workspaces з однаковим системним промптом, тепер ви платите write premium тричі.
- Amazon Bedrock і Google Vertex AI зберегли organization-level ізоляцію — там поведінка попередня.
Реальні розрахунки: скільки ви заощадите
Розглянемо типовий агент-сапорт на Claude Sonnet 4.6 з системним промптом 30 000 токенів і середньою відповіддю 500 output-токенів. Базові ціни Anthropic (травень 2026): $3 за 1M input, $15 за 1M output.
Без кешування, 10 000 запитів на день:
- Input: 30 000 × 10 000 = 300M токенів × $3 = $900/день
- Output: 500 × 10 000 = 5M × $15 = $75/день
- Разом: ~$29 250/місяць
З prompt caching (5-хв TTL), припускаючи hit rate 95%:
- Cache writes (5%): 15M × $3.75 (1.25×) = $56.25/день
- Cache reads (95%): 285M × $0.30 (0.1×) = $85.50/день
- Output: $75/день
- Разом: ~$6 500/місяць
Економія — ~$22 700/місяць, тобто 78% від первісної суми. Окупність впровадження — буквально години роботи. На моєму досвіді більшість команд недооцінюють цей ефект, поки не побачать перший «після»-рахунок.
Чек-ліст впровадження prompt caching у 2026
- Перевірте мінімум токенів для вашої моделі (4 096 для Opus 4.7 і Haiku 4.5).
- Винесіть усі timestamps, user IDs, session IDs з кешованої частини.
- Поставте
cache_control в кінці системного промпту або великих документів.
- Для агентів зі стабільним префіксом і змінним messages — використайте 1-годинний TTL на префіксі + 5-хвилинний на історії.
- Залогуйте
cache_read_input_tokens та cache_creation_input_tokens — без метрик ви не побачите проблем.
- Якщо hit rate < 70% — перевірте whitespace, порядок ключів, динамічні фрагменти.
- Якщо у вас крон-агент рідше 5 хвилин — або pre-warm кешу, або 1-годинний TTL.
- Не забувайте: workspace ізоляція з лютого 2026 — кеш не ділиться між workspaces.
Часті питання (FAQ)
Чи працює prompt caching з tool use?
Так. Tool definitions входять у префікс і кешуються разом з ним. Просто пам'ятайте: будь-яка зміна списку tools (додавання, видалення, редагування description) інвалідує кеш для всіх запитів з тими ж tools. Намагайтеся розгортати зміни tools пакетами, а не по одному.
Скільки коштує cache write проти cache read?
Cache write коштує 1.25× базової ціни input для 5-хвилинного TTL і 2× для 1-годинного. Cache read — 0.1× базової ціни в обох випадках. Тобто 5-хвилинний кеш окуповується вже після одного read, 1-годинний — після двох.
Що буде, якщо мій промпт коротший за мінімум токенів?
Запит просто пройде без кешування. cache_control буде проігноровано без помилки, у відповіді cache_creation_input_tokens буде 0. Ви тихо платите повну ціну input. Перевіряйте usage у логах — це найпоширеніша причина «cache не працює».
Чи можна використовувати prompt caching через Amazon Bedrock або Google Vertex AI?
Так, обидві платформи підтримують prompt caching для Claude-моделей з аналогічним API. Ключова відмінність: Bedrock і Vertex зберегли organization-level ізоляцію кешу, тоді як прямий Claude API і Azure AI Foundry перейшли на workspace-level ізоляцію в лютому 2026.
Скільки cache breakpoints можна поставити в одному запиті?
До 4 breakpoints. Сервер автоматично перевіряє hit на кожному з них і використовує найдовший збіг префіксу. У більшості випадків достатньо одного breakpoint у кінці статичного контенту — додаткові потрібні, лише коли ви маєте кілька рівнів повторюваності (наприклад, базовий промпт + per-tenant конфіг + per-session історія).
Чи зберігається кеш між моделями?
Ні. Ключ кешу включає версію моделі. Перехід з claude-sonnet-4-6 на claude-opus-4-7 повністю скидає весь кеш — наступний запит платитиме write premium з нуля. Враховуйте це при A/B тестуванні моделей.
Підсумок
У 2026 році prompt caching перестав бути «приємним бонусом» і став обов'язковою практикою для будь-якого продакшн-навантаження з Claude API. Зі зміною TTL на 5 хвилин старі реалізації потребують перегляду: 1-годинний TTL для статичних префіксів, нормалізація whitespace, винесення динамічних фрагментів, моніторинг hit rate.
Дотримуючись описаних патернів, ви реально вийдете на 80–95% cache hit rate і скоротите input-витрати у 5–10 разів — без жодних компромісів щодо якості відповідей моделі. І чесно? Це одна з тих рідкісних оптимізацій, де результат настільки очевидний, що не потребує A/B тесту.
