Prompt caching explicat pentru sesiuni lungi de coding cu AI

Prompt caching explicat simplu înseamnă că API-ul refolosește începutul neschimbat al promptului tău, numit prefix stabil, în loc să îl proceseze din nou, iar tokenii din cache sunt taxați la o fracțiune din prețul normal de intrare. Într-o sesiune de coding cu AI, prefixul este întreaga conversație, deci o citire din cache costă aproximativ o zecime din tokenii proaspeți la majoritatea modelelor Claude. Prima tură după expirarea cache-ului plătește un adaos ca să scrie totul din nou, de aceea o pauză lungă este partea scumpă.

Ce anume reține prompt caching?

Cache-ul stochează un prefix al cererii tale. API-ul Anthropic construiește acest prefix într-o ordine fixă: întâi definițiile de unelte, apoi promptul de sistem, apoi mesajele. Pentru un hit e nevoie de o potrivire exactă de la începutul cererii, așa că o modificare oriunde în prefix obligă la reprocesarea a tot ce urmează. Nu există cache pe fișier sau pe paragraf.

Claude Code ordonează fiecare cerere astfel încât părțile care se schimbă cel mai rar să vină primele:

Strat	Conținut	Se schimbă când
Prompt de sistem	Instrucțiuni de bază, definiții de unelte	Se schimbă setul de unelte încărcate
Context de proiect	CLAUDE.md, auto memory, reguli fără filtru de cale	Începe sesiunea sau după /clear ori /compact
Conversație	Mesajele tale, răspunsurile, rezultatele uneltelor	La fiecare tură

Fiecare tură nouă se adaugă la coadă, deci cea mai mare parte din fiecare cerere este identică cu cea dinainte. Exact acest caz este cel pentru care există caching. Prin API activezi funcția cu un câmp cache_control. Un singur câmp la nivelul cererii pornește caching-ul automat, iar pentru control fin poți pune puncte de oprire explicite pe blocuri individuale, maximum patru pe cerere.

"cache_control": {"type": "ephemeral"}

Prompturile mai scurte decât un minim specific modelului nu sunt niciodată puse în cache, iar API-ul nu returnează nicio eroare. La modelele Claude actuale acest minim variază între 512 și 4.096 de tokeni, deci verifică modelul tău în documentația Anthropic despre prompt caching înainte să te întrebi de ce nu se întâmplă nimic.

Cât costă citirile și scrierile în cache?

Caching-ul schimbă prețul prefixului în trei feluri. Fiecare preț este un multiplicator aplicat prețului de bază de intrare al modelului.

Operație	Multiplicator	Durată
Scriere în cache de 5 minute	1,25x prețul de bază	5 minute
Scriere în cache de 1 oră	2x prețul de bază	1 oră
Citire din cache (hit)	0,1x prețul de bază la majoritatea modelelor	La fel ca scrierea care l-a creat

Câteva modele mai noi citesc mai ieftin. Anthropic indică 0,05x pentru Claude Opus 5.5 și 0,025x pentru Claude Fable 5.1 și Mythos 5.1. Aceeași pagină dă și pragul de rentabilitate: o scriere de 5 minute se amortizează după o citire, iar una de 1 oră după două citiri. Prețurile se schimbă, așa că verifică pagina de prețuri Anthropic pentru modelul tău înainte să faci bugetul. Pe scurt, prețul cache-ului la Anthropic înseamnă trei multiplicatori și o durată de viață.

Cât timp ține cache-ul de prompt (prompt cache TTL)?

Prompt cache TTL (time to live, adică durata de viață) este implicit de 5 minute, cu o opțiune de 1 oră pe care o ceri cu "ttl": "1h" în blocul cache_control. Fiecare cerere care lovește cache-ul resetează cronometrul fără cost suplimentar, deci o sesiune rămâne caldă cât timp lucrezi în ea. După o pauză mai lungă decât TTL-ul, intrarea dispare.

Pagina Claude Code despre prompt caching documentează cum alege TTL-ul în locul tău:

• Pe un abonament Claude, în limita utilizării incluse în plan, conversația principală primește 1 oră.
• Pe o cheie API, la un furnizor cloud sau după ce abonamentul trece în credite de utilizare, conversația principală primește 5 minute.
• Subagenții, compactarea și celelalte cereri auxiliare au implicit 5 minute, cu câteva excepții controlate de server pe abonamente.

