Prompt caching LLM 2026: Python průvodce

Aktualizováno: 5. září 2026

Prompt caching je funkce LLM API, která ukládá zpracovaný prefix promptu (systémový prompt, definice nástrojů, dlouhý kontext) na straně poskytovatele a při další shodě prefixu vrací výsledek přibližně 10× levněji a 2–5× rychleji. V praxi ho aktivujete buď implicitně (OpenAI, Gemini 2.5 od 1024–4096 tokenů), nebo explicitně přes cache_control u Anthropic Claude. Tenhle průvodce ukazuje, jak prompt caching využít v Pythonu u tří hlavních poskytovatelů, kolik reálně ušetří a čím se liší od sémantického cachování odpovědí.

Prompt caching je KV-cache mechanismus, který přeskočí opakované zpracování stejného prefixu. Typicky 90 % úspora na cached tokenech a 50–80 % nižší latence do prvního tokenu.
Anthropic používá explicitní cache_control markery s 5min ephemeral nebo 1h extended TTL. Minimum je 1024 tokenů (Sonnet/Opus) nebo 2048 (Haiku).
OpenAI cachuje automaticky prompty ≥1024 tokenů bez konfigurace. TTL je 5–10 minut a při cache hit dostanete 50 % slevu na input tokeny (o3/o4/gpt-5 rodina až 75 %).
Google Gemini nabízí implicit caching (2.5 Flash od 1024 t., Pro od 4096 t., 75 % sleva) i explicit CachedContent s vlastním TTL a fixní storage cenou.
Prompt caching a sémantické cachování řeší různé problémy. První snižuje náklady na opakovaný prefix, druhé eliminuje celé duplicitní requesty.
Nejvyšší ROI má prompt caching u RAG pipeline s dlouhým kontextem, agentů s velkými tool schematy a chatbotů s masivním systémovým promptem.

Jak funguje prompt caching pod pokličkou

Když LLM zpracovává prompt, každý token projde vrstvami transformeru a v každé vrstvě se spočítají key a value vektory pro attention mechanismus. Tenhle KV cache je drahý. U modelu Claude Sonnet zpracování 100 000 tokenů systémového promptu trvá 3–8 sekund a spálí značné množství GPU. Prompt caching tento vypočtený KV cache uloží na straně poskytovatele a při dalším requestu se stejným prefixem ho jen znovu načte místo toho, aby se počítal od nuly.

Klíčové omezení: cache je vždy prefix-based. Musíte skládat prompty tak, aby se stabilní části (systémový prompt, tool definitions, dlouhý dokument) nacházely před proměnnou částí (aktuální dotaz uživatele). Pokud změníte byť jediný token v systémovém promptu, celý prefix se přepočítá znovu. Tohle pravidlo platí u všech tří poskytovatelů a je nejčastějším důvodem, proč lidem v produkci nefunguje očekávaná úspora. (V posledním projektu jsem si tohle nabil nos: injektoval jsem timestamp do systémového promptu a divil se, proč mi hit rate zůstává na nule.)

Druhé praktické omezení je TTL (time-to-live). Ephemeral cache u Anthropic vydrží 5 minut od posledního použití, extended cache 1 hodinu. OpenAI garantuje zhruba 5–10 minut, ale někdy i deset. Gemini explicit cache si nastavíte sami (typicky 10 min až několik hodin). Pokud vaše aplikace obsluhuje sporadické dotazy s odstupem hodin, ephemeral cache neuvidíte ani jednou. Vyplatí se buď extended TTL, nebo synthetic keep-alive request.

Anthropic Claude: explicitní cache_control v Pythonu

Anthropic vyžaduje, abyste sami označili, které bloky promptu se mají cachovat, pomocí cache_control markeru. Vypadá to jednoduše a skýtá to jeden benefit: máte plnou kontrolu nad tím, kde jsou cache breakpointy, což je klíčové u RAG a agentů s dlouhým kontextem. Detaily jsou v oficiální dokumentaci Anthropic prompt caching.

from anthropic import Anthropic

client = Anthropic()

SYSTEM_PROMPT = open("system_prompt_10k_tokens.md").read()
LARGE_DOCUMENT = open("company_handbook.md").read()

def ask_with_cache(user_question: str) -> str:
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": SYSTEM_PROMPT,
                "cache_control": {"type": "ephemeral"},
            },
            {
                "type": "text",
                "text": LARGE_DOCUMENT,
                "cache_control": {"type": "ephemeral"},
            },
        ],
        messages=[{"role": "user", "content": user_question}],
    )
    usage = response.usage
    print(f"cache_creation: {usage.cache_creation_input_tokens}")
    print(f"cache_read:     {usage.cache_read_input_tokens}")
    print(f"input (uncached): {usage.input_tokens}")
    return response.content[0].text

