Claude prompt caching: Kailan ito sulit?

Magkano ang gastos ng prompt caching bago ito makatipid

Pinapayagan ng prompt caching si Claude na gamitin muli ang simula ng prompt sa halip na basahin itong muli sa bawat call. Nakabatay ang buong desisyon sa dalawang multiplier ng base input price ng model. Noong August 2026, nagkakahalaga ang cache write ng 1.25x ng base input para sa 5 minute lifetime, o 2x para sa 1 hour lifetime. Ang cache read ay nagkakahalaga ng 0.1x. Pareho ang mga multiplier na ito sa buong model list, kaya hindi nagbabago ang break-even sa ibaba kapag nagbago ang per-token price.

Ang trade-off ay dagdag-gastos ngayon kapalit ng discount sa mga susunod na request. Isang beses kang magbabayad nang dagdag para i-store ang isang prefix. Ang bawat susunod na request na nagsisimula sa eksaktong parehong bytes ay magbabayad ng ikasampu ng normal na input price para sa bahaging iyon. Kung hindi kailanman gagamitin muli ang isang prefix habang valid ang lifetime nito, magbabayad ka ng 25 percent na dagdag nang walang kapalit na matitipid.

Ang break-even, sa isang linya ng algebra

Tawagin nating B ang base input cost ng prefix kung ipapadala mo ito nang walang cache. Kung walang caching, ang halaga ng N requests ay N na minultiply sa B. Sa 5 minute cache, isinusulat ng unang request ang prefix sa halagang 1.25B, at binabasa ito ng natitirang N minus 1 requests sa halagang 0.1B. Pagpantayin ang dalawang halaga at makukuha ang 0.9N = 1.15, kaya N = 1.28. Mas mura na agad ang second request kaysa sa tuluyang hindi paggamit ng cache.

Ulitin ito gamit ang 2x write ng 1 hour cache at makukuha ang 0.9N = 1.9, kaya N = 2.11. Kailangan ng long cache ng dalawang read bago ito mag-break even. Ito ang dahilan kung bakit hindi ito ang default na pagpipilian.

Ipinapakita sa chart sa ibaba ang halaga nito para sa 20,000 token prefix sa Claude Opus 5, na may base input rate na $5 kada million tokens noong August 2026. I-scale ang bawat value sa 0.6 para sa model na $3 kada million. Hindi nagbabago ang hugis ng curve.

[
  {
    "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"
  }
]

Ang isang request lamang ay nagkakahalaga ng $0.10 kapag walang cache at $0.125 kapag naka-cache. Kaya purong lugi ang pag-cache ng one-shot prompt. Sa second request, ang 5 minute cache ay nasa $0.135 kumpara sa $0.20. Mas mataas pa rin ang halaga ng 1 hour cache sa puntong iyon: $0.21 kumpara sa parehong $0.20. Malalagpasan lamang nito ang uncached line sa third request: $0.22 kumpara sa $0.30. Sa 20 requests, ang pagitan ay $2.00 kumpara sa $0.315.

Nire-refresh din ng cache hit ang entry. Ito ang dahilan kung bakit tinatawag ng published price table ang column na cache hits and refreshes. Dahil dito, maaaring manatiling buhay nang walang takdang oras ang 5 minute entry ng isang busy endpoint sa read prices. Ang 1 hour lifetime naman ay kikita lamang sa 2x write kapag may tunay na pagitan ang traffic.

Magkano ang epekto ng mababang hit rate

May mga cache miss sa totoong traffic. Ang request na hindi tumama sa cache pero may breakpoint pa rin ay sinisingil bilang write, kaya ang tamang paraan ng pag-model nito ay gawing function ng hit rate ang cost. Ipinapakita ito ng chart sa ibaba para sa 1,000 requests, na bawat isa ay may parehong 20,000-token prefix.

[
  {
    "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"
  }
]

Sa 0 percent na hit rate, magbabayad ka ng $125.00 sa halip na $100.00, at dinodoble ng 1 hour cache ang bill sa $200.00. Kapag nilutas ang 1.25 minus 1.15h = 1, magsisimulang makatipid ang 5 minute cache sa hit rate na humigit-kumulang 22 percent. Kaya sa 25 percent, lumalabas na agad ang $96.25. Ang parehong kalkulasyon para sa 2x write ay nagbibigay ng humigit-kumulang 53 percent para sa 1 hour cache. Kaya sa 50 percent na hit rate, nagkakahalaga pa rin ito ng $105.00, na mas mataas sa uncached line. Sa 90 percent, umaabot ang dalawa sa $21.50 at $29.00. Sa 99 percent, umaabot ang short cache sa $11.15, na malapit sa floor na one tenth ng uncached price.

