Penyimpanan cache prompt

Penyimpanan cache 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 penyimpanan cache prompt dengan Messages API menggunakan blok cache_control:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

Dalam contoh ini, seluruh teks "Pride and Prejudice" disimpan dalam cache menggunakan parameter cache_control. Ini memungkinkan penggunaan kembali teks besar ini di berbagai panggilan API tanpa memproses ulang setiap kali. Mengubah hanya pesan pengguna memungkinkan Anda untuk mengajukan berbagai pertanyaan tentang buku sambil memanfaatkan konten yang disimpan dalam cache, menghasilkan respons yang lebih cepat dan efisiensi yang ditingkatkan.

Cara kerja penyimpanan cache prompt

Ketika Anda mengirim permintaan dengan penyimpanan cache prompt diaktifkan:

1. Sistem memeriksa apakah awalan prompt, hingga titik henti cache yang ditentukan, sudah disimpan dalam cache dari kueri baru-baru ini.
2. Jika ditemukan, sistem menggunakan versi yang disimpan dalam cache, mengurangi waktu pemrosesan dan biaya.
3. Jika tidak, sistem memproses prompt lengkap dan menyimpan awalan dalam cache 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-putaran yang panjang

Secara default, cache memiliki masa pakai 5 menit. Cache disegarkan tanpa biaya tambahan setiap kali konten yang disimpan dalam cache digunakan.

Harga

Penyimpanan cache prompt memperkenalkan struktur harga baru. Tabel di bawah menunjukkan harga per juta token untuk setiap model yang didukung:

Cara mengimplementasikan penyimpanan cache prompt

Model yang didukung

Penyimpanan cache prompt saat ini didukung pada:

• Claude Opus 4.5
• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7 (deprecated)
• Claude Haiku 4.5
• Claude Haiku 3.5 (deprecated)
• Claude Haiku 3
• Claude Opus 3 (deprecated)

Menyusun prompt Anda

Tempatkan konten statis (definisi alat, instruksi sistem, konteks, contoh) di awal prompt Anda. Tandai akhir konten yang dapat digunakan kembali untuk penyimpanan cache menggunakan parameter cache_control.

Awalan cache dibuat dalam urutan berikut: tools, system, kemudian messages. Urutan ini membentuk hierarki di mana setiap level dibangun di atas level sebelumnya.

Cara kerja pemeriksaan awalan otomatis

Anda dapat menggunakan hanya satu titik henti cache di akhir konten statis Anda, dan sistem akan secara otomatis menemukan urutan blok yang disimpan dalam cache terpanjang yang cocok. Memahami cara kerjanya membantu Anda mengoptimalkan strategi penyimpanan cache Anda.

Tiga prinsip inti:

1. Kunci cache bersifat kumulatif: Ketika Anda secara eksplisit menyimpan blok dalam cache dengan cache_control, kunci hash cache dihasilkan dengan melakukan hash semua blok sebelumnya dalam percakapan secara berurutan. Ini berarti cache untuk setiap blok bergantung pada semua konten yang datang sebelumnya.

2. Pemeriksaan berurutan mundur: Sistem memeriksa cache hit dengan bekerja mundur dari titik henti eksplisit Anda, memeriksa setiap blok sebelumnya dalam urutan terbalik. Ini memastikan Anda mendapatkan cache hit terpanjang yang mungkin.

3. Jendela lookback 20 blok: Sistem hanya memeriksa hingga 20 blok sebelum setiap titik henti cache_control eksplisit. Setelah memeriksa 20 blok tanpa kecocokan, sistem berhenti memeriksa dan beralih ke titik henti eksplisit berikutnya (jika ada).

Contoh: Memahami jendela lookback

Pertimbangkan percakapan dengan 30 blok konten di mana Anda menetapkan cache_control hanya pada blok 30:

• Jika Anda mengirim blok 31 tanpa perubahan pada blok sebelumnya: Sistem memeriksa blok 30 (cocok!). Anda mendapatkan cache hit pada blok 30, dan hanya blok 31 yang perlu diproses.

