Prompt Caching w Claude API w Pythonie (2026)

Aktualizacja: 31 maja 2026

Prompt caching w Claude API to mechanizm, który zapisuje fragmenty promptu po stronie Anthropic i przy kolejnych wywołaniach pobiera je z cache zamiast przeliczać, obniżając koszt cachowanych tokenów wejściowych o około 90% i skracając latencję pierwszego tokenu 2–5 razy. W Pythonie wystarczy dodać pole cache_control do bloku treści w wiadomości, system prompcie lub definicji narzędzia. W tym poradniku pokażę krok po kroku, jak skonfigurować cache w SDK anthropic, kiedy używać domyślnego TTL 5 minut, a kiedy rozszerzonego 1 godziny, jak cachować definicje tool use i jak realnie zmierzyć oszczędności na produkcji. Bez prompt theatre, tylko liczby.

• Cachowane tokeny wejściowe kosztują w Claude 3.5/4 około 10% ceny standardowych. Przy długich system promptach lub dokumentach RAG realne oszczędności sięgają 85–92%.
• Minimalny rozmiar bloku do cache to 1024 tokeny dla Sonnet/Opus i 2048 dla Haiku. Krótsze prompty Anthropic po prostu pomija.
• Domyślny TTL to 5 minut (ephemeral), rozszerzony 1 godzina kosztuje 2× cenę zapisu, ale opłaca się przy agentach okresowych i kolejkach.
• Cache działa również dla definicji narzędzi (tools) i obrazów, co dla agentów z dużym zestawem tool use bywa decydujące dla budżetu.
• Pomiar oszczędności: pola cache_creation_input_tokens i cache_read_input_tokens w odpowiedzi API. Bez nich operujesz na życzeniach, nie danych.
• Cache jest prefix-matched: kolejność bloków musi być identyczna, inaczej trafienie będzie zerowe, a Ty zapłacisz pełną stawkę.

Czym jest prompt caching w Claude API?

Prompt caching to funkcja Anthropic API, która pozwala oznaczyć fragment promptu jako cacheable. Przy kolejnych wywołaniach z tym samym prefixem fragment jest pobierany z pamięci podręcznej Anthropic zamiast przepuszczany przez model. W praktyce: pierwszy request zapisuje cache (płacisz 1,25× standardowej stawki za zapis), a każdy kolejny czyta z cache (płacisz tylko 0,1× standardowej stawki). Cache jest przypisany do organizacji i modelu, więc nie wycieka między klientami.

Mechanizm działa na zasadzie prefix matching. Claude porównuje początek nowego promptu z istniejącymi wpisami i jeśli prefix jest bajt po bajcie identyczny aż do oznaczenia cache_control, dostajesz hit. Wszystko, co znajduje się po breakpoincie, jest przetwarzane jako świeży input. To dlatego cache jest idealny do scenariuszy, gdzie masz duży, niezmienny kontekst (długi system prompt, dokument, zestaw narzędzi) i zmieniającą się treść użytkownika na końcu.

Cache ephemeral ma domyślny TTL 5 minut od ostatniego użycia (sliding window), bo każde trafienie odświeża licznik. Od końca 2024 dostępny jest też extended cache z TTL 1 godziny, który kosztuje 2× przy zapisie, ale dla agentów uruchamianych okresowo lub kolejek zadań to różnica między płaceniem za cache raz na dobę a kilkanaście razy. Szczegóły są w oficjalnej dokumentacji prompt caching.

Kiedy używać prompt caching, a kiedy nie

W mojej praktyce z agentami i pipeline'ami RAG cache opłaca się w trzech wzorcach: długi system prompt z instrukcjami (powyżej 1500 tokenów), RAG z dużym fragmentem dokumentu (powyżej 2000 tokenów wkleconych do każdego pytania) oraz agenci tool use z dziesiątkami narzędzi (definicje narzędzi liczone razem to często ponad 3000 tokenów). W każdym z tych przypadków stosunek niezmiennego kontekstu do zmiennego inputu użytkownika jest 10:1 lub większy. Wtedy cache spłaca się już przy drugim requeście.

Cache nie ma sensu, gdy każdy request ma inny prompt (np. one-shot klasyfikacja krótkich wiadomości), gdy długość niezmiennego kontekstu jest poniżej minimum (1024 tokeny dla Sonnet/Opus, 2048 dla Haiku) albo gdy między wywołaniami jest więcej niż 5 minut (TTL ephemeral) lub godzina (TTL extended). W tych scenariuszach zapłacisz 25% premii za zapis cache, którego nikt nie przeczyta. Trafiłem na to przy migracji jednego klienta, zostawione cache w endpointcie one-shot kosztowało dosłownie tyle samo, ile uratowane gdzie indziej.

Warto też pamiętać, że cache nie kompresuje promptu. Jeśli walczysz z limitem 200k tokenów kontekstu w Sonnet, prompt caching tego limitu nie zmienia (pomaga tylko z kosztem i latencją, nie z rozmiarem).

Instalacja i pierwsza konfiguracja w Pythonie

SDK anthropic od wersji 0.34 wspiera cache_control natywnie. Nie potrzebujesz już dodatkowego headera, jak w 2024. Instalacja standardowa:

pip install "anthropic>=0.40.0"
export ANTHROPIC_API_KEY="sk-ant-..."

Najprostszy przykład, cachowany system prompt:

from anthropic import Anthropic

client = Anthropic()

LONG_SYSTEM_PROMPT = (
    "Jesteś asystentem prawnym specjalizującym się w polskim KPA.\n"
    "... tutaj 2000+ tokenów instrukcji, przykładów, formatów odpowiedzi ..."
)

def ask(question: str):
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": LONG_SYSTEM_PROMPT,
                "cache_control": {"type": "ephemeral"},
            }
        ],
        messages=[{"role": "user", "content": question}],
    )
    print("cache_creation:", response.usage.cache_creation_input_tokens)
    print("cache_read:    ", response.usage.cache_read_input_tokens)
    print("input:         ", response.usage.input_tokens)
    return response.content[0].text

ask("Jaki jest termin na odwołanie od decyzji administracyjnej?")
ask("A co jeśli decyzja nie zawiera pouczenia?")

Pierwsze wywołanie zwróci cache_creation_input_tokens ≈ 2000 i cache_read = 0. Drugie, w ciągu 5 minut: cache_creation = 0, cache_read ≈ 2000. Płacisz 90% mniej za 2000 tokenów, a Time-to-First-Token spada zwykle z ~1,5 s do ~0,4 s.

Jak cachować system prompt i dokumenty RAG

W pipeline'ach RAG zwykle wstrzykujemy najlepiej dopasowane fragmenty dokumentów do każdego zapytania. Jeśli korpus dokumentów jest stabilny i mały (np. dokumentacja produktu), opłaca się cachować cały dokument w system promcie i zaufać Claude'owi w znajdowaniu odpowiedzi. Zyskujesz prostotę i ogromne oszczędności, pod warunkiem że dokument mieści się w kontekście.

Dla większych korpusów lepiej połączyć cache z klasycznym RAG: stałe instrukcje cachujemy w system promcie, dynamicznie wybrane fragmenty wkładamy do wiadomości użytkownika (bez cache). Oto wzorzec, którego używam u klientów:

from anthropic import Anthropic
client = Anthropic()

INSTRUCTIONS = open("system_prompt.md").read()  # ~3500 tokenow
GLOSSARY = open("glossary.md").read()           # ~1800 tokenow

def answer(question: str, retrieved_chunks: list[str]):
    context_block = "\n\n---\n\n".join(retrieved_chunks)
    return client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system=[
            {"type": "text", "text": INSTRUCTIONS,
             "cache_control": {"type": "ephemeral"}},
            {"type": "text", "text": GLOSSARY,
             "cache_control": {"type": "ephemeral"}},
        ],
        messages=[{
            "role": "user",
            "content": f"Kontekst:\n{context_block}\n\nPytanie: {question}",
        }],
    )

Dwa breakpointy w system są celowe. Anthropic dopuszcza maksymalnie 4 cache breakpointy na request, a każdy tworzy osobny prefix do dopasowania. Dzielenie na sensowne segmenty pozwala częściowo trafiać w cache, gdy np. glosariusz się zmieni, ale instrukcje zostaną nienaruszone.

Jeśli budujesz samokorekcyjny pipeline Agentic RAG z LangGraph, prompt caching jest praktycznie obowiązkowy. Bez niego każda iteracja krytyka i retrievera płaci pełną stawkę za ten sam system prompt.

