Diagnostik cache

Prompt caching (caching prompt) memangkas latensi dan biaya secara signifikan, tetapi hanya ketika 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 dan memberi tahu Anda di mana keduanya menyimpang (model, prompt sistem, alat, atau riwayat pesan) sehingga Anda dapat memperbaiki akar penyebabnya alih-alih menebak-nebak.



Cara kerja diagnostik cache

Ketika header beta ada, API menyimpan fingerprint ringan dari setiap permintaan, yang dikunci oleh id respons. Pada permintaan Anda berikutnya, sertakan id tersebut sebagai diagnostics.previous_message_id. API 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 cara menggabungkan hasil diagnostics dengan usage.cache_read_input_tokens.

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



Penggunaan dasar

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

client = anthropic.Anthropic()

SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"

# Giliran 1: ikut serta dengan previous_message_id=None
r1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[{"role": "user", "content": "Summarize section 1."}],
    diagnostics={"previous_message_id": None},
    betas=["cache-diagnosis-2026-04-07"],
)

# Giliran 2: rujuk id respons sebelumnya
r2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[
        {"role": "user", "content": "Summarize section 1."},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Now summarize section 2."},
    ],
    diagnostics={"previous_message_id": r1.id},
    betas=["cache-diagnosis-2026-04-07"],
)

diagnostics = r2.diagnostics
if diagnostics is None:
    print("No divergence detected.")
elif diagnostics.cache_miss_reason is None:
    print("Comparison still pending.")
else:
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")



Streaming

Dalam respons streaming, diagnostics muncul pada event message_start.

# Giliran 2: streaming, dengan merujuk id respons sebelumnya
with client.beta.messages.stream(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[
        {"role": "user", "content": "Summarize section 1."},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Now summarize section 2."},
    ],
    diagnostics={"previous_message_id": r1.id},
    betas=["cache-diagnosis-2026-04-07"],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print()
    r2 = stream.get_final_message()

diagnostics = r2.diagnostics
if diagnostics is None:
    print("No divergence detected.")
elif diagnostics.cache_miss_reason is None:
    print("Comparison still pending.")
else:
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

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, tampilannya 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 pada type. Respons hanya melaporkan divergensi paling awal, jadi perbaiki itu terlebih dahulu; divergensi berikutnya 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).



Keterbatasan

• Beta: Nama field dan semantik dapat berubah sebelum ketersediaan umum.
• Hanya Claude API: Tidak tersedia di Amazon Bedrock atau Google Cloud.
• Retensi terbatas: Fingerprint untuk pencarian previous_message_id kedaluwarsa setelah periode singkat. Jalankan perbandingan diagnostik antara permintaan yang berjarak dekat.
• Workspace yang sama: Permintaan sebelumnya harus dibuat dengan kunci API dari organisasi dan workspace yang sama.
• Horizon 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 oleh id respons dan dibatasi pada organisasi dan workspace Anda. Fingerprint kedaluwarsa setelah periode singkat dan tidak digunakan untuk tujuan lain apa pun.

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



Lihat juga

• Prompt caching
• Penghitungan token
• Header beta