Prompt caching
Prompt caching adalah fitur yang mengoptimalkan penggunaan API Anda dengan memungkinkan melanjutkan dari prefiks tertentu dalam prompt Anda.
Prompt caching adalah fitur yang kuat yang mengoptimalkan penggunaan API Anda dengan memungkinkan melanjutkan dari prefiks tertentu dalam prompt Anda. Pendekatan ini secara signifikan mengurangi waktu pemrosesan dan biaya untuk tugas berulang atau prompt dengan elemen yang konsisten.
Berikut adalah contoh cara mengimplementasikan prompt caching dengan Messages API menggunakan blok cache_control
:
Dalam contoh ini, seluruh teks “Pride and Prejudice” di-cache menggunakan parameter cache_control
. Ini memungkinkan penggunaan kembali teks besar ini di beberapa panggilan API tanpa memproses ulang setiap kali. Mengubah hanya pesan pengguna memungkinkan Anda mengajukan berbagai pertanyaan tentang buku sambil memanfaatkan konten yang di-cache, menghasilkan respons yang lebih cepat dan efisiensi yang lebih baik.
Cara kerja prompt caching
Ketika Anda mengirim permintaan dengan prompt caching diaktifkan:
- Sistem memeriksa apakah prefiks prompt, hingga titik breakpoint cache yang ditentukan, sudah di-cache dari kueri terbaru.
- Jika ditemukan, sistem menggunakan versi yang di-cache, mengurangi waktu pemrosesan dan biaya.
- Jika tidak, sistem memproses prompt penuh dan meng-cache prefiks setelah respons dimulai.
Ini sangat berguna untuk:
- Prompt dengan banyak contoh
- Jumlah besar konteks atau informasi latar belakang
- Tugas berulang dengan instruksi yang konsisten
- Percakapan multi-turn yang panjang
Secara default, cache memiliki masa hidup 5 menit. Cache disegarkan tanpa biaya tambahan setiap kali konten yang di-cache digunakan.
Jika Anda merasa 5 menit terlalu singkat, Anthropic juga menawarkan durasi cache 1 jam.
Untuk informasi lebih lanjut, lihat Durasi cache 1 jam.
Prompt caching meng-cache prefiks penuh
Prompt caching mereferensikan seluruh prompt - tools
, system
, dan messages
(dalam urutan tersebut) hingga dan termasuk blok yang ditandai dengan cache_control
.
Harga
Prompt caching memperkenalkan struktur harga baru. Tabel di bawah ini menunjukkan harga per juta token untuk setiap model yang didukung:
Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
---|---|---|---|---|---|
Claude Opus 4.1 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Opus 4 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.7 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.5 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Haiku 3.5 | $0.80 / MTok | $1 / MTok | $1.6 / MTok | $0.08 / MTok | $4 / MTok |
Claude Opus 3 (deprecated) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Haiku 3 | $0.25 / MTok | $0.30 / MTok | $0.50 / MTok | $0.03 / MTok | $1.25 / MTok |
Tabel di atas mencerminkan pengali harga berikut untuk prompt caching:
- Token tulis cache 5 menit adalah 1,25 kali harga token input dasar
- Token tulis cache 1 jam adalah 2 kali harga token input dasar
- Token baca cache adalah 0,1 kali harga token input dasar
Cara mengimplementasikan prompt caching
Model yang didukung
Prompt caching saat ini didukung pada:
- Claude Opus 4.1
- Claude Opus 4
- Claude Sonnet 4
- Claude Sonnet 3.7
- Claude Sonnet 3.5 (deprecated)
- Claude Haiku 3.5
- Claude Haiku 3
- Claude Opus 3 (deprecated)
Menyusun prompt Anda
Tempatkan konten statis (definisi tool, instruksi sistem, konteks, contoh) di awal prompt Anda. Tandai akhir konten yang dapat digunakan kembali untuk caching menggunakan parameter cache_control
.
Prefiks cache dibuat dalam urutan berikut: tools
, system
, kemudian messages
. Urutan ini membentuk hierarki di mana setiap level dibangun berdasarkan level sebelumnya.
Cara kerja pemeriksaan prefiks otomatis
Anda dapat menggunakan hanya satu breakpoint cache di akhir konten statis Anda, dan sistem akan secara otomatis menemukan prefiks yang cocok terpanjang. Begini cara kerjanya:
- Ketika Anda menambahkan breakpoint
cache_control
, sistem secara otomatis memeriksa cache hit di semua batas blok konten sebelumnya (hingga sekitar 20 blok sebelum breakpoint eksplisit Anda) - Jika ada dari posisi sebelumnya ini cocok dengan konten yang di-cache dari permintaan sebelumnya, sistem menggunakan prefiks yang cocok terpanjang
- Ini berarti Anda tidak perlu beberapa breakpoint hanya untuk mengaktifkan caching - satu di akhir sudah cukup
Kapan menggunakan beberapa breakpoint
Anda dapat mendefinisikan hingga 4 breakpoint cache jika Anda ingin:
- Meng-cache bagian berbeda yang berubah pada frekuensi berbeda (misalnya, tools jarang berubah, tetapi konteks diperbarui setiap hari)
- Memiliki kontrol lebih atas apa yang di-cache
- Memastikan caching untuk konten lebih dari 20 blok sebelum breakpoint terakhir Anda
Keterbatasan penting: Pemeriksaan prefiks otomatis hanya melihat kembali sekitar 20 blok konten dari setiap breakpoint eksplisit. Jika prompt Anda memiliki lebih dari 20 blok konten sebelum breakpoint cache Anda, konten yang lebih awal dari itu tidak akan diperiksa untuk cache hit kecuali Anda menambahkan breakpoint tambahan.
Keterbatasan cache
Panjang prompt minimum yang dapat di-cache adalah:
- 1024 token untuk Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (deprecated) dan Claude Opus 3 (deprecated)
- 2048 token untuk Claude Haiku 3.5 dan Claude Haiku 3
Prompt yang lebih pendek tidak dapat di-cache, bahkan jika ditandai dengan cache_control
. Setiap permintaan untuk meng-cache lebih sedikit dari jumlah token ini akan diproses tanpa caching. Untuk melihat apakah prompt di-cache, lihat fields penggunaan respons.
Untuk permintaan bersamaan, perhatikan bahwa entri cache hanya tersedia setelah respons pertama dimulai. Jika Anda memerlukan cache hit untuk permintaan paralel, tunggu respons pertama sebelum mengirim permintaan berikutnya.
Saat ini, “ephemeral” adalah satu-satunya jenis cache yang didukung, yang secara default memiliki masa hidup 5 menit.
Memahami biaya breakpoint cache
Breakpoint cache itu sendiri tidak menambah biaya apa pun. Anda hanya dikenakan biaya untuk:
- Penulisan cache: Ketika konten baru ditulis ke cache (25% lebih dari token input dasar untuk TTL 5 menit)
- Pembacaan cache: Ketika konten yang di-cache digunakan (10% dari harga token input dasar)
- Token input reguler: Untuk konten yang tidak di-cache
Menambahkan lebih banyak breakpoint cache_control
tidak meningkatkan biaya Anda - Anda tetap membayar jumlah yang sama berdasarkan konten apa yang benar-benar di-cache dan dibaca. Breakpoint hanya memberi Anda kontrol atas bagian mana yang dapat di-cache secara independen.
Apa yang dapat di-cache
Sebagian besar blok dalam permintaan dapat ditandai untuk caching dengan cache_control
. Ini termasuk:
- Tools: Definisi tool dalam array
tools
- Pesan sistem: Blok konten dalam array
system
- Pesan teks: Blok konten dalam array
messages.content
, untuk turn pengguna dan asisten - Gambar & Dokumen: Blok konten dalam array
messages.content
, dalam turn pengguna - Penggunaan tool dan hasil tool: Blok konten dalam array
messages.content
, dalam turn pengguna dan asisten
Setiap elemen ini dapat ditandai dengan cache_control
untuk mengaktifkan caching untuk bagian permintaan tersebut.
Apa yang tidak dapat di-cache
Meskipun sebagian besar blok permintaan dapat di-cache, ada beberapa pengecualian:
-
Blok thinking tidak dapat di-cache secara langsung dengan
cache_control
. Namun, blok thinking DAPAT di-cache bersama konten lain ketika muncul dalam turn asisten sebelumnya. Ketika di-cache dengan cara ini, mereka DIHITUNG sebagai token input ketika dibaca dari cache. -
Sub-blok konten (seperti citations) sendiri tidak dapat di-cache secara langsung. Sebaliknya, cache blok tingkat atas.
Dalam kasus citations, blok konten dokumen tingkat atas yang berfungsi sebagai materi sumber untuk citations dapat di-cache. Ini memungkinkan Anda menggunakan prompt caching dengan citations secara efektif dengan meng-cache dokumen yang akan direferensikan oleh citations.
-
Blok teks kosong tidak dapat di-cache.
Apa yang membatalkan cache
Modifikasi pada konten yang di-cache dapat membatalkan sebagian atau seluruh cache.
Seperti dijelaskan dalam Menyusun prompt Anda, cache mengikuti hierarki: tools
→ system
→ messages
. Perubahan di setiap level membatalkan level tersebut dan semua level berikutnya.
Tabel berikut menunjukkan bagian cache mana yang dibatalkan oleh berbagai jenis perubahan. ✘ menunjukkan bahwa cache dibatalkan, sedangkan ✓ menunjukkan bahwa cache tetap valid.
Apa yang berubah | Cache tools | Cache system | Cache messages | Dampak |
---|---|---|---|---|
Definisi tool | ✘ | ✘ | ✘ | Memodifikasi definisi tool (nama, deskripsi, parameter) membatalkan seluruh cache |
Toggle pencarian web | ✓ | ✘ | ✘ | Mengaktifkan/menonaktifkan pencarian web memodifikasi prompt sistem |
Toggle citations | ✓ | ✘ | ✘ | Mengaktifkan/menonaktifkan citations memodifikasi prompt sistem |
Pilihan tool | ✓ | ✓ | ✘ | Perubahan pada parameter tool_choice hanya mempengaruhi blok pesan |
Gambar | ✓ | ✓ | ✘ | Menambah/menghapus gambar di mana pun dalam prompt mempengaruhi blok pesan |
Parameter thinking | ✓ | ✓ | ✘ | Perubahan pada pengaturan extended thinking (aktif/nonaktif, anggaran) mempengaruhi blok pesan |
Hasil non-tool yang diteruskan ke permintaan extended thinking | ✓ | ✓ | ✘ | Ketika hasil non-tool diteruskan dalam permintaan saat extended thinking diaktifkan, semua blok thinking yang sebelumnya di-cache dihapus dari konteks, dan pesan apa pun dalam konteks yang mengikuti blok thinking tersebut dihapus dari cache. Untuk detail lebih lanjut, lihat Caching dengan blok thinking. |
Melacak performa cache
Pantau performa cache menggunakan field respons API ini, dalam usage
di respons (atau event message_start
jika streaming):
cache_creation_input_tokens
: Jumlah token yang ditulis ke cache saat membuat entri baru.cache_read_input_tokens
: Jumlah token yang diambil dari cache untuk permintaan ini.input_tokens
: Jumlah token input yang tidak dibaca dari atau digunakan untuk membuat cache.
Praktik terbaik untuk caching yang efektif
Untuk mengoptimalkan performa prompt caching:
- Cache konten yang stabil dan dapat digunakan kembali seperti instruksi sistem, informasi latar belakang, konteks besar, atau definisi tool yang sering digunakan.
- Tempatkan konten yang di-cache di awal prompt untuk performa terbaik.
- Gunakan breakpoint cache secara strategis untuk memisahkan bagian prefiks yang dapat di-cache berbeda.
- Analisis tingkat cache hit secara teratur dan sesuaikan strategi Anda sesuai kebutuhan.
Mengoptimalkan untuk kasus penggunaan berbeda
Sesuaikan strategi prompt caching Anda dengan skenario Anda:
- Agen percakapan: Kurangi biaya dan latensi untuk percakapan yang diperpanjang, terutama yang memiliki instruksi panjang atau dokumen yang diunggah.
- Asisten coding: Tingkatkan autocomplete dan Q&A codebase dengan menjaga bagian yang relevan atau versi ringkasan codebase dalam prompt.
- Pemrosesan dokumen besar: Sertakan materi bentuk panjang lengkap termasuk gambar dalam prompt Anda tanpa meningkatkan latensi respons.
- Set instruksi terperinci: Bagikan daftar instruksi, prosedur, dan contoh yang ekstensif untuk menyetel respons Claude. Developer sering menyertakan satu atau dua contoh dalam prompt, tetapi dengan prompt caching Anda bisa mendapatkan performa yang lebih baik dengan menyertakan 20+ contoh beragam jawaban berkualitas tinggi.
- Penggunaan tool agentic: Tingkatkan performa untuk skenario yang melibatkan beberapa panggilan tool dan perubahan kode iteratif, di mana setiap langkah biasanya memerlukan panggilan API baru.
- Berbicara dengan buku, makalah, dokumentasi, transkrip podcast, dan konten bentuk panjang lainnya: Hidupkan basis pengetahuan apa pun dengan menyematkan seluruh dokumen ke dalam prompt, dan biarkan pengguna mengajukan pertanyaan.
Mengatasi masalah umum
Jika mengalami perilaku yang tidak terduga:
- Pastikan bagian yang di-cache identik dan ditandai dengan cache_control di lokasi yang sama di seluruh panggilan
- Periksa bahwa panggilan dibuat dalam masa hidup cache (5 menit secara default)
- Verifikasi bahwa
tool_choice
dan penggunaan gambar tetap konsisten antar panggilan - Validasi bahwa Anda meng-cache setidaknya jumlah token minimum
- Sistem secara otomatis memeriksa cache hit di batas blok konten sebelumnya (hingga ~20 blok sebelum breakpoint Anda). Untuk prompt dengan lebih dari 20 blok konten, Anda mungkin perlu parameter
cache_control
tambahan lebih awal dalam prompt untuk memastikan semua konten dapat di-cache
Perubahan pada tool_choice
atau keberadaan/ketidakberadaan gambar di mana pun dalam prompt akan membatalkan cache, memerlukan entri cache baru untuk dibuat. Untuk detail lebih lanjut tentang pembatalan cache, lihat Apa yang membatalkan cache.
Caching dengan blok thinking
Ketika menggunakan extended thinking dengan prompt caching, blok thinking memiliki perilaku khusus:
Caching otomatis bersama konten lain: Meskipun blok thinking tidak dapat secara eksplisit ditandai dengan cache_control
, mereka di-cache sebagai bagian dari konten permintaan ketika Anda membuat panggilan API berikutnya dengan hasil tool. Ini biasanya terjadi selama penggunaan tool ketika Anda meneruskan blok thinking kembali untuk melanjutkan percakapan.
Penghitungan token input: Ketika blok thinking dibaca dari cache, mereka dihitung sebagai token input dalam metrik penggunaan Anda. Ini penting untuk perhitungan biaya dan penganggaran token.
Pola pembatalan cache:
- Cache tetap valid ketika hanya hasil tool yang disediakan sebagai pesan pengguna
- Cache dibatalkan ketika konten pengguna non-tool-result ditambahkan, menyebabkan semua blok thinking sebelumnya dihapus
- Perilaku caching ini terjadi bahkan tanpa penanda
cache_control
eksplisit
Untuk detail lebih lanjut tentang pembatalan cache, lihat Apa yang membatalkan cache.
Contoh dengan penggunaan tool:
Ketika blok pengguna non-tool-result disertakan, itu menandai loop asisten baru dan semua blok thinking sebelumnya dihapus dari konteks.
Untuk informasi lebih detail, lihat dokumentasi extended thinking.
Penyimpanan dan berbagi cache
-
Isolasi Organisasi: Cache diisolasi antar organisasi. Organisasi yang berbeda tidak pernah berbagi cache, bahkan jika mereka menggunakan prompt yang identik.
-
Pencocokan Tepat: Cache hit memerlukan segmen prompt yang 100% identik, termasuk semua teks dan gambar hingga dan termasuk blok yang ditandai dengan kontrol cache.
-
Generasi Token Output: Prompt caching tidak berpengaruh pada generasi token output. Respons yang Anda terima akan identik dengan yang akan Anda dapatkan jika prompt caching tidak digunakan.
Durasi cache 1 jam
Jika Anda merasa 5 menit terlalu singkat, Anthropic juga menawarkan durasi cache 1 jam.
Untuk menggunakan cache yang diperpanjang, sertakan ttl
dalam definisi cache_control
seperti ini:
Respons akan mencakup informasi cache terperinci seperti berikut:
Perhatikan bahwa field cache_creation_input_tokens
saat ini sama dengan jumlah nilai dalam objek cache_creation
.
Kapan menggunakan cache 1 jam
Jika Anda memiliki prompt yang digunakan pada irama reguler (yaitu, prompt sistem yang digunakan lebih sering daripada setiap 5 menit), lanjutkan menggunakan cache 5 menit, karena ini akan terus disegarkan tanpa biaya tambahan.
Cache 1 jam paling baik digunakan dalam skenario berikut:
- Ketika Anda memiliki prompt yang kemungkinan digunakan kurang sering dari 5 menit, tetapi lebih sering dari setiap jam. Misalnya, ketika agen samping agentic akan memakan waktu lebih dari 5 menit, atau ketika menyimpan percakapan chat panjang dengan pengguna dan Anda umumnya mengharapkan pengguna tersebut mungkin tidak merespons dalam 5 menit ke depan.
- Ketika latensi penting dan prompt lanjutan Anda mungkin dikirim lebih dari 5 menit.
- Ketika Anda ingin meningkatkan pemanfaatan batas tarif Anda, karena cache hit tidak dikurangkan dari batas tarif Anda.
Cache 5 menit dan 1 jam berperilaku sama dalam hal latensi. Anda umumnya akan melihat peningkatan time-to-first-token untuk dokumen panjang.
Mencampur TTL yang berbeda
Anda dapat menggunakan kontrol cache 1 jam dan 5 menit dalam permintaan yang sama, tetapi dengan batasan penting: Entri cache dengan TTL yang lebih panjang harus muncul sebelum TTL yang lebih pendek (yaitu, entri cache 1 jam harus muncul sebelum entri cache 5 menit apa pun).
Ketika mencampur TTL, kami menentukan tiga lokasi penagihan dalam prompt Anda:
- Posisi
A
: Jumlah token pada cache hit tertinggi (atau 0 jika tidak ada hit). - Posisi
B
: Jumlah token pada blokcache_control
1 jam tertinggi setelahA
(atau sama denganA
jika tidak ada). - Posisi
C
: Jumlah token pada blokcache_control
terakhir.
Jika B
dan/atau C
lebih besar dari A
, mereka tentu akan menjadi cache miss, karena A
adalah cache hit tertinggi.
Anda akan dikenakan biaya untuk:
- Token baca cache untuk
A
. - Token tulis cache 1 jam untuk
(B - A)
. - Token tulis cache 5 menit untuk
(C - B)
.
Berikut adalah 3 contoh. Ini menggambarkan token input dari 3 permintaan, masing-masing memiliki cache hit dan cache miss yang berbeda. Masing-masing memiliki perhitungan harga yang berbeda, ditunjukkan dalam kotak berwarna, sebagai hasilnya.
Contoh prompt caching
Untuk membantu Anda memulai dengan prompt caching, kami telah menyiapkan cookbook prompt caching dengan contoh terperinci dan praktik terbaik.
Di bawah ini, kami telah menyertakan beberapa cuplikan kode yang menampilkan berbagai pola prompt caching. Contoh-contoh ini mendemonstrasikan cara mengimplementasikan caching dalam skenario yang berbeda, membantu Anda memahami aplikasi praktis dari fitur ini: