Prompt caching Anthropic API po polsku, 90% off i jak to działa 2026

Spis treści

• Czym jest prompt caching
• Mechanizm: breakpoints, hash, TTL
• Cennik (10% read, 125% write)
• Kiedy używać
• Kiedy NIE używać
• Implementacja Python
• Implementacja TypeScript
• Caching w Claude Code (automatic)
• Metryki cache_read i cache_creation
• Przykład ROI
• Antywzorce
• FAQ

Aktualizacja: maj 2026. Prompt caching to najprostsza i najmocniejsza optymalizacja kosztów Anthropic API. Cached read tokens kosztują 10% normalnej ceny (90% off), break-even zwraca się po 3-4 użyciach tego samego promptu. Realne kursanci redukują Anthropic bill o 50-80% w pierwszym miesiącu po wdrożeniu. W tym tutorialu pokazuję mechanizm, code samples Python + TypeScript, integrację z Claude Code i 5 antywzorców z prawdziwej praktyki.

Czym jest prompt caching

Prompt caching to feature Anthropic API wydany w sierpniu 2024, który pozwala oznaczyć fragmenty promptu jako cacheable. Przy kolejnych wywołaniach z tym samym prefiksem Anthropic czyta dane z cache zamiast przetwarzać tokeny od zera. Czas latency spada o 30-50% (na cached prefiksie), koszt o 90% (cached read kosztuje 10% bazowej ceny).

To najprostsza optymalizacja, jaką możesz wprowadzić do swojego API workflow. Bez zmian w kodzie aplikacji, tylko dodanie pola cache_control w odpowiednich miejscach. ROI: każde wywołanie z tym samym system promptem oszczędza około 90% kosztu input tokens po pierwszym wywołaniu.

Jak działa: breakpointy, hash, TTL

Cache działa na zasadzie prefiksu deterministycznego. Anthropic oblicza hash z fragmentu promptu do breakpointa (oznaczonego cache_control: ephemeral) i sprawdza, czy taki hash już istnieje. Jeśli tak (cache hit), dane są czytane z cache. Jeśli nie (cache miss), tworzony jest nowy cache entry i ten request płaci cache write premium.

Cache breakpoints umieszczasz w 3 typowych miejscach:

1. System prompt, na końcu długiej instrukcji, np. po opisie konwencji projektu
2. Tools array, na końcu listy dostępnych narzędzi
3. Messages, w długiej konwersacji (na końcu starszych wiadomości)

TTL działa na zasadzie sliding window: każde użycie cache resetuje 5-minutowy zegar. Jeśli używasz cache co minutę, żyje wiecznie. Jeśli zapomnisz na 6 minut, wygasa.

Cennik: 10% read, 125% write

Multipliery cen względem bazowej ceny modelu

Operacja	Multiplier	Komentarz
Input tokens (no cache)	1.0×	Bazowa cena
Cache write (5 min TTL)	1.25×	Pierwszy zapis
Cache write (1h TTL)	2.0×	Extended TTL premium
Cache read	0.1×	90% off
Output tokens	1.0×	Bez wpływu cache

Break-even na 5-min cache: po 3 użyciach (125% + 10% × 3 = 155% vs 300% bez cache). Na 1h cache: po 6 użyciach (200% + 10% × 6 = 260% vs 600%). Konkretne ceny per model: Sonnet 4.6 ~$3/MTok input bazowo, więc cache read $0.30/MTok. Sprawdź anthropic.com/pricing dla najnowszych.

Kiedy używać prompt caching

• Powtarzalne system prompts, CLAUDE.md, długie instrukcje, persona definicje (świetne ROI)
• Tools schema, gdy masz 10+ narzędzi z opisami (oszczędza tokens przy każdym wywołaniu)
• Multi-turn konwersacja, cache na całej historii, każdy nowy turn płaci tylko za nowy fragment
• RAG z stałym kontekstem, np. dokumentacja firmy doklejana do każdego prompta
• Code review / refactor, gdy ten sam file context jest analizowany wielokrotnie

Kiedy NIE używać prompt caching

• Jednorazowe rozmowy, brak powtórzeń = sam koszt write bez korzyści
• Mały context, prompty poniżej 1024 tokens (Sonnet/Opus) / 2048 (Haiku) nie są cacheowane
• Częste zmiany w prefiksie, np. timestamp w system prompt = nowy hash co każdą sekundę
• Random nonces, każde wywołanie unikalne = cache miss zawsze

Implementacja Python

Z Anthropic SDK 0.34+ używasz pola cache_control w fragmentach promptu. Najprostszy przykład:

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Jesteś senior dev. Konwencje: TypeScript, ESM, Vitest. Naming kebab-case. " * 100,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "Napisz funkcję X"}]
)

print(response.usage)
# Pierwszy wywołanie: cache_creation_input_tokens: 1200, cache_read_input_tokens: 0
# Drugie: cache_creation_input_tokens: 0, cache_read_input_tokens: 1200 (90% off)