Poți seta singur TTL-ul conversației principale cu variabila de mediu CLAUDE_CODE_PROMPT_CACHE_TTL sau cu setarea promptCacheTtl. Ambele acceptă 5m sau 1h și cer Claude Code v2.1.242 sau mai nou. Ca să vezi ce TTL au folosit de fapt scrierile tale, rulează comanda de mai jos și citește usage.cache_creation din JSON:

claude -p "hello" --output-format json

Scrierile de o oră apar la ephemeral_1h_input_tokens, cele de cinci minute la ephemeral_5m_input_tokens. TTL-ul mai lung costă mai mult la fiecare scriere, deci se rentabilizează când lași sesiunile în pauză și revii, și pierde puțin la rafalele scurte care nu fac niciodată o pauză de cinci minute. Dacă îți convine mai mult un abonament sau o cheie API este o altă discuție, pe care o tratăm în comparația dintre cele două pentru coding.

De ce o pauză lungă face următoarea tură scumpă?

Claude Code retrimite întreaga conversație la fiecare tură. Cât timp cache-ul e cald, asta costă o singură citire a întregului context. După expirare, tura următoare nu are nimic de citit. Procesează tot contextul ca intrare nouă și îl scrie înapoi în cache la 1,25x sau 2x prețul de bază, iar răspunsul vine și mai greu.

Iată exemplul calculat din README-ul Claude Cache Warm, la prețuri de listă: un context de 800.000 de tokeni pe Claude Opus 5, cu cache de 1 oră.

Caz	Cost (estimare la preț de listă)
Un ping de menținere (citire din cache)	aproximativ 0,40 USD
Revenire la rece după 90 de minute (scriere în cache)	aproximativ 8,00 USD

Calculul se potrivește cu pagina de prețuri Anthropic, unde Opus 5 apare cu 0,50 USD per milion de tokeni pentru hit-uri de cache și 10 USD per milion pentru scrieri de 1 oră. 0,8 milioane de tokeni la 0,50 USD fac 0,40 USD, iar la 10 USD fac 8,00 USD. Consideră ambele sume estimări. Factura ta reală depinde de model, de plan și de cât din context era în cache, iar pe abonament costul apare ca utilizare din limite, nu în dolari. Raportul este partea utilă. O reconstrucție la rece costă cât aproximativ douăzeci de citiri din cache.

Cum îți structurezi prompturile ca să obții mai multe hit-uri?

Păstrează prefixul identic cât de mult poți și pune la final tot ce se schimbă.

• Pune conținutul stabil primul: definițiile de unelte, instrucțiunile de sistem, documentele de referință. Întrebarea care se schimbă vine ultima.
• Nu edita niciodată conținut mai vechi. Un timestamp sau un ID de cerere la începutul promptului de sistem strică potrivirea pentru tot ce vine după el.
• Păstrează stabile definițiile de unelte. În Claude Code, adăugarea sau scoaterea unei definiții de unealtă din cerere invalidează cache-ul, de exemplu când se conectează un server MCP ale cărui unelte se încarcă de la început.
• Alege modelul și nivelul de effort la început. Fiecare model are propriul cache, deci un /model în mijlocul unei sarcini face ca următoarea cerere să citească tot istoricul fără cache. La majoritatea modelelor, schimbarea nivelului de effort face același lucru.
• Rulează /compact la pauze naturale între sarcini. Compactarea înlocuiește istoricul, deci reconstruiește cache-ul prin construcție.
• Evită să pornești fast mode târziu într-o sesiune lungă, pentru că antetul lui face parte din cheia de cache.
• Așteaptă-te la o tură lentă după actualizarea Claude Code, care de regulă schimbă promptul de sistem.

Ca să măsori rezultatul, citește cele două câmpuri de utilizare pe care API-ul le întoarce la fiecare răspuns. cache_creation_input_tokens numără tokenii scriși în cache, iar cache_read_input_tokens pe cei serviți din el. Un raport mare între citiri și scrieri arată că funcționează. În Claude Code, /usage afișează o linie Prompt cache (main) cu ponderea tokenilor de intrare serviți din cache și dacă cache-ul este cald acum (Claude Code v2.1.251 sau mai nou). Pentru produsele construite pe API, aceleași obiceiuri sunt un strat din economiile descrise în cum am redus costurile LLM cu 99%, unde prompt caching-ul furnizorului stă lângă cache-ul pe potrivire exactă și rutare.

Când au sens ping-urile de menținere și când risipesc cota?