Ang hit rate ang dapat mong i-instrument, dahil ito lamang ang input na makokontrol mo kapag fixed na ang prefix size.

Aling mga prefix ang sulit lagyan ng breakpoint

Maaaring maglaman ang isang request ng hanggang apat na cache breakpoint, kaya ang tanong ay kung aling mga block ang dapat lagyan nito. Ang mga kandidato ay mga block na eksaktong magkakapareho sa bawat call at sapat ang laki para magkaroon ng epekto. Ipinapakita ng chart sa ibaba ang halaga ng apat na karaniwang anyo sa 1,000 request, na may 90 porsiyentong hit rate sa 5 minutong cache.

[
  {
    "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"
  }
]

Ang isang bare na 2,000 token system prompt ay nakakatipid ng $7.85 kada 1,000 request kumpara sa $10.00 kapag walang cache. Malaking halaga ito kapag mataas ang volume, pero hindi ito ang dahilan kung bakit kapansin-pansin ang caching. Idagdag ang tool definitions at magiging 8,000 tokens ito, na may $31.40 na natitipid. Ang 25,000 token policy document na tinatanungan sa bawat request ay nakakatipid ng $98.12. Ang huling row ang may epekto sa architecture: ang 120,000 tokens na codebase o transcript context ay nagkakahalaga ng $600.00 kapag walang cache at $129.00 kapag naka-cache, kaya $471.00 ang natitipid.

Ang natitipid ay tumataas kasabay ng laki ng prefix at hit rate, at wala nang iba. Binabago nito kung ano ang sulit ilagay sa prompt: ang aktuwal na halaga ng isang milyong Claude token ay nagiging ikasampu ng sticker price para sa anumang ipinapadala mo nang higit sa isang beses.

Ano ang itsura nito sa buwanang bill

Kinukuha ng chart sa ibaba ang 8,000 token prefix mula sa itaas, isang system prompt kasama ang mga tool definition, at 90 percent hit rate, at ina-apply ito sa mga buwanang volume ng request.

[
  {
    "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"
  }
]

Sa 10,000 request bawat buwan, ang matitipid ay $314.00, ang diperensiya sa pagitan ng $400.00 at $86.00. Sa 100,000 request, ito ay $3,140.00. Sa isang milyong request, ang uncached input bill ay $40,000.00, at inaalis ng caching ang $31,400.00 mula rito. Input tokens lamang ang mga ito. Hiwalay ang presyo ng output, at walang epekto rito ang caching. Mahalaga itong tandaan bago ka mangako sa sinuman ng 90 percent na bawas sa bill. Bahagi ang caching ng mas malawak na mga kasanayan sa pagkontrol sa bill ng AI agent sa isang VPS.

Paano patunayang gumagana ang cache

Huwag umasa sa disenyo. Basahin ang usage block sa response. Iniuulat ng bawat Messages API (application programming interface) reply ang mga cached token na isinulat nito, mga cached token na binasa nito, at mga bagong token na kinailangan nitong i-process.

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)

Patakbuhin ito nang dalawang beses gamit ang parehong document at ibang tanong. Sa unang call, non-zero ang cache_creation_input_tokens at zero ang cache_read_input_tokens. Sa ikalawang call, kabaligtaran ito dahil nakita ang prefix. Ang input_tokens ay binibilang lamang ang mga token pagkatapos ng huling breakpoint, kaya maliit ito sa maayos na ikalawang call—karaniwan, ang bagong user message lamang.

Maaari mong gawin ang parehong check mula sa shell gamit ang request body na na-save sa 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'

Ganito ang karaniwang output ng maayos na ikalawang call:

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

Isang linya ang nagbibigay ng malinaw na sagot. Kung nananatili sa 0 ang cache_read_input_tokens sa bawat call, binabayaran mo ang 1.25x write sa bawat pagkakataon at wala kang natatanggap na cached result.

Para sa 1 hour na lifetime, may time to live (TTL) ang breakpoint:

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

