Prompt caching nedir? İsabet oranını artırmanın 8 kuralı

Prompt caching neyi saklar?

Bir dil modeli istekler arasında hiçbir şey hatırlamaz. Aynı sistem talimatını, aynı belgeyi ya da aynı kod bağlamını yüz kez gönderirseniz model onu yüz kez işler, siz de yüz kez ödersiniz. Prompt caching (istem önbelleği) bunu değiştirir: sağlayıcı, isteğin başındaki değişmeyen kısmı bir kez işleyip saklar; aynı şekilde başlayan sonraki istekler bu kısmı önbellekten okur.

Saklanan şey metnin kendisi değil, modelin o metni işlerken hesapladığı ara durumlardır; bunu bir sonraki bölümde açıyoruz. Bu yüzden eşleşmenin tam olması gerekir: ön ek bayt bayt aynı değilse önbellekten okunamaz.

Üç kavram sık karıştırılıyor:

Kaynak: OpenAI’ın, Anthropic’in, vLLM’in ve GPTCache’in belgeleri, 15 Ekim 2026.

Bunu biz her gün yaşıyoruz: diffox bir pull request’i incelerken birçok uzman ajan aynı bağlamı ayrı çağrılarla okur (nasıl çalıştığını ayrı bir yazıda anlattık).

Önbellek nasıl çalışır?

Bir dil modeli yanıt üretmeye başlamadan önce girdinin tamamını okur; bu aşamaya ön doldurma (prefill) denir. Model bu sırada her token için anahtar (key) ve değer (value) adında ara durumlar hesaplar. OpenAI’ın belgesi bunlara KV durumları der: model yanıtı üretirken önceki token’lara bu durumlar üzerinden geri bakar. Prompt caching’in sakladığı da bunlardır: metnin kendisi değil, modelin metni işlerken hesapladığı tensörler.

Kazanç da buradan gelir. Ön ek önbellekteyse model o kısmın hesabını atlar ve yalnızca yeni token’ları işler. vLLM’in belgesi kazancın nerede bittiğini de söyler: önbellek girdiyi işleme süresini kısaltır, yeni token üretmeyi hızlandırmaz. Bu yüzden önbellekten en çok, ön eki uzun ve yanıtı kısa olan işler kazanır. Prompt Cache makalesi, ilk token’a kadar geçen sürenin GPU’da 8 kata, CPU’da 60 kata kadar kısaldığını ölçtü.

Ön ekin neden bayt bayt aynı olması gerektiği de buradan anlaşılır. vLLM’in tasarım belgesi önbellekteki her bloğu iki şeyle tanımlar: bloğun kendi token’ları ve ondan önceki ön ekin token’ları. Yani aynı cümle, önünde başka bir metin varsa başka bir bloktur. Başa tek bir tarih eklerseniz arkasındaki bütün bloklar yeni blok olur; önbellek ancak değişikliğin olduğu yere kadar işe yarar.

Üstelik bu durumlar küçük değildir. PagedAttention makalesi her isteğin KV cache belleğinin çok büyük olduğunu ve istek boyunca büyüyüp küçüldüğünü yazar. Sağlayıcılar önbelleği bu yüzden dakikalarla sınırlar: Google Cloud’un belgesine göre bellekteki önbellek sınırlıdır ve yer gerektikçe kayıtlar silinir. Anthropic de bu ara durumların yalnızca bellekte tutulduğunu, kalıcı olarak saklanmadığını söyler.

Prompt caching dört sağlayıcıda nasıl açılır, ne kadar kazandırır?

Dört sağlayıcı da önbelleği destekliyor; ama nasıl açıldığı, ön ekin en az ne kadar uzun olması gerektiği ve fiyatı farklı. Tablodaki bilgileri 15 Ekim 2026 günü her sağlayıcının kendi belgesinden okuduk.

Kaynak: sağlayıcıların belgeleri, 15 Ekim 2026. Çarpanlar önbelleksiz girdi fiyatına göredir. Google Cloud satırı Gemini 2.5 ve sonrası içindir.

Anthropic’te ve OpenAI’ın GPT-5.6 sonrası modellerinde önbelleğe yazmak, aynı token’ı önbelleksiz göndermekten pahalıdır, okumak çok daha ucuzdur. Bu yüzden yazmanın 1,25 kat olduğu önbellek ilk okumada, Anthropic’in yazması 2 kat olan 1 saatlik önbelleği ise ikinci okumada kendini amorti eder. Gemini’nin açık önbelleğinde yazma standart fiyattır, ama önbelleğin durduğu her saat için saklama ücreti ödenir; kârlı olup olmadığı, kaç kez okunduğuna ve ne kadar süre tutulduğuna bağlıdır.

