## Prompt caching

*Jak model pisze i ile to kosztuje*

*Ostatnia zmiana: 28 września 2026*

Prompt caching to KV cache zachowany u dostawcy między requestami. Request, który zaczyna się identycznie jak niedawny, pomija prefill tej części: płaci ułamek ceny wejścia i szybciej dostaje pierwszy token.

**Po ludzku:** Kelner, który zna stałych gości, nie pyta od nowa o alergie i ulubiony stolik. Ale wystarczy przedstawić się innym imieniem i zaczyna od zera. I pamięta gościa tylko kilka minut od ostatniej wizyty.

*Interaktywny widżet na stronie: Wybierz układ promptu. Zobacz, jaka część drugiego requestu trafia w cache i ile to kosztuje.*

### Jak działa prompt caching

- Po requeście dostawca zachowuje KV cache promptu w blokach i indeksuje je hashem prefiksu, czyli wszystkiego od początku promptu do końca bloku (temat „Pętla generowania i KV cache”). Request z tym samym początkiem wczytuje te bloki zamiast liczyć je od nowa.
- Trafia tylko identyczny prefiks. K i V każdego tokena zależą od wszystkich tokenów przed nim, a dzięki masce przyczynowej od niczego za nim. Dopisany koniec zostawia więc cache ważny, a pierwszy zmieniony token unieważnia wszystko za nim, nawet gdy dalsza część jest identyczna.
- Zysk jest podwójny: tańsze wejście i krótszy czas do pierwszego tokena, bo prefill pomija trafioną część. Generowania odpowiedzi to nie przyspiesza. Model widzi dokładnie ten sam tekst, więc cache nie zmienia jakości.

### Warunki u dostawców

- Anthropic (wrzesień 2026): odczyt 0,1 ceny wejścia (w najnowszych modelach jeszcze mniej), zapis 1,25 przy wpisie 5-minutowym i 2 przy godzinnym. Punkty cięcia (breakpointy) wskazujesz sam (do 4 znaczników `cache_control`) albo jednym polem w trybie automatycznym. Minimalny prefiks to od 512 do 4096 tokenów zależnie od modelu. Krótszy po cichu się nie zapisze.
- OpenAI cache’uje prefiksy automatycznie. Od GPT-5.6 minimum to 1024 tokeny, zapis kosztuje 1,25, odczyt 0,1, a wpis żyje co najmniej 30 minut. Starsze modele nie mają dopłaty za zapis i domyślnie trzymają wpis ok. 30 minut, najwyżej 24 godziny; przy Zero Data Retention albo w modelach bez retencji 24-godzinnej domyślnie 5–10 minut bezczynności, najwyżej godzinę. Gemini od 2.5 ma cache automatyczny, bez gwarancji trafienia, i jawny, płatny za godzinę przechowywania.
- Każde trafienie odnawia czas życia wpisu. U Anthropic liczy się on od startu requestu, więc generowanie trwające 4 minuty zjada większość 5-minutowego wpisu. Użytkownik, który przy takim wpisie odpisze po kwadransie, zaczyna od zapisu.

### Jak układać prompt pod cache

