Claude prompt caching: jak obliczyć punkt rentowności

Koszty cache'owania promptów przed osiągnięciem oszczędności

Cache'owanie promptów pozwala modelowi Claude na ponowne wykorzystanie początkowej części promptu zamiast ponownego przetwarzania jej przy każdym wywołaniu. Cała kalkulacja opiera się na dwóch mnożnikach bazowej ceny wejściowej modelu. Według stanu na sierpień 2026 roku, zapis w cache kosztuje 1,25x bazowej ceny wejściowej przy czasie przechowywania 5 minut lub 2x przy czasie 1 godziny. Odczyt z cache kosztuje 0,1x. Mnożniki te są stałe dla wszystkich modeli, więc punkt rentowności nie zmienia się wraz ze zmianą ceny za token.

Mechanizm ten polega na poniesieniu dodatkowej opłaty teraz w zamian za zniżkę w przyszłości. Użytkownik płaci raz za zapisanie prefiksu. Każde kolejne żądanie rozpoczynające się od identycznego ciągu bajtów kosztuje jedną dziesiątą standardowej ceny wejściowej dla tej części. Prefiks, który nie zostanie ponownie użyty w czasie swojego obowiązywania, generuje niepotrzebny koszt wyższy o 25 procent.

Punkt rentowności w jednym równaniu algebraicznym

Niech B oznacza podstawowy koszt wejściowy prefiksu w przypadku braku cache. Bez cache N zapytań kosztuje N razy B. Przy 5-minutowym cache pierwsze zapytanie zapisuje prefiks po koszcie 1.25B, a pozostałe N minus 1 zapytań odczytuje go po 0.1B. Po przyrównaniu obu stron otrzymujemy 0.9N = 1.15, czyli N = 1.28. Już drugie zapytanie jest tańsze niż praca bez cache.

Powtarzając to dla 2-krotnego kosztu zapisu przy 1-godzinnym cache, otrzymujemy 0.9N = 1.9, czyli N = 2.11. Dłuższy cache wymaga dwóch odczytów, aby osiągnąć punkt rentowności, dlatego nie jest on wyborem domyślnym.

Poniższy wykres przedstawia wycenę dla prefiksu o długości 20,000 tokenów w modelu Claude Opus 5, którego podstawowa stawka wejściowa wynosi 5 USD za milion tokenów (stan na sierpień 2026). W przypadku modelu o stawce 3 USD za milion tokenów należy przeskalować każdą wartość przez 0.6. Kształt krzywej pozostaje bez zmian.

[
  {
    "requests": 1,
    "uncached_usd": "0.10",
    "cached_5m_usd": "0.125",
    "cached_1h_usd": "0.20"
  },
  {
    "requests": 2,
    "uncached_usd": "0.20",
    "cached_5m_usd": "0.135",
    "cached_1h_usd": "0.21"
  },
  {
    "requests": 3,
    "uncached_usd": "0.30",
    "cached_5m_usd": "0.145",
    "cached_1h_usd": "0.22"
  },
  {
    "requests": 5,
    "uncached_usd": "0.50",
    "cached_5m_usd": "0.165",
    "cached_1h_usd": "0.24"
  },
  {
    "requests": 10,
    "uncached_usd": "1.00",
    "cached_5m_usd": "0.215",
    "cached_1h_usd": "0.29"
  },
  {
    "requests": 20,
    "uncached_usd": "2.00",
    "cached_5m_usd": "0.315",
    "cached_1h_usd": "0.39"
  }
]

Pojedyncze zapytanie kosztuje $0.10 bez cache oraz $0.125 z cache, więc cache'owanie jednorazowego promptu jest nieopłacalne. Przy drugim zapytaniu 5-minutowy cache kosztuje $0.135 w porównaniu do $0.20. 1-godzinny cache jest w tym momencie nadal droższy, kosztując $0.21 wobec tego samego $0.20 i staje się tańszy od wariantu bez cache dopiero przy trzecim zapytaniu: $0.22 wobec $0.30. Przy 20 zapytaniach różnica wynosi $2.00 wobec $0.315.

Trafienie do cache odświeża również wpis, dlatego opublikowana tabela cenowa nazywa tę kolumnę trafieniami i odświeżeniami cache. Obciążony endpoint utrzymuje zatem 5-minutowy wpis w pamięci bezterminowo po cenach odczytu, a 1-godzinny czas życia zwraca się w postaci 2-krotnego kosztu zapisu tylko wtedy, gdy w ruchu występują rzeczywiste przerwy.