Claude API’de birçok çağrı aynı bağlamı okuyorsa işaret ortak bloğa konur, çağrıya özel talimat onun arkasından gelir. ephemeral şu an desteklenen tek önbellek türüdür; örnekteki model adını belgenin kendi örneğinden aldık:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<ortak bağlam: her çağrıda aynı metin>",
      "cache_control": {"type": "ephemeral"}
    },
    {
      "type": "text",
      "text": "<bu çağrıya özel talimat>"
    }
  ],
  "messages": [
    {"role": "user", "content": "<bu çağrının sorusu>"}
  ]
}

Önbellek ne kadar süre sıcak kalır?

Önbellekteki bir kayıt sonsuza kadar kalmaz. Claude Code’un belgesi durumu iki kelimeyle anlatır: kayıt süresi içindeyse önbellek sıcaktır (warm), süresi dolmuşsa soğuktur (cold). Sıcak önbellekte sonraki istek ön eki ucuza okur; soğuk önbellekte ön eki baştan işler ve yazma ücreti öder.

Kaynak: sağlayıcıların belgeleri, 15 Ekim 2026. Gemini’nin örtük önbelleğinin süresi belgede yazmıyor; Google Cloud’da en çok 24 saattir ve kayıtların çoğu daha önce silinir.

Bu süreyi bir sayaç gibi düşünün; iki ayrıntı önemli. Anthropic’te sayaç, yanıtın bittiği andan değil, isteğin başladığı andan itibaren işler: yanıtın gelmesi 4 dakika sürdüyse, aynı ön eki okuyacak sonraki istek yaklaşık 1 dakika içinde başlamalıdır. Anthropic, OpenAI ve Bedrock’ta ise her isabet sayacı sıfırlar; bu yüzden düzenli gelen trafik önbelleği kendiliğinden sıcak tutar.

Çoğu sağlayıcıda, önbelleğin hâlâ sıcak olup olmadığını söyleyen bir endpoint yok. İstisna Gemini’nin açık önbelleğidir: cachedContents.get her zaman bitiş zamanını (expireTime) döndürür, içeriği döndürmez. Anthropic, OpenAI ve Bedrock’ta bunu ancak bir sonraki yanıttan anlarsınız: önbellekten okunan token sayısı sıfıra düştüyse ya ön ek değişmiştir ya da kayıt soğumuştur. Anthropic’in cache diagnostics aracı ikisini birbirinden ayırır: istekler aynıysa ve okuma sıfırsa kaydın süresi dolmuştur.

Claude Code’da süre, nasıl ödediğinize bağlıdır. Belgeye göre Claude aboneliğinde, planınıza dahil kullanımın içindeyken ana konuşma 1 saatlik önbellek kullanır. Kullanım kredisine geçtiğinizde, API anahtarı kullandığınızda ya da bir bulut sağlayıcısı üzerinden bağlandığınızda bu süre 5 dakikadır. Subagent’larda süre abonelikte de 5 dakikadır. Süreyi promptCacheTtl ayarıyla ya da CLAUDE_CODE_PROMPT_CACHE_TTL değişkeniyle değiştirebilirsiniz.

Önbelleğin durumunu üç yerden görebilirsiniz. /usage önbelleğin sıcak mı soğuk mu olduğunu geçerli süreyle birlikte yazar. Durum satırına (status line) gelen JSON’daki prompt_cache nesnesinde warm, ttl ve expires_at alanları bulunur; sonuncusu önbelleğin soğuyacağı anı verir. VS Code eklentisindeki önbellek saati de 5 dakikadan ya da 1 saatten geriye doğru sayar ve kalan dakikayı gösterir; 1 saatlik önbellekte sayaç 60 dakikadan başlar.

Dikkat etmeniz gereken üç şey var:

• İstekler arasındaki boşluk süreyi aşmamalı. Bir istek öncekinden 5 dakikadan uzun süre sonra gelirse ön eki yeniden yazar. Anthropic, ön ek 5 dakikadan sık kullanılıyorsa 5 dakikalık önbellekte kalmayı öneriyor, çünkü yenilenmesi ücretsiz.
• Uzun süre ücretsiz değildir. Anthropic’te 1 saatlik önbelleğe yazmak 2 kat tutar ve ön ek iki kez okunmadan kendini amorti etmez; Gemini’nin açık önbelleğinde her saat için saklama ücreti ödenir.
• Uzun bir aradan sonraki ilk istek pahalıdır. Önbellek soğumuşsa ilk istek ön ekin tamamını yeniden yazar. Asıl istek gelmeden önbelleği ısıtabilirsiniz: Anthropic’te max_tokens: 0 ile, OpenAI’ın GPT-5.6 sonrası modellerinde prompt_cache_options.prewarm ile.

On çağrılık bir örnekte ön ek %78,5 daha ucuza gelir

Sayılar yuvarlak ve varsayımsal; amaç yalnızca belgedeki çarpanları göstermek. 50.000 token’lık ortak bir ön eki 10 çağrı okusun. Birim olarak temel girdi fiyatından ücretlenen bir token’ı alıyoruz; yazmayı 1,25×, okumayı 0,1× sayıyoruz. Anthropic’in 5 dakikalık önbelleği ve OpenAI’ın GPT-5.6 sonrası modellerinin çoğu bu çarpanları kullanır.

önbelleksiz    10 × 50.000 × 1      = 500.000

önbellekli      1 × 50.000 × 1,25   =  62.500   ilk çağrı yazar
              + 9 × 50.000 × 0,1    =  45.000   dokuz çağrı okur
                                    = 107.500

Sırayla başlatılan on çağrı, ön ek için 107.500 token karşılığı öder; bu, önbelleksiz durumdaki 500.000’den %78,5 daha az. Okuma çarpanı 0,05× olan bir modelde toplam 85.000’e iner. 1 saatlik önbellekte yazma 100.000’e çıkar ve toplam 145.000 olur.

Üçüncü çubuk en kötü durumu gösteriyor: aynı on çağrı aynı anda başlıyor. Hiçbiri diğerinin yazdığını okuyamıyor; her biri ön eki kendisi yazarsa toplam 625.000 oluyor. Bu, önbelleği hiç açmamaktan %25 daha pahalı. Nedenini aşağıda, paralel çağrılar bölümünde anlatıyoruz.

İsabet oranını yüksek tutmanın 8 kuralı

Dört sağlayıcının belgeleri isabet için aynı şeyleri söylüyor. Aşağıdaki kuralların her biri en az iki sağlayıcının belgesinde geçiyor.

En sık atlanan kural ikincisi. Claude Code’un sürüm notlarındaki bir satır bunun neden önemli olduğunu gösteriyor: tarihi sistem prompt’undan çıkarmak isabet oranını artırdı. Tarih her gün değişir ve ön ekin başında durursa her yeni günün ilk isteği ön ekin tamamını yeniden yazar.

İki kural ise tek bir sağlayıcıya özgü. OpenAI’ın GPT-5.6 öncesi modellerinde, aynı ön eki paylaşan isteklere sabit bir prompt_cache_key verirsiniz. Bu anahtar istekleri aynı önbelleğe yönlendirmeye yardım eder; belge anahtar başına dakikada yaklaşık 15 istek öneriyor. Anthropic ise araç çağrılarındaki JSON anahtarlarının hep aynı sırada gelmesini istiyor. Belgeye göre Swift ve Go gibi bazı diller anahtarları rastgele sıralıyor ve aynı içerik farklı baytlarla gidiyor.

Önbelleği hangi değişiklikler bozar?

Anthropic’te ve Bedrock’ta önbellek bir hiyerarşi izler: tools, system, messages. Bir düzeydeki değişiklik o düzeyi ve arkasındaki bütün düzeyleri geçersiz kılar. Anthropic’in belgesinde sayılan durumlardan altısı:

Alıntı (citations) özelliğini açıp kapatmak web aramasıyla aynı etkiyi yapar; prompt’a görsel ekleyip çıkarmak ise tool_choice ile aynı. Belgenin “yaygın hata” dediği durum dördüncü kartta: breakpoint, zaman damgası ya da kullanıcının mesajını içeren bir bloktaysa her istek yeni bir kayıt yazar ve hiçbiri okuyamaz. Sistem geriye doğru en çok 20 bloğa bakar; ama aradığı şey değişmemiş içerik değil, önceki bir isteğin yazdığı kayıttır. Önbelleğe yalnızca breakpoint’te yazılır. Bu yüzden işaret, istekler arasında aynı kalan son bloğa konur.

Paralel çağrılarda önbellek nasıl kullanılır?

Aynı ön eki okuyan çağrıları aynı anda başlatmak doğal görünür. Anthropic’in belgesi bu konuda net: eşzamanlı isteklerde önbellek kaydı ancak ilk yanıt başladıktan sonra kullanılabilir olur; paralel isteklerin önbellekten okumasını istiyorsanız, sonrakileri göndermeden önce ilk yanıtı bekleyin. OpenAI da önbelleğin tek tek makinelerde durduğunu ve dakikada 15’ten fazla isteğin başka makinelere gidebileceğini yazıyor.

İlk yanıtın bitmesi gerekmez, başlaması yeter. Belgeler üç yol gösteriyor:

• İlk çağrıyı tek başına gönderin. Claude Code bunu kendisi yapar: bir iş akışında aynı ön eki paylaşan ajanları birlikte başlatırken, ilk ajanın yanıtı başlayana kadar diğerlerini bekletir. Bekleme varsayılan olarak en çok 5.000 milisaniyedir.
• Önbelleği önceden ısıtın. max_tokens: 0 ile gönderilen istek breakpoint’te önbelleğe yazar ve çıktı üretmeden döner; çıktı token’ı için ödeme yapmazsınız. İşaret ortak blokta durmalı, düşünme ayarı ve output_config.effort değeri asıl çağrılarla aynı olmalıdır. Bu istek, çıktı gerektiren bir ayarla (örneğin stream: true) birlikte gönderilirse reddedilir.
• Toplu işte 1 saatlik önbellek kullanın. Batch API’de istekler herhangi bir sırada işlenir ve okuma garanti değildir. Belge, ortak ön eki taşıyan tek bir isteği 1 saatlik önbellekle önce göndermeyi, kalanları da o bitince göndermeyi öneriyor.

İsabet oranı nasıl ölçülür?

Önbelleğin çalıştığını varsaymayın, yanıttan kontrol edin. Dört sağlayıcı da önbellekten okunan token sayısını yanıtın kullanım (usage) bilgisinde ayrı bir alanda verir:

Kaynak: sağlayıcıların belgeleri, 15 Ekim 2026.

İsabet oranı, önbellekten okunan token’ların toplam girdiye oranıdır. OpenAI bunu böyle tanımlıyor ve oranı kullanıcı, çalışma alanı ya da gün bazında toplamayı öneriyor. Burada toplam girdiyi doğru hesaplamak önemli: Anthropic’te ve Bedrock’ta girdi alanı önbelleğe giren token’ları saymaz, toplamı bulmak için üç alanı toplarsınız; Gemini’de promptTokenCount önbellekten okunanları zaten içerir.

Toplam girdi üç alanın toplamıdır. input_tokens tek başına girdinin tamamını göstermez, yalnızca son breakpoint’ten sonraki kısmı sayar. Her şey yolundaysa ilk çağrıda yazma alanı ön ekin uzunluğu kadar olur; sonraki çağrılarda aynı sayı okuma alanında görünür. İki alan da sıfırsa prompt önbelleğe alınmamıştır; en olası neden, ön ekin en kısa uzunluğun altında kalmasıdır. Yazma alanı her çağrıda yüksek kalıyorsa ön ekte bir şey değişiyordur.

Biz her çağrının üç alanını ayrı ayrı kaydediyoruz. Kullanım bilgisi gelmeyen bir çağrıyı sıfır değil, ölçülmemiş sayıyoruz; çünkü boşluğa sıfır yazılırsa o çağrı ücretsizmiş gibi görünür.

Önbellek ne zaman kazandırmaz?

Önbellek her iş yükünde işe yaramaz. Açmadan önce şu dört duruma bakın:

• Ön ek yalnızca bir kez okunuyorsa. Yazma 1,25 kat tutuyorsa ve ön eki okuyan ikinci bir çağrı yoksa %25 fazla ödersiniz.
• Çağrılar arasındaki boşluk süreden uzunsa. Her çağrı önbelleği soğumuş bulur ve ön eki yeniden yazar.
• Ön ek en kısa uzunluğun altındaysa. İstek çalışır ama önbellek devreye girmez; hata da almazsınız.
• Ön ek her istekte değişiyorsa. Başa yazılan bir tarih bile her isteğin önbelleğe baştan yazmasına yol açar.

Kazanç yalnızca paradan ibaret değil: uzun ön eklerde ilk token da daha çabuk gelir. Hız sınırı (rate limit) konusunda sağlayıcılar farklı davranıyor: Anthropic’e ve Bedrock’a göre Claude’da önbellekten okunan token’lar hız sınırına sayılmaz; OpenAI’da ise dakikalık token sınırına sayılır.

diffox’ta bir incelemedeki uzman ajanlar aynı ortak bağlamı okur: değişikliğin diff’ini ve dosya bağlamını. Bu bağlam isteğin başında tek bir blokta durur ve önbellek işareti o bloktadır. İlk çağrı tek başına gider, kalanlar onun ardından paralel başlar. Her çağrının yazdığı ve okuduğu token’ları ayrı ayrı kaydediyoruz.