Jinsi ya kukokotoa faida ya Claude prompt caching

Gharama za prompt caching kabla ya kuleta akiba

Prompt caching inaruhusu Claude kutumia tena sehemu ya mwanzo ya prompt yako badala ya kuisoma upya katika kila ombi, na uamuzi wote unategemea vizidishi viwili kwenye bei ya msingi ya input ya model yako. Kufikia Agosti 2026, uandishi wa cache unagharimu mara 1.25 ya input ya msingi kwa muda wa maisha wa dakika 5, au mara 2 kwa muda wa maisha wa saa 1. Usomaji wa cache unagharimu mara 0.1. Vizidishi hivi vinabaki vilevile katika orodha nzima ya model, kwa hivyo kiwango cha kufidia gharama (break-even) hakibadiliki bei ya kila token inapobadilika.

Huu ni ubadilishaji wa malipo ya ziada sasa dhidi ya punguzo baadaye. Unalipa ziada mara moja ili kuhifadhi prefix. Kila ombi la baadaye linaloanza na byte zilezile hasa hulipa sehemu ya kumi ya bei ya kawaida ya input kwa sehemu hiyo. Prefix ambayo haitumiki tena ndani ya muda wake wa maisha imekugharimu asilimia 25 ya ziada bila faida yoyote.

Kiwango cha kufidia gharama, katika mstari mmoja wa aljebra

Iite B gharama ya msingi ya kuingiza prefix ikiwa utaituma bila caching. Bila caching, maombi N yanagharimu N mara B. Kwa cache ya dakika 5, ombi la kwanza huandika prefix kwa 1.25B na maombi mengine N kutoa 1 huisoma kwa 0.1B. Weka viwili hivyo kuwa sawa na utapata 0.9N = 1.15, kwa hivyo N = 1.28. Ombi la pili tayari ni nafuu kuliko kutotumia caching kabisa.

Rudia hayo kwa uandishi wa 2x wa cache ya saa 1 na utapata 0.9N = 1.9, kwa hivyo N = 2.11. Cache ya muda mrefu inahitaji usomaji miwili kabla ya kufidia gharama, ndiyo sababu si chaguo chaguo-msingi.

Chati hapa chini inapiga bei hii kwa prefix ya token 20,000 kwenye Claude Opus 5, ambayo kiwango chake cha msingi cha uingizaji ni $5 kwa kila milioni ya token kufikia Agosti 2026. Pima kila takwimu kwa 0.6 kwa modeli ya $3 kwa kila milioni. Umbo la mkondo halibadiliki.

[
  {
    "requests": 1,
    "uncached_usd": "0.10",
    "cached_5m_usd": "0.125",
    "cached_1h_usd": "0.20"
  },
  {
    "requests": 2,
    "uncached_usd": "0.20",
    "cached_5m_usd": "0.135",
    "cached_1h_usd": "0.21"
  },
  {
    "requests": 3,
    "uncached_usd": "0.30",
    "cached_5m_usd": "0.145",
    "cached_1h_usd": "0.22"
  },
  {
    "requests": 5,
    "uncached_usd": "0.50",
    "cached_5m_usd": "0.165",
    "cached_1h_usd": "0.24"
  },
  {
    "requests": 10,
    "uncached_usd": "1.00",
    "cached_5m_usd": "0.215",
    "cached_1h_usd": "0.29"
  },
  {
    "requests": 20,
    "uncached_usd": "2.00",
    "cached_5m_usd": "0.315",
    "cached_1h_usd": "0.39"
  }
]

Ombi moja pekee linagharimu $0.10 bila caching na $0.125 likiwa na caching, kwa hivyo kuweka prompt ya mara moja kwenye cache ni hasara tupu. Kufikia ombi la pili, cache ya dakika 5 iko kwenye $0.135 dhidi ya $0.20. Cache ya saa 1 bado iko nyuma wakati huo, $0.21 dhidi ya $0.20 ileile, na inavuka mstari wa kutotumia caching kwenye ombi la tatu pekee: $0.22 dhidi ya $0.30. Kufikia maombi 20, pengo ni $2.00 dhidi ya $0.315.

Cache hit pia hufanya upya (refresh) ingizo, ndiyo sababu jedwali la bei lililochapishwa huita safu hiyo cache hits na refreshes. Kwa hivyo, endpoint yenye shughuli nyingi huweka ingizo la dakika 5 likiwa hai bila kikomo kwa bei za usomaji, na muda wa maisha wa saa 1 hupata tu gharama yake ya uandishi wa 2x wakati trafiki yako inapokuwa na mapengo ya kweli.