Koszty niskiego współczynnika trafień

Rzeczywisty ruch generuje chybienia. Żądanie, które nie trafia do pamięci podręcznej, ale nadal zawiera punkt przerwania, jest rozliczane jako zapis. Uczciwym sposobem modelowania tego zjawiska jest przedstawienie kosztu jako funkcji współczynnika trafień. Poniższy wykres obrazuje to dla 1000 żądań, z których każde zawiera ten sam prefiks o długości 20 000 tokenów.

[
  {
    "hit_rate_percent": 0,
    "cost_5m_usd": "125.00",
    "cost_1h_usd": "200.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 25,
    "cost_5m_usd": "96.25",
    "cost_1h_usd": "152.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 50,
    "cost_5m_usd": "67.50",
    "cost_1h_usd": "105.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 75,
    "cost_5m_usd": "38.75",
    "cost_1h_usd": "57.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 90,
    "cost_5m_usd": "21.50",
    "cost_1h_usd": "29.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 95,
    "cost_5m_usd": "15.75",
    "cost_1h_usd": "19.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 99,
    "cost_5m_usd": "11.15",
    "cost_1h_usd": "11.90",
    "uncached_usd": "100.00"
  }
]

Przy współczynniku trafień wynoszącym 0 procent płacisz $125.00 zamiast $100.00, a godzinna pamięć podręczna podwaja rachunek do $200.00. Rozwiązując równanie 1,25 minus 1,15h = 1, otrzymujemy, że 5-minutowa pamięć podręczna zaczyna przynosić oszczędności przy współczynniku trafień na poziomie około 22 procent, dlatego przy 25 procentach widoczna jest już wartość $96.25. Analogiczne obliczenia dla dwukrotnego zapisu dają wynik około 53 procent dla godzinnej pamięci podręcznej, zatem przy 50-procentowym współczynniku trafień koszt nadal wynosi $105.00, co jest wartością powyżej linii dla braku pamięci podręcznej. Przy 90 procentach obie wartości osiągają poziom $21.50 oraz $29.00. Przy 99 procentach krótka pamięć podręczna osiąga $11.15, co jest wartością zbliżoną do dolnego limitu wynoszącego jedną dziesiątą ceny bez pamięci podręcznej.

Współczynnik trafień to parametr, który należy monitorować, ponieważ jest to jedyna zmienna, na którą masz wpływ po ustaleniu rozmiaru prefiksu.

Które prefiksy warto objąć punktem przerwania

Żądanie może zawierać do czterech punktów przerwania pamięci podręcznej, dlatego należy rozważyć, które bloki powinny je otrzymać. Kandydatami są bloki identyczne pod względem bajtów w różnych wywołaniach oraz na tyle duże, aby miało to znaczenie. Poniższa tabela przedstawia wycenę czterech typowych kształtów dla 1000 żądań przy 90-procentowym współczynniku trafień w 5-minutowej pamięci podręcznej.

[
  {
    "label": "System prompt",
    "prefix_size_tokens": "2,000",
    "uncached_usd": "10.00",
    "cached_usd": "2.15",
    "saved_usd": "7.85"
  },
  {
    "label": "System plus tools",
    "prefix_size_tokens": "8,000",
    "uncached_usd": "40.00",
    "cached_usd": "8.60",
    "saved_usd": "31.40"
  },
  {
    "label": "Policy document",
    "prefix_size_tokens": "25,000",
    "uncached_usd": "125.00",
    "cached_usd": "26.88",
    "saved_usd": "98.12"
  },
  {
    "label": "Codebase context",
    "prefix_size_tokens": "120,000",
    "uncached_usd": "600.00",
    "cached_usd": "129.00",
    "saved_usd": "471.00"
  }
]

Sam systemowy prompt tokenowy 2,000 pozwala zaoszczędzić $7.85 na każde 1000 żądań w porównaniu do $10.00 bez użycia pamięci podręcznej. Przy dużej skali są to wymierne oszczędności, jednak nie to czyni buforowanie interesującym. Po dodaniu definicji narzędzi osiągamy 8,000 tokenów i oszczędność rzędu $31.40. Dokument polityki o rozmiarze 25,000 tokenów, do którego odwołuje się każde żądanie, pozwala zaoszczędzić $98.12. Ostatni wiersz zmienia architekturę: 120,000 tokenów bazy kodu lub kontekstu transkrypcji kosztuje $600.00 bez buforowania i $129.00 z buforowaniem, co daje oszczędność $471.00.