May automatic caching din: maglagay ng isang cache_control field sa top level ng request, at pagkatapos ay awtomatikong mamamahala ang API ng mga breakpoint habang lumalaki ang conversation. Gagamit ito ng isa sa apat mong breakpoint slot. Magsimula rito. Lumipat sa explicit breakpoint kapag kailangan mong eksaktong tukuyin kung saan ilalagay ang boundary.

Ang ordering rule na sumisira sa hit rate

Tumutugma ang cache sa prefix byte for byte mula sa simula ng request. Binubuo ang request sa fixed na pagkakasunod-sunod: tools, pagkatapos ay system, at kasunod ang messages. Kapag may nagbago sa anumang level, nai-invalidate ang level na iyon at lahat ng kasunod nito. Kapag nag-edit ka ng isang tool description, mai-invalidate din ang system prompt at ang buong message history, kahit hindi mo binago ang mga ito.

May isang rule dito na walang exception. Lahat ng nagbabago sa pagitan ng mga call ay dapat ilagay pagkatapos ng lahat ng hindi nagbabago.

Karaniwang sanhi nito ang timestamp. Ang linyang may Current time: 2026-08-03T14:07:11Z sa itaas ng system prompt ay garantisadong magbibigay ng 0 percent hit rate, dahil naiiba ang prefix hash sa bawat call at walang naunang entry ang maaaring tumugma rito. Ilipat ito sa user message, sa pinakadulo. Ganito rin ang epekto ng session identifier o per-request nonce, at ganoon din ang solusyon. Ang mga retrieved document na nag-iiba sa bawat request ay dapat ilagay pagkatapos ng cached block. Kung hindi, itinutulak ng mga ito ang lahat ng stable token sa likod ng boundary na nagbabago.

Ang ikalawang sanhi ay ang paglalagay ng breakpoint sa block na nagbabago. Nagsusulat ang cache sa breakpoint. Kaya kung naiiba ang block sa bawat pagkakataon, walang stable na content ang nase-save. Sa lookback, mga entry lamang na isinulat ng naunang requests sa sarili nilang nagbabagong breakpoint ang makikita. Ilagay ang cache_control sa huling block na magkapareho ang content sa lahat ng requests.

Ang ikatlong sanhi ay parameter change na hindi mo itinuring na bahagi ng prompt content. May ibang cache ang bawat model. Kapag binago ang tool choice, mai-invalidate ang cache mula sa system level pataas. Kapag nagdagdag o nag-alis ka ng tool, mai-invalidate ang lahat.

Ang minimum prefix at ang silent no-op

Hindi naka-cache ang prefix na mas maikli sa minimum ng model, at walang ipinapaalam sa iyo. Walang error o warning. Matagumpay ang request, at parehong 0 ang nakikitang value ng dalawang counter. Noong August 2026, ang mga minimum na inilathala ay:

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

Kung parehong 0 ang nakikitang value ng dalawang counter sa isang request na inaasahan mong naka-cache, tingnan muna ang haba ng prefix bago ang iba pang bagay. Ito rin ang dahilan kung bakit hindi awtomatikong pinakamura para sa caching workload ang model na may pinakamababang presyo. Kailangan ng Haiku 4.5 ng prefix na walong beses na mas mahaba kaysa sa kailangan ng Opus 5 bago gumana ang caching, kaya ang 2,000-token system prompt ay naka-cache sa isa at tahimik na binabalewala sa isa pa.

Saan nagka-cache ang Claude Code para sa iyo, at saan ito hindi makakatulong

Naka-cache ng Claude Code ang sarili nitong prefix. Nasa unahan ng bawat request ang system prompt at mga tool definition at hindi nagbabago ang posisyon ng mga ito, kaya isang beses lang isinusulat ang mga ito at pagkatapos ay binabasa muli sa natitirang bahagi ng session. Dahil dito, mas mababa kaysa sa ipinapahiwatig ng context size ang cost sa bawat turn ng mahabang session. Makikita ito sa mga counter na inilalarawan sa kung paano iniuulat ng Claude Code ang token usage.

Hindi ito makakatulong kapag may pag-edit malapit sa simula ng context. Append-only ang conversation history, kaya ang mga karaniwang bagong turn ay nagdaragdag sa prefix na naka-cache na. Kapag nag-edit ka ng file na binasa nang maaga sa session, nagbabago ang content sa gitna ng prefix na iyon, kaya kailangang isulat muli ang bawat token pagkatapos ng pagbabago. Ganito rin ang nangyayari kapag matagal na walang aktibidad, dahil nag-e-expire ang entry at kailangang magsagawa ng full write sa susunod na turn. Hindi bug ang alinman sa mga ito. Pareho itong direktang resulta ng prefix rule.

