Prompt Caching (Prompt Önbellekleme)

#LLM #MLOps #API #Optimizasyon #Çıkarım

Prompt Önbellekleme, tekrar eden LLM isteklerinde aynı ön ek için hesaplanan KV tensörlerini sunucuda saklayarak giriş maliyetini ve gecikmeyi %50–90 azaltan bir API optimizasyonudur.

Prompt önbellekleme (Prompt Caching), büyük dil modeli (LLM) API'larında aynı prompt ön ekinin birden fazla istekte tekrar tekrar kullanılması durumunda, modelin bu ön ek için önceden hesapladığı dikkat tensörlerini (KV cache) sunucu tarafında saklayarak yeniden hesaplama maliyetini ortadan kaldıran bir optimizasyon tekniğidir. Bir LLM her prompt işlediğinde her token için anahtar-değer (key-value, KV) dikkat tensörleri hesaplar. Prompt önbellekleme bu tensörleri sunucuda saklar; sonraki istek aynı ön ekle başlıyorsa model onları sıfırdan hesaplamak yerine doğrudan önbellekten yükler. Bu sayede hem hesaplama süresi hem de faturalanan giriş maliyeti önemli ölçüde düşer. Teknik özellikle uzun sistem prompt'larının, büyük belgelerin veya kapsamlı örnekler içeren şablonların yüzlerce ya da binlerce ardışık istek için tekrar gönderildiği senaryolarda kayda değer tasarruf sağlar. Ajansal döngülerde (agentic loops), RAG boru hatlarında ve çok turlu sohbet uygulamalarında girdi token maliyetleri toplam harcamanın büyük bölümünü oluşturur; prompt önbellekleme bu senaryolarda üretim AI sistemlerinin ekonomik sürdürülebilirliğini doğrudan etkiler. 2024'ten itibaren Anthropic (Claude), OpenAI (GPT-4o ve üstü), Google (Gemini) ve DeepSeek başta olmak üzere büyük LLM sağlayıcıları bu özelliği sunmaktadır. Uygulamalar arasında fark mevcuttur: Anthropic açık `cache_control` parametresiyle işaret isterken, OpenAI belirli bir token eşiğini aşan sabit ön ekleri otomatik önbellekler. Her iki yaklaşımda da önbellekteki token'lar normal girdi fiyatının %10-50'siyle faturalandırılır; bu oran giriş maliyetlerinde %50 ila %90 tasarruf anlamına gelir. Anthropic'te önbellek ömrü yaklaşık 5 dakika olup her kullanımda yenilenir. Minimum önbellekleme eşiği sağlayıcıya göre 1.024-2.048 token arasında değişir. Maliyet avantajının yanı sıra, önbellekten okunan token'lar yeniden hesaplama gerektirmediğinden ilk token gecikmesi (TTFT, time-to-first-token) de önemli ölçüde düşer; Anthropic bu iyileşmenin %85'e kadar ulaşabildiğini bildirmektedir. vLLM ve SGLang gibi açık kaynak çıkarım çerçeveleri de GPU üzerinde benzer KV önbellekleme mekanizmaları sunar.

Prompt Önbellekleme Nasıl Çalışır?

LLM bir prompt işlediğinde her token için anahtar-değer (KV) dikkat tensörleri hesaplar. Bu hesaplama, özellikle uzun ön ekler için zaman ve maliyet açısından ağırdır. Prompt önbellekleme bu tensörleri sunucu belleğinde saklar.

Sonraki bir API isteği aynı ön ekle başlarsa, model KV tensörlerini sıfırdan üretmek yerine önbellekten yükler ve yalnızca yeni eklenen (sonek) token'ları işler. Buna 'önbellek isabeti' (cache hit) denir ve hem gecikme hem de maliyet anında düşer.

Önbellek farklı sağlayıcılarda farklı uygulanır. Anthropic, geliştiricinin mesaj bloklarına {"cache_control": {"type": "ephemeral"}} parametresi eklemesini ister; böylece hangi ön ekin önbellekleneceğini tam olarak kontrol edebilirsiniz. OpenAI ise 1.024 token üzerindeki sabit ön ekleri otomatik olarak önbellekler; herhangi bir ek parametre gerekmez.

Sağlayıcı Karşılaştırması

Anthropic (Claude)

Açık cache_control parametresi; önbellek okumaları normal girdi fiyatının %10'u; ömür ~5 dk, her kullanımda yenilenir; min. 1.024 token (Sonnet/Haiku)

OpenAI (GPT-4o+)

