Caching Prompt Claude: Kiraan Titik Pulang Modal

Kos caching prompt sebelum memberikan penjimatan

Caching prompt membolehkan Claude menggunakan semula bahagian awal prompt tanpa membacanya semula pada setiap panggilan. Keseluruhan keputusan bergantung pada dua pengganda bagi harga input asas model anda. Setakat August 2026, penulisan cache berharga 1.25x input asas untuk tempoh hayat 5 minit, atau 2x untuk tempoh hayat 1 jam. Pembacaan cache berharga 0.1x. Pengganda ini sama untuk semua model dalam senarai, jadi titik pulang modal di bawah tidak berubah apabila harga setiap token berubah.

Pertukarannya ialah surcaj sekarang berbanding diskaun kemudian. Anda membayar lebihan sekali untuk menyimpan awalan. Setiap permintaan seterusnya yang bermula dengan bait yang sama tepat membayar sepersepuluh daripada harga input biasa bagi bahagian tersebut. Awalan yang tidak pernah digunakan semula dalam tempoh hayatnya menyebabkan anda membayar lebihan 25 peratus tanpa manfaat.

Titik pulang modal, dalam satu baris algebra

Panggil B sebagai kos input asas bagi awalan jika anda menghantarnya tanpa cache. Tanpa caching, N permintaan berharga N didarab dengan 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 lebih murah berbanding tidak menggunakan caching langsung.

Ulang pengiraan itu dengan penulisan 2x bagi cache 1 jam dan anda mendapat 0.9N = 1.9, jadi N = 2.11. Cache yang lebih lama memerlukan dua bacaan sebelum mencapai titik pulang modal. Oleh itu, cache ini bukan pilihan lalai.

Carta di bawah mengira kos ini untuk awalan 20,000 token pada Claude Opus 5, yang kadar input asasnya ialah $5 bagi setiap juta token setakat August 2026. Darabkan setiap angka dengan 0.6 untuk model berharga $3 bagi setiap juta token. Bentuk lengkung 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 sahaja berharga $0.10 tanpa cache dan $0.125 dengan cache. Oleh itu, caching untuk prompt yang hanya digunakan sekali menyebabkan kerugian bersih. Pada permintaan kedua, cache 5 minit berharga $0.135 berbanding $0.20. Cache 1 jam masih lebih mahal pada ketika itu, iaitu $0.21 berbanding $0.20 yang sama, dan hanya menjadi lebih murah daripada penggunaan tanpa cache pada permintaan ketiga: $0.22 berbanding $0.30. Dengan 20 permintaan, jurangnya ialah $2.00 berbanding $0.315.

Cache hit juga menyegarkan entri. Oleh itu, jadual harga yang diterbitkan menamakan lajur tersebut sebagai cache hits and refreshes. Endpoint yang sibuk akan terus mengekalkan entri 5 minit tanpa had pada harga bacaan. Tempoh 1 jam hanya berbaloi dengan kos penulisan 2x apabila trafik anda mempunyai sela masa yang nyata.

Kos kadar cache yang rendah

Trafik sebenar mengalami cache miss. Permintaan yang tidak mendapat cache hit tetapi masih membawa breakpoint dikira sebagai write, jadi cara yang tepat untuk memodelkannya ialah mengira kos sebagai fungsi kadar cache hit. Carta di bawah menunjukkan keadaan ini untuk 1,000 permintaan, 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 cache hit 0 peratus, kosnya ialah $125.00, berbanding $100.00, manakala cache 1 jam menggandakan bil kepada $200.00. Selesaikan 1.25 tolak 1.15h = 1, dan cache 5 minit mula menjimatkan kos pada kadar cache hit kira-kira 22 peratus. Sebab itu kadar 25 peratus sudah menunjukkan $96.25. Pengiraan yang sama untuk write 2x memberikan kira-kira 53 peratus bagi cache 1 jam. Oleh itu, kadar cache hit 50 peratus masih berharga $105.00, iaitu lebih tinggi daripada garis tanpa cache. Pada 90 peratus, kedua-duanya masing-masing berharga $21.50 dan $29.00. Pada 99 peratus, cache jangka pendek mencapai $11.15, hampir dengan paras minimum, iaitu satu persepuluh daripada harga tanpa cache.