Gharama ya hit rate ndogo

Trafiki halisi hupata misses. Ombi linalokosa cache lakini bado likiwa na breakpoint hutoza gharama kama ya write, kwa hivyo njia sahihi ya kukokotoa hii ni kuona gharama kama kazi ya hit rate. Chati hapa chini inaonyesha hilo kwa maombi 1,000, kila moja ikiwa na prefix ya token 20,000.

[
  {
    "hit_rate_percent": 0,
    "cost_5m_usd": "125.00",
    "cost_1h_usd": "200.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 25,
    "cost_5m_usd": "96.25",
    "cost_1h_usd": "152.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 50,
    "cost_5m_usd": "67.50",
    "cost_1h_usd": "105.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 75,
    "cost_5m_usd": "38.75",
    "cost_1h_usd": "57.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 90,
    "cost_5m_usd": "21.50",
    "cost_1h_usd": "29.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 95,
    "cost_5m_usd": "15.75",
    "cost_1h_usd": "19.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 99,
    "cost_5m_usd": "11.15",
    "cost_1h_usd": "11.90",
    "uncached_usd": "100.00"
  }
]

Katika hit rate ya asilimia 0 unalipa $125.00 badala ya $100.00, na cache ya saa 1 huongeza bili mara mbili hadi $200.00. Tatua 1.25 kutoa 1.15h = 1 na cache ya dakika 5 huanza kuokoa pesa katika hit rate ya takriban asilimia 22, ndiyo maana asilimia 25 tayari inaonyesha $96.25. Hesabu hiyo hiyo kwa write ya 2x inatoa takriban asilimia 53 kwa cache ya saa 1, kwa hivyo hit rate ya asilimia 50 bado inagharimu $105.00, juu ya mstari wa uncached. Katika asilimia 90, zote mbili zinafikia $21.50 na $29.00. Katika asilimia 99, cache fupi inafikia $11.15, karibu na kiwango cha chini cha sehemu ya kumi ya bei ya uncached.

Hit rate ndiyo namba ya kufuatilia, kwa sababu ndiyo input pekee unayoweza kudhibiti baada ya ukubwa wa prefix kuwekwa.

Ni viambishi awali (prefixes) vipi vinavyostahili breakpoint

Ombi linaweza kubeba hadi breakpoints nne za cache, kwa hivyo swali ni ni vizuizi vipi vinavyostahili moja. Wagombea ni vizuizi ambavyo ni sawa kabisa kwa baiti (byte-identical) katika kila mwito na ni vikubwa vya kutosha kuleta tofauti. Chati hapa chini inaonyesha gharama za maumbo manne ya kawaida kwa maombi 1,000 kwa kiwango cha hit cha asilimia 90 kwenye cache ya dakika 5.

[
  {
    "label": "System prompt",
    "prefix_size_tokens": "2,000",
    "uncached_usd": "10.00",
    "cached_usd": "2.15",
    "saved_usd": "7.85"
  },
  {
    "label": "System plus tools",
    "prefix_size_tokens": "8,000",
    "uncached_usd": "40.00",
    "cached_usd": "8.60",
    "saved_usd": "31.40"
  },
  {
    "label": "Policy document",
    "prefix_size_tokens": "25,000",
    "uncached_usd": "125.00",
    "cached_usd": "26.88",
    "saved_usd": "98.12"
  },
  {
    "label": "Codebase context",
    "prefix_size_tokens": "120,000",
    "uncached_usd": "600.00",
    "cached_usd": "129.00",
    "saved_usd": "471.00"
  }
]

Mfumo wa prompt wa token 2,000 pekee huokoa $7.85 kwa kila maombi 1,000 dhidi ya $10.00 bila cache. Hii ni pesa halisi kwa ujazo mkubwa, lakini siyo jambo linalofanya caching kuvutia. Ongeza ufafanuzi wa zana (tool definitions) na utafikia token 8,000 na $31.40 zilizookolewa. Hati ya sera ya token 25,000 ambayo kila ombi huuliza maswali kuihusu huokoa $98.12. Mstari wa mwisho ndio unaobadilisha usanifu: token 120,000 za codebase au muktadha wa transcript hugharimu $600.00 bila cache na $129.00 na cache, ikiwa ni akiba ya $471.00.

Akiba huongezeka kulingana na ukubwa wa prefix na kiwango cha hit, na si kitu kingine chochote. Hilo hubadilisha kile kinachostahili kuwekwa kwenye prompt: gharama halisi ya token milioni moja za Claude hushuka hadi sehemu ya kumi ya bei ya kawaida kwa chochote unachotuma zaidi ya mara moja.

