Claude prompt caching: kiedy cache staje się opłacalny?

Koszty cache'owania promptów przed uzyskaniem 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. Decyzja o opłacalności sprowadza się do dwóch mnożników ceny bazowej wejścia modelu. Według stanu na sierpień 2026 roku, zapis do cache kosztuje 1,25x ceny bazowej wejścia dla czasu życia wynoszącego 5 minut lub 2x dla czasu życia wynoszącego 1 godzinę. Odczyt z cache kosztuje 0,1x ceny bazowej. Mnożniki te są stałe dla wszystkich modeli, więc próg opłacalnoś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 jednorazowo za zapisanie prefiksu. Każde kolejne żądanie rozpoczynające się od identycznych bajtów kosztuje jedną dziesiątą standardowej ceny wejścia dla tej części danych. Prefiks, który nie zostanie ponownie wykorzystany w czasie swojego życia, generuje stratę w wysokości 25 procent poniesionych kosztów.

Punkt rentowności w jednym równaniu algebraicznym

Oznaczmy przez B podstawowy koszt wejściowy prefiksu w przypadku braku cache'owania. Bez cache'owania N żądań kosztuje N razy B. Przy 5-minutowym cache'u pierwsze żądanie zapisuje prefiks za 1.25B, a pozostałe N minus 1 żądań odczytuje go za 0.1B. Po przyrównaniu obu stron otrzymujemy 0.9N = 1.15, czyli N = 1.28. Już drugie żądanie jest tańsze niż brak cache'owania.

Powtarzając to dla 2-krotnego kosztu zapisu przy 1-godzinnym cache'u, 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 według stanu na sierpień 2026. Skaluj każdą wartość przez 0.6 dla modelu o stawce 3 USD za milion tokenów. 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 żądanie kosztuje $0.10 bez cache'owania oraz $0.125 z cache'owaniem, więc cache'owanie promptu typu one-shot generuje czystą stratę. Przy drugim żądaniu 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 przewyższa opłacalnością brak cache'owania dopiero przy trzecim żądaniu: $0.22 wobec $0.30. Przy 20 żądaniach różnica wynosi $2.00 wobec $0.315.

Trafienie do cache'u odświeża również wpis, dlatego opublikowana tabela cenowa nazywa tę kolumnę trafieniami i odświeżeniami cache'u. Obciążony punkt końcowy utrzymuje zatem 5-minutowy wpis przy życiu w nieskończoność po cenach odczytu, a 1-godzinny czas życia zwraca swój 2-krotny koszt 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, a mimo to 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 informację, ż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, więc 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 poziom $11.15, zbliżając się do dolnej granicy wynoszącej 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 posiadać. Kandydatami są bloki identyczne pod względem bajtów w różnych wywołaniach oraz wystarczająco 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 system prompt o rozmiarze 2,000 tokenów pozwala zaoszczędzić $7.85 na 1000 żądań w porównaniu do $10.00 bez użycia pamięci podręcznej. Przy dużej skali są to realne 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, o który pyta 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 niczym więcej. 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łasz częściej 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 założeniu 90-procentowej skuteczności trafień, i skaluje te dane do miesięcznych wolumenów zapytań.

