Prompt caching w Claude: kiedy 10× tańsze tokeny naprawdę się opłacają

Zapytanie do Claude z 8-tysięcznym system promptem kosztuje cię tyle samo za każdym razem — chyba że włączysz cache. Wtedy drugie i każde kolejne zapytanie kosztuje dziesięć razy mniej. Brzmi prosto. W praktyce jest kilka pułapek, które potrafią zamienić oszczędność w stratę.

Co to jest prompt caching i kiedy zaczyna się opłacać

Prompt caching pozwala Anthropic API zapamiętać prefix twojego promptu między kolejnymi zapytaniami. Zamiast przesyłać i przeliczać ten sam system prompt za każdym razem, model odczytuje go z pamięci podręcznej. Ty płacisz ułamek ceny.

Mechanizm: 10% read, 125% write

Pierwsze zapytanie z cache'owanym segmentem kosztuje więcej niż zwykle — 125% standardowej ceny inputu, czyli 25% premium za zapis do cache [1]. Każde kolejne odczytanie tego samego segmentu kosztuje już tylko 10% ceny bazowej. Domyślny czas życia cache (TTL) wynosi 5 minut. Jeśli twoje zapytania przychodzą rzadziej, możesz użyć nagłówka beta extended-cache-ttl-2025-04-11, który wydłuża TTL do 1 godziny [1].

Matematyka jest prosta: cache zaczyna się opłacać od drugiego zapytania, pod warunkiem że cache'owany segment jest wystarczająco duży i zapytania przychodzą w oknie TTL.

Próg minimalny: 1024 tokeny dla Sonnet

Nie możesz cache'ować dowolnie małych fragmentów. Dla Claude Sonnet minimalny rozmiar segmentu to 1024 tokeny, dla Haiku — 2048 tokenów [1]. Jeśli twój system prompt ma 500 tokenów, prompt caching po prostu nie zadziała. Wróć do niego, gdy rozbudujesz instrukcje lub dodasz przykłady.

Liczby z cennika — Sonnet, Haiku, Opus

Poniżej twarde liczby z cennika Anthropic per 1 milion tokenów [2]:

Sonnet 4.6: $3 vs $0,30 — różnica 10×

Przy Sonnet 4.6 każdy milion tokenów odczytanych z cache kosztuje $0,30 zamiast $3,00. Jeśli twój system prompt ma 4000 tokenów i wysyłasz 1000 zapytań dziennie, bez cache płacisz za 4 miliony tokenów inputu dziennie — $12. Z cache płacisz $3,75 za pierwsze zapytanie (write) i $0,30 × 3,996M za pozostałe — łącznie około $1,20. Oszczędność: ponad 90% na tej pozycji.

Kiedy break-even

Break-even następuje po dokładnie dwóch zapytaniach w oknie TTL. Pierwsze zapytanie kosztuje 1,25× zamiast 1×, więc "przepłacasz" 0,25 jednostki. Drugie zapytanie kosztuje 0,10× zamiast 1×, więc "zarabiasz" 0,90 jednostki. Saldo po dwóch zapytaniach: +0,65 jednostki na plusie.

W praktyce oznacza to: jeśli dany system prompt jest używany przynajmniej dwa razy w ciągu 5 minut (lub 1 godziny przy extended TTL), cache się opłaca. Zawsze.

Przeliczając na złotówki przy kursie 4 PLN/USD: milion tokenów Sonnet bez cache kosztuje ~12 PLN, z cache read — ~1,20 PLN. Przy 10 milionach tokenów miesięcznie to różnica 108 PLN vs 12 PLN — oszczędność rzędu 96 PLN miesięcznie tylko na jednym modelu, przy jednym use case'u.

Cztery zastosowania, które zwracają już po jednym zapytaniu

Long system prompt w RAG

Systemy RAG często mają rozbudowane instrukcje: jak formatować odpowiedzi, jakie źródła cytować, jak postępować z niejednoznacznymi pytaniami. Taki system prompt łatwo przekracza 2000 tokenów. Cache'ujesz go raz, a każde zapytanie użytkownika odczytuje go za 10% ceny. Przy 500 zapytaniach dziennie i 3000-tokenowym system prompcie oszczędzasz na samym prompcie ponad 85% kosztów inputu [4].

Tool definitions agenta

Definicje narzędzi w agencie mogą być obszerne — szczególnie gdy masz 10–15 funkcji z pełnymi opisami parametrów i przykładami użycia. Te definicje są identyczne w każdym kroku pętli agenta. Oznaczasz je cache_control: {"type": "ephemeral"} raz i każdy kolejny krok pętli odczytuje je z cache [3]. Przy agencie wykonującym 20 kroków na jedno zadanie oszczędność na tool definitions jest natychmiastowa.

Few-shot examples

Jeśli twój prompt zawiera 10–15 przykładów wejście/wyjście (klasyczne few-shot prompting), te przykłady są identyczne dla każdego użytkownika. To idealny kandydat do cache'owania. Przykłady często zajmują 2000–5000 tokenów — dokładnie tyle, żeby cache działał i żeby oszczędność była odczuwalna.