Kadar cache hit ialah metrik yang perlu dipantau kerana selepas saiz prefix ditetapkan, inilah satu-satunya input yang boleh anda kawal.

Awalan yang berbaloi untuk titik cache

Satu permintaan boleh membawa sehingga empat titik pemisah cache. Jadi, persoalannya ialah blok mana yang patut diberikan titik cache. Calon yang sesuai ialah blok yang sama sepenuhnya dari segi bait bagi setiap panggilan dan cukup besar untuk memberi kesan. Carta di bawah membandingkan kos empat bentuk lazim bagi 1,000 permintaan dengan kadar cache hit 90 peratus pada 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"
  }
]

System prompt token 2,000 yang ringkas menjimatkan $7.85 bagi setiap 1,000 permintaan berbanding kos $10.00 tanpa cache. Jumlah ini bermakna pada skala tinggi, tetapi bukan itu yang menjadikan caching menarik. Tambahkan definisi alat, lalu jumlahnya menjadi 8,000 token dan penjimatan menjadi $31.40. Dokumen dasar sepanjang 25,000 token yang dirujuk oleh setiap permintaan menjimatkan $98.12. Baris terakhir ialah baris yang mengubah seni bina: konteks pangkalan kod atau transkrip sepanjang 120,000 token berharga $600.00 tanpa cache dan $129.00 dengan cache, iaitu penjimatan sebanyak $471.00.

Penjimatan meningkat mengikut saiz awalan dan kadar cache hit, dan tidak dipengaruhi oleh perkara lain. Ini mengubah perkara yang berbaloi untuk dimasukkan ke dalam prompt: kos sebenar sejuta token Claude menjadi sepersepuluh daripada harga yang dipaparkan bagi apa-apa kandungan yang dihantar lebih daripada sekali.

Rupanya pada bil bulanan

Carta di bawah mengambil awalan token 8,000 daripada bahagian sebelumnya, bersama gesaan sistem dan takrif alat, pada kadar hit 90 peratus, kemudian mengunjurkannya kepada jumlah 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 ialah $314.00, iaitu perbezaan antara $400.00 dengan $86.00. Pada 100,000 permintaan, penjimatan ialah $3,140.00. Pada sejuta permintaan, bil input tanpa cache ialah $40,000.00, dan caching menghapuskan $31,400.00 daripadanya. Ini hanya melibatkan token input. Output dibilkan secara berasingan dan tidak terjejas oleh caching. Perkara ini perlu diingat sebelum anda menjanjikan pengurangan bil sebanyak 90 peratus kepada sesiapa. Caching melengkapi amalan lain yang lebih luas dalam mengawal bil ejen AI pada VPS.

Cara membuktikan cache berfungsi

Jangan bergantung pada reka bentuk sahaja. Baca blok penggunaan dalam respons. Setiap respons Messages API (antara muka pengaturcaraan aplikasi) 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 dua kali dengan dokumen yang sama dan soalan yang berbeza. Panggilan pertama melaporkan cache_creation_input_tokens bukan sifar dan cache_read_input_tokens sifar. Panggilan kedua memberikan hasil yang sebaliknya kerana awalan telah ditemui. input_tokens hanya mengira token selepas titik henti terakhir. Oleh itu, nilainya kecil dalam panggilan kedua yang berjaya, biasanya hanya mesej pengguna baharu. Kedua-dua panggilan dikenakan bayaran kerana Claude API tidak mempunyai peringkat percuma, walaupun bagi awalan 20,000 token, jumlah pasangan panggilan yang dinyatakan di atas adalah kira-kira empat belas sen.

Pemeriksaan yang sama daripada shell, menggunakan isi permintaan yang anda simpan dalam 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 berjaya memaparkan sesuatu seperti ini:

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

Satu baris memberikan maklumat sebenar. Jika cache_read_input_tokens kekal pada 0 antara panggilan, anda membayar kos penulisan 1.25x setiap kali tetapi tidak menerima apa-apa manfaat daripadanya.

Untuk tempoh hayat 1 jam, titik henti mempunyai masa untuk hidup (TTL):

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

Terdapat juga caching automatik: satu medan cache_control pada peringkat teratas permintaan. Selepas itu, API mengurus titik henti apabila perbualan berkembang. Ia menggunakan satu daripada empat slot titik henti anda. Mulakan dengan kaedah ini. Gunakan titik henti eksplisit apabila anda perlu menentukan dengan tepat lokasi sempadan.