Muonekano wake kwenye ankara ya kila mwezi

Chati iliyo hapa chini inachukua 8,000 token prefix kutoka hapo juu, ikiwa na system prompt pamoja na ufafanuzi wa zana, kwa kiwango cha mafanikio cha asilimia 90, na kuipima kulingana na idadi ya maombi ya kila mwezi.

[
  {
    "label": "10k requests",
    "uncached_usd": "400.00",
    "cached_usd": "86.00",
    "saved_usd": "314.00"
  },
  {
    "label": "100k requests",
    "uncached_usd": "4,000.00",
    "cached_usd": "860.00",
    "saved_usd": "3,140.00"
  },
  {
    "label": "1M requests",
    "uncached_usd": "40,000.00",
    "cached_usd": "8,600.00",
    "saved_usd": "31,400.00"
  }
]

Kwa maombi 10,000 kwa mwezi, akiba ni $314.00, ambayo ni tofauti kati ya $400.00 na $86.00. Kwa maombi 100,000, akiba hiyo ni $3,140.00. Kwa maombi milioni moja, ankara ya input isiyohifadhiwa kwenye cache ni $40,000.00 na utumiaji wa cache unaondoa $31,400.00 ya gharama hiyo. Hizi ni token za input pekee. Output inatozwa bei tofauti na cache haina athari yoyote kwake, jambo ambalo ni muhimu kukumbuka kabla ya kumwahidi mtu yeyote punguzo la asilimia 90 kwenye ankara. Caching inafanya kazi sambamba na mbinu nyingine pana za kudhibiti gharama za AI agent kwenye VPS.

Jinsi ya kuthibitisha kuwa cache inafanya kazi

Usiuamini usanifu pekee. Soma sehemu ya matumizi kwenye majibu. Kila jibu la Messages API (application programming interface) huripoti tokeni zilizohifadhiwa kwenye cache ilizoandika, tokeni zilizohifadhiwa ilizosoma, na tokeni mpya ilizopaswa kuchakata.

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=512,
    system=[
        {
            "type": "text",
            "text": POLICY_DOCUMENT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": question}],
)

u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)

Iendeshe mara mbili kwa kutumia hati ileile na swali tofauti. Ombi la kwanza huripoti cache_creation_input_tokens isiyo sifuri na cache_read_input_tokens ya sifuri. Ombi la pili hubadilisha hali hiyo, kwa sababu kiambishi awali (prefix) kilipatikana. input_tokens huhesabu tu tokeni zilizopo baada ya breakpoint ya mwisho, kwa hivyo kwenye ombi la pili lililo salama huwa ndogo, kwa kawaida ni ujumbe mpya wa mtumiaji pekee. Maombi yote mawili hutoza gharama, kwa sababu Claude API haina kiwango cha bure, ingawa kwa kiambishi awali cha tokeni 20,000 kilichotajwa hapo juu, gharama ya jozi hiyo ni takriban senti kumi na nne.

Ukaguzi uleule kutoka kwenye shell, dhidi ya mwili wa ombi (request body) uliouhifadhi kwenye request.json:

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @request.json | jq '.usage'

Ombi la pili lililo salama huchapisha kitu kama hiki:

{
  "input_tokens": 42,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 20143,
  "output_tokens": 187
}

Mstari mmoja hukuambia ukweli. Ikiwa cache_read_input_tokens itabaki kuwa 0 katika maombi yote, unalipa gharama ya 1.25x ya kuandika kila wakati na hupati chochote kama faida.

Kwa muda wa kuishi wa saa 1, breakpoint hubeba muda wa kuishi (TTL):

{
  "type": "text",
  "text": "your stable prefix",
  "cache_control": {"type": "ephemeral", "ttl": "1h"}
}

Pia kuna caching ya kiotomatiki: sehemu moja ya cache_control kwenye ngazi ya juu ya ombi, ambapo API hudhibiti breakpoint kadiri mazungumzo yanavyokua. Hii hutumia moja ya nafasi zako nne za breakpoint. Anzia hapo. Hamia kwenye breakpoint za wazi (explicit) pale unapohitaji kuamua hasa mahali mpaka unapoanzia.

Kanuni ya mpangilio inayoharibu viwango vya hit

Cache inalinganisha prefix byte kwa byte kuanzia mwanzo wa ombi, na ombi hilo huunganishwa kwa mpangilio maalum: tools, kisha system, kisha messages. Mabadiliko katika ngazi yoyote hubatilisha ngazi hiyo na kila kitu kinachofuata. Hariri maelezo ya tool moja na system prompt pamoja na historia nzima ya ujumbe vitabatilishwa, hata kama hukuvigusa.

