Cara Kira Titik Pulang Modal Claude Prompt Caching

Kos cache prompt sebelum ia menjimatkan

Cache prompt membolehkan Claude menggunakan semula bahagian hadapan prompt anda dan bukannya membacanya semula pada setiap panggilan. Keseluruhan keputusan bergantung kepada dua pengganda pada harga input asas model anda. Setakat Ogos 2026, penulisan cache berharga 1.25x input asas untuk jangka hayat 5 minit, atau 2x untuk jangka hayat 1 jam. Bacaan cache pula berharga 0.1x. Pengganda ini kekal merentas senarai model, jadi titik pulang modal di bawah tidak berubah apabila harga per-token berubah.

Pertukaran ini adalah surcaj sekarang berbanding diskaun kemudian. Anda membayar lebih sekali untuk menyimpan awalan (prefix). Setiap permintaan seterusnya yang bermula dengan bait yang sama persis kemudiannya membayar satu persepuluh daripada harga input biasa untuk bahagian tersebut. Awalan yang tidak pernah digunakan semula dalam jangka hayatnya menyebabkan anda membayar 25 peratus lebih tanpa sebarang faedah.

Titik pulang modal, dalam satu baris algebra

Katakan B ialah kos input asas bagi awalan (prefix) jika anda menghantarnya tanpa caching. Tanpa caching, N permintaan menelan kos N kali B. Dengan cache 5 minit, permintaan pertama menulis awalan pada 1.25B dan N tolak 1 permintaan yang lain membacanya pada 0.1B. Samakan kedua-duanya dan anda mendapat 0.9N = 1.15, jadi N = 1.28. Permintaan kedua sudah pun lebih murah berbanding tidak menggunakan caching langsung.

Ulangi langkah tersebut dengan penulisan 2x bagi cache 1 jam dan anda mendapat 0.9N = 1.9, jadi N = 2.11. Cache jangka panjang memerlukan dua bacaan sebelum mencapai titik pulang modal, itulah sebabnya ia bukan pilihan lalai.

Carta di bawah meletakkan harga ini untuk awalan 20,000 token pada Claude Opus 5, yang kadar input asasnya ialah $5 bagi setiap juta token setakat Ogos 2026. Skalakan setiap angka dengan 0.6 untuk model $3 bagi setiap juta token. Bentuk lengkung tersebut tidak berubah.

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

Satu permintaan secara sendirian menelan kos $0.10 tanpa cache dan $0.125 dengan cache, jadi melakukan caching pada prompt sekali guna (one-shot) adalah kerugian semata-mata. Menjelang permintaan kedua, cache 5 minit berada pada $0.135 berbanding $0.20. Cache 1 jam masih ketinggalan pada ketika itu, $0.21 berbanding $0.20 yang sama, dan ia hanya melepasi garisan tanpa cache pada permintaan ketiga: $0.22 berbanding $0.30. Menjelang 20 permintaan, jurangnya ialah $2.00 berbanding $0.315.

Hit cache juga menyegarkan entri tersebut, itulah sebabnya jadual harga yang diterbitkan menamakan lajur itu sebagai cache hits and refreshes. Oleh itu, titik akhir yang sibuk akan mengekalkan entri 5 minit hidup selama-lamanya pada harga bacaan, dan jangka hayat 1 jam hanya memperoleh kos penulisan 2x apabila trafik anda mempunyai jurang sebenar di dalamnya.

Kos kadar hit yang rendah

Trafik sebenar mengalami miss. Permintaan yang terlepas daripada cache tetapi masih membawa breakpoint akan dikenakan caj sebagai penulisan (write), jadi cara yang tepat untuk memodelkan perkara ini adalah dengan mengira kos sebagai fungsi kadar hit. Carta di bawah menunjukkan perkara tersebut untuk 1,000 permintaan, dengan setiap satunya membawa prefix 20,000 token yang sama.

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

Pada kadar hit 0 peratus, anda membayar $125.00 berbanding $100.00, dan cache 1 jam menggandakan bil kepada $200.00. Selesaikan persamaan 1.25 tolak 1.15h = 1 dan cache 5 minit mula menjimatkan wang pada kadar hit sekitar 22 peratus, itulah sebabnya 25 peratus sudah menunjukkan $96.25. Pengiraan yang sama untuk penulisan 2x memberikan sekitar 53 peratus untuk cache 1 jam, jadi kadar hit 50 peratus masih menelan kos $105.00, iaitu di atas garisan tanpa cache. Pada 90 peratus, kedua-duanya berada pada $21.50 dan $29.00. Pada 99 peratus, cache jangka pendek mencapai $11.15, hampir kepada paras lantai iaitu satu persepuluh daripada harga tanpa cache.

