Uzun bir sistem istemi—RAG bağlamı, araç kataloğu, aracı kuralları, örnekler—gönderiyorsanız muhtemelen her çağrıda tam giriş fiyatını ödüyorsunuz. Anthropic'in istem önbelleğe alması, önbelleğe alınan bölümde bunu ücretin %10'una düşürür. OpenAI de aynı şeyi örtük olarak yapar. Çoğu ekip bunun 30 dakikalık çalışmaya değdiğini görür; çünkü giriş maliyeti satırını güvenilir biçimde %60–90 azaltır.
Kunavo ikisini de destekler. Kendi cache_control eşik noktalarınız Messages API'den değiştirilmeden geçer; biçimde böyle bir alan gönderecek yer bulunmayan Chat Completions ve Responses API'lerinde Kunavo bunları sizin için ayarlar ve gönderdiğiniz içeriğin etrafını, 4 sınırını hiçbir zaman aşmadan tamamlar. Bu yazı her ikisini, önbellekleri sessizce geçersiz kılan tuzakları ve isabet oranınızı nasıl doğrulayacağınızı anlatır.
Öncesi ve sonrası
Aynı 18K token'lık sistem istemini on kez gönderen naif döngü:
# What most people start with: every call re-pays for the whole prompt.
import anthropic
client = anthropic.Anthropic(
api_key="sk-kn-...",
base_url="https://api.kunavo.com",
)
SYSTEM = open("system-prompt.md").read() # 18,000 tokens of rules + examples
# 10 user questions in a session. Every call sends the 18K-token system block.
for question in questions:
resp = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=600,
system=SYSTEM,
messages=[{"role": "user", "content": question}],
)
# Cost per call (input only): 18,000 × $3 / 1M = $0.054
# 10 calls: $0.54 in input alone.Şimdi sistem bloğunu önbelleğe alınabilir olarak işaretleyin—tek bir ek alan:
# The fix: mark the static prefix as cacheable. After the first call,
# subsequent calls within ~5 minutes pay 10% the input rate on the cached
# portion. Same answer, 89% cheaper.
resp = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=600,
system=[
{
"type": "text",
"text": SYSTEM,
"cache_control": {"type": "ephemeral"}, # mark cacheable
}
],
messages=[{"role": "user", "content": question}],
)
# First call (cache write): 18,000 × $3.75 / 1M = $0.0675 (1.25× input)
# Calls 2–10 (cache hit): 18,000 × $0.30 / 1M = $0.0054 each
# Total: $0.0675 + 9 × $0.0054 = $0.116 (was $0.54 — 78.5% saved)Bu oturumda giriş maliyetinin %78,5'ini tasarruf ettiniz. İlk çağrı, önbelleği yazmak için giriş ücretinin yaklaşık 1.25 katını ödediğinden naif sürümden biraz daha pahalıdır. 2–10. çağrılar ücretin %10'unu öder. Başabaş noktası 2. çağrıdır; 3. çağrıda öne geçersiniz. 10. çağrıda fark çok büyüktür.
OpenAI tarzı: yapılacak hiçbir şey yok
OpenAI Chat Completions biçiminde cache_control alanı yoktur; çünkü OpenAI kendi sunucularında örtük olarak önbelleğe alır. Claude ise bunu yapmaz; yalnızca bir eşik noktasının işaretlediği içeriği önbelleğe alır. Bu nedenle bir Claude modeline /v1/chat/completions veya /v1/responses üzerinden ulaştığınızda Kunavo eşik noktalarını sizin adınıza ayarlar: konuşmada en az bir assistant dönüşü olduğunda son mesaja kayan bir eşik noktası, ardından system sonrasında ve tools sonrasında birer tane. Modelin ilk yanıtından sonra gönderilen bir system veya developer mesajı system içine taşınmaz, konuşmada kalır (kendi eşik noktası bir saatlik önbellek istemiyorsa). İstek böyle bir mesajla bitiyorsa kayan eşik noktası onun hemen önündeki bloğa konur; kalan eşik noktaları da ardından hâlâ başka içerik gelen son birkaç böyle mesajın hemen önüne konur. Sizin belirlediğiniz noktalar tam olarak yerlerinde bırakılır—Kunavo yalnızca boş bıraktığınız konumları doldurur ve bunu yalnızca toplam 4 sınırına kadar yapar. Yapılandırılacak bir şey yoktur; Anthropic veya OpenAI yolundan gelmenize bakılmaksızın aynı model aynı maliyete sahiptir:
# OpenAI Chat Completions style — Kunavo sets the breakpoints for you.
# No flag to set. The "usage" object tells you what was cached.
from openai import OpenAI
client = OpenAI(
api_key="sk-kn-...",
base_url="https://api.kunavo.com/v1",
)
resp = client.chat.completions.create(
model="claude-sonnet-4-6",
messages=[
{"role": "system", "content": LONG_SYSTEM_PROMPT}, # >1024 tokens
{"role": "user", "content": "Latest question…"},
],
)
# In the response:
# resp.usage.prompt_tokens_details.cached_tokens → 17,800
# resp.usage.prompt_tokens → 18,200
# 17.8K/18.2K = 98% of input came from cache. Bill reflects that automatically.Önbellekten ne kadarının sunulduğunu görmek için usage.prompt_tokens_details.cached_tokens okuyun. Sabit önek ne kadar büyükse tasarruf da o kadar büyüktür. Temel kural: sistem isteminiz değişken kullanıcı içeriğinizden kısaysa önbellekleme pek işe yaramaz. İstemi, statik parçalar büyük olacak ve başta yer alacak şekilde yeniden düzenleyin.
Çok katmanlı önbellekleme—en fazla 4 eşik noktası
Bazı katmanların diğerlerinden daha hızlı değiştiği aracı döngülerinde birden çok cache_control eşik noktası belirleyin. Her biri, o noktaya kadar olan her şeyin anlık görüntüsüdür:
# Anthropic supports up to 4 cache breakpoints per request — use them
# to keep the cache hot even as later layers change.
client.messages.create(
model="claude-sonnet-4-6",
max_tokens=600,
system=[
{"type": "text",
"text": ROLE_AND_RULES, # ~3,000 tokens
"cache_control": {"type": "ephemeral"}}, # breakpoint 1
{"type": "text",
"text": LARGE_KNOWLEDGE_BASE, # ~15,000 tokens, rarely changes
"cache_control": {"type": "ephemeral"}}, # breakpoint 2
],
messages=[
{"role": "user",
"content": [
{"type": "text",
"text": CONVERSATION_HISTORY, # grows each turn
"cache_control": {"type": "ephemeral"}}, # breakpoint 3
{"type": "text", "text": new_question},
]},
],
)
# When CONVERSATION_HISTORY changes, breakpoints 1+2 still hit cache.
# Only breakpoint 3 + the new question pay full input rate.Önbellek anahtarı tüm önektir. N konumuna bir token eklerseniz N'deki veya sonrasındaki her eşik noktası geçersiz kılınır. Sıra önemlidir: en kararlı içerik önce. Kurallar katmanı nadiren değişmeli; bilgi tabanı haftalık güncellenmeli; konuşma her turda büyümelidir.
Önbelleği sessizce bozan yaygın yollar
- Geçerli tarihi veya bir request_id'yi isteme koymak. Her çağrı yeni bir önek oluşturur ve önbellek isabet oranı %0 olur. İstem girdilerinizi hash'leyip çağrılar arasında karşılaştırın.
- Deterministik olmayan sistem istemi oluşturma. Sistemi bir dict'ten oluşturuyorsanız bazı Python sürümlerinde dict yineleme sırası önemlidir. Anahtarları açıkça sıralayın.
- Önbellek ömrü yaklaşık 5 dakikadır. Seyrek trafik düzenleri (10 dakikada bir çağrı) hiç isabet alamaz. Çağrıları toplu çalıştırın veya kaybı kabul edin.
- 1.024 token minimumu. 1K token'ın altında OpenAI tarzı önbellekleme devreye girmez. Küçük statik parçaları tek ve daha uzun bir önekte birleştirin.
- Araçlar / işlev tanımları öneğin parçasıdır. Kataloğa yeni bir araç eklemek herkes için önbelleği geçersiz kılar. Araç kataloğunu sabit tutun ve sürümleyin.
İsabet oranını doğrulama
Göremediğiniz önbellekleme mühendislik değil, umuttur. Her çağrıda usage kaydedin:
# Always read usage. If cached_tokens is 0 when you expected a hit,
# something's wrong — usually a non-deterministic prefix.
resp = client.messages.create(...)
u = resp.usage
print({
"input_uncached": u.input_tokens,
"input_cache_read": u.cache_read_input_tokens,
"input_cache_write": u.cache_creation_input_tokens,
"output": u.output_tokens,
})
# A common gotcha: putting today's date or a request_id in the system prompt
# silently invalidates the cache. Hash your inputs; verify cache_read_input_tokens
# is non-zero on the 2nd identical call.Kunavo kontrol panelindeki Kullanım sayfası, model ve gün bazında önbellek dağılımını gösterir. Toplam girişin yüzdesi olarak cache_read_input_tokens büyüyorsa önbellekleme çalışıyor demektir. 0'da kalıyor veya büyük ölçüde dalgalanıyorsa yukarıdaki tuzak listesini gözden geçirin.
Kunavo'da gerçek maliyet
Her modelin önbellek ücreti fiyatlandırma sayfasında yayımlanır:
- Anthropic modelleri: önbellek okuma ücreti, giriş ücretinin 10% oranındadır — Claude Fable 5.1 için %2,5, Claude Opus 5.5 için %5. Önbellek yazmaları giriş ücretinin 1.25 katıdır—Anthropic'in beş dakikalık çarpanı—ve Kunavo, bir saatlik yazmaları Anthropic'in 2 katının altında, aynı 1.25 kat üzerinden faturalandırır.
- OpenAI / Gemini modelleri: önbellek okumalarında giriş ücretine uygulanan oran 10% olarak belirlenmiştir (sağlayıcıların yayımladığı oran). Önbellek yazmaları GPT-5.6 ve GPT-6 Astra'da giriş ücretinin 1.25 katı, diğer tüm modellerde normal giriş ücretidir.
- Tüm önbellek fiyatlarına Kunavo'nun model indirimi zaten dahildir (modele göre üst akış liste fiyatının altında). Bu nedenle Kunavo'da Sonnet 4.6 önbellek okumasının maliyeti şu şekilde hesaplanır:
$3 × 0.40 × 0.10 = $0.12 per 1M tokens. Önbelleksiz üst akış fiyatından yaklaşık 25 kat daha ucuzdur.
Önbelleklemenin yanıt olmadığı durumlar
Çalışmanın değmeyeceği birkaç durum:
- Kısa istemler (toplam <1K token). Ek yük baskındır; uğraşmayın.
- Tekrarlanan trafik olmayan tek seferlik görevler. İlk çağrı biraz daha pahalıdır; önbellekleme yalnızca 2. çağrıdan itibaren kendini amorti eder.
- Yüksek çıktı, düşük giriş gerektiren görevler (yaratıcı yazım, kod üretimi). Giriş zaten faturanın küçük bir bölümüdür. Bunun yerine çıktı bütçesi sınırlarına odaklanın.
Diğer her şey için—RAG sohbet botları, sabit araç kataloğuna sahip aracılar, statik değerlendirme ölçütü üzerinde çalışan sınıflandırıcılar, tutarlı few-shot örnekleri kullanan yapılandırılmış çıkarım hatları—önbellekleme tek bir öğleden sonra uygulanabilecek en yüksek getirili optimizasyondur. Bunu maliyet optimizasyonu kılavuzumuzdaki diğer dört teknikle birleştirirseniz çıktı kalitesinden tek bir ödün vermeden %70 maliyet azalması gerçekçidir.
Zaten Kunavo'da mısınız? /app/usage adresini açın ve en büyük modelinizin önbellek sütununu kontrol edin. Sıfırsa parayı masada bırakıyorsunuz. Tam kılavuz: /docs/caching.