Diagnostik cache

Prompt caching (caching prompt) memangkas latensi dan biaya secara signifikan, tetapi hanya jika bagian awal prompt Anda identik byte demi byte dengan permintaan terbaru. Alat yang diurutkan ulang, timestamp yang diinterpolasi ke dalam prompt sistem Anda, atau pengeditan pada pesan sebelumnya dapat secara diam-diam membatalkan cache. Tanpa diagnostik cache, satu-satunya sinyal adalah usage.cache_read_input_tokens yang turun menjadi nol, tanpa indikasi apa yang berubah.

Diagnostik cache menutup celah tersebut. Berikan id dari respons Anda sebelumnya, dan API akan membandingkan kedua permintaan tersebut dan memberi tahu Anda di mana keduanya mulai berbeda (model, prompt sistem, alat, atau riwayat pesan) sehingga Anda dapat memperbaiki akar penyebabnya alih-alih menebak-nebak.

Cara kerja diagnostik cache

Ketika beta header disertakan, API menyimpan "fingerprint" (sidik jari) ringan dari setiap permintaan, yang dikunci berdasarkan id respons. Pada permintaan berikutnya, sertakan id tersebut sebagai diagnostics.previous_message_id. API akan membangun ulang fingerprint untuk permintaan baru, membandingkannya dengan yang tersimpan, dan melampirkan objek diagnostics ke respons yang menjelaskan titik divergensi pertama.

Perbandingan ini berkaitan dengan struktur permintaan, terlepas dari apakah cache benar-benar hit. Lihat Membaca diagnostik bersama usage untuk mengetahui cara menggabungkan hasil diagnostics dengan usage.cache_read_input_tokens.

Fingerprint hanya berisi hash dan estimasi jumlah token (tidak pernah berisi konten prompt mentah), disimpan untuk waktu terbatas, dibatasi cakupannya pada organisasi dan workspace Anda, dan tidak digunakan untuk tujuan lain apa pun.

Penggunaan dasar

Kirim beta header pada setiap giliran. Pada giliran pertama, berikan "previous_message_id": null untuk ikut serta tanpa pesan sebelumnya yang dapat dibandingkan. Pada giliran berikutnya, berikan id dari respons sebelumnya.

Streaming

Dalam respons streaming, diagnostics muncul pada event message_start.

Event message_start membawa field diagnostics lengkap; lihat Format respons untuk nilai-nilai yang mungkin.

Meneruskan diagnostik melalui loop percakapan

Dalam percakapan multi-giliran, teruskan id respons terbaru sebagai previous_message_id pada setiap giliran. Iterasi pertama memberikan null untuk ikut serta; setiap iterasi berikutnya memberikan id dari respons sebelumnya.

Format respons

Field diagnostics pada Message respons memiliki empat kemungkinan status:

Ketika cache_miss_reason tidak null, bentuknya seperti ini:

{
  "id": "msg_01Xyz...",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "..." }],
  "usage": {
    "input_tokens": 42,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 41850,
    "output_tokens": 210
  },
  "diagnostics": {
    "cache_miss_reason": {
      "type": "system_changed",
      "cache_missed_input_tokens": 41850
    }
  }
}

Tipe alasan cache miss

cache_miss_reason adalah discriminated union berdasarkan type. Respons hanya melaporkan divergensi paling awal, jadi perbaiki itu terlebih dahulu; divergensi selanjutnya mungkin tersembunyi di baliknya.

Membaca diagnostik bersama usage

diagnostics menjawab "apakah permintaan saya berubah?" sementara usage.cache_read_input_tokens menjawab "apakah cache hit?". Menggabungkan keduanya memberi tahu Anda di mana harus mencari.

Matriks ini berlaku untuk giliran di mana Anda memberikan previous_message_id yang sebenarnya. Pada giliran pertama (previous_message_id: null), diagnostics selalu null dan cache_read_input_tokens biasanya nol karena cache sedang ditulis, bukan dibaca; tidak diperlukan pemecahan masalah. Matriks ini juga tidak berlaku ketika cache_miss_reason bernilai null (perbandingan masih tertunda; periksa giliran berikutnya) atau ketika type-nya adalah previous_message_not_found atau unavailable (tidak ada perbandingan yang dihasilkan).

Batasan

• Beta: Nama field dan semantik dapat berubah sebelum ketersediaan umum.
• Hanya Claude API: Tidak tersedia di Amazon Bedrock atau Vertex AI.
• Retensi terbatas: Fingerprint untuk pencarian previous_message_id kedaluwarsa setelah periode singkat. Jalankan perbandingan diagnostik antara permintaan yang berdekatan waktunya.
• Workspace yang sama: Permintaan sebelumnya harus dibuat dengan kunci API dari organisasi dan workspace yang sama.
• Cakrawala perbandingan: Untuk percakapan yang sangat panjang di mana satu-satunya perubahan berada jauh di dalam daftar pesan, respons mungkin berupa unavailable alih-alih lokasi yang tepat.
• Best-effort: Diagnostik tidak pernah memblokir atau menggagalkan permintaan Anda. Jika informasi diagnostik tidak tersedia, respons mengembalikan unavailable, atau cache_miss_reason: null ketika perbandingan masih berjalan.

Retensi data

Diagnostik cache memenuhi syarat ZDR (qualified). Anthropic tidak menyimpan teks mentah dari prompt Anda atau output Claude untuk fitur ini.

Fingerprint yang disimpan untuk setiap permintaan hanya terdiri dari hash kriptografis dan estimasi jumlah token, dikunci berdasarkan id respons dan dibatasi cakupannya pada organisasi dan workspace Anda. Fingerprint kedaluwarsa setelah periode singkat dan tidak digunakan untuk tujuan lain apa pun.

Untuk kelayakan ZDR di seluruh fitur, lihat API dan retensi data.

Lihat juga

• Caching prompt
• Penghitungan token
• Beta header