Un ping de menținere este o tură minusculă trimisă înainte să expire TTL-ul. Este o tură reală de model: API-ul citește tot contextul din cache, ceea ce resetează cronometrul. Costă o citire din cache plus câțiva tokeni de ieșire, iar pe abonament se scade din limitele tale de utilizare. Dacă merită depinde de TTL și de cât timp lipsești.

Situație	Ping?	De ce
Context mare, TTL de 1 oră, aștepți un subagent sau un build pe care îl vei verifica sigur	Da	O citire la aproximativ 0,1x înlocuiește o rescriere la 2x
Context mic (Cache Warm sare peste orice sub 20.000 de tokeni, implicit)	Nu	Reconstruirea unui context mic e ieftină
TTL de 5 minute și o pauză de o oră sau mai mult	De obicei nu	Aproximativ 11 ping-uri la interval de 4 minute costă deja cât o rescriere la 1,25x
Poate nu mai revii azi	Nu	Pe un cache de 1 oră, ping-urile nu se mai amortizează după aproximativ 19, adică circa 16 ore
Cache-ul a expirat deja, de exemplu laptopul a intrat în sleep	Nu	Ping-ul ar fi chiar rescrierea scumpă

Pragurile vin din README-ul Cache Warm și presupun prețul standard de citire de 0,1x. La modelele cu citiri mai ieftine se mută mai târziu. De aici ies două reguli practice. Prima: obține TTL-ul de 1 oră înainte să automatizezi ceva, pentru că transformă circa cincisprezece ping-uri pe oră într-unul singur. A doua: trimite ping doar sesiunilor la care știi sigur că revii. Verifică termenii și regulile de plan actuale ale Anthropic înainte să rulezi orice automatizare pe un abonament: ping-urile sunt ture obișnuite, dar consumă cota ta.

Cum automatizează Claude Cache Warm menținerea cache-ului?

Claude Cache Warm este un plugin pentru Claude Code, cu licență MIT, care trimite ping-urile în locul tău. Îl instalezi din Claude Code cu cele două comenzi din depozitul GitHub:

/plugin marketplace add FiredMosquito831/claude-cache-warm
/plugin install cache-warm@claude-cache-warm

Pornește o sesiune nouă și încălzirea e activă. Implicit încălzește doar sesiunile care așteaptă un subagent sau o sarcină din fundal, pentru că în acelea ești sigur că te întorci. Ping-ul trece prin sesiunea vie, deci lovește exact același prefix: același prompt de sistem, aceleași unelte, același istoric. Un apel extern claude -p --resume sau o cerere API brută nu pot garanta asta.

Cronometrul numără de la ultima ta cerere reală, deci o sesiune pe care o folosești nu primește niciodată ping. Pluginul sare peste ping și când cache-ul a expirat deja, când ai lipsit mai mult decât limita de inactivitate (180 de minute implicit), când contextul are sub 20.000 de tokeni sau când încălzirea e oprită.

ccw status              # sesiuni, numărătoare până la următorul ping, cost per ping
ccw interval 30         # ping la fiecare 30 de minute, sau auto
ccw when always         # încălzește orice sesiune inactivă, nu doar cele cu lucru în fundal
ccw dashboard           # deschide http://127.0.0.1:4777/

Intervalul auto este de 50 de minute pe un cache de 1 oră și de 4 minute pe unul de 5 minute, detectat din transcript. Panoul local arată rata de hit, reconstrucțiile la rece și cât ar fi economisit încălzirea, totul extras din propriile tale transcripturi, deci păstrează-le: vezi ghidul nostru despre istoricul sesiunilor Claude Code. Cunoaște limitele. Monitoarele de plugin sunt o funcție experimentală Claude Code care rulează doar în sesiuni CLI interactive, deci pluginul revine la o sarcină programată în sesiune când nu rulează niciun monitor. Fiecare ping adaugă două mesaje scurte în transcript. Sumele în dolari folosesc prețuri de listă și sunt estimări. Schimbările de model și /compact invalidează cache-ul indiferent ce face un plugin.

Unde se leagă asta de munca Danube Labs?

Danube Labs este un studio de software și AI condus de fondator, în București, și a construit Claude Cache Warm, apoi l-a publicat ca open source. Aceeași disciplină a prefixului se aplică oricărui produs construit pe un API de LLM, unde e printre cele mai ieftine economii posibile. Dacă vrei o a doua părere despre unde se duc banii tăi pe LLM-uri, vezi proiectele noastre de sisteme AI sau programează un apel introductiv gratuit.