Cache z tools schema:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=[
        {"name": "get_weather", "description": "...", "input_schema": {...}},
        # ... 9 więcej narzędzi z długimi opisami
        {
            "name": "last_tool",
            "description": "...",
            "input_schema": {...},
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "..."}]
)

Implementacja TypeScript

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: longSystemPrompt,
      cache_control: { type: "ephemeral" }
    }
  ],
  messages: [{ role: "user", content: userMessage }]
});

console.log(response.usage);
// { input_tokens, cache_creation_input_tokens, cache_read_input_tokens, output_tokens }

Cache w długiej konwersacji (messages history):

messages: [
  { role: "user", content: msg1 },
  { role: "assistant", content: resp1 },
  { role: "user", content: msg2 },
  {
    role: "assistant",
    content: [
      { type: "text", text: resp2, cache_control: { type: "ephemeral" } }
    ]
  },
  // Nowa wiadomość po cache breakpoint, płaci tylko za nią
  { role: "user", content: msg3 }
]

Caching w Claude Code (automatic)

Claude Code (CLI od Anthropic) używa cachingu automatycznie, bez konfiguracji. Cacheowane są:

• CLAUDE.md, czytane na start każdej sesji
• Tools schema, definicje narzędzi (Bash, Edit, Write, MCP tools)
• Konwersacja historyczna, w długich sesjach starsze wiadomości są cacheowane

Możesz sprawdzić cache hit rate uruchamiając Claude Code z flagą --debug, w logach pokażą się pola cache_read_input_tokens i cache_creation_input_tokens. Pełna integracja z Claude Code opisana w Claude Code tutorial po polsku.

Metryki cache_read i cache_creation

W response od Anthropic API masz dostęp do 4 metryk usage:

{
  "usage": {
    "input_tokens": 50,           // nowe tokeny w tym requeście
    "cache_creation_input_tokens": 0,   // nowo zapisane do cache
    "cache_read_input_tokens": 1200,    // czytane z cache (90% off)
    "output_tokens": 300
  }
}

Cache hit rate = cache_read / (cache_read + input + cache_creation). Cel: 60-80% przy intensywnym workflow z powtarzalnym system promptem. Poniżej 40% oznacza że źle ustawiłeś breakpointy albo prompt zbyt często się zmienia.

Przykład ROI: 10k tokens system prompt × 100 wywołań

Realistyczny scenariusz: aplikacja używa Anthropic API ze stałym system promptem o długości 10 000 tokens. Robi 100 wywołań dziennie.

Porównanie kosztów Sonnet 4.6, $3/MTok input bazowo

Wariant	Koszt input tokens / dzień	Koszt / miesiąc (30 dni)
Bez cache	100 × 10k × $3/MTok = $3	$90 (~360 zł)
Z cache 5min (1× write, 99× read)	10k × $3.75/MTok + 99 × 10k × $0.30/MTok = $0.04 + $0.30 = $0.34	$10.20 (~41 zł)

Oszczędność: $90 → $10 = 88% off. Roczna skala dla intensywnego workflow: $1080 → $122, zaoszczędzone $958. Dla zespołu 10 devów: nieco poniżej $10k oszczędności rocznie.

Antywzorce

1. Timestamp w system promptcie, zmienia hash co sekundę, cache zawsze miss. Trzymaj prefiks deterministyczny.
2. Brak monitoringu cache hit rate, nie wiesz czy cache działa. Loguj cache_read_input_tokens w każdym requeście.
3. Cache na mały prompt, poniżej 1024 tokens (Sonnet) cache nie działa, zwracane 0. Sprawdź minimum przed dodaniem cache_control.
4. 4 breakpointy zamiast 1, jeśli prompt rzadko się zmienia w środku, 1 breakpoint na końcu wystarczy. Każdy dodatkowy = potencjalne miss przy zmianie.
5. Cache z random nonce w prompcie, każde wywołanie unikalne, cache zawsze miss. Trzymaj prefiks bez randomów.

FAQ

Najczęstsze pytania o prompt caching znajdziesz w sekcji FAQ powyżej.

Powiązane artykuły

Claude Code•9 min

Claude Code cena 2026, ile kosztuje i czy jest darmowy

Claude Code cena w PLN i USD, plany Pro i Max, API pay-as-you-go, darmowe kredyty i alternatywy. Najtańsza legalna ścieżka. Stan maj 2026.

Czytaj

Claude Code•9 min

Claude Max plan po polsku, ceny i limity 2026

Plan Claude Max po polsku: ceny Max 5x i 20x, ile zapytań daje, Claude Pro vs Max, Max vs API. Limity sesji i tygodniowe. Stan maj 2026, dla kogo warto.

Czytaj

Claude Code•15 min

Claude Code Skills po polsku, tutorial Agent Skills 2026

Pierwszy polski tutorial Agent Skills w Claude Code. SKILL.md, frontmatter, progressive disclosure, jak tworzyć skille krok po kroku, vs subagents i MCP.

Czytaj