Claude API önbelleği: kısa istemde hiç çalışmayabilir

Claude API’de istem önbelleğini kullanmak için tekrar kullanılacak sabit öneğin sonuna cache_control ekleyin; kullanıcı sorusu, zaman damgası ve araç sonucu gibi değişken içeriği bu sınırdan sonra gönderin. Fakat önek seçilen modelin asgari token eşiğini aşmıyorsa istek normal biçimde işlenir, hata dönmez ve önbellek oluşmaz.

Ekonomik sonuç da yalnızca cache_control eklenmesine bağlı değildir. İlk çağrı daha pahalı bir önbellek yazımıdır; tasarruf, aynı önek TTL dolmadan yeterli sayıda yeniden okunduğunda başlar. Bu yüzden önek uzunluğunu, değişmezliğini, tekrar aralığını ve çağrı sayısını birlikte hesaplamak gerekir.

Kısa istem neden önbelleğe girmeyebilir?

Anthropic’in istem önbelleği belgesine göre asgari uzunluk modele göre değişir: Claude Fable 5.1, Mythos 5.1, Opus 5 ve Fable 5 için 512; Opus 4.8, Sonnet 5, Sonnet 4.6 ve Sonnet 4.5 için 1.024; Opus 4.7 için 2.048; Opus 4.6, Opus 4.5 ve Haiku 4.5 için 4.096 token gerekir. Daha kısa bir önek cache_control taşısa bile önbelleğe alınmaz ve bu nedenle hata oluşmaz.

Başlıktaki “hiç çalışmayabilir” ifadesinin sınırı budur: API çağrısı başarısız olmaz, yalnızca önbellekleme devreye girmez. Örneğin Claude Sonnet 4.6’ya gönderilen 700 tokenlık sabit sistem istemi, kaç kez yinelenirse yinelensin 1.024 token eşiğinin altında kalır. İstemi anlamsız metinle şişirmek yerine her çağrıda gerçekten gereken politika, örnek, araç tanımı veya referans içeriğini aynı sabit önekte toplamak daha doğru olur.

İlk yanıttaki cache_creation_input_tokens alanı yazılan token sayısını göstermelidir. Aynı önekle yapılan sonraki çağrıda cache_read_input_tokens sıfırdan büyük olmalıdır. İki değer de sıfırsa önce model eşiğini, sonra cache_control konumunu ve önekin aynı kalıp kalmadığını kontrol edin.

Beş dakika ve bir saat için başa baş hesabı

Resmî Claude fiyat tablosunda beş dakikalık yazma çoğu modelde standart giriş fiyatının 1,25 katı, bir saatlik yazma 2 katı ve önbellek okuması 0,1 katı olarak fiyatlanıyor. Claude Fable 5.1 ve Mythos 5.1 okumalarında 0,025 katlık istisna bulunuyor; aşağıdaki hesap Sonnet 4.6 gibi 0,1 katsayılı modeller içindir.

Önbelleğe uygun token sayısı C, standart giriş token fiyatı P ve aynı önekle toplam çağrı sayısı N olsun. Önbelleksiz maliyet N × C × P’dir. Beş dakikalık seçenek C × P × [1,25 + 0,1 × (N−1)], bir saatlik seçenek ise C × P × [2 + 0,1 × (N−1)] tutar. İki durumda da bulunan değişken sonek ve çıktı maliyetleri karşılaştırmadan çıkarılmıştır.

• 5 dakikalık TTL: Bir yazma ve bir okuma 1,35 birim, aynı önekin iki kez normal işlenmesi 2 birimdir. İlk okuma, yani toplam ikinci çağrı tasarruf sağlar.
• 1 saatlik TTL: Bir yazma ve bir okuma 2,1 birimdir; iki normal çağrının 2 birimlik maliyetinden yüksektir. İkinci okuma geldiğinde toplam 2,2 birim, üç normal çağrının maliyeti ise 3 birim olur.

Koşullu örnekte Claude Sonnet 4.6 ile 10.000 tokenlık bir önek kullanalım. Standart giriş fiyatı milyon token başına 3 dolar olduğundan normal işleme 0,03 dolar tutar. İki çağrı önbelleksiz 0,06 dolarken beş dakikalık bir yazma ve bir okuma 0,0405 dolardır; yalnızca sabit önek üzerindeki tasarruf yüzde 32,5 olur.

Aynı iki çağrı bir saatlik TTL ile 0,063 dolara çıkar ve henüz avantaj sağlamaz. Üç çağrıda önbelleksiz maliyet 0,09 dolar, bir saatlik yazma ile iki okuma 0,066 dolardır; fark yaklaşık yüzde 26,7’dir. Sonuç olarak beş dakika içinde en az bir okuma, bir saatlik seçenek içinse en az iki okuma beklenmiyorsa ilgili yazma maliyeti kendini karşılamaz.

Sabit sistem istemini değişken araç sonucundan ayırın