Oszczędności skalują się wraz z rozmiarem prefiksu oraz współczynnikiem trafień i nie zależą od niczego innego. Zmienia to podejście do tego, co w ogóle warto umieszczać w prompcie: ile faktycznie kosztuje milion tokenów Claude spada do jednej dziesiątej ceny katalogowej w przypadku wszystkiego, co wysyła się więcej niż raz.

Jak to wygląda na miesięcznym rachunku

Poniższy wykres wykorzystuje prefiks tokenów 8,000 z powyższego przykładu, prompt systemowy oraz definicje narzędzi przy 90-procentowym współczynniku trafień i skaluje te wartości do miesięcznej liczby żądań.

[
  {
    "label": "10k requests",
    "uncached_usd": "400.00",
    "cached_usd": "86.00",
    "saved_usd": "314.00"
  },
  {
    "label": "100k requests",
    "uncached_usd": "4,000.00",
    "cached_usd": "860.00",
    "saved_usd": "3,140.00"
  },
  {
    "label": "1M requests",
    "uncached_usd": "40,000.00",
    "cached_usd": "8,600.00",
    "saved_usd": "31,400.00"
  }
]

Przy 10 000 żądań miesięcznie oszczędność wynosi $314.00, co stanowi różnicę między $400.00 a $86.00. Przy 100 000 żądań kwota ta wynosi $3,140.00. Przy milionie żądań rachunek za wejściowe tokeny bez cache'owania wynosi $40,000.00, a mechanizm cache'owania pozwala zaoszczędzić $31,400.00 tej kwoty. Dotyczy to wyłącznie tokenów wejściowych. Tokeny wyjściowe są wyceniane oddzielnie i cache'owanie nie ma na nie wpływu, o czym należy pamiętać przed złożeniem komukolwiek obietnicy 90-procentowej redukcji rachunków. Cache'owanie jest jednym z elementów szerszej strategii utrzymywania kosztów agenta AI pod kontrolą na serwerze VPS.

Jak zweryfikować działanie pamięci podręcznej

Nie należy polegać wyłącznie na założeniach projektowych. Należy odczytać blok użycia w odpowiedzi. Każda odpowiedź Messages API raportuje liczbę zapisanych tokenów w pamięci podręcznej, liczbę odczytanych tokenów oraz liczbę nowych tokenów, które musiały zostać przetworzone.

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=512,
    system=[
        {
            "type": "text",
            "text": POLICY_DOCUMENT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": question}],
)

u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)

Należy uruchomić zapytanie dwukrotnie dla tego samego dokumentu, zadając inne pytanie. Pierwsze wywołanie wykaże wartość niezerową dla cache_creation_input_tokens oraz zero dla cache_read_input_tokens. Drugie wywołanie odwróci tę relację, ponieważ prefiks zostanie odnaleziony. Wartość input_tokens zlicza tylko tokeny znajdujące się po ostatnim punkcie podziału (breakpoint), więc w przypadku poprawnego działania drugiego wywołania powinna być ona niewielka – zazwyczaj obejmuje tylko nową wiadomość użytkownika.

Analogiczną weryfikację można przeprowadzić z poziomu powłoki, używając treści żądania zapisanej w pliku request.json:

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @request.json | jq '.usage'

Poprawne drugie wywołanie zwróci wynik zbliżony do poniższego:

{
  "input_tokens": 42,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 20143,
  "output_tokens": 187
}

Jeden wiersz zawiera kluczowe informacje. Jeśli wartość cache_read_input_tokens pozostaje na poziomie 0 w kolejnych wywołaniach, oznacza to, że za każdym razem ponoszony jest koszt zapisu 1.25x bez uzyskania korzyści z pamięci podręcznej.

W przypadku czasu życia wynoszącego 1 godzinę, punkt podziału posiada określony czas wygaśnięcia (TTL):

{
  "type": "text",
  "text": "your stable prefix",
  "cache_control": {"type": "ephemeral", "ttl": "1h"}
}

Dostępna jest również automatyczna pamięć podręczna: pojedyncze pole cache_control na najwyższym poziomie żądania, po którym API zarządza punktami podziału w miarę rozwoju konwersacji. Zużywa ono jeden z czterech dostępnych slotów punktów podziału. Warto zacząć od tego rozwiązania. Do jawnych punktów podziału należy przejść w momencie, gdy wymagane jest precyzyjne określenie miejsca granicznego.

Reguła kolejności obniżająca skuteczność pamięci podręcznej

