İstem önbelleğe alma

30 bin token'lık bir sistem isteminde Claude Sonnet 5 ile önbellek okuma maliyeti $1.4 / 1M yerine $0.14 / 1M olur. Oturum başına aynı bağlamı 50 kez yeniden gönderen bir ajan için önbellek, girdi faturasını yaklaşık %90 azaltır.

Nasıl etkinleştirilir

Herhangi bir sistem bloğuna, mesaja veya araç tanımına bir cache_control: { type: "ephemeral" } kesme noktası ekleyin. Model ilk çağrıda bu noktaya kadarki bölümü önbelleğe alır; aynı önek baytlarını paylaşan sonraki çağrılar önbelleği kullanır.

from openai import OpenAI

client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

# Mark the large, stable prefix once with cache_control.
# Every subsequent call that sends the same prefix reads it back
# from cache at 0.10× the input rate on Claude Sonnet 5.
# Per-model rates are in the pricing table below.
SYSTEM = [
    {
        "type": "text",
        "text": open("long_system_prompt.txt").read(),
        "cache_control": {"type": "ephemeral"},
    },
]

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": "Summarize the doc above in 3 bullets."},
    ],
)

u = resp.usage
# OpenAI-compat fields populated by Kunavo:
# - prompt_tokens_details.cached_tokens — read from cache
# - cache_creation_input_tokens          — written to cache this call
print(u.prompt_tokens_details.cached_tokens,
      getattr(u, "cache_creation_input_tokens", 0))

Anthropic'in kendi Messages API'sinde aynı veri iletim biçimi kullanılır — cache_control Claude'a çevrilmeden aktarılır:

# Native Anthropic Messages API — cache_control passes through untranslated.
curl https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "system": [
      {
        "type": "text",
        "text": "<your large stable system prompt>",
        "cache_control": { "type": "ephemeral" }
      }
    ],
    "messages": [
      { "role": "user", "content": "Summarize the doc above in 3 bullets." }
    ],
    "max_tokens": 1024
  }'

OpenAI biçimli uç noktalarda otomatik kesme noktaları

OpenAI Chat Completions ve Responses biçimlerinde cache_control alanı hiç yoktur — OpenAI kendi sunucularında örtük olarak önbelleğe alır. Claude ise bunu yapmaz: yalnızca bir kesme noktasıyla işaretlenen içeriği önbelleğe alır. Dolayısıyla OpenAI konuşan bir istemcinin önbelleğe alma isteğinde bulunma yolu yoktur; isteğinin doğrudan çevirisi Claude'a ulaştığında hiçbir kesme noktası içermez ve uzun bir sohbetin her turunda tüm geçmiş tam girdi ücreti üzerinden yeniden ücretlendirilir.

Dolayısıyla /v1/chat/completions veya /v1/responses üzerinden bir Claude modeline ulaştığınızda Kunavo, protokolün taşıyamadığı kesme noktalarını ayarlar. Etkinleştirmeniz gereken bir şey yoktur. Bu yalnızca Claude modelleri için geçerlidir — diğer tüm model aileleri, sağlayıcılarının örtük önbelleğe aldığı bir protokol üzerinden sunulur ve yerleştirilecek kesme noktaları yoktur.

# Plain OpenAI Chat Completions — no cache_control anywhere in the body.
# The format has no field for one; Kunavo inserts the breakpoints instead.
resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": LONG_SYSTEM_PROMPT},
        {"role": "user", "content": "first question"},
        {"role": "assistant", "content": "...previous answer..."},
        {"role": "user", "content": "follow-up"},
    ],
)

u = resp.usage
# Turn that writes the cache:
#   u.cache_creation_input_tokens            -> 18,000
#   u.prompt_tokens_details.cached_tokens    ->      0
# Next turn, same prefix, inside the 5-minute window:
#   u.cache_creation_input_tokens            ->    240   (only the new turn)
#   u.prompt_tokens_details.cached_tokens    -> 18,000
#
# Both stuck at 0 on a conversation well over the threshold? The prefix is
# changing between calls — a timestamp or request id inside the cached span.