Hii inatoa kanuni moja isiyo na ubaguzi. Kila kitu kinachobadilika kati ya maombi lazima kiwekwe baada ya kila kitu kisichobadilika.

Mkosa-hatia wa kawaida ni timestamp. Mstari unaosomeka Current time: 2026-08-03T14:07:11Z juu ya system prompt huhakikisha kiwango cha hit cha asilimia 0, kwa sababu hash ya prefix ni tofauti katika kila ombi na hakuna ingizo la awali linaloweza kulingana nalo. Ihamishe kwenye user message, mwishoni. Kitambulisho cha session au nonce ya kila ombi huvuruga mambo kwa njia ile ile na ina suluhisho sawa. Nyaraka zilizorejeshwa ambazo hutofautiana kwa kila ombi pia zinapaswa kuwekwa baada ya block iliyohifadhiwa kwenye cache, vinginevyo zitasukuma kila token thabiti nyuma ya mpaka unaohamahama.

Mkosa-hatia wa pili ni kuweka breakpoint kwenye block inayobadilika. Uandikaji wa cache hutokea kwenye breakpoint, kwa hivyo ikiwa block hiyo ni tofauti kila wakati, hakuna kitu thabiti kinachohifadhiwa, na utafutaji wa nyuma hupata tu maingizo ambayo maombi ya awali yaliandika kwenye breakpoint zao zinazohamahama. Weka cache_control kwenye block ya mwisho ambayo maudhui yake ni sawa katika maombi yote.

Wa tatu ni mabadiliko ya parameter ambayo hukuyazingatia kama maudhui ya prompt. Model tofauti ina cache tofauti. Kubadilisha chaguo la tool hubatilisha kuanzia ngazi ya system kuendelea. Kuongeza au kuondoa tool hubatilisha kila kitu.

Prefix ya chini kabisa, na no-op kimya

Prefix fupi kuliko kiwango cha chini cha model haihifadhiwi kwenye cache, na hakuna taarifa inayokujulisha. Hakuna error, hakuna onyo. Ombi linafanikiwa na counter zote mbili zinasoma 0. Kufikia Agosti 2026, viwango vya chini vilivyochapishwa ni:

• 512 tokens kwenye Claude Opus 5 na Claude Fable 5
• 1,024 tokens kwenye Claude Sonnet 5 na Claude Opus 4.8
• 4,096 tokens kwenye Claude Haiku 4.5

Ikiwa counter zote mbili zinasoma 0 kwenye ombi ambalo unaamini limehifadhiwa kwenye cache, kagua urefu wa prefix kabla ya kitu kingine chochote. Hii ndiyo sababu model ya bei nafuu si lazima iwe ya bei nafuu zaidi kwa kazi ya caching. Haiku 4.5 inahitaji prefix ndefu mara nane kuliko Opus 5 kabla ya caching kuanza kufanya kazi, kwa hivyo system prompt ya 2,000 tokens inahifadhiwa kwenye moja na kupuuzwa kimya kimya kwenye nyingine.

Mahali ambapo Claude Code huhifadhi cache kwa ajili yako, na mahali ambapo haiwezi

Claude Code huhifadhi prefix yake yenyewe kwenye cache. Prompt ya mfumo na ufafanuzi wa zana hukaa mwanzoni mwa kila ombi na havisogei, kwa hivyo huandikwa mara moja na kusomwa tena kwa muda wote wa kikao. Hii ndiyo sababu gharama ya kila hatua katika kikao kirefu iko chini sana kuliko ukubwa wa muktadha unavyopendekeza, na inaonekana kwenye vihesabio vilivyoelezwa katika jinsi Claude Code inavyoripoti matumizi ya token.

Mahali ambapo haiwezi kukusaidia ni uhariri ulio karibu na mwanzo wa muktadha. Historia ya mazungumzo huongezeka tu (append-only), kwa hivyo hatua mpya za kawaida huongeza prefix ambayo tayari imehifadhiwa kwenye cache. Kuhariri faili iliyosomwa mapema kwenye kikao hubadilisha maudhui yaliyo katikati ya prefix hiyo, na kila token baada ya mabadiliko hayo lazima iandikwe tena. Muda mrefu wa kutofanya kazi (idle gap) hufanya vivyo hivyo, kwa sababu ingizo huisha muda wake na hatua inayofuata hulipia uandishi kamili. Hakuna kati ya haya ambayo ni hitilafu (bug). Yote mawili ni kanuni ya prefix inayofanya kile inachosema hasa.