Pamięć podręczna dopasowuje prefiks bajt po bajcie od początku żądania, a żądanie jest składane w ustalonej kolejności: narzędzia, następnie system, a na końcu komunikaty. Zmiana na dowolnym poziomie unieważnia ten poziom oraz wszystko, co po nim następuje. Edycja opisu jednego narzędzia powoduje unieważnienie promptu systemowego oraz całej historii komunikatów, nawet jeśli nie zostały one zmodyfikowane.

Wynika z tego jedna reguła bez wyjątków. Wszystko, co zmienia się pomiędzy wywołaniami, musi znajdować się za wszystkim, co pozostaje niezmienne.

Najczęstszą przyczyną problemów jest znacznik czasu. Linia o treści Current time: 2026-08-03T14:07:11Z na początku promptu systemowego gwarantuje zerową skuteczność pamięci podręcznej, ponieważ skrót prefiksu jest inny przy każdym wywołaniu i żaden wcześniejszy wpis nie może zostać dopasowany. Należy przenieść ten element do komunikatu użytkownika, na sam koniec. Identyfikator sesji lub nonce dla każdego żądania powoduje ten sam problem i wymaga analogicznej poprawki. Pobrane dokumenty, które różnią się w zależności od żądania, również powinny znajdować się za blokiem buforowanym, w przeciwnym razie wypchną każdy stabilny token poza granicę, która ulega przesunięciu.

Drugą przyczyną jest umieszczenie punktu przerwania (breakpoint) w bloku, który ulega zmianie. Zapisy do pamięci podręcznej odbywają się w punkcie przerwania, więc jeśli dany blok jest za każdym razem inny, nic stabilnego nie zostanie zapisane, a mechanizm wyszukiwania wstecznego znajdzie jedynie wpisy utworzone przez wcześniejsze żądania w ich własnych, zmiennych punktach przerwania. Należy umieścić cache_control w ostatnim bloku, którego zawartość jest identyczna dla wszystkich żądań.

Trzecią przyczyną jest zmiana parametru, która nie jest postrzegana jako zawartość promptu. Inny model korzysta z innej pamięci podręcznej. Zmiana wyboru narzędzi unieważnia dane począwszy od poziomu systemowego. Dodanie lub usunięcie narzędzia unieważnia wszystko.

Minimalny prefiks i cicha operacja no-op

Prefiks krótszy od minimalnego wymaganego przez model nie jest buforowany, a system nie generuje żadnego powiadomienia. Brak błędu, brak ostrzeżenia. Żądanie kończy się powodzeniem, a oba liczniki wskazują 0. Według stanu na sierpień 2026 opublikowane wartości minimalne to:

• 512 tokenów dla Claude Opus 5 oraz Claude Fable 5
• 1 024 tokeny dla Claude Sonnet 5 oraz Claude Opus 4.8
• 4 096 tokenów dla Claude Haiku 4.5

Jeśli oba liczniki wskazują 0 przy żądaniu, które powinno być buforowane, w pierwszej kolejności należy sprawdzić długość prefiksu. Jest to również powód, dla którego najtańszy model nie zawsze jest najtańszy w przypadku obciążeń wymagających buforowania. Model Haiku 4.5 wymaga prefiksu ośmiokrotnie dłuższego niż Opus 5, aby buforowanie w ogóle zadziałało. W rezultacie system prompt o długości 2 000 tokenów jest buforowany w jednym modelu, a w drugim jest cicho ignorowany.

Gdzie Claude Code stosuje pamięć podręczną, a gdzie nie może tego zrobić

Claude Code buforuje własny prefiks. Prompt systemowy oraz definicje narzędzi znajdują się na początku każdego żądania i nie ulegają zmianie, dlatego są zapisywane raz i odczytywane przez resztę sesji. Z tego powodu koszt pojedynczej tury w długiej sesji jest znacznie niższy, niż sugerowałby rozmiar kontekstu, co widać w licznikach opisanych w sposób raportowania użycia tokenów przez Claude Code.

Mechanizm ten nie pomaga w przypadku edycji w początkowej części kontekstu. Historia konwersacji jest rozszerzana tylko przez dopisywanie, więc standardowe nowe tury wydłużają prefiks, który jest już w pamięci podręcznej. Edycja pliku odczytanego na wczesnym etapie sesji zmienia zawartość w środku tego prefiksu, co wymusza ponowne zapisanie każdego tokenu znajdującego się po zmianie. Długa przerwa w aktywności powoduje ten sam efekt, ponieważ wpis wygasa, a kolejna tura wymaga pełnego zapisu. Żadna z tych sytuacji nie jest błędem. Obie wynikają z zasady działania prefiksu.