Nereye ve bütçenin hangi sırayla harcandığına bakalım:

• Son mesaja eklenen kayan bir kesme noktası — son mesajın son içerik bloğuna eklenir; böylece ondan önceki her şey önbelleğe alınır. İstek, sohbette kalan bir sistem mesajıyla bitiyorsa (aşağıya bakın), bunun yerine o mesajın hemen önündeki bloğa eklenir. Yalnızca messages zaten bir asistan turu içerdiğinde eklenir: önbelleğe yazma, girdinin 1.25× kadar ücretlendirilir; bu nedenle kimsenin yeniden göndermeyeceği bir istemi işaretlemek dörtte bir oranında fazladan ücrete yol açar ve hiçbir tasarruf sağlamaz. Önceki bir asistan turu, bu kesin önekin yeniden gönderilmek üzere olduğunun göstergesidir.
• system üzerinde bir, tools üzerinde bir — istemin sabit başlangıç kısmı. Tek seferlik bir çağrıda bile işaretlemeye değer; çünkü sistem istemini bir kez gönderen bir çağıran, sonraki çağrıda neredeyse her zaman aynısını gönderir.
• Sohbette kalan bir sistem mesajının önünde — kayan nokta ile system ve tools noktalarından artan bütçe, ardından başka bir şey gelen bu tür mesajların sonuncusunun hemen önündeki bloğa, sonra da bir öncekinin önüne eklenir. En son doldurulur, çünkü buna yalnızca böyle bir mesajı turdan tura taşıyan bir istemci ihtiyaç duyar; böyle bir mesaj içermeyen bir sohbette, ki sohbetlerin neredeyse tamamı böyledir, bu konum yoktur.