Kung sarili mong client ang sinusulat mo, gamitin ang layout mula sa unang request sa halip na ayusin ito pagkatapos: buuin ang call gaya ng ginagawa sa unang Claude API app sa isang VPS, kung saan nauuna ang stable blocks at nasa hulihan ang volatile blocks.

Mga failure mode at kung ano ang makikita mo

Write ang bawat call. Non-zero ang cache_creation_input_tokens sa bawat request habang nananatiling 0 ang cache_read_input_tokens. May nagbabago sa isang bahagi bago o sa mismong breakpoint sa pagitan ng mga call. I-print ang unang 200 character ng binuong prefix sa dalawang magkasunod na request, pagkatapos ay ihambing ang mga ito nang biswal.

Parehong 0 ang dalawang counter. Mas maikli sa minimum ng model ang prefix, o hindi nakarating sa API ang field na cache_control. Bilangin muna ang mga token ng prefix, pagkatapos ay i-log ang aktuwal na request body na ipinadala mo.

Gumagana ang mga read, tapos humihinto. May sunod-sunod na hit, kasunod ang isang write, at pagkatapos ay may mga hit ulit. Mas mahaba sa lifetime ang pagitan ng mga request. Tanggapin ang write, o lumipat sa 1 hour TTL kapag nakumpirma mong lumalagpas sa 53 percent ang hit rate mo.

Bumababa ang hit rate pagkatapos ng deploy. Na-edit ang isang tool description o nagbago ang model. Pareho nitong ini-invalidate ang buong prefix. Asahan ang isang magastos na write round pagkatapos ng bawat deploy na nagbabago sa prompt.

Tumaas ang bill pagkatapos mong i-enable ang caching. Mas mababa sa break-even ang hit rate mo. Kung nasa humigit-kumulang 22 percent pababa ang hit rate sa 5 minute cache, mas mura ang pagpapadala ng prefix nang walang cache. Ganito rin sa 1 hour cache kung nasa humigit-kumulang 53 percent pababa ang hit rate.

FAQ

Ilang beses kailangang gamitin muli ang isang prompt bago maging sulit ang caching?

Isang beses, sa 5 minute cache. Ang write ay nagkakahalaga ng 1.25x ng base input at ang read ay 0.1x, kaya ang N uncached request ay nagkakahalaga ng N, samantalang ang N cached request ay nagkakahalaga ng 1.25 plus 0.1 times N minus 1. Nagkakasinghalaga ang dalawang ito sa N = 1.28, kaya mas sulit na agad ang second request. Ang 1 hour cache ay may write cost na 2x at nagkakasinghalaga sa N = 2.11, kaya kailangan nito ng dalawang read.

Bakit palaging zero ang cache_read_input_tokens?

Suriin muna ang prefix length: kapag mas mababa ito sa minimum ng model—512 tokens sa Claude Opus 5 at 4,096 sa Claude Haiku 4.5 noong August 2026—tahimik na nilalaktawan ang caching at parehong 0 ang nababasang counter. Kung sapat ang haba ng prefix, hanapin ang content na nagbabago sa pagitan ng mga call at nasa breakpoint o bago nito, gaya ng timestamp o session identifier sa system prompt. Kung dati ay gumagana ang mga counter at bigla silang tumigil, mas mahaba sa cache lifetime ang pagitan ng mga request.

Binabago ba ng prompt caching ang mga sagot ni Claude?

Hindi. Ini-store ng cache ang processed form ng mga token na naipadala mo na, at pareho pa rin ang prompt na nakikita ng model. Feature ito para sa billing at latency, hindi pagbabago sa behaviour. Ibig sabihin, maaari mo itong i-enable sa gumaganang prompt nang hindi inuulit ang iyong evaluations.

Dapat ba akong magbayad para sa 1 hour cache?

Tanging kapag may mga gap na lampas 5 minutes ang traffic mo at mananatili sa humigit-kumulang 53 percent ang hit rate mo. Dalawang beses na mas malaki ang downside ng 2x write kapag miss kumpara sa 1.25x write. Nare-refresh ang isang 5 minute entry sa bawat hit, kaya napapanatili ito ng steady traffic sa read prices nang hindi kailanman nagbabayad para sa mas mahabang lifetime.