Kadar hit ialah angka yang perlu diukur, kerana ia merupakan satu-satunya input yang anda kawal selepas saiz prefix ditetapkan.

Awalan yang berbaloi untuk breakpoint

Satu permintaan boleh membawa sehingga empat cache breakpoint, jadi persoalannya ialah blok mana yang wajar diberikan breakpoint. Calon yang sesuai ialah blok yang mempunyai bait yang sama merentas panggilan dan cukup besar untuk memberi kesan. Carta di bawah menunjukkan harga bagi empat bentuk biasa untuk 1,000 permintaan pada kadar hit 90 peratus dalam cache 5 minit.

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

Sistem prompt token 2,000 yang ringkas menjimatkan $7.85 bagi setiap 1,000 permintaan berbanding $10.00 tanpa cache. Ini melibatkan wang sebenar jika dalam jumlah yang besar, tetapi itu bukan perkara yang menjadikan caching menarik. Tambahkan definisi alat dan anda akan mencapai 8,000 token dengan penjimatan $31.40. Dokumen polisi 25,000 token yang dirujuk oleh setiap permintaan menjimatkan $98.12. Baris terakhir adalah yang mengubah seni bina: 120,000 token kod atau konteks transkrip menelan kos $600.00 tanpa cache dan $129.00 dengan cache, iaitu penjimatan sebanyak $471.00.

Penjimatan berskala mengikut saiz awalan dan kadar hit, dan tidak bergantung pada perkara lain. Ini mengubah apa yang sebenarnya berbaloi untuk diletakkan dalam prompt: kos sebenar sejuta token Claude turun kepada satu persepuluh daripada harga asal bagi apa sahaja yang anda hantar lebih daripada sekali.

Gambaran pada bil bulanan

Carta di bawah mengambil 8,000 token awalan daripada bahagian atas, sistem prompt berserta definisi alatan, pada kadar hit 90 peratus, dan menentukurkannya mengikut volum permintaan bulanan.

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

Pada 10,000 permintaan sebulan, penjimatan adalah $314.00, iaitu perbezaan antara $400.00 dan $86.00. Pada 100,000 permintaan, jumlahnya ialah $3,140.00. Pada satu juta permintaan, bil input tanpa cache adalah $40,000.00 dan caching membuang $31,400.00 daripadanya. Ini hanyalah token input. Output diletakkan harga secara berasingan dan caching tidak memberi kesan kepadanya, perkara yang perlu diingat sebelum anda menjanjikan sesiapa pemotongan bil sebanyak 90 peratus. Caching berfungsi seiring dengan amalan yang lebih luas dalam mengawal bil ejen AI pada VPS.

Cara membuktikan cache berfungsi

Jangan hanya mempercayai reka bentuknya. Baca blok penggunaan pada respons. Setiap balasan Messages API melaporkan token cache yang ditulisnya, token cache yang dibacanya, dan token baharu yang perlu diproses.

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)

Jalankan arahan tersebut dua kali dengan dokumen yang sama tetapi soalan yang berbeza. Panggilan pertama melaporkan cache_creation_input_tokens yang bukan sifar dan cache_read_input_tokens yang sifar. Panggilan kedua akan menterbalikkan keadaan tersebut, kerana awalan telah ditemui. input_tokens hanya mengira token selepas breakpoint terakhir, jadi pada panggilan kedua yang sihat, nilainya adalah kecil, biasanya hanya mesej pengguna yang baharu.

Semakan yang sama daripada shell, terhadap badan permintaan yang telah anda simpan ke 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'

Panggilan kedua yang sihat akan mencetak sesuatu seperti ini:

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

Satu baris akan memberitahu anda perkara sebenar. Jika cache_read_input_tokens kekal pada 0 merentasi panggilan, anda membayar 1.25x kos penulisan setiap kali dan tidak mendapat sebarang pulangan daripadanya.

Untuk jangka hayat 1 jam, breakpoint membawa time to live (TTL):

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

Terdapat juga caching automatik: satu medan cache_control pada peringkat atas permintaan, yang mana API akan menguruskan breakpoint apabila perbualan berkembang. Ia menggunakan satu daripada empat slot breakpoint anda. Mulakan di situ. Beralih kepada breakpoint eksplisit apabila anda perlu menentukan dengan tepat di mana sempadan tersebut diletakkan.

