Kad Claude obrađuje prompt, interno izračunava takozvani KV (key-value) cache — matematički prikaz već procesiranih tokena u pažnji modela. Prompt caching omogućuje da Anthropic taj međurezultat privremeno zadrži. Sljedeći zahtjev koji koristi isti prefiks (identičan sistemski prompt, definicije alata i povijest) jednostavno preskače skupi korak ponovnog izračuna.
Za aplikacije s velikim kontekstnim prozorom, ovo nije kozmetička optimizacija. Recimo da 100 000 tokena konteksta šaljete 50 puta tijekom radnog sata. Bez keša platit ćete punu cijenu svaki put. S kešem? Prvi zahtjev košta 125 % (premija za upis), a svaki sljedeći — tek 10 %.
Kada ima smisla koristiti prompt caching
- Veliki sistemski promptovi: detaljne instrukcije za agenta, stilski vodiči, priručnici.
- Definicije alata (tool use): skupovi od 10+ alata s kompleksnim JSON shemama.
- Dohvaćeni dokumenti u RAG-u: dugi dokumenti koji se u sesiji ponavljaju.
- Višekratne konverzacije: chat povijest koja se akumulira između zahtjeva.
- Few-shot primjeri: dugačke liste demonstrativnih parova ulaz-izlaz.
Kada NEMA smisla
Ako je svaki vaš prompt jedinstven (primjerice, pojedinačna izolirana pitanja korisnika bez zajedničkog konteksta), prompt caching će vas samo koštati dodatnih 25 %. Jer ćete plaćati upise u keš koje, realno, nitko nikad neće pročitati.
Cjenovni model prompt cachinga 2026.
Cijene su izražene kao množitelji bazne cijene ulaznog tokena (base input token price):
- Obični ulazni token: 1,0× (standardna cijena).
- Upis u keš, 5 min TTL: 1,25× (25 % premija za prvo keširanje).
- Upis u keš, 1 sat TTL: 2,0× (dvostruka cijena za prošireni TTL).
- Čitanje iz keša: 0,1× (90 % popusta na svaki cache hit).
- Izlazni token: nepromijenjeno (generiranje se ne kešira).
Praktični izračun povrata ulaganja
Pretpostavimo prompt od 100 000 tokena i claude-sonnet-4-5 cijenu od 3 USD po milijun ulaznih tokena.
- Bez cachinga, 10 zahtjeva: 10 × 100 000 × 3 USD/1M = 3,00 USD.
- S 5-minutnim kešem, 10 zahtjeva: 1 × 1,25 × 0,30 USD + 9 × 0,10 × 0,30 USD = 0,375 + 0,27 = 0,645 USD.
Ušteda: ~78,5 %. Uz dovoljno cache hitova iznad 4-5, ušteda se približava teoretskom maksimumu od 90 %. Nije loše za par dodatnih redaka koda.
Prvi korak: minimalna implementacija u Pythonu
Prije bilo čega provjerite da imate instaliran anthropic SDK verzije 0.39.0 ili novije:
pip install "anthropic>=0.39.0"
Postavite API ključ:
export ANTHROPIC_API_KEY="sk-ant-..."
Sljedeći primjer pokazuje kako keširati dugački sistemski prompt. Ključna je oznaka cache_control s tipom ephemeral:
from anthropic import Anthropic
client = Anthropic()
LONG_SYSTEM_PROMPT = """
Ti si strucni pravni asistent specijaliziran za hrvatsko radno pravo.
... (minimalno 1024 tokena statickog sadrzaja) ...
"""
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": LONG_SYSTEM_PROMPT,
"cache_control": {"type": "ephemeral"}
}
],
messages=[
{"role": "user", "content": "Koji je otkazni rok nakon 5 godina staza?"}
]
)
print(response.usage)
# Usage(input_tokens=15,
# cache_creation_input_tokens=1240,
# cache_read_input_tokens=0,
# output_tokens=280)
Na prvom pozivu vidjet ćete cache_creation_input_tokens > 0. Na drugom pozivu istim sistemskim promptom cache_read_input_tokens bit će popunjen, a cache_creation_input_tokens jednak 0 — to je potvrda cache hita. Jednostavno.
Važno: minimalna veličina bloka
Prompt caching odbacuje blokove kraće od praga:
- Claude Opus 4.1, Sonnet 4.5, Sonnet 4: minimalno 1 024 tokena.
- Claude Haiku 4.5, Haiku 3.5, Haiku 3: minimalno 2 048 tokena.
Ako je vaš sistemski prompt kraći, spojite ga s definicijama alata u isti keširani blok tako da zajedno prijeđu prag. Ovo je ujedno i najčešća zamka u koju razvojni timovi upadaju prvi put.
Hijerarhija keširanja: tools → system → messages
Anthropic gradi prefiks keša u fiksnom redoslijedu: najprije definicije alata, potom sistemski prompt, zatim povijest poruka. Cache breakpoint na poruci implicitno keširа sve što je ispred nje — uključujući tools i system.
Možete postaviti do 4 breakpointa u jednom zahtjevu, što omogućuje različite granice za različite dijelove prompta. Dobra vijest: dodavanje više breakpointova ne košta dodatno. Naplata ovisi isključivo o tome koliko tokena je stvarno keširano i pročitano.
Primjer s više breakpointova: RAG s dokumentima
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=[
{
"name": "search_knowledge_base",
"description": "...",
"input_schema": {...},
"cache_control": {"type": "ephemeral"} # breakpoint 1
}
],
system=[
{
"type": "text",
"text": SYSTEM_INSTRUCTIONS,
"cache_control": {"type": "ephemeral"} # breakpoint 2
}
],
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": RETRIEVED_DOCUMENTS,
"cache_control": {"type": "ephemeral"} # breakpoint 3
},
{
"type": "text",
"text": user_question
}
]
}
]
)
Ovdje alati i sistemski prompt keširaju se zajedno i ostaju stabilni tijekom svih zahtjeva. Dohvaćeni dokumenti keširaju se na granici 3 — ako korisnik postavi više pitanja o istim dokumentima, svi daljnji pozivi koriste keš. Ovo je, po mom mišljenju, jedan od najneiskorištenijih obrazaca u tipičnim RAG implementacijama.
TTL od 5 minuta ili 1 sata: kada odabrati koji
Zadani TTL je 5 minuta, a timer se resetirа na svaki pogodak. Dakle, u aktivnoj sesiji s upitom svake 2 minute keš ostaje topao beskonačno — bez dodatne cijene.
TTL od 1 sata uključujete ovako:
"cache_control": {"type": "ephemeral", "ttl": "1h"}
Odluka: 5 min ili 1 h?
- Koristite 5 min TTL kada je promet redovit i frekvenca zahtjeva brža od 5 minuta. Jeftiniji upis (1,25×) i automatsko osvježavanje čuva vas od nepotrebne cijene.
- Koristite 1 h TTL za batch obradu, noćne poslove, ili aplikacije s neredovitim prometom gdje zahtjevi dolaze u naletima svakih 20-40 minuta. Dvostruka premija na upis isplati se nakon dovoljnog broja hitova.
Miješanje 5 min i 1 h TTL-ova
Možete ih kombinirati u istom zahtjevu, ali s pravilom: blokovi s dužim TTL-om moraju biti ispred onih s kraćim. Tipičan obrazac — definicije alata na 1 h (stabilne tijekom cijelog dana), a povijest poruka na 5 min (mijenja se po sesiji).
Provjera je li keš zapravo pogođen
U response.usage polju promatrajte tri vrijednosti:
cache_creation_input_tokens: koliko je tokena upisano u keš ovim zahtjevom.cache_read_input_tokens: koliko je tokena pročitano iz keša (cache hit).input_tokens: koliko je nekeširanih tokena obrađeno.
Jednostavan helper za izračun hit-rate metrike:
def cache_hit_ratio(usage):
total = (usage.cache_read_input_tokens
+ usage.cache_creation_input_tokens
+ usage.input_tokens)
if total == 0:
return 0.0
return usage.cache_read_input_tokens / total
# U produkciji: logirajte ovaj omjer u Datadog/Prometheus
Ako su i cache_creation_input_tokens i cache_read_input_tokens jednaki 0, vaš blok je bio kraći od minimalnog praga i nije uopće keširan. Klasika početničke muke.
Promjena iz veljače 2026: izolacija keša po workspaceu
Od 5. veljače 2026. Anthropic je na Claude API-ju i Azure AI Foundry preview-u promijenio model izolacije keša s razine organizacije na razinu workspace.
Praktične posljedice:
- Ako ste dijelili isti sistemski prompt između više workspaceova, sada svaki workspace ima vlastiti keš — i plaća vlastiti upis.
- Dev, staging i prod workspaceovi neće dijeliti keš. Planirajte testove s tim u vidu.
- Amazon Bedrock i Google Vertex AI i dalje koriste organizacijsku izolaciju.
Ako imate monorepo s više workspaceova iste aplikacije, razmislite o konsolidaciji ili prihvatite dodatnu cijenu upisa. Nažalost, nema srednjeg puta.
Najčešće greške koje invalidiraju keš
- Dinamički sadržaj u keširanoj zoni. Trenutni timestamp, korisnikovo ime, slučajni ID bilo gdje prije
cache_control granice pokvarit će prefiks.
- Mijenjanje redoslijeda alata. Dict literali u Pythonu znaju se serijalizirati u različitim redoslijedima — uvijek sortirajte alate deterministički.
- Različiti modeli. Keš je vezan za točan ID modela;
claude-sonnet-4-5 i claude-sonnet-4 ne dijele keš.
- Promjena
temperature ili drugih inferencijskih parametara. Neki parametri invalidiraju keš; držite ih konstantnim tijekom sesije.
- Premještanje breakpointa. Ako na prošlom zahtjevu niste imali
cache_control točno na istom mjestu, novi zahtjev pravi novi upis.
Napredna strategija: hibridni keš za chat aplikacije
Za produkcijski chatbot s dugačkom povijesti preporučena arhitektura ima tri sloja:
- Sloj 1 — alati + sistemski prompt (1 h TTL). Ovo se mijenja tek pri deployovima.
- Sloj 2 — povijest razgovora do zadnjih N poruka (5 min TTL). Raste između upita, ali ostaje topla tijekom aktivnog razgovora.
- Sloj 3 — trenutna korisnikova poruka (bez keša). Uvijek nova.
def build_cached_messages(history, new_user_msg):
messages = []
# Cijeli povijest ide u jedan blok s 5 min TTL kesiranjem
if history:
history_text = "\n".join(
f"{m['role']}: {m['content']}" for m in history
)
messages.append({
"role": "user",
"content": [
{
"type": "text",
"text": f"[HISTORY]{history_text}[/HISTORY]",
"cache_control": {"type": "ephemeral"}
}
]
})
messages.append({"role": "user", "content": new_user_msg})
return messages
Mjerenje stvarne uštede u produkciji
Ne vjerujte teoretskim brojkama — uvijek izmjerite. Sam sam se više puta opekao kad je "teoretska" ušteda u produkciji ispala tek polovica očekivane. Minimalna telemetrija koju treba logirati po zahtjevu:
request_id, workspace_id, model.cache_creation_input_tokens, cache_read_input_tokens, input_tokens, output_tokens.- Izračunati
effective_cost_usd koristeći tabelu cijena.
latency_ms ukupno i time_to_first_token_ms.
Nakon tjedan dana prometa usporedite prosječni hit-rate po endpointu. Ako je ispod 50 %, vjerojatno vam je prompt dinamičniji nego što mislite — pregledajte ga zajedno s dev timom da pronađete izvor nestabilnosti.
Kada prompt caching NIJE dovoljan
Ako i nakon keširanja vaši troškovi ostaju previsoki, sljedeći koraci su:
- Batch API s 50 % popustom za nehitne poslove.
- Selekcija modela — Haiku 4.5 za rutiranje, Sonnet 4.5 za glavnu logiku.
- Sažimanje povijesti razgovora umjesto slanja cijele.
- Embedding-baziran dohvat umjesto slanja cijelog dokumenta u kontekst.
Prompt caching je često prva, ali rijetko posljednja optimizacija.
Često postavljana pitanja (FAQ)
Koliko dugo traje Claude prompt cache?
Zadani TTL je 5 minuta i resetirа se na svaki pogodak. Opciono možete postaviti 1 sat TTL koristeći "ttl": "1h" u cache_control bloku, uz dvostruku cijenu upisa.
Koliko iznosi popust na cache read?
90 %. Cache read tokeni naplaćuju se po 0,1× bazne cijene ulaznih tokena. Cache write košta 1,25× za 5 min TTL ili 2,0× za 1 sat TTL.
Je li prompt caching automatski ili ga moram eksplicitno uključiti?
Morate ga eksplicitno uključiti postavljanjem "cache_control": {"type": "ephemeral"} na željeni content block. Anthropic ne keširа automatski.
Može li se prompt caching koristiti sa streamingom?
Da. Metrike keša pojavit će se u message_start događaju na početku streama, tako da odmah znate je li bio cache hit.
Rade li Amazon Bedrock i Google Vertex AI isto?
Uglavnom da — cache_control sintaksa i cjenovni model su isti. Glavna razlika: od veljače 2026. izolacija keša je per-workspace na Anthropic API-ju, dok Bedrock i Vertex AI zadržavaju izolaciju na razini organizacije.
Što ako je moj sistemski prompt kraći od 1024 tokena?
Keš neće biti kreiran. Rješenje: spojite sistemski prompt s definicijama alata ili few-shot primjerima u jedan blok koji zajedno prelazi prag, ili ga proširite detaljnijim uputama umjesto da odustanete.
Zaključak
Prompt caching u Claude API-ju je 2026. prešao iz "lijepo-imati" u "obavezno" za svaku produkcijsku LLM aplikaciju. Uz 90 % popust na cache read i smanjenje latencije do 85 %, dobro konfigurirano keširanje često vraća investiciju razvoja već u prvom tjednu prometa.
Ključni zaključci: držite keširani prefiks statičnim, iskoristite svih 4 moguća breakpointa kad imate različite zone stabilnosti, pazite na novu per-workspace izolaciju uvedenu u veljači 2026., i — najvažnije — uvijek mjerite hit-rate u produkciji. Kombinirano s Batch API-jem i pametnom selekcijom modela, prompt caching je najbrži put do održivog ekonomičnog LLM sustava.