ask_with_cache("Jaká je politika home office?")
ask_with_cache("Kolik dní dovolené mají noví zaměstnanci?")

První volání zapíše dva bloky do cache (cache_creation_input_tokens jsou dražší, 125 % ceny běžných input tokenů). Druhé volání během 5 minut vrátí cache_read_input_tokens (10 % ceny běžných input tokenů). Máte až 4 cache breakpointy na jeden request, což umožňuje granulární kontrolu: systémový prompt zvlášť, tool definitions zvlášť, dokument zvlášť, historie konverzace zvlášť.

Cachování tool definitions u agentů

U function calling a tool use pipeline tvoří definice nástrojů (JSON schemata) často 2000–8000 tokenů, které se nikdy nemění. Umístěte je hned za systémový prompt a označte poslední tool cache breakpointem:

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=2048,
    system=[{"type": "text", "text": SYSTEM_PROMPT,
             "cache_control": {"type": "ephemeral"}}],
    tools=[
        {"name": "search_db", "description": "...", "input_schema": {...}},
        {"name": "send_email", "description": "...", "input_schema": {...}},
        {"name": "create_ticket", "description": "...", "input_schema": {...},
         "cache_control": {"type": "ephemeral"}},
    ],
    messages=history + [{"role": "user", "content": user_input}],
)

OpenAI: automatické cachování a jak ho ověřit

OpenAI zavedlo prompt caching v říjnu 2024 jako plně automatickou funkci, takže nemusíte v kódu měnit vůbec nic. Pokud prompt přesáhne 1024 tokenů a má stejný prefix jako nedávný request na stejném účtu, OpenAI vrátí cached_tokens s 50% slevou (u modelů o3, o4-mini a gpt-5 rodiny až 75 %). TTL se pohybuje mezi 5 a 10 minutami a v obdobích nízkého zatížení někdy až hodinu. Kompletní podmínky najdete v OpenAI prompt caching guide.

from openai import OpenAI

client = OpenAI()

SYSTEM_PROMPT = open("system_prompt_10k_tokens.md").read()

def ask_openai(user_question: str) -> str:
    resp = client.chat.completions.create(
        model="gpt-5",
        messages=[
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "user", "content": user_question},
        ],
    )
    usage = resp.usage
    cached = usage.prompt_tokens_details.cached_tokens
    total_in = usage.prompt_tokens
    print(f"prompt tokens: {total_in}  cached: {cached}  "
          f"hit rate: {cached / total_in:.1%}")
    return resp.choices[0].message.content

ask_openai("Vysvětli mi HR politiku")
ask_openai("A co onboarding?")

V prvním volání bude cached_tokens nula, protože se cache právě vytváří. Druhé volání by mělo vrátit číslo blízké délce systémového promptu (zaokrouhleno dolů na násobky 128 tokenů). Pokud se hit rate drží na nule i po několika requestech, nejčastější příčiny jsou tři: prefix je pod 1024 tokenů, mezi requesty ubíhá víc než zhruba 10 minut, nebo se prompt mění dřív než pomyslený cache breakpoint.

Google Gemini: implicit vs explicit CachedContent

Gemini nabízí dva režimy současně. Implicit caching je od Gemini 2.5 Flash aktivní automaticky pro prompty ≥1024 tokenů (Pro ≥4096 t.) a poskytuje 75 % slevu na cached input tokeny. Explicit CachedContent vyžaduje, abyste vytvořili objekt cache s vlastním TTL, dostali zpět jeho handle a při každém requestu ho předali. Explicit varianta účtuje dodatečnou storage cenu za GB-hodinu, ale garantuje hit rate 100 % po dobu TTL. Přehled najdete v Gemini context caching dokumentaci.

from google import genai
from google.genai import types
import datetime

client = genai.Client()

document_text = open("large_manual.md").read()

cache = client.caches.create(
    model="gemini-2.5-pro",
    config=types.CreateCachedContentConfig(
        display_name="product_manual_v3",
        system_instruction="Jsi asistent zákaznické podpory. Odpovídej stručně.",
        contents=[document_text],
        ttl=datetime.timedelta(hours=1),
    ),
)
print(f"cache handle: {cache.name}  tokens: {cache.usage_metadata.total_token_count}")