Document Q&A

Użytkownik wgrywa 50-stronicowy dokument i zadaje do niego 15 pytań. Bez cache każde pytanie przesyła cały dokument od nowa. Z cache dokument jest ładowany raz (write), a 14 kolejnych pytań odczytuje go za 10% ceny. Przy dokumencie o rozmiarze 20 000 tokenów i 15 pytaniach oszczędzasz na 14 odczytach: 14 × 20 000 × 0,90 × $3/M = $0,756 na jednej sesji. Przy 100 sesjach dziennie to $75,60 dziennie — tylko na tym jednym wzorcu.

Jeden znak zmienia wszystko — pułapki cache miss

Tu zaczyna się część, której dokumentacja nie podkreśla wystarczająco mocno.

Cache key to kombinacja: model + definicje narzędzi + treść prefixu do breakpointu [5]. Zmiana jednego znaku w cache'owanym segmencie — literówka, dodatkowa spacja, zmiana kolejności pola w JSON — powoduje cache miss. Zamiast płacić 0,10× płacisz 1,25×. Nie dostajesz zwrotu za nieudany write z poprzedniego zapytania.

Idempotentny system prompt

System prompt musi być bitowo identyczny między zapytaniami. To oznacza: żadnych dynamicznych elementów w cache'owanej części. Data, godzina, imię użytkownika, losowe seed — wszystko to musi trafić do części promptu poza cache'owanym prefixem. Jeśli wstrzykujesz Dzisiaj jest {data} do system promptu, który chcesz cache'ować, cache nie zadziała nigdy.

Rozwiązanie: podziel system prompt na dwie części. Pierwsza — statyczna, cache'owana — zawiera instrukcje, przykłady, definicje zachowania. Druga — dynamiczna, bez cache — zawiera kontekst sesji, datę, dane użytkownika. Anthropic pozwala na maksymalnie 4 cache breakpointy per request [3], więc masz przestrzeń na taką architekturę.

Stable tool order

Jeśli twój agent dynamicznie dobiera narzędzia do każdego zapytania i zmienia ich kolejność, cache miss jest gwarantowany. Definicje narzędzi muszą być w tej samej kolejności przy każdym zapytaniu. Jeśli używasz 15 narzędzi, ale dla danego użytkownika aktywnych jest tylko 8 — albo zawsze wysyłasz wszystkie 15 (cache działa), albo akceptujesz cache miss przy każdej zmianie zestawu.

To jest realne ograniczenie dla złożonych agentów z dynamicznym doborem narzędzi. Nie ma tu dobrego obejścia — musisz wybrać między elastycznością a oszczędnością.

Warto też pamiętać, że cache jest per-model. Jeśli przełączasz się między Sonnet a Haiku w zależności od złożoności zapytania, każdy model ma osobny cache. Nie ma współdzielenia.

Czy się opłaca dla twojej firmy

Prompt caching opłaca się w jednym, konkretnym scenariuszu: masz duży, stabilny prefix promptu i wysyłasz do niego wiele zapytań w krótkim czasie. "Duży" oznacza powyżej 1024 tokenów dla Sonnet, "stabilny" oznacza bitowo identyczny, "wiele" oznacza przynajmniej dwa w oknie TTL.

Jeśli budujesz chatbota obsługi klienta dla polskiej firmy e-commerce — z rozbudowaną bazą wiedzy o produktach w system prompcie, kilkudziesięcioma przykładami obsługi reklamacji i definicjami narzędzi do sprawdzania statusu zamówień — prompt caching zwróci się w pierwszym tygodniu. Przy 1000 zapytaniach dziennie i 5000-tokenowym system prompcie oszczędzasz około $4,05 dziennie na Sonnet, czyli ponad 490 PLN miesięcznie.

Jeśli natomiast budujesz narzędzie do jednorazowej analizy dokumentów — każdy użytkownik wgrywa inny dokument, zadaje jedno pytanie i wychodzi — cache nie pomoże. Każde zapytanie to nowy dokument, nowy prefix, gwarantowany cache miss.

Dla JDG lub małej sp. z o.o. z budżetem API poniżej $50 miesięcznie różnica może być mniejsza niż koszt czasu potrzebnego na prawidłową implementację. Dla aplikacji z ruchem powyżej 10 000 zapytań dziennie prompt caching to nie optymalizacja — to obowiązek.

Werdykt: Jeśli twój system prompt lub kontekst dokumentu przekracza 2000 tokenów i to samo zapytanie pojawia się więcej niż raz w ciągu godziny — włącz cache dziś. Jeśli twój prompt jest krótki lub dynamiczny — nie trać czasu na implementację i wróć do tego, gdy architektura się ustabilizuje.

Źródła

[1] Prompt Caching — Anthropic Docs — https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching

[2] Claude API Pricing — Anthropic — https://www.anthropic.com/pricing

[3] Messages API — cache_control parameter — https://docs.anthropic.com/en/api/messages

[4] Introducing Prompt Caching with Claude — Anthropic Blog — https://www.anthropic.com/news/prompt-caching

[5] Cache structure constraints — https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching#what-can-be-cached