Caching prompt
Cache prefiks prompt dengan cache_control untuk memangkas biaya dan latensi, menggunakan caching otomatis atau breakpoint eksplisit dengan TTL 5 menit atau 1 jam.
Penggunaan berbeda menurut produk
cache_control, di level teratas atau pada blok.“Prompt caching” (caching prompt) mengoptimalkan penggunaan API Anda dengan memungkinkan API melanjutkan dari prefiks tertentu dalam prompt Anda. Ini secara signifikan mengurangi waktu pemrosesan dan biaya untuk tugas berulang atau prompt dengan elemen yang konsisten.
Ada dua cara untuk mengaktifkan caching prompt:
- Caching otomatis: Tambahkan satu field
cache_controldi tingkat teratas permintaan Anda. Sistem secara otomatis menerapkan “cache breakpoint” (titik henti cache) ke blok terakhir yang dapat di-cache dan memindahkannya maju seiring percakapan bertambah. Paling cocok untuk percakapan multi-giliran di mana riwayat pesan yang terus bertambah harus di-cache secara otomatis. - Cache breakpoint eksplisit: Tempatkan
cache_controllangsung pada blok konten individual untuk kontrol yang lebih rinci atas apa saja yang di-cache.
Salah satu cara untuk memulai adalah dengan caching otomatis:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages=[
{
"role": "user",
"content": "Analyze the major themes in 'Pride and Prejudice'.",
}
],
)
print(response.usage.model_dump_json())Dengan caching otomatis, sistem meng-cache semua konten hingga dan termasuk blok terakhir yang dapat di-cache. Pada permintaan berikutnya dengan prefiks yang sama, konten yang di-cache digunakan kembali secara otomatis.
Cara kerja caching prompt
Saat Anda mengirim permintaan dengan caching prompt diaktifkan:
- Sistem memeriksa apakah prefiks prompt, hingga breakpoint cache yang ditentukan, sudah di-cache dari kueri terbaru.
- Jika ditemukan, sistem menggunakan versi yang di-cache, sehingga mengurangi waktu pemrosesan dan biaya.
- Jika tidak, sistem memproses prompt lengkap dan meng-cache prefiks setelah respons dimulai.
Ini sangat berguna untuk:
- Prompt dengan banyak contoh
- Konteks atau informasi latar belakang dalam jumlah besar
- Tugas berulang dengan instruksi yang konsisten
- Percakapan multi-giliran yang panjang
Secara default, cache memiliki masa hidup 5 menit. Cache diperbarui tanpa biaya tambahan setiap kali konten yang di-cache digunakan.
Masa hidup diukur sejak awal permintaan yang menulis atau membaca entri cache, bukan sejak akhir responsnya. Waktu yang dihabiskan untuk menghasilkan respons dihitung terhadap masa hidup: jika respons membutuhkan 4 menit untuk di-stream, permintaan lanjutan yang menggunakan kembali prefiks yang di-cache yang sama harus dimulai dalam waktu sekitar 1 menit setelah respons tersebut selesai.
Jika 5 menit terlalu singkat, Anda dapat menggunakan durasi cache 1 jam dengan biaya tambahan (lihat Harga).
Caching prompt mencakup seluruh prefiks: tools, system, dan messages (dalam urutan tersebut), hingga dan termasuk blok yang ditandai dengan cache_control.
Harga
Caching prompt memiliki harganya sendiri. Tabel berikut menunjukkan harga per juta token untuk setiap model yang didukung:
| Model | Token dasar | Caching prompt | |||
|---|---|---|---|---|---|
| Nama | Input | Output | Penulisan 5 mnt | Penulisan 1 jam | Hit dan penyegaran |
Claude Fable 5.2For demanding reasoning and long-horizon agentic work | US$8 / MTok | US$40 / MTok | US$10 / MTok | US$16 / MTok | US$0,20 / MTok1 |
Claude Opus 5.5For long-running agentic coding and knowledge work | US$4 / MTok | US$20 / MTok | US$5 / MTok | US$8 / MTok | US$0,20 / MTok2 |
Claude Sonnet 5.5The best combination of speed and intelligence | US$2 / MTok | US$10 / MTok | US$2,50 / MTok | US$4 / MTok | US$0,10 / MTok2 |
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing | US$0,10 / MTokuntuk prompt hingga 100.000 token | US$0,50 / MTok | US$0,125 / MTok | US$0,20 / MTok | US$0,01 / MTok |
US$0,50 / MTokuntuk prompt di atas 100.000 token | US$2,50 / MTok | US$0,625 / MTok | US$1 / MTok | US$0,05 / MTok | |
US$8 / MTok | US$40 / MTok | US$10 / MTok | US$16 / MTok | US$0,20 / MTok1 | |
US$10 / MTok | US$50 / MTok | US$12,50 / MTok | US$20 / MTok | US$0,25 / MTok1 | |
US$10 / MTok | US$50 / MTok | US$12,50 / MTok | US$20 / MTok | US$0,25 / MTok1 | |
US$10 / MTok | US$50 / MTok | US$12,50 / MTok | US$20 / MTok | US$1 / MTok | |
US$10 / MTok | US$50 / MTok | US$12,50 / MTok | US$20 / MTok | US$1 / MTok | |
US$5 / MTok | US$25 / MTok | US$6,25 / MTok | US$10 / MTok | US$0,50 / MTok | |
US$5 / MTok | US$25 / MTok | US$6,25 / MTok | US$10 / MTok | US$0,50 / MTok | |
US$5 / MTok | US$25 / MTok | US$6,25 / MTok | US$10 / MTok | US$0,50 / MTok | |
US$5 / MTok | US$25 / MTok | US$6,25 / MTok | US$10 / MTok | US$0,50 / MTok | |
US$5 / MTok | US$25 / MTok | US$6,25 / MTok | US$10 / MTok | US$0,50 / MTok | |
Claude Opus 4.1 | US$15 / MTok | US$75 / MTok | US$18,75 / MTok | US$30 / MTok | US$1,50 / MTok |
Claude Opus 4 | US$15 / MTok | US$75 / MTok | US$18,75 / MTok | US$30 / MTok | US$1,50 / MTok |
US$2 / MTok | US$10 / MTok | US$2,50 / MTok | US$4 / MTok | US$0,20 / MTok | |
US$3 / MTok | US$15 / MTok | US$3,75 / MTok | US$6 / MTok | US$0,30 / MTok | |
US$3 / MTok | US$15 / MTok | US$3,75 / MTok | US$6 / MTok | US$0,30 / MTok | |
Claude Sonnet 4 | US$3 / MTok | US$15 / MTok | US$3,75 / MTok | US$6 / MTok | US$0,30 / MTok |
US$1 / MTok | US$5 / MTok | US$1,25 / MTok | US$2 / MTok | US$0,10 / MTok | |
1 Cache hit dan penyegaran cache pada Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, dan Claude Mythos 5.1 dikenakan harga 0,025x harga input dasar.
2 Cache hit dan penyegaran cache pada Claude Opus 5.5 dan Claude Sonnet 5.5 dikenakan harga 0,05x harga input dasar.
Semua model lainnya menggunakan pengali standar 0,1x.
Model yang didukung
Caching prompt (baik otomatis maupun eksplisit) didukung pada semua model Claude yang aktif.
Caching otomatis
Caching otomatis mengaktifkan caching prompt dengan satu field. Alih-alih menempatkan cache_control pada blok konten individual, tambahkan satu field cache_control di tingkat teratas body permintaan Anda. Sistem secara otomatis menerapkan breakpoint cache ke blok terakhir yang dapat di-cache.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are a helpful assistant that remembers our conversation.",
messages=[
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{
"role": "assistant",
"content": "Nice to meet you, Alex! How can I help with your ML work today?",
},
{"role": "user", "content": "What did I say I work on?"},
],
)
print(response.usage.model_dump_json())Cara kerja caching otomatis dalam percakapan multi-giliran
Dengan caching otomatis, titik cache bergerak maju secara otomatis seiring percakapan bertambah. Setiap permintaan baru meng-cache semuanya hingga blok terakhir yang dapat di-cache, dan konten sebelumnya dibaca dari cache.
| Permintaan | Konten | Perilaku cache |
|---|---|---|
| Permintaan 1 | System + User(1) + Asst(1) + User(2) ◀ cache | Semuanya ditulis ke cache |
| Permintaan 2 | System + User(1) + Asst(1) + User(2) + Asst(2) + User(3) ◀ cache | System hingga User(2) dibaca dari cache; Asst(2) + User(3) ditulis ke cache |
| Permintaan 3 | System + User(1) + Asst(1) + User(2) + Asst(2) + User(3) + Asst(3) + User(4) ◀ cache | System hingga User(3) dibaca dari cache; Asst(3) + User(4) ditulis ke cache |
Breakpoint cache secara otomatis berpindah ke blok terakhir yang dapat di-cache dalam setiap permintaan, sehingga Anda tidak perlu memperbarui penanda cache_control apa pun seiring percakapan bertambah.
Dukungan TTL
Secara default, caching otomatis menggunakan TTL 5 menit. Anda dapat menentukan TTL 1 jam dengan harga 2x harga token input dasar:
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }Menggabungkan dengan caching tingkat blok
Caching otomatis kompatibel dengan breakpoint cache eksplisit. Saat digunakan bersama, breakpoint cache otomatis menggunakan salah satu dari 4 slot breakpoint yang tersedia.
Ini memungkinkan Anda menggabungkan kedua pendekatan. Misalnya, gunakan breakpoint eksplisit untuk meng-cache prompt sistem Anda, sementara caching otomatis menangani percakapan:
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": { "type": "ephemeral" },
"system": [
{
"type": "text",
"text": "You are a helpful assistant.",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What are the key terms?" }]
}Apa yang tetap sama
Caching otomatis menggunakan infrastruktur caching dasar yang sama. Harga, ambang batas token minimum, persyaratan urutan konteks, dan jendela lookback 20 blok semuanya berlaku sama seperti pada breakpoint eksplisit.
Kasus tepi
- Jika blok terakhir sudah memiliki
cache_controleksplisit dengan TTL yang sama, caching otomatis tidak melakukan apa-apa. - Jika blok terakhir memiliki
cache_controleksplisit dengan TTL yang berbeda, API mengembalikan error 400. - Jika sudah ada 4 breakpoint tingkat blok eksplisit, API mengembalikan error 400 (tidak ada slot tersisa untuk caching otomatis).
- Jika blok terakhir tidak memenuhi syarat sebagai target breakpoint cache otomatis, sistem secara diam-diam berjalan mundur untuk menemukan blok terdekat yang memenuhi syarat. Jika tidak ada yang ditemukan, caching dilewati.
Cache breakpoint eksplisit
Untuk kontrol lebih atas caching, Anda dapat menempatkan cache_control langsung pada blok konten individual. Ini berguna saat Anda perlu meng-cache bagian berbeda yang berubah dengan frekuensi berbeda, atau memerlukan kontrol rinci atas apa saja yang di-cache.
Menyusun prompt Anda
Tempatkan konten statis (definisi alat, 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, lalu messages. Urutan ini membentuk hierarki di mana setiap tingkat dibangun di atas tingkat sebelumnya.
Cara kerja pemeriksaan prefiks otomatis
Anda dapat menggunakan hanya satu breakpoint cache di akhir konten statis Anda, dan sistem secara otomatis menemukan prefiks terpanjang yang sudah ditulis ke cache oleh permintaan sebelumnya. Memahami cara kerjanya membantu Anda mengoptimalkan strategi caching Anda.
Tiga prinsip inti:
-
Penulisan cache hanya terjadi di breakpoint Anda. Menandai blok dengan
cache_controlmenulis tepat satu entri cache: hash dari prefiks yang berakhir di blok tersebut. Sistem tidak menulis entri untuk posisi yang lebih awal. Karena hash bersifat kumulatif, mencakup semuanya hingga dan termasuk breakpoint, mengubah blok apa pun di atau sebelum breakpoint menghasilkan hash yang berbeda pada permintaan berikutnya. -
Pembacaan cache melihat ke belakang untuk entri yang ditulis oleh permintaan sebelumnya. Pada setiap permintaan, sistem menghitung hash prefiks di breakpoint Anda dan memeriksa entri cache yang cocok. Jika tidak ada, sistem berjalan mundur satu blok pada satu waktu, memeriksa apakah hash prefiks di setiap posisi sebelumnya cocok dengan sesuatu yang sudah ada di cache. Sistem mencari penulisan sebelumnya, bukan konten yang stabil.
-
Jendela lookback adalah 20 blok. Sistem memeriksa paling banyak 20 posisi untuk setiap breakpoint, dengan menghitung breakpoint itu sendiri sebagai yang pertama. Jika sistem tidak menemukan entri yang cocok dalam jendela tersebut, pemeriksaan berhenti (atau dilanjutkan dari breakpoint eksplisit berikutnya, jika ada). Pada Claude API, rangkaian blok
tool_useberturut-turut dihitung sebagai satu posisi, begitu juga rangkaian bloktool_resultberturut-turut, sehingga giliran dengan banyak panggilan alat paralel tidak dengan sendirinya mendorong entri permintaan sebelumnya keluar dari jendela.
Contoh: Lookback dalam percakapan yang terus bertambah
Anda menambahkan blok baru setiap giliran dan mengatur cache_control pada blok terakhir setiap permintaan:
- Giliran 1: 10 blok, breakpoint pada blok 10. Belum ada entri cache sebelumnya. Sistem menulis entri di blok 10.
- Giliran 2: 15 blok, breakpoint pada blok 15. Blok 15 tidak memiliki entri, sehingga sistem berjalan mundur ke blok 10 dan menemukan entri giliran 1. Cache hit di blok 10. Sistem hanya memproses blok 11 hingga 15 dari awal dan menulis entri baru di blok 15.
- Giliran 3: 35 blok, breakpoint pada blok 35. Sistem memeriksa 20 posisi (blok 35 hingga 16) dan tidak menemukan apa pun. Entri giliran 2 di blok 15 berada satu posisi di luar jendela, sehingga tidak ada cache hit. Menambahkan breakpoint kedua di blok 15 memulai jendela lookback kedua di sana, yang menemukan entri giliran 2.
Kesalahan umum: Breakpoint pada konten yang berubah setiap permintaan
Prompt Anda memiliki konteks sistem statis yang besar (blok 1 hingga 5) diikuti oleh blok per permintaan yang berisi timestamp dan pesan pengguna (blok 6). Anda mengatur cache_control pada blok 6:
- Permintaan 1: Penulisan cache di blok 6. Hash mencakup timestamp.
- Permintaan 2: Timestamp berbeda, sehingga hash prefiks di blok 6 berbeda. Lookback berjalan melalui blok 5, 4, 3, 2, dan 1, tetapi sistem tidak pernah menulis entri di posisi mana pun tersebut. Tidak ada cache hit. Anda membayar penulisan cache baru pada setiap permintaan dan tidak pernah mendapatkan pembacaan.
Lookback tidak menemukan konten stabil di belakang breakpoint Anda lalu meng-cache-nya. Lookback menemukan entri yang sudah ditulis oleh permintaan sebelumnya, dan penulisan hanya terjadi di breakpoint. Pindahkan cache_control ke blok 5, blok terakhir yang tetap sama di seluruh permintaan, dan setiap permintaan berikutnya membaca prefiks yang di-cache. Caching otomatis memiliki masalah yang sama: caching otomatis menempatkan breakpoint pada blok terakhir yang dapat di-cache, yang dalam struktur ini adalah blok yang berubah setiap permintaan, jadi gunakan breakpoint eksplisit pada blok 5 sebagai gantinya.
Poin penting: Tempatkan cache_control pada blok terakhir yang prefiksnya identik di seluruh permintaan yang ingin Anda bagikan cache-nya. Dalam percakapan yang terus bertambah, blok terakhir berfungsi selama setiap giliran menambahkan kurang dari 20 blok: konten sebelumnya tidak pernah berubah, sehingga lookback permintaan berikutnya menemukan penulisan sebelumnya. Untuk prompt dengan sufiks yang bervariasi (timestamp, konteks per permintaan, pesan yang masuk), tempatkan breakpoint di akhir prefiks statis, bukan pada blok yang bervariasi.
Kapan menggunakan beberapa breakpoint
Anda dapat menentukan hingga 4 cache breakpoint jika Anda ingin:
- Meng-cache bagian berbeda yang berubah dengan frekuensi berbeda (misalnya, alat jarang berubah, tetapi konteks diperbarui setiap hari)
- Memiliki kontrol lebih atas apa saja yang di-cache
- Memastikan cache hit ketika percakapan yang terus bertambah mendorong breakpoint Anda 20 blok atau lebih melewati penulisan cache terakhir
Memahami biaya breakpoint cache
Cache breakpoint itu sendiri tidak menambah biaya apa pun. Anda hanya dikenakan biaya untuk:
- Penulisan cache: Saat konten baru ditulis ke cache (25 persen lebih mahal dari token input dasar untuk TTL 5 menit)
- Pembacaan cache: Saat konten yang di-cache digunakan (10 persen dari harga token input dasar, dengan pengecualian per model)
- Token input reguler: Untuk konten apa pun 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 memberi Anda kontrol atas bagian mana yang dapat di-cache secara independen.
Strategi dan pertimbangan caching
Batasan cache
Pada Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Google managed), dan Microsoft Foundry, panjang prompt minimum yang dapat di-cache adalah:
- 512 token untuk Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, Claude Mythos 5, dan Claude Haiku 5.5
- 2.048 token untuk Claude Mythos Preview dan Claude Opus 4.7
- 4.096 token untuk Claude Opus 4.6 dan Claude Opus 4.5
- 1.024 token untuk Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 (tidak digunakan lagi), Claude Opus 4.1 (dihentikan, kecuali di Claude Models on Google Cloud (Google managed) dan Bedrock), Claude Opus 4 (dihentikan, kecuali di Claude Models on Google Cloud (Google managed)), dan Claude Sonnet 4 (dihentikan, kecuali di Claude Models on Google Cloud (Google managed) dan Bedrock)
- 4.096 token untuk Claude Haiku 4.5
Batas minimum ini berlaku di masing-masing platform tersebut tempat model tersedia.
Prompt yang lebih pendek tidak dapat di-cache, bahkan jika ditandai dengan cache_control. Setiap permintaan untuk meng-cache kurang dari jumlah token ini diproses tanpa caching, dan tidak ada error yang dikembalikan. Untuk memeriksa apakah prompt di-cache, lihat field usage respons: jika cache_creation_input_tokens dan cache_read_input_tokens keduanya 0, prompt tidak di-cache (kemungkinan karena tidak memenuhi persyaratan panjang minimum).
Jika prompt Anda sedikit kurang dari batas minimum untuk model dan platform Anda, memperluas konten yang di-cache untuk mencapai ambang batas sering kali sepadan. Pembacaan cache jauh lebih murah daripada token input yang tidak di-cache, sehingga mencapai batas minimum dapat mengurangi biaya untuk prompt yang sering digunakan kembali.
Untuk permintaan bersamaan, perhatikan bahwa entri cache baru tersedia setelah respons pertama dimulai. Jika Anda memerlukan cache hit untuk permintaan paralel, tunggu respons pertama sebelum mengirim permintaan berikutnya.
ephemeral adalah satu-satunya jenis cache yang didukung, yang secara default memiliki masa hidup 5 menit.
Apa yang dapat di-cache
Sebagian besar blok dalam permintaan dapat di-cache. Ini termasuk:
- Alat: Definisi alat dalam array
tools - Pesan sistem: Blok konten dalam array
system - Pesan teks: Blok konten dalam array
messages.content, untuk giliran pengguna maupun asisten - Gambar dan dokumen: Blok konten dalam array
messages.content, pada giliran pengguna - Penggunaan alat dan hasil alat: Blok konten dalam array
messages.content, pada giliran pengguna maupun asisten
Setiap elemen ini dapat di-cache, baik secara otomatis atau dengan menandainya menggunakan cache_control.
Apa yang tidak dapat di-cache
Meskipun sebagian besar blok permintaan dapat di-cache, ada beberapa pengecualian:
-
Blok pemikiran tidak dapat di-cache secara langsung dengan
cache_control. Namun, blok pemikiran DAPAT di-cache bersama konten lain ketika muncul di giliran asisten sebelumnya. Saat di-cache dengan cara ini, blok tersebut DIHITUNG sebagai token input saat dibaca dari cache. -
Blok sub-konten (seperti kutipan) itu sendiri tidak dapat di-cache secara langsung. Sebagai gantinya, cache blok tingkat teratas.
Dalam kasus kutipan, blok konten dokumen tingkat teratas yang berfungsi sebagai bahan sumber untuk kutipan dapat di-cache. Ini memungkinkan Anda menggunakan caching prompt dengan kutipan secara efektif dengan meng-cache dokumen yang dirujuk oleh kutipan.
-
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 tingkat membatalkan tingkat tersebut dan semua tingkat 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 alat | Cache sistem | Cache pesan | Dampak |
|---|---|---|---|---|
| Definisi alat | ✘ | ✘ | ✘ | Memodifikasi definisi alat (nama, deskripsi, parameter) membatalkan seluruh cache |
| Toggle pencarian web | ✓ | ✘ | ✘ | Mengaktifkan/menonaktifkan pencarian web memodifikasi prompt sistem |
| Toggle kutipan | ✓ | ✘ | ✘ | Mengaktifkan/menonaktifkan kutipan memodifikasi prompt sistem |
| Pengaturan kecepatan | ✓ | ✘ | ✘ | Beralih antara speed: "fast" dan kecepatan standar membatalkan cache sistem dan pesan |
| Pilihan alat | ✓ | ✓ | ✘ | Perubahan pada parameter tool_choice hanya memengaruhi blok pesan |
| Gambar | ✓ | ✓ | ✘ | Menambahkan/menghapus gambar di mana pun dalam prompt memengaruhi blok pesan |
| Parameter pemikiran | Spesifik model | Spesifik model | ✘ | Konfigurasi pemikiran (mode, dan budget_tokens dalam mode diperpanjang) dirender ke dalam prompt, sehingga mengubahnya selalu membatalkan blok pesan; cache alat dan sistem juga dibatalkan pada model yang merender konfigurasi sebelum keduanya. Lihat Pemikiran dan caching prompt. |
| Pengaturan effort | Spesifik model | Spesifik model | ✘ | Mengubah nilai output_config.effort dapat membatalkan blok pesan, dan pada beberapa model juga cache alat dan sistem (lihat Pemikiran dan caching prompt). Mengatur effort secara eksplisit ke nilai default model setara dengan menghilangkannya dan tidak membatalkan cache. Pada model yang mendukung effort per pesan, perubahan effort yang dibawa dalam pesan role: "system" di dalam messages membiarkan prefiks yang di-cache tetap utuh. |
| Hasil non-alat yang diteruskan ke permintaan dengan pemikiran | ✓ | ✓ | Spesifik model | Pada Claude Opus 4.5 dan model Opus yang lebih baru, Claude Sonnet 4.6 dan model Sonnet yang lebih baru, Claude Haiku 5.5, serta setiap model Claude Fable dan Claude Mythos, blok pemikiran dipertahankan secara default, sehingga cache tetap valid (✓). Pada model lain, semua blok pemikiran yang sebelumnya di-cache dihapus dari konteks, dan pesan apa pun yang mengikuti blok pemikiran tersebut dihapus dari cache (✘). Untuk detail lebih lanjut, lihat Caching dengan blok pemikiran. |
| Blok pemikiran yang tidak disertakan | ✓ | ✓ | ✘ | Ketika API tidak menyertakan blok pemikiran yang tidak dipertahankan pada permintaan tersebut, prefiks yang di-cache berubah mulai dari posisi blok tersebut dan seterusnya pada permintaan tersebut. Blok yang dapat dibaca oleh model penerima, yang diteruskan kembali tanpa perubahan, menjaga cache tetap utuh. |
Pada model yang mendukung perubahan alat di tengah percakapan, header beta inline-tools-2026-09-15 memungkinkan Anda menambahkan alat, atau mengubah definisi alat, di tengah percakapan tanpa mengedit tools. Kirim definisi dalam blok tool_addition di pesan sistem di tengah percakapan dan biarkan tools persis seperti yang pertama kali Anda kirim. Prefiks yang di-cache tetap cocok, sehingga hanya pesan yang ditambahkan yang diproses sebagai input baru. Satu-satunya pengecualian adalah array tools tanpa alat non-deferred, di mana alat pertama yang didefinisikan dengan cara ini menyebabkan satu cache miss penuh pada permintaan tersebut. Lihat Mendefinisikan alat dalam pesan.
Melacak kinerja cache
Pantau kinerja cache menggunakan field respons API berikut, di dalam usage pada respons (atau event message_start jika menggunakan streaming):
cache_creation_input_tokens: Jumlah token yang ditulis ke cache saat membuat entri barucache_read_input_tokens: Jumlah token yang diambil dari cache untuk permintaan iniinput_tokens: Jumlah token input yang tidak dibaca dari atau digunakan untuk membuat cache (yaitu, token setelah breakpoint cache terakhir)
Caching dengan blok pemikiran
Saat menggunakan pemikiran dengan caching prompt, blok pemikiran memiliki perilaku khusus:
Caching otomatis bersama konten lain: Meskipun blok pemikiran tidak dapat ditandai secara eksplisit dengan cache_control, blok tersebut di-cache sebagai bagian dari konten permintaan saat Anda melakukan panggilan API berikutnya dengan hasil alat. Ini umumnya terjadi selama penggunaan alat saat Anda meneruskan blok pemikiran kembali untuk melanjutkan percakapan.
Penghitungan token input: Saat blok pemikiran dibaca dari cache, blok tersebut dihitung sebagai token input dalam metrik penggunaan Anda. Ini penting untuk perhitungan biaya dan penganggaran token.
Pola pembatalan cache:
- Cache tetap valid saat hanya hasil alat yang diberikan sebagai pesan pengguna.
- Pada Claude Opus 4.5 dan model Opus yang lebih baru, Claude Sonnet 4.6 dan model Sonnet yang lebih baru, Claude Haiku 5.5, serta setiap model Claude Fable dan Claude Mythos, blok pemikiran dipertahankan secara default bahkan saat konten pengguna yang bukan hasil alat ditambahkan, sehingga cache tetap valid.
- Pada model lain, menambahkan konten pengguna yang bukan hasil alat membatalkan cache dan menghapus semua blok pemikiran sebelumnya dari konteks.
- Perilaku caching ini terjadi bahkan tanpa penanda
cache_controleksplisit.
Untuk detail lebih lanjut tentang pembatalan cache, lihat Apa yang membatalkan cache.
Contoh dengan penggunaan alat:
Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]
Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1
Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)Pada model yang mempertahankan pemikiran sebelumnya, blok pemikiran sebelumnya tetap berada dalam konteks secara default dan tetap menjadi bagian dari prefiks yang di-cache. Pada model lain, semua blok pemikiran sebelumnya dihapus dari konteks pada titik ini.
Untuk informasi lebih rinci, lihat Pemikiran dan caching prompt.
Penyimpanan dan berbagi cache
-
Isolasi organisasi dan workspace: Cache diisolasi antar organisasi. Organisasi yang berbeda tidak pernah berbagi cache, bahkan jika mereka menggunakan prompt yang identik. Cache juga diisolasi per workspace dalam suatu organisasi di Claude API, Claude Platform on AWS, dan Microsoft Foundry; Claude Models on Google Cloud (Google managed) dan Bedrock hanya menggunakan isolasi tingkat organisasi.
-
Pencocokan persis: Cache hit memerlukan segmen prompt yang 100 persen identik, termasuk semua teks dan gambar hingga dan termasuk blok yang ditandai dengan kontrol cache.
-
Pembuatan token output: Caching prompt tidak berpengaruh pada pembuatan token output. Respons yang Anda terima identik dengan yang akan Anda dapatkan jika caching prompt tidak digunakan.
Praktik terbaik untuk caching yang efektif
Untuk mengoptimalkan kinerja caching prompt:
- Mulailah dengan caching otomatis untuk percakapan multi-giliran. Caching otomatis menangani pengelolaan breakpoint secara otomatis.
- Gunakan breakpoint tingkat blok eksplisit saat Anda perlu meng-cache bagian berbeda dengan frekuensi perubahan berbeda.
- Cache konten yang stabil dan dapat digunakan kembali seperti instruksi sistem, informasi latar belakang, konteks besar, atau definisi alat yang sering digunakan.
- Tempatkan konten yang di-cache di awal prompt untuk kinerja terbaik.
- Gunakan cache breakpoint secara strategis untuk memisahkan bagian prefiks berbeda yang dapat di-cache.
- Tempatkan breakpoint pada blok terakhir yang tetap identik di seluruh permintaan. Untuk prompt dengan prefiks statis dan sufiks yang bervariasi (timestamp, konteks per permintaan, pesan yang masuk), itu adalah akhir prefiks, bukan blok yang bervariasi.
- Analisis tingkat cache hit secara teratur dan sesuaikan strategi Anda sesuai kebutuhan.
Mengoptimalkan untuk berbagai kasus penggunaan
Sesuaikan strategi caching prompt Anda dengan skenario Anda:
- Agen percakapan: Kurangi biaya dan latensi untuk percakapan panjang, terutama yang memiliki instruksi panjang atau dokumen yang diunggah.
- Asisten coding: Tingkatkan auto-complete dan tanya jawab basis kode dengan menyimpan bagian yang relevan atau versi ringkasan basis kode dalam prompt.
- Pemrosesan dokumen besar: Sertakan materi bentuk panjang yang lengkap termasuk gambar dalam prompt Anda tanpa meningkatkan latensi respons.
- Set instruksi terperinci: Bagikan daftar instruksi, prosedur, dan contoh yang ekstensif untuk menyempurnakan respons Claude. Developer sering menyertakan satu atau dua contoh dalam prompt, tetapi dengan caching prompt Anda bisa mendapatkan kinerja yang lebih baik lagi dengan menyertakan 20+ contoh beragam dari jawaban berkualitas tinggi.
- Penggunaan alat agentik: Tingkatkan kinerja untuk skenario yang melibatkan banyak panggilan alat dan perubahan kode iteratif, di mana setiap langkah biasanya memerlukan panggilan API baru.
- Buku, makalah, dokumentasi, transkrip podcast, dan konten bentuk panjang lainnya: Jadikan basis pengetahuan apa pun interaktif dengan menyematkan seluruh dokumen ke dalam prompt, dan biarkan pengguna mengajukan pertanyaan.
Memecahkan masalah umum
Jika Anda mengalami perilaku yang tidak terduga:
- Pastikan bagian yang di-cache identik di seluruh panggilan. Untuk breakpoint eksplisit, verifikasi bahwa penanda
cache_controlberada di lokasi yang sama. - Periksa bahwa panggilan dilakukan dalam masa hidup cache (5 menit secara default).
- Verifikasi bahwa
tool_choice, penggunaan gambar, konfigurasi pemikiran, danoutput_config.efforttetap konsisten antar panggilan. - Validasi bahwa Anda meng-cache setidaknya jumlah token minimum untuk model dan platform Anda (lihat Batasan cache).
- Pastikan breakpoint Anda berada pada blok yang tetap identik di seluruh permintaan. Penulisan cache hanya terjadi di breakpoint, dan jika blok tersebut berubah (timestamp, konteks per permintaan, pesan yang masuk), hash prefiks tidak akan pernah cocok. Lookback tidak menemukan konten stabil di belakang breakpoint; lookback hanya menemukan entri yang ditulis oleh permintaan sebelumnya di breakpoint mereka sendiri.
- Verifikasi bahwa kunci dalam blok konten
tool_useAnda memiliki urutan yang stabil karena beberapa bahasa (misalnya, Swift, Go) mengacak urutan kunci selama konversi JSON, sehingga merusak cache. - Gunakan diagnostik cache agar API membandingkan permintaan berturut-turut dan melaporkan bagian prompt mana yang menyimpang.
Durasi cache 1 jam
Jika Anda merasa 5 menit terlalu singkat, Anthropic juga menawarkan durasi cache 1 jam dengan biaya tambahan (lihat Harga).
Untuk menggunakan cache yang diperpanjang, sertakan ttl dalam definisi cache_control seperti ini:
"cache_control": {
"type": "ephemeral",
"ttl": "1h"
}Respons menyertakan informasi cache terperinci seperti berikut:
{
"usage": {
"input_tokens": 2048,
"cache_read_input_tokens": 1800,
"cache_creation_input_tokens": 248,
"output_tokens": 503,
"cache_creation": {
"ephemeral_5m_input_tokens": 148,
"ephemeral_1h_input_tokens": 100
}
}
}Field cache_creation_input_tokens sama dengan jumlah nilai dalam objek cache_creation.
Jika Anda melihat penulisan ephemeral_5m_input_tokens yang tidak Anda minta saat menggunakan alat server seperti pencarian web, lihat Hasil alat server di-cache secara otomatis.
Kapan menggunakan cache 1 jam
Jika Anda menggunakan prompt dengan ritme teratur (misalnya, prompt sistem yang Anda kirim lebih sering dari setiap 5 menit), tetap gunakan cache 5 menit, karena cache ini terus diperbarui tanpa biaya tambahan.
Cache 1 jam paling baik digunakan dalam skenario berikut:
- Saat Anda memiliki prompt yang kemungkinan digunakan lebih jarang dari setiap 5 menit, tetapi lebih sering dari setiap jam. Misalnya, saat side-agent agentik memakan waktu lebih dari 5 menit, atau saat menyimpan percakapan chat panjang dengan pengguna dan Anda umumnya memperkirakan pengguna tersebut mungkin tidak merespons dalam 5 menit ke depan.
- Saat latensi penting dan prompt lanjutan Anda mungkin dikirim setelah lebih dari 5 menit.
- Saat Anda ingin meningkatkan pemanfaatan batas laju Anda, karena cache hit tidak dipotong dari batas laju Anda.
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 lebih panjang harus muncul sebelum TTL yang lebih pendek (yaitu, entri cache 1 jam harus muncul sebelum entri cache 5 menit mana pun).
Saat mencampur TTL, Claude API menentukan tiga lokasi penagihan dalam prompt Anda:
- Posisi
A: Jumlah token pada cache hit terakhir dalam prompt Anda (atau 0 jika tidak ada hit).- Cache hit pada entri yang di-cache dengan TTL 5 menit tidak diakui sebagai hit jika blok
cache_controldengan TTL 1 jam yang posisinya berada setelah entri tersebut merupakan cache miss. - Permintaan yang membaca entri yang di-cache dengan TTL 5 menit memulai ulang masa hidup 5 menit milik entri tersebut, meskipun permintaan tersebut kini mengatur
"ttl": "1h".
- Cache hit pada entri yang di-cache dengan TTL 5 menit tidak diakui sebagai hit jika blok
- Posisi
B: Jumlah token pada blokcache_controlterakhir dengan TTL 1 jam yang posisinya berada setelahA(atau sama denganAjika tidak ada). - Posisi
C: Jumlah token pada blokcache_controlterakhir.
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 tiga contoh permintaan, yang masing-masing memiliki cache hit dan cache miss yang berbeda. Masing-masing memiliki perhitungan harga yang berbeda, yang ditunjukkan dalam kotak.
Memanaskan cache terlebih dahulu
“Cache pre-warming” (pemanasan cache terlebih dahulu) memungkinkan Anda memuat prompt sistem atau definisi alat ke dalam cache prompt sebelum pengguna memicu permintaan sebenarnya. Ini dapat mengurangi penalti latensi cache-miss pada interaksi pengguna pertama, sehingga menurunkan “time-to-first-token” (waktu hingga token pertama), atau TTFT, untuk aplikasi yang sensitif terhadap latensi.
Cara kerjanya
Atur max_tokens: 0 dalam permintaan Anda. API membaca prompt Anda ke dalam model dan menulis cache pada setiap breakpoint cache_control, lalu langsung kembali tanpa menghasilkan output apa pun. Respons memiliki array content kosong, stop_reason: "max_tokens", dan blok usage yang terisi lengkap.
Tempatkan breakpoint cache_control pada blok terakhir yang dibagikan dengan permintaan lanjutan (biasanya prompt sistem atau definisi alat Anda), bukan pada pesan pengguna placeholder. Jika tidak, entri cache akan dikunci ke placeholder dan permintaan lanjutan tidak akan mengenainya. Gunakan juga konfigurasi pemikiran dan output_config.effort yang sama dengan permintaan lanjutan Anda: nilai-nilai tersebut dirender ke dalam prompt (lihat Apa yang membatalkan cache), sehingga pemanasan dengan konfigurasi berbeda dapat menulis entri yang tidak pernah dikenai oleh lalu lintas sebenarnya. Ini berarti menggunakan breakpoint cache eksplisit alih-alih caching otomatis, karena caching otomatis menempatkan breakpoint pada blok terakhir, yang di sini adalah placeholder. Pesan pengguna placeholder dapat berupa string apa pun dengan konten non-whitespace (contoh di sini menggunakan "warmup"); kontennya dibaca ke dalam model tetapi tidak pernah dijawab.
client = anthropic.Anthropic()
# Jalankan ini sebelum pengguna datang untuk memanaskan cache prompt sistem bersama.
prewarm = client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=[
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason) # "max_tokens"
print(prewarm.content) # []
print(prewarm.usage)API mengembalikan array content kosong:
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [],
"model": "claude-opus-5-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 8,
"cache_creation_input_tokens": 5120,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"iterations": [
{
"input_tokens": 8,
"output_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 5120,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"type": "message"
}
],
"output_tokens": 0,
"service_tier": "standard",
"inference_geo": "global"
}
}Pola penggunaan umum
Buat permintaan pemanasan saat aplikasi Anda dimulai (atau pada interval terjadwal), lalu kirim permintaan pengguna sebenarnya setelah pemanasan selesai:
client = anthropic.Anthropic()
SYSTEM_PROMPT = [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
]
def prewarm_cache() -> None:
"""Call this at application startup or on a scheduled interval."""
client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": "warmup"}],
)
def respond(user_message: str) -> anthropic.types.Message:
"""The real user request; benefits from a warm cache."""
return client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": user_message}],
)
# Panaskan cache sebelum lalu lintas pengguna tiba.
prewarm_cache()
# Nanti, saat pengguna mengirim pesan, prefiks prompt sistem sudah ada di cache.
response = respond("How do I implement a binary search tree?")
for block in response.content:
if block.type == "text":
print(block.text)Perlu diingat bahwa TTL cache tetap berlaku. Untuk cache default 5 menit, kirim permintaan pemanasan baru setidaknya setiap 5 menit agar cache tetap hangat. Untuk jeda yang lebih panjang antar permintaan pengguna, gunakan durasi cache 1 jam sebagai gantinya.
Batasan
Permintaan max_tokens: 0 ditolak dengan invalid_request_error jika salah satu dari hal berikut diatur, karena masing-masing menyiratkan output yang tidak dapat dihasilkan oleh anggaran nol token:
stream: true- Pemikiran diperpanjang (
thinking.type: "enabled") - Output terstruktur (
output_config.format) tool_choiceberupa{"type": "tool", ...}atau{"type": "any"}
max_tokens: 0 juga ditolak di dalam permintaan Message Batches. Pemanasan menargetkan time-to-first-token, yang tidak berlaku untuk pemrosesan batch, dan entri cache yang ditulis selama pemrosesan batch kemungkinan akan kedaluwarsa sebelum permintaan lanjutan dijalankan.
Mengganti solusi max_tokens=1
Beberapa aplikasi mengirim permintaan max_tokens: 1 untuk memanaskan cache. Utamakan max_tokens: 0 jika permintaan memungkinkannya: tidak ada output yang dihasilkan, sehingga tidak ada balasan satu token yang perlu dibuang, tidak ada token output yang ditagih, dan maksud permintaan menjadi jelas.
Contoh caching prompt
Untuk membantu Anda memulai dengan caching prompt, resep caching prompt di Claude Cookbook menyediakan contoh terperinci dan praktik terbaik.
Cuplikan kode berikut menampilkan berbagai pola caching prompt. Contoh-contoh ini menunjukkan cara mengimplementasikan caching dalam berbagai skenario, membantu Anda memahami aplikasi praktis dari fitur ini:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing legal documents.",
},
{
"type": "text",
"text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "What are the key terms and conditions in this agreement?",
}
],
)
print(response.usage.model_dump_json())Contoh ini menunjukkan penggunaan dasar caching prompt, dengan meng-cache teks lengkap perjanjian hukum sebagai prefiks sambil membiarkan instruksi pengguna tidak di-cache.
Untuk permintaan pertama:
input_tokens: Jumlah token hanya dalam pesan penggunacache_creation_input_tokens: Jumlah token dalam seluruh pesan sistem, termasuk dokumen hukumcache_read_input_tokens: 0 (tidak ada cache hit pada permintaan pertama)
Untuk permintaan berikutnya dalam masa hidup cache:
input_tokens: Jumlah token hanya dalam pesan penggunacache_creation_input_tokens: 0 (tidak ada pembuatan cache baru)cache_read_input_tokens: Jumlah token dalam seluruh pesan sistem yang di-cache
Definisi alat dapat di-cache dengan menempatkan cache_control pada alat terakhir dalam array tools Anda. Semua alat yang didefinisikan sebelum dan termasuk alat tersebut di-cache sebagai satu prefiks.
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": { "location": { "type": "string" } },
"required": ["location"]
}
},
{
"name": "get_time",
"description": "Get the current time in a given time zone",
"input_schema": {
"type": "object",
"properties": { "timezone": { "type": "string" } },
"required": ["timezone"]
},
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}Pada permintaan pertama, cache_creation_input_tokens mencerminkan jumlah token dari semua definisi alat. Pada permintaan berikutnya dalam masa hidup cache, token tersebut muncul di bawah cache_read_input_tokens sebagai gantinya.
Untuk interaksi terperinci antara definisi alat, defer_loading, dan pembatalan cache, lihat Penggunaan alat dengan caching prompt.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "...long system prompt",
"cache_control": {"type": "ephemeral"},
}
],
messages=[
# ...percakapan panjang sejauh ini
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hello, can you tell me more about the solar system?",
}
],
},
{
"role": "assistant",
"content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
},
{
"role": "user",
"content": [
{"type": "text", "text": "Good to know."},
{
"type": "text",
"text": "Tell me more about Mars.",
"cache_control": {"type": "ephemeral"},
},
],
},
],
)
print(response.usage.model_dump_json())Contoh ini menunjukkan cara menggunakan caching prompt dalam percakapan multi-giliran.
Pada setiap giliran, blok terakhir dari pesan terakhir ditandai dengan cache_control sehingga percakapan dapat di-cache secara bertahap. Sistem secara otomatis mencari dan menggunakan urutan blok terpanjang yang sebelumnya di-cache untuk pesan lanjutan. Blok yang ditandai dengan cache_control pada giliran sebelumnya tidak ditandai lagi, tetapi permintaan dalam waktu 5 menit tetap membacanya dari cache dan memperbarui masa hidupnya.
Parameter cache_control juga ditempatkan pada pesan sistem. Jika pesan sistem dikeluarkan dari cache setelah tidak digunakan selama lebih dari 5 menit, permintaan berikutnya akan menambahkannya kembali.
Pendekatan ini berguna untuk mempertahankan konteks dalam percakapan yang sedang berlangsung tanpa berulang kali memproses informasi yang sama.
Jika ini diatur dengan benar, Anda akan melihat hal berikut dalam respons usage dari setiap permintaan:
input_tokens: Jumlah token dalam pesan pengguna baru (minimal)cache_creation_input_tokens: Jumlah token dalam giliran asisten dan pengguna yang barucache_read_input_tokens: Jumlah token dalam percakapan hingga giliran sebelumnya
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[
{
"name": "search_documents",
"description": "Search through the knowledge base",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"}
},
"required": ["query"],
},
},
{
"name": "get_document",
"description": "Retrieve a specific document by ID",
"input_schema": {
"type": "object",
"properties": {
"doc_id": {"type": "string", "description": "Document ID"}
},
"required": ["doc_id"],
},
"cache_control": {"type": "ephemeral"},
},
],
system=[
{
"type": "text",
"text": """You are a helpful research assistant with access to a document knowledge base.
# Instructions
- Always search for relevant documents before answering
- Provide citations for your sources
- Be objective and accurate in your responses
- If multiple documents contain relevant information, synthesize them
- Acknowledge when information is not available in the knowledge base""",
"cache_control": {"type": "ephemeral"},
},
{
"type": "text",
"text": """# Knowledge Base Context
Here are the relevant documents for this conversation:
## Document 1: Solar System Overview
The solar system consists of the Sun and all objects that orbit it...
## Document 2: Planetary Characteristics
Each planet has unique features. Mercury is the smallest planet...
## Document 3: Mars Exploration
Mars has been a target of exploration for decades...
[Additional documents...]""",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Can you search for information about Mars rovers?",
},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "tool_1",
"name": "search_documents",
"input": {"query": "Mars rovers"},
}
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "tool_1",
"content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
}
],
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
}
],
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Yes, please tell me about the Perseverance rover specifically.",
"cache_control": {"type": "ephemeral"},
}
],
},
],
)
print(response.usage.model_dump_json())Contoh komprehensif ini menunjukkan cara menggunakan keempat breakpoint cache yang tersedia untuk mengoptimalkan berbagai bagian prompt Anda:
-
Cache alat (breakpoint cache 1): Parameter
cache_controlpada definisi alat terakhir meng-cache semua definisi alat. -
Cache instruksi yang dapat digunakan kembali (breakpoint cache 2): Instruksi statis dalam prompt sistem di-cache secara terpisah. Instruksi ini jarang berubah antar permintaan.
-
Cache konteks RAG (breakpoint cache 3): Dokumen basis pengetahuan di-cache secara independen, memungkinkan Anda memperbarui dokumen RAG tanpa membatalkan cache alat atau instruksi.
-
Cache riwayat percakapan (breakpoint cache 4): Pesan pengguna terakhir ditandai dengan
cache_controluntuk memungkinkan caching bertahap dari percakapan seiring berjalannya.
Pendekatan ini memberikan fleksibilitas maksimum:
- Jika Anda menambahkan giliran baru ke percakapan tanpa mengubah konten sebelumnya, keempat segmen cache digunakan kembali.
- Jika Anda memperbarui dokumen RAG tetapi mempertahankan alat dan instruksi yang sama, dua segmen cache pertama digunakan kembali.
- Jika Anda mengubah percakapan tetapi mempertahankan alat, instruksi, dan dokumen yang sama, tiga segmen pertama digunakan kembali.
- Perubahan pada breakpoint mana pun membatalkan segmen tersebut dan semua yang ada setelahnya, sedangkan segmen yang di-cache sebelumnya tetap valid.
Untuk permintaan pertama:
input_tokens: Minimal (token setelah breakpoint cache terakhir, mendekati 0 dalam contoh ini)cache_creation_input_tokens: Token dalam semua segmen yang di-cache (alat + instruksi + dokumen RAG + riwayat percakapan)cache_read_input_tokens: 0 (tidak ada cache hit)
Untuk permintaan berikutnya dengan hanya pesan pengguna baru (dan breakpoint keempat dipindahkan ke pesan terakhir yang baru tersebut, seperti dalam contoh):
input_tokens: Minimal (token setelah breakpoint cache terakhir, mendekati 0 dalam contoh ini)cache_creation_input_tokens: Token dalam pesan pengguna baru dan giliran asisten sebelumnya (segmen percakapan baru yang sedang di-cache)cache_read_input_tokens: Semua token yang sebelumnya di-cache (alat + instruksi + dokumen RAG + percakapan sebelumnya)
Pola ini sangat efektif untuk:
- Aplikasi RAG dengan konteks dokumen besar
- Sistem agen yang menggunakan banyak alat
- Percakapan berdurasi panjang yang perlu mempertahankan konteks
- Aplikasi yang perlu mengoptimalkan berbagai bagian prompt secara independen
Retensi data
Caching prompt (baik otomatis maupun eksplisit) memenuhi syarat ZDR. Anthropic tidak menyimpan teks mentah dari prompt Anda atau respons Claude.
Representasi cache KV (key-value) dan hash kriptografis dari konten yang di-cache hanya disimpan di memori dan tidak disimpan secara permanen (at rest). Entri yang di-cache memiliki masa hidup minimum 5 menit (standar) atau 1 jam (diperpanjang), setelah itu entri tersebut dihapus dengan segera, meskipun tidak seketika. Entri cache diisolasi antar organisasi dan, pada Claude API, Claude Platform on AWS, dan Microsoft Foundry, antar workspace dalam satu organisasi.
FAQ
Dalam sebagian besar kasus, satu breakpoint cache di akhir konten statis Anda sudah cukup. Penulisan cache hanya terjadi pada blok yang Anda tandai. Tempatkan pada blok terakhir yang tetap identik di seluruh permintaan, dan setiap permintaan berikutnya akan membaca entri yang sama. Jika blok berikutnya bervariasi pada setiap permintaan (stempel waktu, pesan masuk), tempatkan breakpoint sebelumnya, pada blok stabil terakhir.
Anda hanya memerlukan beberapa breakpoint jika:
- Percakapan yang terus bertambah mendorong breakpoint Anda 20 blok atau lebih melewati penulisan cache terakhir, sehingga entri sebelumnya berada di luar jendela lookback
- Anda ingin meng-cache bagian yang diperbarui dengan frekuensi berbeda secara independen
- Anda memerlukan kontrol eksplisit atas apa yang di-cache untuk optimasi biaya
Contoh: Jika Anda memiliki instruksi sistem (jarang berubah) dan konteks RAG (berubah setiap hari), Anda dapat menggunakan dua breakpoint untuk meng-cache keduanya secara terpisah.
Tidak, breakpoint cache itu sendiri gratis. Anda hanya membayar untuk:
- Menulis konten ke cache (25 persen lebih mahal dari token input dasar untuk TTL 5 menit)
- Membaca dari cache (sebagian kecil dari harga token input dasar)
- Token input reguler untuk konten yang tidak di-cache
Jumlah breakpoint tidak memengaruhi harga; yang penting hanyalah jumlah konten yang di-cache dan dibaca.
Respons usage mencakup tiga field token input terpisah yang bersama-sama mewakili total input Anda:
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokenscache_read_input_tokens: Token yang diambil dari cache (semua yang ada sebelum breakpoint cache yang telah di-cache)cache_creation_input_tokens: Token baru yang ditulis ke cache (pada breakpoint cache)input_tokens: Token setelah breakpoint cache terakhir yang tidak di-cache
Penting: input_tokens TIDAK mewakili semua token input, hanya bagian setelah breakpoint cache terakhir Anda. Jika Anda memiliki konten yang di-cache, input_tokens biasanya jauh lebih kecil dari total input Anda.
Contoh: Dengan dokumen 200k token yang di-cache dan pertanyaan pengguna 50 token:
cache_read_input_tokens: 200.000cache_creation_input_tokens: 0input_tokens: 50- Total: 200.050 token
Rincian ini sangat penting untuk memahami biaya dan penggunaan batas laju Anda. Lihat Melacak kinerja cache untuk detail lebih lanjut.
Masa hidup minimum default cache (TTL) adalah 5 menit. Masa hidup ini diperbarui setiap kali konten yang di-cache digunakan.
Jika Anda merasa 5 menit terlalu singkat, Anthropic juga menawarkan TTL cache 1 jam.
Masa hidup diukur dari awal permintaan yang menulis atau membaca entri cache, bukan dari akhir responsnya. Waktu yang dihabiskan untuk menghasilkan respons dihitung terhadap masa hidup, sehingga jendela bagi permintaan lanjutan untuk menggunakan kembali cache adalah masa hidup dikurangi waktu pembuatan.
Jika permintaan Anda menghasilkan respons panjang dan permintaan berikutnya mungkin baru dimulai setelah masa hidup berakhir, gunakan TTL cache 1 jam.
Anda dapat menentukan hingga 4 breakpoint cache (menggunakan parameter cache_control) dalam prompt Anda.
Caching prompt didukung pada semua model Claude yang aktif.
Mengubah parameter pemikiran (beralih mode, atau mengubah anggaran dalam mode diperpanjang) membatalkan prefiks pesan yang di-cache, dan juga dapat membatalkan prompt sistem dan alat yang di-cache, karena konfigurasi pemikiran dirender ke dalam prompt. Mengubah nilai output_config.effort dapat memberikan efek yang sama.
Untuk detail lebih lanjut tentang pembatalan cache, lihat Apa yang membatalkan cache.
Untuk informasi lebih lanjut tentang pemikiran, termasuk interaksinya dengan penggunaan alat dan caching prompt, lihat Pemikiran dan caching prompt.
Cara termudah adalah menambahkan "cache_control": {"type": "ephemeral"} di tingkat atas body permintaan Anda (caching otomatis). Atau, sertakan setidaknya satu breakpoint cache_control pada blok konten individual (breakpoint cache eksplisit).
Ya, caching prompt dapat digunakan bersama fitur API lainnya seperti penggunaan alat dan kemampuan vision. Namun, mengubah ada tidaknya gambar dalam prompt atau memodifikasi pengaturan penggunaan alat akan merusak cache.
Untuk detail lebih lanjut tentang pembatalan cache, lihat Apa yang membatalkan cache.
Caching prompt memiliki harganya sendiri: penulisan cache 5 menit berbiaya 25 persen lebih mahal dari token input dasar, penulisan cache 1 jam berbiaya 2x token input dasar, dan cache hit berbiaya sebagian kecil dari harga token input dasar, dengan pengali untuk setiap model.
Tidak ada cara untuk membersihkan cache secara manual. Prefiks yang di-cache secara otomatis kedaluwarsa setelah minimal 5 menit tidak aktif.
Anda dapat memantau kinerja cache menggunakan field cache_creation_input_tokens dan cache_read_input_tokens dalam respons API.
Lihat Apa yang membatalkan cache untuk detail lebih lanjut tentang pembatalan cache, termasuk daftar perubahan yang memerlukan pembuatan entri cache baru.
Caching prompt dirancang dengan langkah-langkah privasi dan pemisahan data yang kuat:
-
Kunci cache dibuat menggunakan hash kriptografis dari prompt hingga titik kontrol cache. Ini berarti hanya permintaan dengan prompt identik yang dapat mengakses cache tertentu.
-
Pada Claude API, Claude Platform on AWS, dan Microsoft Foundry, cache diisolasi per workspace dalam satu organisasi. Pada Claude Models on Google Cloud (Google managed) dan Bedrock, cache diisolasi per organisasi. Dalam setiap kasus, cache tidak pernah dibagikan antar organisasi, bahkan untuk prompt yang identik. Lihat Penyimpanan dan berbagi cache untuk detailnya.
-
Mekanisme caching dirancang untuk menjaga integritas dan privasi setiap percakapan atau konteks yang unik.
-
Aman untuk menggunakan
cache_controldi mana saja dalam prompt Anda. Agar caching menghasilkan pembacaan, tempatkan breakpoint di akhir prefiks yang stabil: menempatkannya pada blok yang berubah di setiap permintaan (seperti stempel waktu atau input sembarang dari pengguna) akan menulis entri baru setiap kali dan tidak pernah menghasilkan hit.
Langkah-langkah ini memastikan bahwa caching prompt menjaga privasi dan keamanan data sambil menawarkan manfaat kinerja.
Ya, caching prompt dapat digunakan dengan permintaan Message Batches API Anda. Namun, karena permintaan batch asinkron dapat diproses secara bersamaan dan dalam urutan apa pun, cache hit disediakan berdasarkan upaya terbaik (best-effort).
Cache 1 jam dapat membantu meningkatkan cache hit Anda. Cara paling hemat biaya untuk menggunakannya adalah sebagai berikut:
- Kumpulkan sekumpulan permintaan pesan yang memiliki prefiks bersama.
- Kirim permintaan batch dengan satu permintaan yang memiliki prefiks bersama ini dan blok cache 1 jam. Ini menulis prefiks ke cache 1 jam.
- Segera setelah ini selesai, kirimkan sisa permintaan. Anda harus memantau job untuk mengetahui kapan job tersebut selesai.
Ini biasanya lebih baik daripada menggunakan cache 5 menit karena umum bagi permintaan batch untuk memerlukan waktu antara 5 menit dan 1 jam untuk selesai.
Error ini biasanya muncul ketika Anda telah meng-upgrade SDK atau menggunakan contoh kode yang sudah usang. Caching prompt tersedia di client.messages, tanpa prefiks beta. Alih-alih:
client.beta.prompt_caching.messages.create(**params)Gunakan:
client.messages.create(**params)Error ini biasanya muncul ketika Anda telah meng-upgrade SDK atau menggunakan contoh kode yang sudah usang. Caching prompt tersedia di client.messages, tanpa prefiks beta. Alih-alih:
client.beta.promptCaching.messages.create(/* ... */);Gunakan:
client.messages.create(/* ... */);Ketersediaan
Claude API
- API
- Messages API
- Managed Agents Beta
- Model
- Semua model
Amazon Bedrock
- API
- Messages API
- Model
- Semua model
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Model
- Semua model
Claude Platform on AWS
- API
- Messages API
- Managed Agents Beta
- Model
- Semua model
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents Beta
- Model
- Semua model
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Model
- Semua model
Microsoft Foundry
- API
- Messages API
- Model
- Semua model
Penanganan data
Ikhtisar penanganan dataEndpoint yang berlaku
/v1/messages
Tidak termasuk Model yang dicakup
Prompt Anda dan output Claude tidak disimpan. Representasi cache KV dan hash kriptografis disimpan di memori selama TTL cache dan segera dihapus setelah kedaluwarsa. Pelajari lebih lanjut
Apakah halaman ini membantu?