Caching prompt Claude—tarif, objek penggunaan, dan alasan tingkat hit menurun di balik gateway

Caching prompt adalah satu tuas terbesar pada tagihan agent, dan yang paling mungkin diam-diam tidak bekerja. Jika ditandai dengan benar, bagian permintaan Anda yang berulang ditagihkan sebesar sepersepuluh tarif input. Jika ditandai dengan keliru — atau diarahkan melalui sesuatu yang menulis ulang awalan Anda — biayanya lebih besar daripada tarif biasa, karena Anda membayar untuk menulis entri cache yang tidak pernah dibaca.

Mekanismenya telah didokumentasikan dengan baik di tempat lain. Yang tidak didokumentasikan di mana pun adalah apa yang berubah ketika permintaan melewati gateway, yang merupakan situasi sebagian besar pembaca halaman ini. Keduanya dijelaskan di bawah.

Referensi untuk melakukannya di Kunavo — field permintaan, tarif cache setiap model, dan pemeriksaan dengan dua permintaan — adalah dokumentasi prompt caching; halaman ini membahas mengapa cache berhenti menguntungkan.

Mekanismenya secara singkat

Anda menandai awalan yang stabil — system prompt, skema alat, atau dokumen — lalu penyedia menyimpan bentuknya yang telah diproses. Permintaan berikutnya yang awalan-nya persis sama membacanya kembali, bukan memprosesnya ulang.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

Dua sifat melakukan seluruh pekerjaan sekaligus menimbulkan seluruh masalah. Pencocokan dilakukan pada awalan, sehingga apa pun yang berubah di bagian awal membatalkan semua bagian setelahnya. Entri juga memiliki masa berlaku, sehingga percakapan dengan jeda panjang antar-giliran membangun ulang, bukan membaca ulang.

Biayanya

Kolom ketiga adalah rasio standar: pembacaan berbiaya sepersepuluh input. Kolom keempat juga standar — sebuah penulisan cache berbiaya 1,25× input, pengali yang dicantumkan Anthropic untuk entri lima menit — dan karena kedua rasio berlaku pada harga input Kunavo, masing-masing memiliki diskon yang sama dari harga resmi Anthropic seperti input model. Perbedaan Kunavo dari Anthropic adalah entri satu jam: Anthropic mencantumkan penulisan tersebut sebesar 2× input, sedangkan Kunavo menagihnya sebesar 1,25× yang sama. Ini penting khususnya untuk beban kerja yang sering membangun ulang — agent yang berjalan lama, percakapan lambat, apa pun yang awalan-nya sering berubah — karena pada beban kerja tersebut penulisan, bukan pembacaan, mendominasi baris cache pada tagihan.

Kedua angka dibaca dari katalog saat dirender, sumber yang sama yang dibaca tabel harga dan kalkulator Claude — tidak ada tarif yang diketik manual di halaman ini.

Membaca objek penggunaan

Jangan menyimpulkan perilaku cache dari tagihan; setiap respons memberi tahu Anda secara langsung, dan ketiga jumlah token tersebut sudah mencakup seluruh diagnosis.

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

Mengapa rasio hit turun di balik gateway

Cache berada di upstream yang membuatnya, dan pencocokan awalan harus persis. Kedua fakta tersebut bersama-sama menghasilkan tiga mode kegagalan yang tidak pernah terjadi ketika Anda langsung memanggil satu penyedia:

Perutean berpindah. Jika permintaan berturut-turut jatuh ke upstream berbeda, permintaan kedua tidak menemukan cache — entri yang ditulis pertama tidak terlihat dari tempat permintaan kedua berjalan. Ini tidak terlihat di log Anda sendiri dan hanya muncul sebagai jumlah pembuatan cache yang seharusnya merupakan pembacaan. Ini adalah penyebab paling umum, dan itulah alasan gateway yang bebas merutekan ulang antar-upstream dapat lebih murah per token tetapi lebih mahal per sesi.

Sesuatu disisipkan sebelum awalan Anda. Lapisan yang menulis ulang system message, menormalkan definisi alat, atau mengurutkan ulang bidang menghasilkan awalan berbeda, dan awalan berbeda berarti cache miss. Tidak ada kesalahan; tagihan hanya meningkat.

Jeda lebih lama daripada masa berlaku entri. Agent yang berpikir selama beberapa menit di antara giliran dapat membangun ulang setiap kali. Ini adalah sifat beban kerja Anda, bukan gateway, tetapi berinteraksi buruk dengan masalah pertama: pembangunan ulang juga merupakan peluang untuk merutekan ulang.

Diagnosis untuk ketiganya sama — pantau cache_creation_input_tokens sepanjang sesi. Nilai yang datar dan besar berarti Anda membangun ulang. Besar sekali lalu nol setelahnya berarti caching bekerja. Di Kunavo, biaya tingkat permintaan dan jumlah token yang di-cache tersedia di tampilan penggunaan, dan referensi caching memuat detail tingkat endpoint.

Apa yang harus dilakukan

Jaga agar awalan yang di-cache benar-benar stabil — letakkan apa pun yang berubah per permintaan setelah blok yang ditandai, jangan pernah sebelumnya. Jika memungkinkan, kelompokkan giliran agent lebih berdekatan, karena waktu menganggur adalah musuh entri berumur pendek. Ukur sesi dari awal hingga akhir, bukan satu permintaan: caching adalah sifat suatu rangkaian, dan estimasi per permintaan tidak dapat melihatnya. Kalkulator biaya token Claude memiliki bidang token yang di-cache tepat karena alasan ini — atur ke bagian prompt yang benar-benar berulang dan angka bulanan tidak lagi bersifat fiksi.

Pertanyaan umum