Caching prompt
Caching prompt adalah fitur yang kuat yang mengoptimalkan penggunaan API Anda dengan memungkinkan melanjutkan dari awalan 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 caching prompt 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 memprosesnya ulang setiap kali. Mengubah hanya pesan pengguna memungkinkan Anda mengajukan berbagai pertanyaan tentang buku sambil memanfaatkan konten yang di-cache, yang menghasilkan respons lebih cepat dan efisiensi yang lebih baik.
Cara kerja caching prompt
Ketika Anda mengirim permintaan dengan caching prompt diaktifkan:
- Sistem memeriksa apakah awalan prompt, hingga titik cache yang ditentukan, sudah di-cache dari kueri sebelumnya.
- Jika ditemukan, sistem menggunakan versi yang di-cache, mengurangi waktu pemrosesan dan biaya.
- Jika tidak, sistem memproses prompt lengkap dan menyimpan awalan dalam cache setelah respons dimulai.
Ini sangat berguna untuk:
- Prompt dengan banyak contoh
- Jumlah konteks atau informasi latar belakang yang besar
- Tugas berulang dengan instruksi yang konsisten
- Percakapan multi-giliran yang panjang
Secara default, cache memiliki masa aktif 5 menit. Cache disegarkan tanpa biaya tambahan setiap kali konten yang di-cache digunakan.
Caching prompt menyimpan seluruh awalan
Caching prompt mereferensikan seluruh prompt - tools
, system
, dan messages
(dalam urutan tersebut) hingga dan termasuk blok yang ditandai dengan cache_control
.
Harga
Caching prompt 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 | $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 | $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 | $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 |
Catatan:
- Token penulisan cache 5 menit adalah 1,25 kali harga token input dasar
- Token penulisan cache 1 jam adalah 2 kali harga token input dasar
- Token pembacaan cache adalah 0,1 kali harga token input dasar
- Token input dan output reguler dihargai dengan tarif standar
Cara mengimplementasikan caching prompt
Model yang didukung
Caching prompt saat ini didukung pada:
- Claude Opus 4
- Claude Sonnet 4
- Claude Sonnet 3.7
- Claude Sonnet 3.5
- Claude Haiku 3.5
- Claude Haiku 3
- Claude Opus 3
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
.
Awalan cache dibuat dalam urutan berikut: tools
, system
, kemudian messages
.
Menggunakan parameter cache_control
, Anda dapat menentukan hingga 4 titik cache, memungkinkan Anda menyimpan bagian yang dapat digunakan kembali secara terpisah. Untuk setiap titik, sistem akan secara otomatis memeriksa cache hit pada posisi sebelumnya dan menggunakan awalan yang cocok terpanjang jika ditemukan.
Batasan 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 dan Claude Opus 3
- 2048 token untuk Claude Haiku 3.5 dan Claude Haiku 3
Prompt yang lebih pendek tidak dapat di-cache, meskipun ditandai dengan cache_control
. Setiap permintaan untuk menyimpan token kurang dari jumlah ini akan diproses tanpa caching. Untuk melihat apakah prompt di-cache, lihat bidang 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 aktif 5 menit.
Apa yang dapat di-cache
Sebagian besar blok dalam permintaan dapat ditandai untuk caching dengan cache_control
. Ini termasuk:
- Tools: Definisi alat dalam array
tools
- Pesan sistem: Blok konten dalam array
system
- Pesan teks: Blok konten dalam array
messages.content
, untuk giliran pengguna dan asisten - Gambar & Dokumen: Blok konten dalam array
messages.content
, dalam giliran pengguna - Penggunaan alat dan hasil alat: Blok konten dalam array
messages.content
, dalam giliran pengguna dan asisten
Masing-masing 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 pemikiran tidak dapat di-cache langsung dengan
cache_control
. Namun, blok pemikiran DAPAT di-cache bersama konten lain ketika muncul dalam giliran asisten sebelumnya. Ketika di-cache dengan cara ini, mereka DIHITUNG sebagai token input saat dibaca dari cache. -
Blok sub-konten (seperti kutipan) sendiri tidak dapat di-cache secara langsung. Sebagai gantinya, cache blok tingkat atas.
Dalam kasus kutipan, blok konten dokumen tingkat atas yang berfungsi sebagai bahan sumber untuk kutipan dapat di-cache. Ini memungkinkan Anda menggunakan caching prompt dengan kutipan secara efektif dengan menyimpan dokumen yang akan direferensikan kutipan.
-
Blok teks kosong tidak dapat di-cache.
Melacak performa cache
Pantau performa cache menggunakan bidang 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 efektif
Untuk mengoptimalkan performa caching prompt:
- 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 performa terbaik.
- Gunakan titik cache secara strategis untuk memisahkan bagian awalan yang dapat di-cache.
- Secara teratur menganalisis tingkat hit cache dan menyesuaikan 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 yang panjang, terutama yang memiliki instruksi panjang atau dokumen yang diunggah.
- Asisten pengkodean: Tingkatkan autocomplete dan tanya jawab basis kode dengan menyimpan bagian yang relevan atau versi ringkasan dari basis kode 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 luas untuk menyempurnakan respons Claude. Pengembang sering menyertakan satu atau dua contoh dalam prompt, tetapi dengan caching prompt Anda bisa mendapatkan performa yang lebih baik dengan menyertakan 20+ contoh jawaban berkualitas tinggi yang beragam.
- Penggunaan alat agentik: Tingkatkan performa untuk skenario yang melibatkan beberapa panggilan alat 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 membiarkan pengguna mengajukan pertanyaan.
Memecahkan 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 dilakukan dalam masa aktif cache (5 menit secara default)
- Verifikasi bahwa
tool_choice
dan penggunaan gambar tetap konsisten antar panggilan - Validasi bahwa Anda menyimpan setidaknya jumlah token minimum
- Meskipun sistem akan mencoba menggunakan konten yang sebelumnya di-cache pada posisi sebelum titik cache, Anda dapat menggunakan parameter
cache_control
tambahan untuk menjamin pencarian cache pada bagian sebelumnya dari prompt, yang mungkin berguna untuk kueri dengan daftar blok konten yang sangat panjang
Perhatikan bahwa perubahan pada tool_choice
atau keberadaan/ketiadaan gambar di mana pun dalam prompt akan membatalkan cache, yang memerlukan entri cache baru untuk dibuat.
Caching dengan blok pemikiran
Saat menggunakan pemikiran diperpanjang dengan caching prompt, blok pemikiran memiliki perilaku khusus:
Caching otomatis bersama konten lain: Meskipun blok pemikiran tidak dapat secara eksplisit ditandai dengan cache_control
, mereka di-cache sebagai bagian dari konten permintaan ketika Anda membuat panggilan API berikutnya dengan hasil alat. Ini biasanya terjadi selama penggunaan alat ketika Anda meneruskan blok pemikiran kembali untuk melanjutkan percakapan.
Penghitungan token input: Ketika blok pemikiran 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 alat yang disediakan sebagai pesan pengguna
- Cache dibatalkan ketika konten pengguna non-hasil-alat ditambahkan, menyebabkan semua blok pemikiran sebelumnya dihapus
- Perilaku caching ini terjadi bahkan tanpa penanda
cache_control
eksplisit
Contoh dengan penggunaan alat:
Ketika blok pengguna non-hasil-alat disertakan, itu menandakan loop asisten baru dan semua blok pemikiran sebelumnya dihapus dari konteks.
Untuk informasi lebih rinci, lihat dokumentasi pemikiran diperpanjang.
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 100% identik, termasuk semua teks dan gambar hingga dan termasuk blok yang ditandai dengan cache control.
-
Generasi Token Output: Caching prompt tidak berpengaruh pada generasi token output. Respons yang Anda terima akan identik dengan yang Anda dapatkan jika caching prompt tidak digunakan.
Durasi cache 1 jam (beta)
Jika Anda merasa bahwa 5 menit terlalu singkat, Anthropic juga menawarkan durasi cache 1 jam.
Untuk menggunakan cache yang diperpanjang, tambahkan extended-cache-ttl-2025-04-11
sebagai header beta ke permintaan Anda, dan kemudian sertakan ttl
dalam definisi cache_control
seperti ini:
Respons akan menyertakan informasi cache terperinci seperti berikut:
Perhatikan bahwa bidang 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 dari 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 sampingan agentik akan membutuhkan 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 berikutnya.
- Ketika latensi penting dan prompt lanjutan Anda mungkin dikirim setelah 5 menit.
- Ketika Anda ingin meningkatkan pemanfaatan batas rate, karena cache hit tidak dikurangkan dari batas rate Anda.
Cache 5 menit dan 1 jam berperilaku sama sehubungan dengan latensi. Anda umumnya akan melihat waktu-ke-token-pertama yang lebih baik 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 lebih lama harus muncul sebelum TTL yang lebih pendek (yaitu, entri cache 1 jam harus muncul sebelum entri cache 5 menit).
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 pasti akan menjadi cache miss, karena A
adalah cache hit tertinggi.
Anda akan dikenakan biaya untuk:
- Token pembacaan cache untuk
A
. - Token penulisan cache 1 jam untuk
(B - A)
. - Token penulisan 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 harga yang dihitung berbeda, ditunjukkan dalam kotak berwarna, sebagai hasilnya.
Contoh caching prompt
Untuk membantu Anda memulai dengan caching prompt, kami telah menyiapkan buku resep caching prompt dengan contoh terperinci dan praktik terbaik.
Di bawah ini, kami telah menyertakan beberapa cuplikan kode yang menampilkan berbagai pola caching prompt. Contoh-contoh ini menunjukkan cara mengimplementasikan caching dalam skenario yang berbeda, membantu Anda memahami aplikasi praktis dari fitur ini: