Claude prompt önbellekleme — oranlar, kullanım nesnesi ve geçidin arkasında isabet oranlarının neden düştüğü

İstem önbelleğe alma, bir aracının faturasında tek başına en büyük kaldıraçtır ve sessizce çalışmama ihtimali en yüksek özelliktir. Doğru işaretlendiğinde isteğinizin tekrarlanan kısmı, girdi ücretinin onda biri üzerinden faturalandırılır. Yanlış işaretlendiğinde — veya önekinizi yeniden yazan bir şey üzerinden yönlendirildiğinde — düz ücretten daha yüksek faturalandırılır; çünkü hiç kimsenin okumadığı önbellek girdilerini yazmak için ödeme yaparsınız.

Mekanizma başka yerlerde iyi belgelenmiştir. Hiçbir yerde belgelenmeyen şey, isteğin bir gateway üzerinden geçtiğinde neyin değiştiğidir; bunu okuyan insanların çoğu bu durumdadır. Her ikisi de aşağıda açıklanıyor.

Mekanizma kısaca

Sabit bir öneki — sistem istemi, araç şeması veya belge — işaretlersiniz ve sağlayıcı bunun işlenmiş hâlini saklar. Öneki tam olarak eşleşen sonraki istek, yeniden işlemek yerine onu geri okur.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

Tüm işi yapan ve tüm sorunlara yol açan iki özellik vardır. Eşleşme bir önek üzerinden yapılır; bu nedenle başlarda değişen herhangi bir şey, kendisinden sonraki her şeyi geçersiz kılar. Ayrıca bir girdinin bir yaşam süresi vardır; bu nedenle turlar arasında uzun boşluklar bulunan bir konuşma okumak yerine yeniden oluşturur.

Maliyeti

Üçüncü sütun standart oranı gösterir: okuma, girdinin onda birine mal olur. Dördüncü de standarttır — bir önbellek yazma işlemi girdinin 1,25×'ine mal olur; bu, Anthropic'in beş dakikalık bir girdi için listelediği çarpandır — ve her iki oran da Kunavo'nun girdi fiyatına uygulandığından her biri, Anthropic listesine göre model girdisiyle aynı indirime sahiptir. Kunavo'nun Anthropic'ten ayrıldığı nokta bir saatlik girdidir: Anthropic bu yazmayı girdinin 2×'si olarak listelerken Kunavo bunu aynı 1,25× üzerinden faturalandırır. Bu, özellikle sık yeniden oluşturulan iş yükleri — uzun süre çalışan aracılar, yavaş ilerleyen konuşmalar ve öneki sık değişen her şey — için önemlidir; çünkü yazmaların, okumaların değil, faturanın önbellek satırına hükmettiği iş yükleri bunlardır.

Her iki rakam da oluşturma sırasında katalogdan okunur; fiyatlandırma tablosunun ve Claude hesaplayıcının okuduğu kaynak aynıdır — bu sayfada elle girilmiş ücret yoktur.

Kullanım nesnesini okuma

Önbellek davranışını faturadan çıkarmayın; her yanıt bunu size doğrudan söyler ve üç token sayısı tüm teşhisi oluşturur.

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

Gateway arkasında isabet oranları neden düşer?

Önbellek onu oluşturan upstream'de yaşar ve önek eşleşmesi tamdır. Bu iki gerçek, tek bir sağlayıcıyı doğrudan çağırdığınızda hiç oluşmayan üç hata modu ortaya çıkarır:

Yönlendirme değişti. Ardışık istekler farklı upstream'lere ulaşırsa ikincisi önbellek bulamaz — ilkinin yazdığı girdi, ikincinin çalıştığı yerden görünmez. Bu durum kendi günlüklerinizde görünmez ve yalnızca okuma olması gerekirken görülen önbellek oluşturma sayısı olarak ortaya çıkar. En yaygın neden budur ve upstream'ler arasında serbestçe yeniden yönlendirme yapan bir gateway'in token başına daha ucuz, oturum başına daha pahalı olmasının sebebidir.

Önekinizin önüne bir şey eklendi. Sistem mesajını yeniden yazan, araç tanımlarını normalleştiren veya alanları yeniden sıralayan bir katman farklı bir önek üretir; farklı bir önek de isabetsizdir. Hiçbir hata oluşmaz; yalnızca fatura yükselir.

Boşluk, girdinin yaşam süresini aştı. Turlar arasında birkaç dakika düşünen bir aracı her seferinde yeniden oluşturabilir. Bu, gateway'den ziyade iş yükünüzün özelliğidir, ancak ilkiyle kötü etkileşir: yeniden oluşturma aynı zamanda yeniden yönlendirme fırsatıdır.

Üçünün de teşhisi aynıdır — bir oturum boyunca cache_creation_input_tokens değerini izleyin. Düz ve yüksek olması yeniden oluşturduğunuz anlamına gelir. Bir kez yüksek, sonrasında sıfır olması çalıştığını gösterir. Kunavo'da istek düzeyindeki maliyet ve önbelleğe alınan token sayıları kullanım görünümünde bulunur; önbelleğe alma referansı uç noktasına ilişkin ayrıntıları içerir.

Bununla ne yapmalı?

Önbelleğe alınan öneki gerçekten sabit tutun — istek başına değişen her şeyi işaretli bloğun ardına koyun, asla önüne değil. Kısa ömürlü bir girdinin düşmanı boşta kalma süresi olduğundan, mümkün olan yerlerde bir aracının turlarını birbirine daha yakın toplu hâle getirin. Ayrıca tek bir istek yerine oturumu uçtan uca ölçün: önbelleğe alma bir istek dizisinin özelliğidir ve istek başına tahmin bunu göremez. Claude token maliyeti hesaplayıcıda tam da bu nedenle önbelleğe alınan token alanı vardır — bunu isteminizin gerçekten tekrarlanan kısmının oranına ayarlayın; aylık rakam kurgu olmaktan çıkar.

Sık sorulan sorular