Prompt caching z tool use i agentami

Definicje narzędzi (tools) potrafią być największym kosztem ukrytym w agentach. Zestaw 20 narzędzi z opisami i JSON Schema potrafi spuchnąć do 5–8k tokenów na każdy krok agenta. Cache to zmienia diametralnie. cache_control kładziesz na ostatnim narzędziu w liście, a wszystkie wcześniejsze są cachowane jako prefix.

tools = [
    {"name": "search_db", "description": "...", "input_schema": {}},
    {"name": "send_email", "description": "...", "input_schema": {}},
    # ... 18 kolejnych narzedzi ...
    {
        "name": "create_ticket",
        "description": "Tworzy ticket w Jirze.",
        "input_schema": {},
        "cache_control": {"type": "ephemeral"},
    },
]

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Zaloz ticket o crash w mobile."}],
)

Cache obejmuje wszystko od początku promptu (system + tools) aż do breakpointu. Jeśli chcesz cachować również dotychczasową konwersację w pętli agenta, dodaj drugi breakpoint na ostatniej wiadomości assistant. Każdy następny krok agenta czyta wtedy z cache zarówno całą historię, jak i wszystkie narzędzia.

Mechanizm jest spójny z tym, co opisałem w poradniku tool use w Claude API. Cache nie wpływa na semantykę wywołań narzędzi, tylko na rozliczenie. Działa identycznie z serwerami Model Context Protocol (MCP): definicje narzędzi pobrane z serwera MCP możesz cachować dokładnie tak samo.

TTL 5 minut vs 1 godzina – co się opłaca?

Anthropic udostępnia dwa warianty TTL i wybór jednego z nich to często różnica między 30% a 80% oszczędności w skali miesiąca.

Cecha	Ephemeral 5 min	Extended 1 godzina
Cena zapisu (vs input)	1,25×	2,00×
Cena odczytu (vs input)	0,10×	0,10×
Sliding window	tak (odświeża się przy hicie)	tak
Próg opłacalności (hity)	≥2 w 5 min	≥3 w godzinę
Idealne use case	chat live, panel operatora	cron, kolejki zadań, batch
Konfiguracja	{"type": "ephemeral"}	{"type": "ephemeral", "ttl": "1h"}

Praktyczna reguła: jeśli oczekiwany rozkład requestów jest burstowy (sesja użytkownika, pętla agenta), TTL 5 minut zwykle wygrywa. Jeśli requesty rozkładają się równomiernie w czasie (worker, który odpytuje kolejkę co 10 minut), TTL 1 godziny zwraca się już przy pierwszym dodatkowym hicie, którego nie złapałbyś z 5-minutowym oknem.

Jak zmierzyć realne oszczędności

Bez pomiaru prompt caching staje się dokładnie tym, czego nie znoszę, prompt theatre. Każdy messages.create zwraca obiekt usage z czterema kluczowymi polami: input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens. Zbieraj je do każdej tracy.

# Cennik Claude Sonnet 4.6 (kwiecien 2026, USD / 1M tokenow)
PRICE_INPUT       = 3.00
PRICE_CACHE_WRITE = 3.75   # 1.25x input
PRICE_CACHE_READ  = 0.30   # 0.10x input
PRICE_OUTPUT      = 15.00

def calc_cost(usage) -> float:
    return (
        usage.input_tokens                * PRICE_INPUT       +
        usage.cache_creation_input_tokens * PRICE_CACHE_WRITE +
        usage.cache_read_input_tokens     * PRICE_CACHE_READ  +
        usage.output_tokens               * PRICE_OUTPUT
    ) / 1_000_000

def baseline_cost(usage) -> float:
    # ile by kosztowalo, gdyby cache nie istnial
    total_input = (usage.input_tokens
                   + usage.cache_creation_input_tokens
                   + usage.cache_read_input_tokens)
    return (total_input * PRICE_INPUT + usage.output_tokens * PRICE_OUTPUT) / 1_000_000

# po requescie:
saved = baseline_cost(r.usage) - calc_cost(r.usage)
print(f"Saved: ${saved:.6f} ({saved/baseline_cost(r.usage)*100:.1f}%)")