• Jika Anda memodifikasi blok 25 dan mengirim blok 31: Sistem memeriksa mundur dari blok 30 → 29 → 28... → 25 (tidak cocok) → 24 (cocok!). Karena blok 24 belum berubah, Anda mendapatkan cache hit pada blok 24, dan hanya blok 25-30 yang perlu diproses ulang.

• Jika Anda memodifikasi blok 5 dan mengirim blok 31: Sistem memeriksa mundur dari blok 30 → 29 → 28... → 11 (pemeriksaan #20). Setelah 20 pemeriksaan tanpa menemukan kecocokan, sistem berhenti mencari. Karena blok 5 berada di luar jendela 20 blok, tidak ada cache hit yang terjadi dan semua blok perlu diproses ulang. Namun, jika Anda telah menetapkan titik henti cache_control eksplisit pada blok 5, sistem akan terus memeriksa dari titik henti itu: blok 5 (tidak cocok) → blok 4 (cocok!). Ini memungkinkan cache hit pada blok 4, menunjukkan mengapa Anda harus menempatkan titik henti sebelum konten yang dapat diedit.

Kesimpulan utama: Selalu tetapkan titik henti cache eksplisit di akhir percakapan Anda untuk memaksimalkan peluang cache hit. Selain itu, tetapkan titik henti tepat sebelum blok konten yang mungkin dapat diedit untuk memastikan bagian tersebut dapat disimpan dalam cache secara independen.

Kapan menggunakan beberapa titik henti

Anda dapat menentukan hingga 4 titik henti cache jika Anda ingin:

• Menyimpan bagian berbeda dalam cache yang berubah pada frekuensi berbeda (misalnya, alat jarang berubah, tetapi konteks diperbarui setiap hari)
• Memiliki kontrol lebih besar atas apa yang disimpan dalam cache
• Memastikan penyimpanan cache untuk konten lebih dari 20 blok sebelum titik henti cache Anda
• Menempatkan titik henti sebelum konten yang dapat diedit untuk menjamin cache hit bahkan ketika perubahan terjadi di luar jendela 20 blok

Batasan cache

Panjang prompt yang dapat disimpan dalam cache minimum adalah:

• 4096 token untuk Claude Opus 4.5
• 1024 token untuk Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (deprecated), dan Claude Opus 3 (deprecated)
• 4096 token untuk Claude Haiku 4.5
• 2048 token untuk Claude Haiku 3.5 (deprecated) dan Claude Haiku 3

Prompt yang lebih pendek tidak dapat disimpan dalam cache, bahkan jika ditandai dengan cache_control. Permintaan apa pun untuk menyimpan lebih sedikit dari jumlah token ini dalam cache akan diproses tanpa penyimpanan cache. Untuk melihat apakah prompt disimpan dalam cache, lihat field 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 pakai 5 menit.

Memahami biaya titik henti cache

Titik henti 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 disimpan dalam cache digunakan (10% dari harga token input dasar)
• Token input reguler: Untuk konten apa pun yang tidak disimpan dalam cache

Menambahkan lebih banyak titik henti cache_control tidak meningkatkan biaya Anda - Anda masih membayar jumlah yang sama berdasarkan konten apa yang benar-benar disimpan dalam cache dan dibaca. Titik henti hanya memberi Anda kontrol atas bagian mana yang dapat disimpan dalam cache secara independen.

Apa yang dapat disimpan dalam cache

Sebagian besar blok dalam permintaan dapat ditunjuk untuk penyimpanan cache dengan cache_control. Ini termasuk:

• Alat: Definisi alat dalam array tools
• Pesan sistem: Blok konten dalam array system
• Pesan teks: Blok konten dalam array messages.content, untuk putaran pengguna dan asisten
• Gambar & Dokumen: Blok konten dalam array messages.content, dalam putaran pengguna
• Penggunaan alat dan hasil alat: Blok konten dalam array messages.content, dalam putaran pengguna dan asisten

Setiap elemen ini dapat ditandai dengan cache_control untuk mengaktifkan penyimpanan cache untuk bagian itu dari permintaan.

Apa yang tidak dapat disimpan dalam cache

Meskipun sebagian besar blok permintaan dapat disimpan dalam cache, ada beberapa pengecualian:

• Blok pemikiran tidak dapat disimpan dalam cache secara langsung dengan cache_control. Namun, blok pemikiran DAPAT disimpan dalam cache bersama konten lain ketika muncul dalam putaran asisten sebelumnya. Ketika disimpan dalam cache dengan cara ini, mereka MENGHITUNG sebagai token input ketika dibaca dari cache.

• Blok sub-konten (seperti citations) itu sendiri tidak dapat disimpan dalam cache secara langsung. Sebaliknya, simpan blok tingkat atas dalam cache.

  Dalam kasus kutipan, blok konten dokumen tingkat atas yang berfungsi sebagai materi sumber untuk kutipan dapat disimpan dalam cache. Ini memungkinkan Anda menggunakan penyimpanan cache prompt dengan kutipan secara efektif dengan menyimpan dokumen yang akan direferensikan oleh kutipan dalam cache.

• Blok teks kosong tidak dapat disimpan dalam cache.

Apa yang membatalkan cache

Modifikasi konten yang disimpan dalam 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 itu dan semua level berikutnya.

Tabel berikut menunjukkan bagian cache mana yang dibatalkan oleh berbagai jenis perubahan. ✘ menunjukkan bahwa cache dibatalkan, sementara ✓ menunjukkan bahwa cache tetap valid.

Melacak kinerja cache

Pantau kinerja cache menggunakan field respons API ini, dalam usage dalam 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 (yaitu, token setelah titik henti cache terakhir).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Praktik terbaik untuk penyimpanan cache yang efektif

Untuk mengoptimalkan kinerja penyimpanan cache prompt:

• Simpan konten stabil dan dapat digunakan kembali dalam cache seperti instruksi sistem, informasi latar belakang, konteks besar, atau definisi alat yang sering digunakan.
• Tempatkan konten yang disimpan dalam cache di awal prompt untuk kinerja terbaik.
• Gunakan titik henti cache secara strategis untuk memisahkan bagian awalan yang berbeda yang dapat disimpan dalam cache.
• Tetapkan titik henti cache di akhir percakapan dan tepat sebelum konten yang dapat diedit untuk memaksimalkan tingkat cache hit, terutama saat bekerja dengan prompt yang memiliki lebih dari 20 blok konten.
• Secara teratur analisis tingkat cache hit dan sesuaikan strategi Anda sesuai kebutuhan.

Mengoptimalkan untuk kasus penggunaan yang berbeda

Sesuaikan strategi penyimpanan cache prompt Anda dengan skenario Anda:

• Agen percakapan: Kurangi biaya dan latensi untuk percakapan yang diperpanjang, terutama yang memiliki instruksi panjang atau dokumen yang diunggah.
• Asisten pengkodean: Tingkatkan pelengkapan otomatis dan Q&A basis kode dengan menyimpan bagian yang relevan atau versi ringkasan basis kode dalam prompt.
• Pemrosesan dokumen besar: Gabungkan 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 penyimpanan cache prompt Anda dapat mencapai kinerja yang lebih baik dengan menyertakan 20+ contoh beragam jawaban berkualitas tinggi.
• Penggunaan alat agentic: Tingkatkan kinerja untuk skenario yang melibatkan beberapa panggilan alat dan perubahan kode berulang, 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 kepadanya.

Pemecahan masalah masalah umum

Jika mengalami perilaku yang tidak terduga:

• Pastikan bagian yang disimpan dalam cache identik dan ditandai dengan cache_control di lokasi yang sama di seluruh panggilan
• Periksa bahwa panggilan dilakukan dalam masa pakai cache (5 menit secara default)
• Verifikasi bahwa tool_choice dan penggunaan gambar tetap konsisten antara panggilan
• Validasi bahwa Anda menyimpan setidaknya jumlah token minimum dalam cache
• Sistem secara otomatis memeriksa cache hit pada batas blok konten sebelumnya (hingga ~20 blok sebelum titik henti Anda). Untuk prompt dengan lebih dari 20 blok konten, Anda mungkin memerlukan parameter cache_control tambahan lebih awal dalam prompt untuk memastikan semua konten dapat disimpan dalam cache
• Verifikasi bahwa kunci dalam blok konten tool_use Anda memiliki urutan yang stabil karena beberapa bahasa (misalnya Swift, Go) mengacak urutan kunci selama konversi JSON, memecahkan cache

Penyimpanan cache dengan blok pemikiran

Ketika menggunakan pemikiran yang diperluas dengan penyimpanan cache prompt, blok pemikiran memiliki perilaku khusus:

Penyimpanan cache otomatis bersama konten lain: Meskipun blok pemikiran tidak dapat secara eksplisit ditandai dengan cache_control, mereka disimpan dalam 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 menghitung sebagai token input dalam metrik penggunaan Anda. Ini penting untuk perhitungan biaya dan anggaran 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 dilepas
• Perilaku penyimpanan cache ini terjadi bahkan tanpa penanda cache_control eksplisit

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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

Ketika blok pengguna non-hasil-alat disertakan, itu menunjuk loop asisten baru dan semua blok pemikiran sebelumnya dihapus dari konteks.

Untuk informasi lebih terperinci, lihat dokumentasi pemikiran yang diperluas.

Penyimpanan cache dan berbagi

• Isolasi Organisasi: Cache terisolasi antara 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.

• Pembuatan Token Output: Penyimpanan cache prompt tidak memiliki efek pada pembuatan token output. Respons yang Anda terima akan identik dengan apa yang akan Anda dapatkan jika penyimpanan cache prompt tidak digunakan.

Durasi cache 1 jam

Jika Anda menemukan bahwa 5 menit terlalu singkat, Anthropic juga menawarkan durasi cache 1 jam dengan biaya tambahan.

Untuk menggunakan cache yang diperluas, sertakan ttl dalam definisi cache_control seperti ini:

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

Respons akan mencakup informasi cache terperinci seperti berikut:

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,

        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

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 dengan ritme teratur (yaitu, prompt sistem yang digunakan lebih sering daripada setiap 5 menit), terus gunakan 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 daripada 5 menit, tetapi lebih sering daripada setiap jam. Misalnya, ketika agen samping agentic akan memakan waktu lebih lama dari 5 menit, atau ketika menyimpan percakapan obrolan panjang dengan pengguna dan Anda umumnya mengharapkan pengguna tersebut mungkin tidak merespons dalam 5 menit berikutnya.
• Ketika latensi penting dan prompt tindak lanjut Anda mungkin dikirim di luar 5 menit.
• Ketika Anda ingin meningkatkan pemanfaatan batas laju Anda, karena cache hit tidak dikurangkan 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 lama harus muncul sebelum TTL lebih pendek (yaitu, entri cache 1 jam harus muncul sebelum entri cache 5 menit apa pun).

Saat mencampur TTL, kami menentukan tiga lokasi penagihan dalam prompt Anda:

1. Posisi A: Jumlah token pada cache hit tertinggi (atau 0 jika tidak ada hit).
2. Posisi B: Jumlah token pada blok cache_control 1 jam tertinggi setelah A (atau sama dengan A jika tidak ada).
3. Posisi C: Jumlah token pada blok cache_control terakhir.

Anda akan dikenakan biaya untuk:

1. Token pembacaan cache untuk A.
2. Token penulisan cache 1 jam untuk (B - A).
3. 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 penagihan yang berbeda, ditampilkan dalam kotak berwarna, sebagai hasilnya.

Contoh prompt caching

Untuk membantu Anda memulai dengan prompt caching, kami telah menyiapkan prompt caching cookbook dengan contoh terperinci dan praktik terbaik.

Di bawah ini, kami telah menyertakan beberapa cuplikan kode yang menampilkan berbagai pola prompt caching. Contoh-contoh ini menunjukkan cara mengimplementasikan caching dalam skenario berbeda, membantu Anda memahami aplikasi praktis dari fitur ini:

FAQ