def ask_gemini(question: str) -> str:
    resp = client.models.generate_content(
        model="gemini-2.5-pro",
        contents=question,
        config=types.GenerateContentConfig(cached_content=cache.name),
    )
    md = resp.usage_metadata
    print(f"cached: {md.cached_content_token_count}  "
          f"prompt: {md.prompt_token_count}")
    return resp.text

ask_gemini("Jak resetovat zařízení do továrního nastavení?")
ask_gemini("A co když je zamčené heslem?")

Explicit cache dává smysl u dokumentů, které dotazujete opakovaně během delší doby. Například právní kancelář analyzující tentýž kontrakt několik hodin, nebo customer support agent, který drží celý manuál v kontextu po celou pracovní směnu. Nezapomeňte cache po skončení práce smazat přes client.caches.delete(cache.name), jinak se storage účtuje dál (učil jsem se tuhle lekci na faktuře).

Kolik reálně ušetří prompt caching

Cenová logika je u všech tří poskytovatelů podobná: cache write je dražší než běžný input, cache read je výrazně levnější. Konkrétní čísla (stav září 2026) shrnuje tabulka:

Poskytovatel / model	Cache write	Cache read	Min. délka	TTL
Claude Sonnet 5 (ephemeral)	125 % input	10 % input	1024 t.	5 min
Claude Sonnet 5 (extended 1h)	200 % input	10 % input	1024 t.	60 min
Claude Haiku 4.5	125 % input	10 % input	2048 t.	5 min
GPT-5 / o4-mini	100 % input	25 % input	1024 t.	5–10 min
GPT-4o rodina	100 % input	50 % input	1024 t.	5–10 min
Gemini 2.5 Pro (implicit)	100 % input	25 % input	4096 t.	~5 min
Gemini 2.5 Flash (explicit)	100 % input + storage	25 % input	1024 t.	libovolné

Modelový příklad: RAG chatbot se systémovým promptem 6000 tokenů, retrievovaným kontextem 12 000 tokenů (perzistentní 5 minut) a průměrným dotazem 200 tokenů. Bez cachingu platíte 18 200 input tokenů na dotaz. S cachingem u Claude Sonnet 5: první dotaz 6000×1,25 + 12 000×1,25 + 200 = 22 700 tokenových jednotek, každý další dotaz do 5 minut jen 18 000×0,10 + 200 = 2000 jednotek. Při 10 dotazech v pětiminutovém okně klesnou náklady z 182 000 na 40 700, což je úspora 78 %.

Prompt caching vs sémantické cachování

Tyhle dva mechanismy si často pletou i zkušení engineeři, ale řeší úplně jiné problémy. Prompt caching zrychluje a zlevňuje zpracování opakovaného prefixu promptu. Samotná odpověď se generuje pokaždé znovu. Sémantické cachování naopak přeskočí celý LLM request, když je nový dotaz sémanticky podobný nějakému předchozímu, a vrátí uloženou odpověď z Redis nebo vektorové databáze.

Vlastnost	Prompt caching	Sémantické cachování
Kde běží	U poskytovatele (Anthropic/OpenAI/Google)	Ve vaší infrastruktuře (Redis + embeddings)
Co se cachuje	Vypočtený KV cache prefixu	Celý pár (dotaz → odpověď)
Kdy je hit	Přesná shoda prefixu tokenů	Cosine similarity dotazu > práh
Úspora latence	50–80 % TTFT	95–99 % (žádný LLM call)
Úspora nákladů	50–90 % na input tokenech	100 % na cache hit
Riziko	Žádné, odpověď se generuje čerstvě	Zastaralá odpověď, false positive hit

V produkci se obě techniky doplňují. Nejdřív zkontrolujte sémantický cache: pokud je hit, vrátíte odpověď za desítky milisekund. Pokud je miss, pošlete request na LLM s aktivním prompt cachingem, který zredukuje jak latenci, tak náklady na zpracování společného prefixu. Detaily implementace najdete v článku Sémantické cachování LLM v Pythonu.

Kdy prompt caching nasadit a kdy se mu vyhnout

Prompt caching není zázračná pilulka a v některých scénářích může dokonce prodražit provoz, protože cache write stojí 125 % standardní ceny (Anthropic) nebo znamená storage poplatky (Gemini explicit). Ideální kandidáti jsou:

RAG chatboti se stabilním systémovým promptem a velkým, ale statickým kontextem (dokumentace, produktový katalog).
Agenti s bohatou tool sadou: 15+ nástrojů znamená často 5000+ tokenů schémat.
Multi-turn konverzace, kde historie roste, ale prefix zůstává stabilní.
Batch analýza jednoho dokumentu s mnoha dotazy: právní review, medical records analysis, code review.

Naopak nezapínejte prompt caching v těchto případech:

Jednorázové dotazy bez opakovaného prefixu, kde každý request má unikátní systémový prompt.
Sporadické dotazy s odstupem hodin, když nechcete platit extended cache.
Prompt pod minimální délkou: pod 1024 tokenů (2048 pro Claude Haiku) cache vůbec nevznikne.
Prompty s per-request dynamickým obsahem uprostřed, například timestamp injektovaný do systémového promptu ruší cache.

Monitoring cache hit rate v produkci

Nasadit prompt caching bez měření je nejrychlejší cesta k zklamání z nulové úspory. Honestly, tohle je chyba, kterou v produkci vidím pořád. V produkci potřebujete sledovat tři metriky: cache hit rate (procento tokenů, které přišly z cache), cache creation overhead (kolik navíc jste zaplatili za cache write) a effective savings (rozdíl proti scénáři bez cachingu). Nejjednodušší integrace je přes Langfuse pro observabilitu LLM, protože automaticky parsuje usage objekty všech tří poskytovatelů a vizualizuje cache metriky na dashboardu.

from langfuse import observe
from langfuse.openai import openai as lf_openai

@observe(name="rag_query")
def rag_query(user_q: str, context: str) -> str:
    resp = lf_openai.chat.completions.create(
        model="gpt-5",
        messages=[
            {"role": "system", "content": SYSTEM_PROMPT + "\n\n" + context},
            {"role": "user", "content": user_q},
        ],
    )
    usage = resp.usage
    cached = usage.prompt_tokens_details.cached_tokens or 0
    savings = cached * 0.75  # 75% sleva u gpt-5
    print(f"hit_rate={cached/usage.prompt_tokens:.1%} saved_tokens={savings:.0f}")
    return resp.choices[0].message.content

Zdravý cache hit rate v RAG aplikaci se pohybuje mezi 40 % a 85 % celkových input tokenů. Pokud je nižší, buď máte příliš krátký prefix, nebo se prefix mezi requesty mění (typicky kvůli non-deterministickému formátování, časovým razítkům nebo shufflovanému retrievovanému kontextu). Nastavte alarm na propad hit rate pod stanovenou hranici. Takový propad často indikuje deployment, který nechtěně změnil systémový prompt o jeden token.

Často kladené otázky

Jak dlouho vydrží prompt cache?

U Anthropic je výchozí TTL 5 minut od posledního použití (ephemeral), volitelně 1 hodina (extended). OpenAI garantuje 5–10 minut a v období nízkého zatížení někdy až 60 minut. Google Gemini nabízí implicit cache s cca 5min TTL a explicit CachedContent, kde si TTL nastavíte sami (minuty až hodiny).

Kolik ušetří prompt caching v reálné aplikaci?

Typická úspora u RAG chatbota s 10 000 tokenovým systémovým promptem a několika dotazy za minutu je 60–80 % nákladů na input tokeny. U agentů s velkými tool schematy může dosáhnout až 85 %. Latence do prvního tokenu (TTFT) klesne o 50–80 %.

Podporuje OpenAI prompt caching automaticky?

Ano. OpenAI cachuje automaticky všechny prompty od 1024 tokenů výše bez jakékoli konfigurace v kódu. Cache hit poznáte podle pole prompt_tokens_details.cached_tokens v response usage objektu.

Jaký je rozdíl mezi prompt cachingem a sémantickým cachováním?

Prompt caching běží u poskytovatele LLM a cachuje vypočtený KV cache prefixu promptu, přičemž odpověď se generuje pokaždé znovu. Sémantické cachování běží ve vaší infrastruktuře (Redis + embeddings) a vrací celou uloženou odpověď, když je nový dotaz sémanticky podobný předchozímu. Techniky se v produkci doplňují.

Funguje prompt caching s tool use a function calling?

Ano a je to jedno z nejlepších uplatnění. Definice nástrojů bývají 2000–8000 tokenů statického JSON schématu. U Anthropic označíte poslední tool cache_control markerem, u OpenAI a Gemini se tool definice cachují automaticky jako součást prefixu.

Proč mi cache hit rate zůstává nulový?

Tři nejčastější příčiny: prefix je pod minimální délkou (1024 tokenů, u Claude Haiku 2048), mezi requesty ubíhá víc než TTL, nebo se prefix mezi requesty mění byť o jediný token, typicky kvůli časovému razítku, per-request UUID nebo náhodně řazenému kontextu z retrieveru.