Peraturan susunan yang memusnahkan kadar cache hit

Cache memadankan awalan bait satu demi satu dari awal permintaan, dan permintaan dibina mengikut susunan tetap: tools, kemudian system, kemudian messages. Perubahan pada mana-mana peringkat membatalkan peringkat tersebut dan semua peringkat selepasnya. Edit satu penerangan tool akan membatalkan system prompt dan seluruh sejarah mesej bersamanya, walaupun anda tidak mengubahnya.

Ini menghasilkan satu peraturan tanpa pengecualian. Apa-apa yang berubah antara panggilan mesti diletakkan selepas semua yang tidak berubah.

Punca yang lazim ialah cap masa. Baris yang mengandungi Current time: 2026-08-03T14:07:11Z di bahagian atas system prompt menjamin kadar cache hit sebanyak 0 peratus, kerana hash awalan berubah pada setiap panggilan dan tiada entri terdahulu boleh sepadan dengannya. Alihkannya ke user message, di bahagian akhir. Pengecam sesi atau nonce bagi setiap permintaan menimbulkan masalah yang sama dan memerlukan pembaikan yang sama. Dokumen yang diperoleh semula dan berbeza bagi setiap permintaan juga mesti diletakkan selepas blok cache; jika tidak, semua token stabil di belakangnya akan ditolak ke belakang sempadan yang berubah.

Punca kedua ialah meletakkan breakpoint pada blok yang berubah. Cache ditulis pada breakpoint, jadi jika blok itu berbeza setiap kali, tiada kandungan stabil yang pernah disimpan, dan carian ke belakang hanya menemukan entri yang ditulis oleh permintaan terdahulu pada breakpointnya yang turut berubah. Letakkan cache_control pada blok terakhir yang kandungannya sama bagi semua permintaan.

Punca ketiga ialah perubahan parameter yang tidak anda anggap sebagai kandungan prompt. Model yang berbeza mempunyai cache yang berbeza. Menukar pilihan tool akan membatalkan cache bermula dari peringkat system dan seterusnya. Menambah atau membuang tool akan membatalkan semuanya.

Awalan minimum dan tiada operasi secara senyap

Awalan yang lebih pendek daripada minimum model tidak akan dicache dan tiada apa-apa pemberitahuan diberikan. Tiada ralat dan tiada amaran. Permintaan berjaya, manakala kedua-dua pembilang menunjukkan 0. Setakat August 2026, minimum yang diterbitkan ialah:

• 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 untuk permintaan yang anda percaya telah dicache, semak panjang awalan terlebih dahulu. Ini juga sebab model paling murah tidak semestinya paling murah untuk beban kerja caching. Haiku 4.5 memerlukan awalan lapan kali lebih panjang daripada Opus 5 sebelum caching mula digunakan. Oleh itu, system prompt sepanjang 2,000 token dicache pada satu model tetapi diabaikan secara senyap pada model yang satu lagi.

Tempat Claude Code menyimpan cache untuk anda dan tempat cache tidak membantu

Claude Code menyimpan cache untuk prefixnya sendiri. System prompt dan definisi alat berada di bahagian awal setiap permintaan dan tidak berubah, jadi kedua-duanya ditulis sekali lalu dibaca semula untuk sepanjang sesi. Sebab itu kos bagi setiap giliran dalam sesi yang panjang jauh lebih rendah daripada yang dicadangkan oleh saiz konteks, dan perkara ini dapat dilihat dalam pembilang yang diterangkan dalam cara Claude Code melaporkan penggunaan token.

Cache tidak membantu apabila anda mengedit bahagian yang hampir dengan permulaan konteks. Sejarah perbualan hanya boleh ditambah, jadi giliran baharu biasa akan memanjangkan prefix yang sudah dicache. Mengedit fail yang dibaca pada awal sesi mengubah kandungan di tengah-tengah prefix itu, dan setiap token selepas perubahan tersebut perlu ditulis semula. Tempoh tidak aktif yang panjang menghasilkan kesan yang sama kerana entri itu tamat tempoh dan giliran seterusnya perlu membayar kos penulisan penuh. Kedua-duanya bukan pepijat. Kedua-duanya ialah peraturan prefix yang berfungsi seperti yang dinyatakan.