Ikiwa unaandika mteja wako mwenyewe badala yake, tumia mpangilio kutoka kwa ombi la kwanza badala ya kuurekebisha baadaye: jenga mwito (call) kwa njia ambayo programu ya kwanza ya Claude API kwenye VPS inafanya, huku vizuizi thabiti vikiwa mwanzo na vile vinavyobadilika vikiwa mwisho.

Njia za kufeli, na utakachokiona

Kila ombi ni uandishi. cache_creation_input_tokens si sufuri katika kila ombi wakati cache_read_input_tokens inabaki 0. Kuna kitu kwenye au kabla ya breakpoint kinabadilika kati ya maombi. Chapisha herufi 200 za kwanza za prefix uliyokusanya kwenye maombi mawili mfululizo na uzilinganishe kwa macho.

Kaunta zote mbili ni 0. Prefix iko chini ya kiwango cha chini cha model, au sehemu ya cache_control haikufika kwenye API. Hesabu token za prefix kwanza, kisha uweke kwenye logi mwili wa ombi uliotuma kweli.

Usomaji unafanya kazi, kisha unasimama. Mfululizo wa hits, kisha uandishi, kisha hits tena. Muda uliopita kati ya maombi ulikuwa mrefu kuliko muda wa uhai (lifetime). Kubali uandishi, au hamia kwenye TTL ya saa 1 baada ya kuhakikisha kiwango chako cha hits kinavuka asilimia 53.

Kiwango cha hits kinashuka baada ya deploy. Maelezo ya zana yamehaririwa au model imebadilishwa. Vyote hivi vinabatilisha prefix nzima. Tarajia mzunguko mmoja wa gharama kubwa wa uandishi baada ya kila deploy inayohusu prompt.

Bili imepanda baada ya kuwezesha caching. Kiwango chako cha hits kiko chini ya kiwango cha faida (break-even). Chini ya asilimia 22 kwenye cache ya dakika 5, kutuma prefix bila cache ni nafuu zaidi, na chini ya asilimia 53 hali hiyo ni ya kweli kwa cache ya saa 1.

FAQ

Je, ni mara ngapi prompt inapaswa kutumika tena kabla ya caching kuanza kuwa na faida?

Mara moja, kwa cache ya dakika 5. Uandishi unagharimu 1.25x ya input ya msingi na usomaji unagharimu 0.1x, kwa hivyo maombi N yasiyo na cache yanagharimu N, wakati maombi N yaliyo na cache yanagharimu 1.25 jumlisha 0.1 mara N kutoa 1. Gharama hizi mbili hukutana kwenye N = 1.28, kwa hivyo ombi la pili tayari lina faida. Cache ya saa 1 huandika kwa 2x na kukutana kwenye N = 2.11, kwa hivyo inahitaji usomaji miwili.

Kwa nini cache_read_input_tokens huwa sifuri kila wakati?

Kwanza, angalia urefu wa prefix: chini ya kiwango cha chini cha mfano, token 512 kwenye Claude Opus 5 na 4,096 kwenye Claude Haiku 4.5 kufikia Agosti 2026, caching hurukwa kimya kimya na vihesabio vyote viwili husoma 0. Ikiwa prefix ni ndefu ya kutosha, tafuta maudhui yanayobadilika kati ya maombi yaliyopo kwenye au kabla ya sehemu ya kukatika (breakpoint), kama vile timestamp au kitambulishi cha session kwenye system prompt. Ikiwa vihesabio vilikuwa vikifanya kazi na vikaacha, pengo kati ya maombi lilikuwa refu kuliko muda wa kuishi wa cache.

Je, prompt caching hubadilisha majibu ya Claude?

Hapana. Cache huhifadhi umbo lililochakatwa la token ulizotuma tayari, na mfano (model) huona prompt ile ile kwa njia yoyote ile. Hii ni kipengele cha malipo na latency, si mabadiliko ya tabia. Hii pia inamaanisha unaweza kuiwasha kwenye prompt inayofanya kazi bila kurudia tathmini zako.

Je, nilipe kwa ajili ya cache ya saa 1?

Fanya hivyo tu wakati trafiki yako ina mapengo marefu kuliko dakika 5 na hit rate yako bado itafikia takriban asilimia 53. Uandishi wa 2x ni mara mbili ya hasara ya uandishi wa 1.25x unapokosa (miss). Ingizo la dakika 5 hujihuisha (refresh) kila unapopata hit, kwa hivyo trafiki thabiti huiweka hai kwa bei za usomaji bila kulipia muda mrefu wa kuishi.