- Najpierw to, co stałe: definicje narzędzi, system prompt, duże dokumenty, przykłady. Potem historia, na końcu nowa wiadomość. U Anthropic hierarchia to `tools` → `system` → `messages`, więc zmiana narzędzi unieważnia wszystko.
- Historię tylko dopisuj. Agent w każdej turze wysyła ją całą (temat „Okno kontekstowe i agent”), a tylko dopisywana historia pozwala każdej turze przeczytać z cache’u wszystko poza najnowszą częścią. Edycja starej wiadomości, kompakcja, wycięcie starego wyniku narzędzia albo przestawienie narzędzi unieważnia cache od tego miejsca. Oszczędzanie okna (temat „Context engineering i pamięć”) trzeba więc zestawić z kosztem chybienia.
- Typowi zabójcy prefiksu: data i godzina albo identyfikator sesji na początku, niedeterministyczna kolejność kluczy JSON albo narzędzi, zmiana modelu, poziomu myślenia albo schematu odpowiedzi w trakcie rozmowy.
- Mierz trafienia w `usage`: `cache_read_input_tokens` w Anthropic, `cached_tokens` w OpenAI. Hit rate to tokeny z cache’u przez wszystkie tokeny wejściowe. W Anthropic `input_tokens` liczy tylko to, co stoi za ostatnim breakpointem, więc całe wejście to `input_tokens` + `cache_creation_input_tokens` + `cache_read_input_tokens`; w OpenAI `input_tokens` już zawiera `cached_tokens`. Zero trafień przy powtarzalnym prefiksie znaczy, że coś go zmienia.
- Opłacalność: przy zapisie 1,25 i odczycie 0,1 wpis zwraca się już przy jednym trafieniu (1,35 zamiast 2 cen wejścia). Godzinny wpis za 2 potrzebuje dwóch trafień. Prefiks, który się nie powtarza, tylko dopłaca za zapis.

### Sprawdź się

**Pytanie:** Jak działa prompt caching i jak układać pod niego prompt?

**Krótka odpowiedź:** To KV cache zachowany u dostawcy między requestami. Działa tylko przy identycznym prefiksie, bo K i V tokena zależą od wszystkiego przed nim: pierwszy zmieniony token unieważnia resztę. Dlatego stałe części, czyli narzędzia, system prompt i duże dokumenty, idą na początek, historię się tylko dopisuje, a zmienne dane trafiają na koniec. Odczyt kosztuje zwykle 10% ceny wejścia, zapis bywa droższy od zwykłego wejścia, a wpis żyje minuty. Zysk to tańsze wejście i krótszy czas do pierwszego tokena. Hit rate odczytuje się z pól usage.

### Pytania pogłębiające

- **Rachunek za agenta jest wysoki, a hit rate niski. Co sprawdzasz?** Porównaj kolejne requesty token po tokenie i szukaj pierwszej różnicy: data lub identyfikator na początku, niedeterministyczna serializacja narzędzi i JSON-a, edycja historii, zmiana modelu albo poziomu myślenia. Potem sprawdź, czy przerwy między turami nie są dłuższe niż czas życia wpisu i czy prefiks przekracza minimalną długość.
- **Czym prompt caching różni się od cache’u semantycznego?** Prompt caching przechowuje obliczenia dla identycznego prefiksu, a model i tak generuje nową odpowiedź, więc jakość się nie zmienia. Cache semantyczny zwraca starą odpowiedź na podobne pytanie: oszczędza całe wywołanie, ale może zwrócić odpowiedź na inne pytanie.
- **Kiedy caching się nie opłaca?** Gdy prefiks rzadko się powtarza w czasie życia wpisu. Przy dopłacie za zapis każdy wpis bez trafienia kosztuje więcej niż request bez cache’u.
- **Czy cache może zdradzić dane innego użytkownika?** Duzi dostawcy nie dzielą cache’u między organizacjami, ale w twojej aplikacji użytkownicy z tym samym prefiksem trafiają w ten sam wpis. Trafienie widać po krótszym czasie odpowiedzi, więc ktoś może sprawdzić, czy inny użytkownik niedawno wysłał dany tekst. Audyt z 2025 roku wykrył cache współdzielony globalnie, między organizacjami, u 7 z 17 dostawców API, a co najmniej pięciu zmieniło to dopiero po zgłoszeniu. Rozdziel cache per klient (w Anthropic osobny workspace, w OpenAI od GPT-5.6 osobny prompt_cache_key; w starszych modelach klucz wpływa tylko na routing) albo trzymaj wrażliwe dane poza wspólnym prefiksem.

### Źródła

- [Dokumentacja Claude: prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [Dokumentacja OpenAI: prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)
- [Manus: Context Engineering for AI Agents](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
- [Auditing Prompt Caching in Language Model APIs (arXiv)](https://arxiv.org/abs/2502.07776)

Strona interaktywna: https://howaiworks.dev/pl/promptcache/