Peraturan susunan yang menjejaskan kadar hit

Cache memadankan awalan bait demi bait dari permulaan permintaan, dan permintaan tersebut disusun dalam tertib tetap: alatan, kemudian sistem, seterusnya mesej. Perubahan pada mana-mana peringkat akan membatalkan peringkat tersebut dan segala yang mengikutinya. Sunting satu perihalan alat dan gesaan sistem serta keseluruhan sejarah mesej akan dibatalkan bersamanya, walaupun anda tidak menyentuhnya.

Ini memberikan satu peraturan tanpa pengecualian. Apa-apa yang berubah antara panggilan mestilah diletakkan selepas segala yang tidak berubah.

Penyebab biasa ialah cap masa. Baris yang membaca Current time: 2026-08-03T14:07:11Z di bahagian atas gesaan sistem menjamin kadar hit 0 peratus, kerana hash awalan berbeza pada setiap panggilan dan tiada entri terdahulu yang boleh memadankannya. Pindahkan ia ke dalam mesej pengguna, di bahagian akhir. Pengecam sesi atau nonce bagi setiap permintaan merosakkan perkara dengan cara yang sama dan mempunyai penyelesaian yang serupa. Dokumen yang diambil yang berbeza bagi setiap permintaan juga perlu diletakkan selepas blok yang dicache, atau ia akan menolak setiap token stabil ke belakang sempadan yang bergerak.

Penyebab kedua ialah meletakkan titik henti (breakpoint) pada blok yang berubah. Penulisan cache berlaku pada titik henti, jadi jika blok itu berbeza setiap kali, tiada apa yang stabil akan disimpan, dan carian imbas balik hanya menemui entri yang ditulis oleh permintaan terdahulu pada titik henti mereka sendiri yang bergerak. Letakkan cache_control pada blok terakhir yang kandungannya adalah sama merentas permintaan.

Penyebab ketiga ialah perubahan parameter yang tidak anda fikirkan sebagai kandungan gesaan. Model yang berbeza mempunyai cache yang berbeza. Menukar pilihan alat akan membatalkan dari peringkat sistem ke atas. Menambah atau membuang alat akan membatalkan segala-galanya.

Awalan minimum dan no-op senyap

Awalan yang lebih pendek daripada minimum model tidak akan dicache, dan tiada pemberitahuan mengenainya. Tiada ralat, tiada amaran. Permintaan tersebut berjaya dan kedua-dua pembilang menunjukkan 0. Setakat Ogos 2026, nilai minimum yang diterbitkan adalah:

• 512 token pada Claude Opus 5 dan Claude Fable 5
• 1,024 token pada Claude Sonnet 5 dan Claude Opus 4.8
• 4,096 token pada Claude Haiku 4.5

Jika kedua-dua pembilang menunjukkan 0 pada permintaan yang anda jangkakan dicache, periksa panjang awalan sebelum perkara lain. Inilah sebabnya model paling murah tidak semestinya menjadi yang paling murah untuk beban kerja caching. Haiku 4.5 memerlukan awalan yang lapan kali lebih panjang daripada Opus 5 sebelum caching bermula, jadi prompt sistem 2,000 token akan dicache pada satu model tetapi diabaikan secara senyap pada model yang satu lagi.

Tempat Claude Code melakukan cache untuk anda, dan tempat ia tidak boleh melakukannya

Claude Code melakukan cache pada prefiksnya sendiri. Prompt sistem dan definisi alat terletak di bahagian hadapan setiap permintaan dan tidak berubah, jadi ia ditulis sekali dan dibaca semula untuk sepanjang sesi tersebut. Itulah sebabnya kos setiap giliran bagi sesi yang panjang adalah jauh lebih rendah daripada apa yang dicadangkan oleh saiz konteks, dan ia dipaparkan dalam pembilang yang diterangkan dalam cara Claude Code melaporkan penggunaan token.

Di mana ia tidak dapat membantu anda adalah suntingan berhampiran permulaan konteks. Sejarah perbualan hanya boleh ditambah (append-only), jadi giliran baharu yang biasa akan memanjangkan prefiks yang sudah pun di-cache. Menyunting fail yang dibaca pada awal sesi akan mengubah kandungan di tengah-tengah prefiks tersebut, dan setiap token selepas perubahan itu perlu ditulis semula. Jurang masa terbiar yang lama juga memberikan kesan yang sama, kerana entri tersebut tamat tempoh dan giliran seterusnya perlu membayar kos penulisan penuh. Kedua-duanya bukanlah pepijat. Kedua-duanya adalah peraturan prefiks yang berfungsi tepat seperti yang dinyatakan.

