Prompt caching

Prompt caching memungkinkan provider memakai ulang bagian awal prompt yang sudah pernah diprosesnya. Saat banyak request diawali teks yang sama, misalnya system prompt panjang, sekumpulan tools, atau dokumen besar, provider membaca bagian yang berulang dari cache dengan harga lebih murah. Ini biasanya mempersingkat waktu sampai response mulai muncul. Yang melakukan caching adalah provider. kenari meneruskan jumlah token cache di usage dan menagihnya pada baris harganya sendiri.

Bagaimana sebuah request di-cache

Cache mencocokkan bagian awal prompt, jadi urutan prompt-mu menentukan apa yang bisa dipakai ulang. Taruh konten yang tetap di depan: system prompt, definisi tools, dokumen referensi. Taruh yang berubah di belakang: pertanyaan user. Perubahan di mana pun pada bagian yang di-cache memutus kecocokan sejak titik itu.

Apa yang kamu kirim bergantung pada format API yang kamu panggil. Sebagian provider meng-cache awalan yang berulang dengan sendirinya. Provider lain hanya meng-cache bagian yang ditandai dengan cache_control.

Format yang kamu panggil	Yang dikirim
Chat completions	Tidak ada. Jika provider membutuhkan tanda, kenari menandai system prompt dan pesan terakhir untukmu.
Responses	Tidak ada. kenari menandai system prompt dan pesan terakhir untukmu jika provider membutuhkan tanda.
Messages	Tanda `cache_control` buatanmu sendiri. Tanda itu diteruskan apa adanya, dan kenari tidak menambah tanda. Request yang juga memuat server tool `kenari:` dibangun ulang oleh kenari, sehingga tandamu diganti dengan dua tanda otomatis.

Kamu tidak bisa melihat gaya API yang dipakai provider, jadi baca usage setelah request untuk mengetahui apakah ada yang di-cache. Di Messages, cache_control diabaikan jika provider meng-cache dengan sendirinya. Provider juga menetapkan panjang prompt minimum untuk caching, dan prompt yang lebih pendek tidak pernah di-cache.

Request Messages ini menandai system prompt yang panjang untuk di-cache. handbook.txt adalah contoh berkas teks yang cukup panjang untuk mencapai batas minimum provider:

import os

import anthropic

client = anthropic.Anthropic(
    base_url="https://kenari.id",
    api_key=os.environ["KENARI_API_KEY"],
)

with open("handbook.txt") as file:
    handbook = file.read()

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=512,
    system=[
        {"type": "text", "text": handbook, "cache_control": {"type": "ephemeral"}},
    ],
    messages=[{"role": "user", "content": "Berapa hari cuti tahunan yang saya dapat?"}],
)
print(message.usage)

Kirim request yang sama sekali lagi tidak lama kemudian. Jika model meng-cache prompt, message.usage.cache_read_input_tokens bernilai di atas 0 pada response kedua. Jika tetap 0, tidak ada yang di-cache.

Baca cache di usage

Setiap format melaporkan cache read di field-nya sendiri.

Format	Cache read	Cache write
Chat completions	`usage.prompt_tokens_details.cached_tokens`	Tidak dilaporkan
Messages	`usage.cache_read_input_tokens`	`usage.cache_creation_input_tokens`
Responses	`usage.input_tokens_details.cached_tokens`	Tidak dilaporkan

Format-format ini menghitung dengan cara berbeda:

Di Chat completions dan Responses, prompt_tokens atau input_tokens adalah seluruh prompt, dan cached_tokens adalah bagian darinya yang berasal dari cache.
Di Messages, input_tokens tidak termasuk token yang di-cache. Seluruh prompt adalah input_tokens + cache_read_input_tokens + cache_creation_input_tokens.

Field cache di Messages hanya muncul jika provider melaporkannya. Di response Chat completions non-streaming, cached_tokens bernilai 0 jika tidak ada yang di-cache. Di stream, prompt_tokens_details hanya ada jika ada yang di-cache.

Cara menghitung biaya cache

Setiap model punya harga Cache read dan Cache write di samping Input dan Output, di bagian pricing pada GET /v1/models. kenari menagih token cache dengan harga itu. Cara harga yang kosong beralih ke Input, dan rumus lengkapnya, ada di Cara penagihan.

Cache gratis di paket

Sebagian paket tidak menghitung token yang di-cache sebagai pemakaian kuota untuk model dalam daftar cache gratis paket itu. Harga katalog tidak berubah, tetapi token cache yang memenuhi syarat tidak dihitung sebagai pemakaian kuota dan tidak ikut dalam tagihan saldo setelah jendela habis. Lihat Langganan.

Gunakan key cache yang sama dalam satu percakapan

Agar request lanjutan memakai prefix cache yang sama, kirim string prompt_cache_key di Chat completions atau Responses, dan pakai nilai yang sama di setiap request dalam satu percakapan. Key yang valid dan tidak kosong yang kamu kirim didahulukan daripada key yang diturunkan kenari dari percakapan. kenari memangkas spasi di awal dan akhir, serta mengabaikan key kosong atau yang lebih panjang dari 512 byte, sehingga key turunan yang dipakai.

Dua kebiasaan menjaga cache tetap bekerja:

Jangan ubah system prompt atau pesan user pertama antar giliran.
Mulai percakapan dengan teks. Percakapan yang pesan user pertamanya tanpa teks, misalnya hanya gambar, tidak mendapat key otomatis, jadi kirim prompt_cache_key sendiri.

Batasan dan jebakan

Entri cache kedaluwarsa setelah batas waktu yang ditetapkan provider. Request pertama setelah itu adalah miss.
Tidak semua model meng-cache prompt. Periksa usage alih-alih berasumsi.
Request pertama untuk sebuah prompt pasti miss. Hit baru muncul mulai request kedua.
Hit tidak pernah dijamin. Baca usage untuk melihat apa yang terjadi, dan jangan membangun logika yang mengandalkan sebuah request pasti ter-cache.