Jeśli tworzysz własnego klienta, zastosuj układ z pierwszego żądania zamiast dostosowywać go później: buduj wywołanie w sposób opisany w pierwsza aplikacja Claude API na VPS, umieszczając stabilne bloki na początku, a zmienne na końcu.

Tryby awarii i ich objawy

Każde wywołanie to zapis. Wartość cache_creation_input_tokens jest niezerowa przy każdym żądaniu, podczas gdy cache_read_input_tokens pozostaje na poziomie 0. Coś w punkcie przerwania lub przed nim zmienia się pomiędzy wywołaniami. Należy wyświetlić pierwsze 200 znaków złożonego prefiksu dla dwóch kolejnych żądań i porównać je wzrokowo.

Oba liczniki wynoszą 0. Prefiks jest krótszy niż minimum wymagane przez model lub pole cache_control nigdy nie dotarło do API. Należy najpierw policzyć tokeny prefiksu, a następnie zarejestrować w logach faktycznie wysłane ciało żądania.

Odczyty działają, a potem ustają. Seria trafień, następnie zapis, a potem znów trafienia. Przerwa między żądaniami była dłuższa niż czas życia (lifetime). Należy zaakceptować zapis lub przejść na TTL wynoszący 1 godzinę, gdy wskaźnik trafień przekroczy 53 procent.

Wskaźnik trafień spada po wdrożeniu. Opis narzędzia został edytowany lub zmieniono model. Oba te działania unieważniają cały prefiks. Należy spodziewać się jednej kosztownej rundy zapisów po każdym wdrożeniu, które dotyczy promptu.

Rachunek wzrósł po włączeniu buforowania. Wskaźnik trafień jest poniżej progu opłacalności. Przy buforze 5-minutowym, jeśli wskaźnik wynosi poniżej około 22 procent, wysyłanie prefiksu bez buforowania jest tańsze; w przypadku bufora 1-godzinnego zasada ta obowiązuje poniżej około 53 procent.

FAQ

Ile razy należy użyć promptu, aby buforowanie stało się opłacalne?

Wystarczy raz przy buforze 5-minutowym. Zapis kosztuje 1,25x ceny wejściowej, a odczyt 0,1x, więc N zapytań bez bufora kosztuje N, podczas gdy N zapytań z buforem kosztuje 1,25 plus 0,1 razy N minus 1. Punkt przecięcia przypada na N = 1,28, co oznacza, że już drugie zapytanie przynosi oszczędność. Bufor 1-godzinny kosztuje 2x przy zapisie i osiąga próg opłacalności przy N = 2,11, więc wymaga dwóch odczytów.

Dlaczego cache_read_input_tokens zawsze wynosi zero?

Najpierw sprawdź długość prefiksu: poniżej minimum modelu, czyli 512 tokenów dla Claude Opus 5 oraz 4096 dla Claude Haiku 4.5 według stanu na sierpień 2026, buforowanie jest pomijane bez powiadomienia, a oba liczniki wskazują 0. Jeśli prefiks jest wystarczająco długi, poszukaj treści zmieniających się między wywołaniami, które znajdują się przed lub w punkcie podziału, takich jak znacznik czasu lub identyfikator sesji w system prompt. Jeśli liczniki działały i przestały, przerwa między zapytaniami była dłuższa niż czas życia bufora.

Czy buforowanie promptów zmienia odpowiedzi Claude?

Nie. Bufor przechowuje przetworzoną postać tokenów, które zostały już wysłane, a model w obu przypadkach otrzymuje ten sam prompt. Jest to funkcja optymalizująca rozliczenia i opóźnienia, a nie zmiana zachowania modelu. Oznacza to również, że można włączyć tę funkcję dla działającego promptu bez konieczności ponownego przeprowadzania ewaluacji.

Czy warto płacić za bufor 1-godzinny?

Tylko wtedy, gdy przerwy w ruchu są dłuższe niż 5 minut, a wskaźnik trafień (hit rate) nadal przekracza około 53 procent. Koszt zapisu 2x jest dwukrotnie wyższy niż koszt 1,25x w przypadku chybienia. Wpis 5-minutowy odświeża się przy każdym trafieniu, więc stały ruch utrzymuje go przy życiu w cenie odczytu, bez konieczności płacenia za dłuższy czas przechowywania.