Claude API öneki tools, system ve messages sırasıyla oluşur. Nadir değişen araç tanımlarını ve sistem talimatlarını önce yerleştirin; her çağrıda değişen araç sonucunu ve kullanıcı sorusunu messages içinde bunlardan sonra gönderin. Açık önbellek sınırı, aynı kalmasını istediğiniz son içerik bloğunda bulunmalıdır.

Python SDK düzeni: SYSTEM = [{"type": "text", "text": STATIC_POLICY, "cache_control": {"type": "ephemeral", "ttl": "1h"}}] tanımını oluşturun. Ardından messages = [{"role": "user", "content": [{"type": "text", "text": "Araç sonucu: " + tool_output + "\nSoru: " + question}]}] değerini client.messages.create(model="claude-sonnet-4-6", max_tokens=800, system=SYSTEM, messages=messages) çağrısına verin.

Bu yapıda STATIC_POLICY önbelleğe yazılabilir; tool_output ve question ise değişken sonek olarak normal işlenir. Araç tanımları da isteğe ekleniyorsa bunların sistem alanından önce geldiğini unutmayın: bir araç şemasını değiştirmek, ardından gelen sistem ve mesaj öneklerini de geçersiz kılabilir.

Çok turlu konuşmalarda istek düzeyindeki cache_control otomatik olarak son uygun bloğa ilerlediği için daha az kod gerektirir. Her çağrıda değişen bir son blok varsa açık sınır daha güvenlidir; aksi halde yeni değer farklı bir önek oluşturabilir ve tekrar tekrar yazma ücreti doğurabilir.

Öneğin gerçekten yeniden kullanıldığını ölçün

Önbellek anlamsal benzerliği değil, aynı başlangıç dizisini eşleştirir. Önbellek sınırından önceki sistem metnini, araç tanımını veya başka bir bloğu değiştirmek yeni bir önek üretir. Modeli değiştirmek de ayrı bir önbellek alanına geçmek anlamına gelir.

Her yanıt için cache_creation_input_tokens, cache_read_input_tokens ve input_tokens değerlerini kaydedin. Toplam giriş miktarı bu üç alanın toplamıdır; input_tokens yalnızca son önbellek sınırından sonraki normal işlenen kısmı gösterir. Gerçek maliyeti hesaplarken yazılan ve okunan tokenları kendi katsayılarıyla fiyatlandırın: yüksek görünen bir isabet oranı, özellikle bir saatlik pahalı ve sık tekrarlanan yazmaları tek başına açıklamaz.

TTL, yanıtın bitişinden değil isteğin başlangıcından ölçülür ve her başarılı okuma süreyi yeniler. Uzun süren bir yanıt beş dakikalık pencerenin bir bölümünü tüketebileceği için sonraki isteğin ne zaman başladığını da ölçüme katın. Paralel çağrılarda ise ilk önbellek girdisi, ilk yanıt üretilmeye başlayıncaya kadar diğer istekler tarafından kullanılamaz.

Üretim kararını iş yüküne göre verin

Önce gerçek trafik kayıtlarından sabit önek uzunluğunu ve aynı öneğin seçilen TTL içinde kaç kez tekrarlandığını çıkarın. İlk çağrıda yazma, sonraki çağrılarda okuma görmeden teorik tasarruf oranını üretim beklentisi olarak kullanmayın.

1. Önekin kullanılan modelin asgari token eşiğini geçtiğini doğrulayın.
2. Değişken içeriği açık önbellek sınırından sonraya taşıyın.
3. Beş dakika içinde ikinci çağrı bekleniyorsa varsayılan TTL’nin maliyetini hesaplayın.
4. Aralık beş dakikayı aşıyor, fakat bir saat içinde en az üç toplam çağrı oluşuyorsa bir saatlik TTL’yi karşılaştırın.
5. Her istem sürümü için yazma, okuma ve normal giriş tokenlarını ayrı izleyin.

Bağımsız bir 500’den fazla ajan oturumunu kapsayan değerlendirme, DeepResearch Bench üzerinde 10.000 tokenlık sistem istemleriyle sağlayıcılar genelinde API maliyetinin yüzde 41–80, ilk token süresinin yüzde 13–31 azalabildiğini buldu. Çalışmada dinamik içeriği sona taşıyan ve değişken araç sonuçlarını önbellek dışında bırakan sınırlar, tüm bağlamı gelişigüzel önbelleğe almaktan daha tutarlı yarar sağladı.

Bu oranlar uzun ve tekrarlanan ajan oturumlarına aittir; kısa veya seyrek yinelenen her iş yükü için garanti değildir. Claude API önbelleğinin ekonomik olup olmadığı, model eşiği geçildikten sonra ölçülen gerçek yazma ve okuma sayılarıyla belirlenmelidir.

Ayrıca okuyun:

• Claude Code’da onayları kapatmak yerine izinleri böyle sınırlayın
• Claude güvenlik araştırmacılarını geçti, ama ölçümün bir sınırı var
• Claude 10 bin bilim insanına açıldı, kritik biyoloji erişimi sınırlı