İki sınır bunu kısıtlar. İstem — mesajlar, system ve araç şemaları dâhil — 8.192 karakterden kısaysa hiçbir şey eklenmez: Anthropic, kendi minimum önbelleğe alınabilir uzunluğundan (1.024 token, Haiku'da 2.048) kısa bir önek üzerindeki kesme noktasını sessizce yok sayar ve ne yazma ne de okuma ücreti alır; dolayısıyla böyle bir noktayı eklemek hiçbir fayda sağlamaz. Ayrıca Anthropic istek başına en fazla 4 kesme noktasını kabul eder — beşinci nokta sessizce yok sayılmaz, doğrudan 400 hatası verir.

Modelin ilk yanıtından sonra gönderilen bir sistem ya da developer mesajı system alanına taşınmaz; gönderildiği turda, sohbetin içinde kalır. Taşınsaydı, eklendiği turda istemin başı değişir ve tüm geçmiş önbelleğe yeniden yazılırdı. Üst sağlayıcı kabul ediyorsa Claude bunu bir sistem mesajı olarak alır; aksi hâlde o kullanıcı turunun içinde, <system-reminder> etiketleri arasında metin olarak alır. Modelin ilk yanıtından önce gönderilen bir sistem mesajı ya da kendi kesme noktası bir saatlik önbellek isteyen bir mesaj yine system alanına gider.

Raporlamada hiçbir şey değişmez: Yanıt alanları bölümünde açıklanan aynı cached_tokens ve cache_creation_input_tokens alanları, kesme noktalarını siz eklemiş olsanız da ağ geçidi eklemiş olsa da doldurulur. Bu nedenle, eklenen bir kesme noktasının gerçekten isabet sağladığını kullanım nesnesinden kontrol edebilirsiniz.

Fiyatlandırma

Önbellek ücretleri her modelin girdi fiyatından ve sağlayıcının kendi oranlarından hesaplanır — aşağıdaki tablolar esas alınmalıdır ve içlerindeki her ücret, elle girilmek yerine ilgili modelin girdi fiyatından hesaplanır. Önbellek okumaları, hem Anthropic'te hem OpenAI'de girdi ücretinin 0.10× oranında ücretlendirilir, 2 istisna ile: 0.025× on Claude Fable 5.1, 0.05× on Claude Opus 5.5. Önbellek yazmaları, tüm Claude modellerinde ve GPT-6 Astra, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol ve GPT-5.6 Terra üzerinde girdi ücretinin 1.25× oranında ücretlendirilir. Kunavo, Claude'un 1 saat TTL'li yazmalarını da aynı 1.25× oranında ücretlendirir; bu, Anthropic'in 2× oranından düşüktür. Diğer tüm modellerde ayrı bir yazma fiyatı yoktur: yazmalar normal girdi ücreti üzerinden ücretlendirilir. Her iki durumda da bir kez bile yeniden kullanılan bir öneğin önbelleğe alınmış hâli, yeni gönderilmesinden daha ucuza gelir. Her sınıfa modelin kendi indirimi uygulanır; bu nedenle önbellek fiyatları da modelin girdi ve çıktı fiyatları gibi sağlayıcının liste fiyatından aynı oranda indirimlidir.

Yakınlık yönlendirmesi önbelleği sıcak tutar

Üst sağlayıcıların istem önbellekleri API anahtarı başına tutulur. Her istek rastgele bir üst sağlayıcı anahtarına yönlendirilirse önbellek isabet oranı yaklaşık 1/N olur. Kunavo, sistem isteminizden ve ilk kullanıcı mesajınızdan sabit bir karma türetir ve aynı öneke sahip tüm çağrıları aynı üst sağlayıcı anahtarına yönlendirir — ağırlıklı rendezvous hashing kullanarak havuz değiştiğinde yalnızca yaklaşık 1/N anahtarı yeniden eşler.

Herhangi bir ayar yapmanız gerekmez. Yakınlık yönlendirmesi tüm sohbet çağrılarına otomatik olarak uygulanır. (Görsel / video / TTS isteklerinde rastgele yönlendirme kullanılır — bu kipler için anahtar başına önbellek yoktur.)

Kontrol paneli ölçümleri

Çağrılarınız önbellekten yararlanmaya başladığında /app/usage, seçili zaman aralığı için toplam iki ölçüm sunar:

• İsabet oranı — önbellekten sunulan girdi token'ları ÷ toplam girdi token'ları. Çağrı başına token sayılarından hesaplanır ve kesindir.
• Tasarruf — bu zaman aralığında USD cinsinden tasarruf; her model için ayrı ayrı ve modelin gerçek önbellek okuma ücreti kullanılarak hesaplanır (düz ortalama varsayımı yapılmaz). Bu, katalog fiyatlarıyla hesaplanan bir tahmindir — gerçek faturalar katalog fiyatıyla tabanlandığından ve önbellekli çağrılar bu tabanın altında kalabildiğinden, bu rakam fiilî tasarruf için oldukça dar bir üst sınırdır. Tipik sohbet iş yüklerinde ikisi arasındaki fark birkaç yüzdeyi geçmez.

Her çağrının ayrıntı sayfasında (/app/usage/<id>) sıfırdan farklı olduklarında önbelleğe alınan ve önbelleğe yazılan token sayıları ile fiilen faturalandırılan tutar gösterilir.

Yanıt alanları

Kunavo, önbellek token'larını her iki yanıt biçiminde de sunar. OpenAI ile uyumlu /v1/chat/completions uç noktasında:

/v1/messages adresindeki Anthropic'e özgü Messages API'de Anthropic'in özgün alanları olduğu gibi aktarılır:

Sonraki adımlar

• Messages API başvurusu — açıklamalı önbellek örnekleriyle Anthropic'in kendi biçimi.
• Claude istem önbelleğe alma — önbelleği teşhis eden kullanım nesnesi değerleri ve bir ağ geçidi üzerinden yönlendirmenin isabet oranını bozduğu üç yol.
• Faturalandırma ve kayıt defteri — önbelleği hesaba katan max() tabanının üst sağlayıcı maliyetiyle etkileşimi.
• Tam fiyat tablosu — tüm sohbet modellerinin yeni girdi / çıktı fiyatları ve en altta önbellek alt tablosu.