[
  {
    "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 zapytań miesięcznie oszczędność wynosi $314.00, co stanowi różnicę między $400.00 a $86.00. Przy 100 000 zapytań kwota ta wynosi $3,140.00. Przy milionie zapytań rachunek za tokeny wejściowe bez buforowania wynosi $40,000.00, a buforowanie pozwala wyeliminować z tego $31,400.00. Dotyczy to wyłącznie tokenów wejściowych. Tokeny wyjściowe są wyceniane oddzielnie i buforowanie nie ma na nie wpływu, o czym należy pamiętać przed złożeniem obietnicy 90-procentowej redukcji kosztów. Buforowanie stanowi uzupełnienie szerszych praktyk w zakresie kontrolowania kosztów agenta AI na serwerze VPS.

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

Nie należy polegać wyłącznie na założeniach projektowych. Należy sprawdzić 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 wykonać zapytanie dwukrotnie z tym samym dokumentem, ale innym pytaniem. 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 został odnaleziony. Wartość input_tokens zlicza tylko tokeny znajdujące się po ostatnim punkcie przerwania, więc w poprawnie działającym drugim wywołaniu jest ona niewielka i zazwyczaj obejmuje tylko nową wiadomość użytkownika. Oba wywołania są płatne, ponieważ Claude API nie posiada darmowego planu, choć przy prefiksie o długości 20 000 tokenów koszt pary zapytań wynosi około czternastu centów.

Analogiczną weryfikację można przeprowadzić z poziomu powłoki, korzystając z 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 zwraca dane w następującym formacie:

{
  "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 równa 0 w kolejnych wywołaniach, oznacza to, że za każdym razem naliczana jest opłata za zapis (1.25x), a mechanizm pamięci podręcznej nie przynosi korzyści.

W przypadku okresu ważności wynoszącego 1 godzinę, punkt przerwania posiada czas życia (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 przerwania w miarę rozwoju konwersacji. Zużywa ono jeden z czterech dostępnych slotów punktów przerwania. Od tego należy rozpocząć konfigurację. Do jawnych punktów przerwania warto przejść w momencie, gdy konieczne jest precyzyjne określenie miejsca podziału.

Reguła kolejności obniżająca skuteczność trafień

Pamięć podręczna dopasowuje prefiks bajt po bajcie od początku żądania, a żądanie jest zestawiane 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 elementami, które pozostają stałe.

Typowym problemem jest znacznik czasu. Linia o treści Current time: 2026-08-03T14:07:11Z na początku promptu systemowego gwarantuje zerową skuteczność trafień, ponieważ hash prefiksu jest za każdym razem inny i żaden wcześniejszy wpis nie może zostać dopasowany. Należy przenieść taki element do komunikatu użytkownika, na sam koniec. Identyfikator sesji lub nonce dla każdego żądania powoduje ten sam problem i wymaga analogicznego rozwiązania. Dokumenty pobrane, które różnią się w zależności od żądania, również powinny znajdować się za blokiem buforowanym, w przeciwnym razie wypychają każdy stabilny token poza granicę, która ulega przesunięciu.

Drugim problemem jest umieszczenie punktu przerwania (breakpoint) na 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 jest zapisywane, a mechanizm wyszukiwania znajduje jedynie wpisy utworzone przez wcześniejsze żądania w ich własnych, zmiennych punktach przerwania. Należy umieścić cache_control na ostatnim bloku, którego zawartość jest identyczna dla wszystkich żądań.

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

Minimalny prefiks i cicha operacja no-op

Prefiks krótszy niż minimalna wymagana długość dla danego modelu nie jest buforowany, a system nie generuje żadnego powiadomienia. Nie występuje błąd ani ostrzeżenie. Żądanie kończy się powodzeniem, a oba liczniki wskazują 0. Według stanu na sierpień 2026 opublikowane wartości minimalne wynoszą:

• 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 w żą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 automatycznie najbardziej opłacalny w przypadku obciążeń wymagających buforowania. Model Claude Haiku 4.5 wymaga prefiksu ośmiokrotnie dłuższego niż Claude Opus 5, aby buforowanie w ogóle zostało uruchomione. W rezultacie system prompt o długości 2 000 tokenów będzie buforowany w jednym modelu, podczas gdy w drugim zostanie zignorowany bez żadnego komunikatu.

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

Claude Code przechowuje w pamięci podręcznej 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 zużycia tokenów przez Claude Code.

Mechanizm ten nie pomaga w przypadku edycji w początkowej części kontekstu. Historia konwersacji jest rozszerzana wyłącznie przez dopisywanie, więc standardowe nowe tury wydłużają prefiks, który znajduje się 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 wiąże się z pełnym kosztem 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. cache_creation_input_tokens jest niezerowe przy każdym żądaniu, podczas gdy cache_read_input_tokens pozostaje równe 0. Coś w punkcie przerwania lub przed nim zmienia się między wywołaniami. Wyświetl pierwsze 200 znaków złożonego prefiksu dla dwóch kolejnych żądań i porównaj je wzrokowo.

Oba liczniki wynoszą 0. Prefiks jest poniżej minimum wymaganego przez model lub pole cache_control nigdy nie dotarło do API. Najpierw policz tokeny prefiksu, a następnie zaloguj treść żądania, która została faktycznie wysłana.

Odczyty działają, a potem ustają. Seria trafień, potem zapis, a następnie znów trafienia. Przerwa między żądaniami była dłuższa niż czas życia (lifetime). Zaakceptuj zapis lub przejdź na TTL 1 godziny, 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. Po każdym wdrożeniu modyfikującym prompt należy spodziewać się jednej kosztownej rundy zapisów.

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; to samo dotyczy bufora 1-godzinnego przy wskaźniku poniżej około 53 procent.

FAQ

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

Wystarczy raz, w przypadku bufora 5-minutowego. 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, więc już drugie zapytanie przynosi oszczędność. Bufor 1-godzinny kosztuje 2x przy zapisie i punkt przecięcia przypada na 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, która zmienia się między wywołaniami przed punktem podziału lub w nim, na przykład znacznika czasu lub identyfikatora 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ą formę tokenów, które już wysłano, a model widzi ten sam prompt w obu przypadkach. Jest to funkcja optymalizacji kosztów i opóźnień, a nie zmiana zachowania. 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 ruch charakteryzuje się przerwami dłuższymi niż 5 minut, a wskaźnik trafień nadal przekracza około 53 procent. Zapis 2x oznacza dwukrotnie większą stratę niż zapis 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.