Otomatik önbellekleme, ek kod gerekmez; önbellek okumaları normal fiyatın %50'si; min. 1.024 token; önbelleklenip önbelleklenmediği yanıt meta verisinden izlenebilir

Google Gemini

Context Caching adıyla sunulan özellik; büyük belgeler ve sistem talimatları için önbellekleme; fiyatlandırma bağımsız bir 'cache token' kavramıyla işler

vLLM / SGLang (açık kaynak)

GPU üzerinde KV cache yönetimi; PagedAttention (vLLM) ve prefix caching (SGLang); kendi altyapısını yönetenler için sıfır API maliyetiyle benzer kazanım

En Verimli Kullanım Alanları

  • check_circle RAG boru hatları: Her sorguda büyük belge koleksiyonlarını veya vektör arama sonuçlarını sistem prompt'una eklemek gerektiğinde, sabit belge bloğunu önbelleğe almak sorgu başına maliyeti dramatik biçimde düşürür.
  • check_circle Ajansal döngüler: Ajan çerçevelerinde (LangChain, AutoGen vb.) araç tanımları ve talimatlar her adımda gönderilir; bu sabit bölümü önbelleğe almak döngü başına %50+ tasarruf sağlar.
  • check_circle Uzun sistem prompt'lu chatbot'lar: Kişilik, kural seti veya ürün bilgisi içeren binlerce token uzunluğunda sabit sistem talimatı, her konuşma turunda yeniden gönderilmek zorunda kalmaz.
  • check_circle Kod tabanı analizi ve kodlama asistanı: Büyük kod dosyaları veya API dokümantasyonu bağlam olarak sabitlenip önbelleğe alınır; geliştirici soruları yalnızca kısa sonek olarak gönderilir.
  • check_circle Çok dilli içerik üretimi: Aynı kaynak metin birden fazla dile çevrildiğinde, kaynak metin bir kez önbelleğe alınır; her dil için yalnızca hedef dil talimatı eklenir.

Yüksek Önbellek İsabeti İçin Tasarım İpuçları

Önbelleklemenin gerçek değer üretmesi, prompt'un mimarisine bağlıdır. Şu ilkeleri uygulamak önbellek isabeti oranını artırır:

Sabit ön ek + değişen sonek: Sistem talimatları, belgeler ve örnekler prompt'un başına; kullanıcı girdisi en sona yerleştirilmeli. Önbellek token dizisinin başından itibaren tutarlı olmasını gerektirir.

Tek bir büyük sistem bloğu: Küçük birçok parçaya bölmek yerine tüm sabit içeriği tek bir system mesajında birleştirmek, Anthropic'te minimum 1.024 token eşiğini daha kolay aşmayı sağlar.

Önbellek ömrünü yönetin: Anthropic'te TTL 5 dakikadır; düşük trafikli uygulamalarda önbellek soğuyabilir. Yüksek isabet oranı için istek sıklığının bu sürenin altında kalması idealdir.

Değişen kısımları en sona bırakın: Tarih, kullanıcı adı gibi dinamik veriler soneca (suffix) taşındığında, ön ek sabit kalır ve önbellek tam isabet yapar.

Prompt Önbelleğinin Faydaları

Maliyet Azaltma

Önbelleğe alınan token'lar normal token fiyatının %10'una işlenir; uzun sistem mesajlarında ciddi tasarruf.

Gecikme İyileşmesi

Önbellekteki prefix yeniden işlenmez; ilk token süresi (TTFT) önemli ölçüde kısalır.

Uzun Bağlam Ekonomisi

100K token'lık doküman önbelleğe alındığında her konuşma turunda yalnızca yeni token'lar ücretlendirilir.

Minimum Prefix Gerekliliği

Claude'da en az 1024 token olmalıdır; kısa sistem mesajları önbellekten yararlanamaz.

terminal Anthropic ve OpenAI'de Kod Örneği

Anthropic tarafında önbellek açıkça işaretlenir. Sabit içeriğin bulunduğu son bloğa cache_control eklenir ve o noktaya kadarki tüm ön ek önbelleğe alınır:

import anthropic client = anthropic.Anthropic()

resp = client.messages.create( model = "claude-sonnet-5", max_tokens = 1024, system = [ { "type": "text", "text": uzun_dokuman, "cache_control": {"type": "ephemeral"}, } ], messages = [{"role": "user", "content": "Belgede garanti süresi kaç ay?"}], )

print(resp.usage.cache_creation_input_tokens) print(resp.usage.cache_read_input_tokens) print(resp.usage.input_tokens)

İlk istekte cache_creation_input_tokens dolu, cache_read_input_tokens sıfır gelir. İkinci istekte tam tersi olmalı. Bu iki alan izlenmezse önbelleğin çalışıp çalışmadığı anlaşılamaz.

İnce yerleşimle uğraşmak istemiyorsanız isteğin en üstüne cache_control = {"type": "ephemeral"} vermek yeterli; API son önbelleklenebilir bloğu kendisi işaretler. Bir saatlik uzun ömür için değer {"type": "ephemeral", "ttl": "1h"} olur, bu seçenek yazma ücretini yükseltir.

OpenAI tarafında ek parametre yoktur, önbellekleme otomatik devreye girer. Yapılacak tek şey sabit içeriği prompt'un başına koymak ve sayacı okumaktır:

resp = client.chat.completions.create(model = "gpt-4.1", messages = mesajlar) print(resp.usage.prompt_tokens_details.cached_tokens)

payments Örnek Maliyet Hesabı

  • check_circle Senaryo: 20.000 token uzunluğunda sabit bir sistem promptu ve belge bloğu var. Uygulama saatte 200 istek gönderiyor, yani yaklaşık her 18 saniyede bir. Model Claude Sonnet 5 ve girdi fiyatı 1 milyon token başına 3 dolar.
  • check_circle Önbelleksiz maliyet: 20.000 x 200 = 4.000.000 girdi token'ı. 4 x 3 dolar = saatte 12 dolar. Bu tutarın tamamı her seferinde yeniden işlenen aynı metin için ödenir.
  • check_circle Önbellekli maliyet: Yazma bir kez yapılır: 20.000 token x 3,75 dolar/M = 0,075 dolar. Kalan 199 istek okumadır: 3.980.000 x 0,30 dolar/M = 1,19 dolar. Toplam yaklaşık 1,27 dolar, yani %89 tasarruf.
  • check_circle Çarpanlar: Anthropic'te önbelleğe yazılan token normal girdi fiyatının 1,25 katı, önbellekten okunan ise 0,1 katı faturalanır. 5 dakikalık varsayılan ömür yerine 1 saatlik ömür seçilirse yazma çarpanı 2 katına çıkar, okuma yine 0,1 kalır.
  • check_circle Başa baş noktası: 5 dakikalık ömürde ilk istek 1,25 birim, sonraki her istek 0,1 birim. İki istekte toplam 1,35 birim eder ve önbelleksiz 2 birimin altına iner; yani ikinci istekte kâra geçersiniz. 1 saatlik ömürde yazma 2 birim olduğu için başa baş üçüncü istekte oluşur.
  • check_circle Trafik seyrekse: İstekler arası boşluk 5 dakikayı aşıyorsa önbellek her seferinde yeniden yazılır ve maliyet önbelleksiz senaryonun üzerine çıkar. Bu durumda ya 1 saatlik ömrü seçin ya da önbelleği istemli olarak ısıtın: max_tokens değeri 0 olan boş bir istek ön eki önbelleğe yazar.

bug_report Önbellek Isabet Etmiyorsa Kontrol Listesi

  • check_circle Ön ekin başında değişen bir şey var: İstek tools, ardından system, en son messages sırasıyla işlenir. Sistem promptunun içine tarih damgası, oturum kimliği veya kullanıcı adı koyduysanız her istek farklı bir ön ek üretir ve önbellek hiç tutmaz. Değişken içeriği son cache_control işaretinden sonraya taşıyın.
  • check_circle Araç listesi her istekte farklı sıralanıyor: Araç tanımları ön ekin en başında yer alır. Tool listesini bir sözlükte dolaşarak üretiyorsanız sıralama istekten isteğe değişebilir. Listeyi deterministik tutun ve JSON serileştirmede anahtar sırasını sabitleyin.
  • check_circle Ön ek minimum eşiğin altında: Anthropic'te önbelleklenebilir en kısa ön ek yaklaşık 1.024 token. Bunun altında hata alınmaz, istek sessizce normal fiyattan faturalanır ve cache_creation_input_tokens sıfır döner. Küçük parçaları tek bir büyük system bloğunda birleştirmek eşiği aşmayı kolaylaştırır.
  • check_circle Dörtten fazla işaret konmuş: Bir istekte en fazla 4 cache_control işareti kullanılabilir. Pratikte iki işaret yeter: biri araç ve sistem bloğunun sonuna, biri konuşma geçmişinin son sabit noktasına.
  • check_circle Model veya istek yapısı değişti: Önbellek modele bağlıdır. A/B testi için model adını değiştirmek, yeni bir sürüme geçmek veya ön eki etkileyen bir parametreyi oynatmak önbelleği sıfırlar. Aynı API anahtarıyla çalışan servisler aynı ön eki paylaşabilir, farklı müşteriler paylaşamaz.
  • check_circle Tanılama ile doğrulama: Neyin bozduğunu bulamıyorsanız Anthropic'in beta önbellek tanılama özelliği işe yarar: istek client.beta.messages üzerinden cache-diagnosis-2026-04-07 beta bayrağıyla gönderilir, diagnostics alanına bir önceki yanıtın kimliği verilir ve API eşleşmenin hangi noktada koptuğunu raporlar.

Sıkça Sorulan Sorular

  • check_circle Prompt caching ile KV cache arasındaki fark nedir? KV cache, GPU üzerinde tek bir çıkarım sırasında dikkat hesaplamalarını hızlandıran bir donanım/yazılım optimizasyonudur. Prompt caching ise birden fazla API isteği arasında kalıcı olan, sunucu tarafında tutulan bir önbellektir; farklı kullanıcı isteklerinin aynı ön eki paylaşmasına olanak tanır.
  • check_circle Kullanıcı gizliliği açısından güvenli mi? Büyük sağlayıcılar (Anthropic, OpenAI) önbelleğin yalnızca aynı API anahtarına ait istekler arasında paylaşıldığını garanti eder; farklı müşterilerin önbelleği birbirinden sızdırılmaz. Bununla birlikte, hassas veriler içeren ön ekler önbelleklenmeden önce bu garanti politikaları dikkatlice incelenmelidir.
  • check_circle Önbellek isabetimi nasıl izleyebilirim? Anthropic yanıt nesnesinde usage.cache_read_input_tokens ve usage.cache_creation_input_tokens alanlarını döndürür. OpenAI ise usage.prompt_tokens_details.cached_tokens bilgisini sağlar. Bu metrikleri izleyerek önbellek tasarrufu oranını hesaplayabilirsiniz.
  • check_circle Minimum token sayısına ulaşamazsam ne olur? Ön ek minimum eşiğin (Anthropic: 1.024, OpenAI: 1.024 token) altındaysa önbellekleme gerçekleşmez; istek normal girdi fiyatıyla faturalandırılır ve hata alınmaz. Anthropic'te cache_creation_input_tokens 0 döner.
  • check_circle Açık kaynak modellerde prompt caching var mı? Evet. vLLM'in prefix caching özelliği ve SGLang'ın RadixAttention mekanizması, kendi GPU altyapısını yönetenler için benzer kazanımlar sağlar. Bu çerçeveler API maliyeti olmaksızın sunucu tarafı KV önbelleğini yönetir.
  • check_circle Prompt caching gecikmeyi ne kadar azaltır? İlk token'a kadar geçen süre (TTFT) uzun ön eklerde belirgin biçimde düşer, çünkü model ön ekin dikkat tensörlerini yeniden hesaplamaz. Kazanç ön ekin uzunluğuyla doğru orantılıdır: 2.000 token'lık bir sistem promptunda fark sınırlıyken 50.000 token'lık bir belgede yanıt neredeyse anında başlar.
  • check_circle Önbelleğe yazmak ek ücret alır mı? Evet. Anthropic'te önbelleğe yazılan token'lar normal girdi fiyatının 1,25 katı faturalanır; 1 saatlik ömür seçilirse bu çarpan 2 olur. Okuma ise 0,1 kattır. 5 dakikalık varsayılan ömürde ikinci istekte, 1 saatlik ömürde üçüncü istekte başa baş noktası geçilir.
  • check_circle Bir istekte kaç tane cache_control işareti kullanabilirim? En fazla 4 tane. Çoğu uygulamada iki işaret yeterlidir: biri araç tanımları ve sabit sistem bloğunun sonuna, diğeri konuşma geçmişinin son sabit noktasına. Fazla işaret ek kazanç getirmez, sınırın aşılması ise hataya yol açar.
  • check_circle 5 dakikalık önbellek mi 1 saatlik mi seçmeliyim? İstekleriniz arasındaki boşluk 5 dakikanın altındaysa varsayılan ömür yeterlidir, çünkü her kullanım süreyi baştan başlatır. Günde birkaç kez çalışan toplu işlerde veya seyrek trafikli panellerde 1 saatlik ömür daha ucuza gelir; yazma 2 kat pahalı olsa da tekrar tekrar yazmaktan kurtarır.