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:

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-opus-4-20250514",
    "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
JSON
{"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” 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:

  1. Sistem memeriksa apakah awalan prompt, hingga titik cache yang ditentukan, sudah di-cache dari kueri sebelumnya.
  2. Jika ditemukan, sistem menggunakan versi yang di-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 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:

ModelBase Input Tokens5m Cache Writes1h Cache WritesCache Hits & RefreshesOutput 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:

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 menyimpan konten permintaannya (bukan responsnya)
# Cache mencakup: pesan pengguna, thinking_block_1, blok penggunaan alat 1, dan 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]
# Blok pengguna non-hasil-alat menyebabkan semua blok pemikiran diabaikan
# Permintaan ini diproses seolah-olah blok pemikiran tidak pernah ada

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:

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

Respons akan menyertakan 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 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:

  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.

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:

  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 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:


FAQ