Jika anda sebaliknya menulis klien anda sendiri, gunakan susun atur daripada permintaan pertama dan bukannya mengubah suainya kemudian: bina panggilan tersebut seperti yang dilakukan oleh aplikasi API Claude pertama pada VPS, dengan blok yang stabil diletakkan di hadapan dan blok yang tidak stabil diletakkan di bahagian akhir.

Mod kegagalan dan perkara yang akan anda lihat

Setiap panggilan adalah penulisan. cache_creation_input_tokens bukan sifar pada setiap permintaan manakala cache_read_input_tokens kekal 0. Sesuatu pada atau sebelum titik henti berubah antara panggilan. Cetak 200 aksara pertama awalan yang dipasang pada dua permintaan berturut-turut dan bandingkan secara visual.

Kedua-dua pembilang adalah 0. Awalan berada di bawah minimum model, atau medan cache_control tidak pernah sampai ke API. Kira token awalan dahulu, kemudian log badan permintaan yang anda benar-benar hantar.

Bacaan berfungsi, kemudian terhenti. Satu siri hit, kemudian penulisan, kemudian hit semula. Jarak antara permintaan lebih lama daripada jangka hayat. Terima penulisan tersebut, atau beralih kepada TTL 1 jam sebaik sahaja anda menyemak kadar hit anda melepasi 53 peratus.

Kadar hit jatuh selepas penggunaan (deploy). Penerangan alat telah disunting atau model telah ditukar. Kedua-duanya membatalkan keseluruhan awalan. Jangkakan satu pusingan penulisan yang mahal selepas setiap penggunaan yang melibatkan prompt.

Bil meningkat selepas anda mendayakan caching. Kadar hit anda berada di bawah titik pulang modal. Di bawah kira-kira 22 peratus pada cache 5 minit, menghantar awalan tanpa cache adalah lebih murah, dan di bawah kira-kira 53 peratus, perkara yang sama berlaku untuk cache 1 jam.

FAQ

Berapa kali prompt perlu digunakan semula sebelum caching menjadi berbaloi?

Sekali sahaja, untuk cache 5 minit. Penulisan (write) menelan kos 1.25x input asas dan pembacaan (read) menelan kos 0.1x, jadi N permintaan tanpa cache menelan kos N manakala N permintaan dengan cache menelan kos 1.25 tambah 0.1 darab N tolak 1. Kedua-dua nilai ini bersilang pada N = 1.28, jadi permintaan kedua sudah pun menjimatkan kos. Cache 1 jam menulis pada 2x dan bersilang pada N = 2.11, jadi ia memerlukan dua pembacaan.

Mengapa cache_read_input_tokens sentiasa sifar?

Semak panjang awalan (prefix) terlebih dahulu: di bawah minimum model, iaitu 512 token pada Claude Opus 5 dan 4,096 pada Claude Haiku 4.5 setakat Ogos 2026, caching dilangkau secara senyap dan kedua-dua pembilang akan membaca 0. Jika awalan cukup panjang, cari kandungan yang berubah antara panggilan yang terletak pada atau sebelum titik putus (breakpoint), seperti cap masa atau pengecam sesi dalam system prompt. Jika pembilang berfungsi sebelum ini tetapi berhenti, jurang antara permintaan adalah lebih lama daripada jangka hayat cache.

Adakah prompt caching mengubah jawapan Claude?

Tidak. Cache menyimpan bentuk token yang telah diproses yang telah anda hantar, dan model melihat prompt yang sama dalam kedua-dua keadaan. Ia merupakan ciri pengebilan dan kependaman (latency), bukan perubahan dalam tingkah laku. Ini juga bermakna anda boleh mendayakannya pada prompt yang sedang berfungsi tanpa perlu menjalankan semula penilaian (evaluation) anda.

Patutkah saya membayar untuk cache 1 jam?

Hanya apabila trafik anda mempunyai jurang lebih lama daripada 5 minit dan kadar hit anda masih mencapai kira-kira 53 peratus. Penulisan 2x adalah dua kali ganda lebih merugikan berbanding penulisan 1.25x apabila anda terlepas (miss). Entri 5 minit diperbaharui pada setiap hit, jadi trafik yang stabil mengekalkannya pada harga bacaan tanpa perlu membayar untuk jangka hayat yang lebih lama.