U klientów najczęściej widzę oszczędność rzędu 60–85% na koszcie wejścia po pełnym wdrożeniu, co dla agentów RAG odpowiada 40–60% redukcji całkowitego rachunku (output wciąż kosztuje pełną stawkę). Te liczby warto śledzić w jednym dashboardzie razem z hit rate. Jeśli hit rate spada poniżej 70%, to sygnał, że albo breakpointy są źle ustawione, albo TTL jest za krótki. Świetnie do tego nadaje się Langfuse, który opisywałem w kontekście ewaluacji agentów AI w Pythonie. Pola usage z Anthropic mapują się bezpośrednio na jego model śledzenia tokenów.

Najczęstsze błędy i pułapki

Szczerze, pięć rzeczy, na które natykam się w code review prawie zawsze, gdy ktoś dodaje prompt caching pierwszy raz:

1. Zmienna część we wnętrzu cachowanego bloku. Dodajesz datetime.now() albo identyfikator usera do system promptu „dla kontekstu" i już prefix nigdy się nie powtarza. Cache creation rośnie, read jest płaski. Trzymaj zmienność po breakpoincie.
2. Zmiana kolejności narzędzi przy każdym wywołaniu. Niektórzy generują listę tools ze słownika i Python <3.7 albo niedeterministyczne źródło daje za każdym razem inny porządek. Sortuj jawnie.
3. Cache pod progiem 1024 tokenów. Anthropic po cichu pomija breakpoint zbyt krótki. Nie dostajesz błędu, dostajesz pełną cenę. Sprawdzaj długość przed wysyłką.
4. Brak monitorowania hit rate. Jeden źle przesunięty znak białej spacji w szablonie i hit rate spada do 0. Bez metryki nie zobaczysz tego miesiącami (mi się raz zdarzyło zauważyć dopiero po kwartale).
5. Cache w środowiskach testowych. Test integracyjny robi 3 requesty raz na deploy, więc płacisz tylko za zapis. Wyłączaj cache w testach lub mockuj messages.create.

Cały kontrakt API jest opisany w repozytorium anthropic-sdk-python na GitHubie. Warto zerknąć w typy BetaPromptCachingBetaCacheControlEphemeralParam, żeby zobaczyć dokładne kształty payloadu, zanim zaczniesz konstruować requesty dynamicznie.

Najczęściej zadawane pytania

Ile kosztuje prompt caching w Claude API?

Zapis do cache kosztuje 1,25× standardowej ceny inputu (TTL 5 min) lub 2× (TTL 1h). Odczyt z cache kosztuje 0,10× standardowej ceny, czyli 90% taniej. Output (odpowiedź modelu) jest rozliczany normalnie, cache nie ma na niego wpływu.

Jak długo trwa pamięć podręczna promptu w Claude?

Domyślnie 5 minut od ostatniego trafienia (sliding window) dla cache ephemeral. Dostępny jest też wariant extended z TTL 1 godziny, który kosztuje 2× przy zapisie. Cache nie ma twardego limitu maksymalnej liczby wpisów, ale każdy request może mieć maksymalnie 4 breakpointy.

Czy prompt caching działa z tool use i function calling?

Tak. Możesz cachować zarówno definicje narzędzi (pole tools), jak i historię wywołań w wiadomościach. cache_control umieszczasz na ostatnim narzędziu, które chcesz włączyć do prefixu, a wszystkie wcześniejsze są cachowane automatycznie. To kluczowe dla agentów z dużym zestawem narzędzi.

Czy można cachować system prompt w Claude?

Tak i jest to najczęstszy use case. System prompt musi być przekazany jako lista bloków (nie string), z polem cache_control na bloku do zapamiętania. Minimalna długość to 1024 tokeny dla modeli Sonnet/Opus i 2048 dla Haiku. Krótsze prompty zostaną zignorowane bez ostrzeżenia.

Dlaczego mój prompt caching nie działa mimo ustawienia cache_control?

Najczęstsze przyczyny: prompt jest poniżej minimalnej długości 1024/2048 tokenów, w cachowanym bloku znajduje się zmienna część (data, ID użytkownika), kolejność bloków zmienia się między requestami albo system prompt jest przekazany jako string zamiast listy bloków. Zawsze sprawdzaj response.usage.cache_creation_input_tokens i cache_read_input_tokens, by zweryfikować realne zachowanie cache.