Cache promptów w Claude: ile kosztuje i dlaczego przestaje działać

Czym jest cache promptów

Claude czyta cały prompt przy każdym zapytaniu: definicje narzędzi, system prompt, dotychczasową rozmowę i nową wiadomość. W większości aplikacji pierwsze trzy części prawie się nie zmieniają, a Ty za każdym razem płacisz za nie pełną cenę.

Cache promptów pozwala Anthropic zachować pracę wykonaną już na początku Twojego promptu. Zaznaczasz, gdzie kończy się część do ponownego użycia. To miejsce nazywa się punktem cache (breakpoint). Następne zapytanie, które zaczyna się dokładnie tą samą treścią, odczytuje ją z cache za ułamek ceny.

Trzeci wiersz pokazuje całe ryzyko na jednym obrazku. Nic się nie zepsuło. Zapytanie się powiodło, odpowiedź była dobra. Tylko część objęta cache kosztowała ponad dwanaście razy więcej niż jedno zapytanie wcześniej.

Ile kosztuje token

Przy włączonym cache token wejścia ma jedną z czterech cen. Wszystkie podaje się jako wielokrotność zwykłej ceny wejścia danego modelu.

Jeden szczegół w tej tabeli łatwo przeoczyć. W większości modeli odczyt to jedna dziesiąta ceny wejścia, ale w Claude Opus 5.5 tylko jedna dwudziesta, a w Claude Fable 5.1 jedna czterdziesta. Im droższy model, tym więcej kosztuje pudło w porównaniu z trafieniem.

Kiedy się zwraca

Zapis do cache to mały zakład, że ten sam prefiks zostanie użyty jeszcze raz. Przy czasie życia 5 minut zakład zwraca się już przy drugim zapytaniu: jeden zapis i jeden odczyt kosztują 1,35 ceny wejścia, a bez cache 2. Przy czasie życia 1 godziny potrzeba trzech zapytań.

Jest jeszcze jeden warunek. Prefiks musi mieć minimalną długość, żeby w ogóle trafił do cache.

Zasada prefiksu

Każde zapytanie jest składane w stałej kolejności: definicje narzędzi, potem system prompt, potem wiadomości. Cache dopasowuje treść od pierwszego bajtu do punktu cache. Jeśli cokolwiek przed tym punktem się różni, dopasowanie kończy się w miejscu różnicy.

Wynika z tego jedna reguła projektowa. To, co się nie zmienia, daj na początek, a to, co zmienia się przy każdym zapytaniu, na koniec.

const response = await client.messages.create({
  model: 'claude-sonnet-5-5',
  max_tokens: 1024,
  // Automatyczny cache: punkt cache przesuwa się z końcem rozmowy
  cache_control: { type: 'ephemeral' },
  system: [
    // Stały punkt cache po części, która nigdy się nie zmienia
    { type: 'text', text: SYSTEM_PROMPT, cache_control: { type: 'ephemeral' } },
  ],
  messages,
})

To połączenie najlepiej sprawdza się na produkcji. Punkt cache na system prompcie gwarantuje miejsce odczytu dla dużej, stałej części. Ustawienie na najwyższym poziomie przesuwa drugi punkt do przodu wraz z rozmową, więc każda tura odczytuje wszystko, co było przed nią.

• Zapytanie może mieć do czterech punktów cache. Automatyczny cache zajmuje jeden z nich.
• Odczyt może trafić tylko tam, gdzie wcześniejsze zapytanie coś zapisało. Cache sam nie znajduje stałej treści. Znajduje wpisy zapisane w punkcie cache.
• Od każdego punktu cache system cofa się najwyżej o 20 bloków treści w poszukiwaniu wcześniejszego wpisu. Jedna tura, która dodaje ich więcej, na przykład długa seria wywołań narzędzi, może nie znaleźć poprzedniego wpisu. W długich turach dodaj punkt cache w połowie.
• Wpis w cache da się odczytać dopiero wtedy, gdy pierwsza odpowiedź zacznie się strumieniować. Dziesięć identycznych zapytań wysłanych w tej samej chwili zapłaci cenę zapisu. Wyślij jedno, poczekaj na pierwszy token i dopiero wtedy wyślij resztę.

Co po cichu psuje cache

Żadna z tych rzeczy nie zgłasza błędu. Każda zamienia odczyty w zapisy.

Niektóre zmiany są bezpieczniejsze, niż wyglądają. Zmiana tool_choice między zapytaniami zostawia narzędzia i system prompt w cache. Dodanie wiadomości nigdy nie wpływa na to, co było przed nią.

5 minut czy 1 godzina

Wpis w cache żyje domyślnie 5 minut albo 1 godzinę, jeśli o to poprosisz. Każdy odczyt zeruje zegar bez opłaty. Dlatego pytanie nie brzmi, jak długo trwają Twoje sesje, tylko jak długie są przerwy między zapytaniami ze wspólnym prefiksem.

• Zegar liczy się od początku zapytania, a nie od końca. Jeśli odpowiedź generuje się cztery minuty, następne zapytanie ma około minuty na start, zanim wpis 5-minutowy wygaśnie.
• W jednym zapytaniu można mieszać czasy życia, z jednym ograniczeniem: punkt cache na 1 godzinę musi być przed każdym punktem 5-minutowym.
• O 1 godzinę prosi się zapisem cache_control: { type: "ephemeral", ttl: "1h" }.
• Zapytanie z max_tokens: 0 zapisuje albo odświeża cache bez generowania odpowiedzi. Przydaje się przy starcie aplikacji, gdy pierwszy prawdziwy użytkownik nie powinien czekać na zimny start.

Jak sprawdzić, że działa

Każda odpowiedź zawiera blok usage. To jedyny wiarygodny dowód, że cache działa.

"usage": {
  "cache_read_input_tokens": 14000,     // odczytane z cache, tanio
  "cache_creation_input_tokens": 600,   // zapisane do cache, w cenie zapisu
  "input_tokens": 45,                   // po ostatnim punkcie cache, pełna cena
  "output_tokens": 380
}

Trzy pola wejścia sumują się do rozmiaru Twojego promptu. Jeśli input_tokens wygląda na zaskakująco małe, reszta przyszła z cache.

• Zdrowy: cache_read_input_tokens obejmuje prawie całą wcześniejszą rozmowę i rośnie z każdą turą. cache_creation_input_tokens ma mniej więcej rozmiar ostatniej tury.
• Zepsuty: cache_creation_input_tokens jest bliskie pełnemu promptowi przy każdym zapytaniu, a odczyty są bliskie zera.
• Brak cache: oba pola cache mają zero. Prefiks jest zapewne krótszy niż minimum albo nie ma punktu cache.

Żeby znaleźć przyczynę, zapisz pełną treść dwóch kolejnych zapytań i je porównaj. Pierwsze miejsce, w którym się różnią przed najnowszą wiadomością, to właśnie to, co psuje cache.

Przykład liczbowy

Weź system prompt o długości 14 000 tokenów wysyłany w 100 000 wywołań miesięcznie, na modelu w cenie 2 USD za milion tokenów wejścia. Tabela pokazuje koszt samego prefiksu.

Działający cache oszczędza na tym jednym prompcie około 2 450 USD miesięcznie. Zepsuty cache kosztuje 700 USD miesięcznie więcej niż brak cache, dlatego kontrola bloku usage jest ważniejsza niż samo wdrożenie.

Cache w Amazon Bedrock

Jeśli używasz Claude przez Amazon Bedrock, żeby korzystać z kredytów AWS, cache też tam działa, z tymi samymi minimalnymi długościami i oboma czasami życia w aktualnych modelach. Kilka rzeczy się różni.

• Cache jest rozdzielony na poziomie organizacji, a nie workspace’u.
• AWS zaznacza, że inferencja międzyregionalna może przy dużym obciążeniu zwiększać liczbę zapisów do cache, bo zapytanie może trafić do regionu, który nie widział jeszcze prefiksu.
• Cache działa tylko przy inferencji na żądanie, nie przy przetwarzaniu wsadowym Bedrock.
• Claude Opus 4.6 i starsze modele korzystają ze starszych API Bedrock, gdzie pola zużycia nazywają się cacheReadInputTokens i cacheWriteInputTokens i gdzie automatyczny cache nie jest dostępny.
• Amazon CloudWatch publikuje dla Bedrock runtime liczniki CacheReadInputTokenCount i CacheWriteInputTokenCount. Jeśli Twój endpoint ich nie publikuje, zapisuj blok usage z każdej odpowiedzi samodzielnie.