Jika anda menulis client anda sendiri, gunakan susun atur ini sejak permintaan pertama dan jangan cuba menyesuaikannya kemudian: bina panggilan seperti yang ditunjukkan dalam aplikasi Claude API pertama pada VPS, dengan blok yang stabil di bahagian awal dan blok yang berubah-ubah di bahagian akhir.

Mod kegagalan dan perkara yang akan anda lihat

Setiap panggilan ialah operasi tulis. 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 bagi awalan yang telah dipasang pada dua permintaan berturutan, kemudian bandingkan secara visual.

Kedua-dua pembilang ialah 0. Awalan lebih pendek daripada panjang minimum model, atau medan cache_control tidak pernah sampai ke API. Kira token awalan dahulu, kemudian catat badan permintaan yang sebenarnya anda hantar.

Bacaan berjaya, kemudian berhenti. Beberapa bacaan berjaya, diikuti operasi tulis, kemudian bacaan berjaya semula. Jeda antara permintaan lebih panjang daripada tempoh hayat. Terima operasi tulis tersebut, atau gunakan TTL 1 jam selepas anda mengesahkan bahawa kadar cache hit melebihi 53 peratus.

Kadar cache hit menurun selepas deploy. Perihalan alat telah diedit atau model telah ditukar. Kedua-duanya membatalkan keseluruhan awalan. Jangkakan satu pusingan operasi tulis yang mahal selepas setiap deploy yang mengubah prompt.

Bil meningkat selepas anda mendayakan caching. Kadar cache hit anda berada di bawah titik pulang modal. Pada cache 5 minit, menghantar awalan tanpa caching adalah lebih murah apabila kadarnya di bawah kira-kira 22 peratus. Perkara yang sama terpakai pada cache 1 jam apabila kadarnya di bawah kira-kira 53 peratus.

FAQ

Berapa kali prompt perlu digunakan semula sebelum caching berbaloi?

Sekali, untuk cache 5 minit. Kos penulisan ialah 1.25x input asas dan kos pembacaan ialah 0.1x. Oleh itu, N permintaan tanpa cache berharga N, manakala N permintaan dengan cache berharga 1.25 tambah 0.1 didarab dengan N tolak 1. Kedua-duanya bersilang pada N = 1.28, jadi permintaan kedua sudah lebih menjimatkan. Cache 1 jam mempunyai kos penulisan 2x dan bersilang pada N = 2.11, jadi ia memerlukan dua pembacaan.

Mengapakah cache_read_input_tokens sentiasa bernilai sifar?

Semak panjang awalan terlebih dahulu. Jika panjangnya kurang daripada minimum model, iaitu 512 token pada Claude Opus 5 dan 4,096 pada Claude Haiku 4.5 setakat August 2026, caching dilangkau secara senyap dan kedua-dua pembilang bernilai 0. Jika awalan cukup panjang, cari kandungan yang berubah antara panggilan dan berada pada atau sebelum titik pemisah, seperti cap masa atau pengecam sesi dalam system prompt. Jika pembilang sebelum ini berfungsi tetapi kemudian berhenti, jarak antara permintaan melebihi tempoh hayat cache.

Adakah prompt caching mengubah jawapan Claude?

Tidak. Cache menyimpan bentuk token yang telah diproses dan dihantar sebelum ini, dan model melihat prompt yang sama dalam kedua-dua keadaan. Ini ialah ciri pengebilan dan kependaman, bukan perubahan tingkah laku. Oleh itu, anda boleh mengaktifkannya pada prompt yang berfungsi tanpa menjalankan semula penilaian.

Patutkah saya membayar cache 1 jam?

Hanya jika trafik anda mempunyai jeda lebih daripada 5 minit dan kadar cache hit anda masih dijangka melebihi kira-kira 53 peratus. Kos penulisan 2x mempunyai kesan negatif dua kali ganda berbanding kos penulisan 1.25x apabila cache miss berlaku. Entri 5 minit disegarkan semula pada setiap cache hit. Oleh itu, trafik yang berterusan mengekalkannya pada kos pembacaan tanpa perlu membayar tempoh hayat yang lebih panjang.