Prompt Caching Nedir? API Maliyetini %90 Düşürme (2026)

Bir uygulama geliştiriyorsunuz: her kullanıcı sorusundan önce modele 8.000 tokenlik bir sistem promptu gönderiyorsunuz. Ürün kuralları, ton rehberi, bilgi tabanı özeti hep orada. Günde 2.000 API çağrısı yapıyorsunuz ve her seferinde bu bağlamı sıfırdan işletiyorsunuz. Ay sonunda fatura geldiğinde rakamlar sizi şaşırtıyor.

Prompt caching tam olarak bu problemi çözüyor: tekrar eden bağlam bloklarını bir kez işleyip sonraki çağrılarda aynı hesaplamayı yapmadan kullanma. 2024 sonunda Anthropic’in Claude API’sine, ardından Google Gemini ve AWS Bedrock’a eklendi. Yüksek hacimli üretim ortamlarında hem maliyeti hem gecikmeyi ölçülebilir biçimde düşürüyor.

Bu yazıda prompt caching’in nasıl çalıştığını, hangi sağlayıcıların ne kadar kontrol sunduğunu ve gerçek bir senaryo üzerinden ne kadar tasarruf sağladığını ele alıyoruz. Kod örnekleri Python ve Node.js SDK’larını kapsıyor.

Prompt Caching Nedir?

Büyük dil modelleri bir metin üretmeden önce iki aşama geçirir: prefill (girdi tokenlarını işleme) ve decode (yanıt üretme). Prefill, hesaplama açısından pahalı bir adımdır; her token için bir attention hesabı yapılır ve bu değerler geçici olarak bellekte tutulur. Siz her API çağrısında aynı sistem promptunu gönderdiğinizde, model bu prefill işlemini tekrar tekrar çalıştırır.

Prompt caching bu prefill çıktısını, yani KV (key-value) cache değerlerini, sunucuda bir süre saklar. Aynı prefix ile yeni bir çağrı geldiğinde model önbelleği okur ve hesaplamayı atlar. Sonuç: daha düşük maliyet, daha hızlı yanıt.

Anthropic API’sindeki fiyat farkı tablosu bu avantajı netleştirir:

İlk çağrıda cache write maliyeti biraz yüksek. Ama ikinci çağrıdan itibaren aynı prefix için ödediğiniz, normal tokenin onda biri. Günde onlarca çağrı yapan düşük hacimli projelerde fark küçük kalıyor; ama yüzlerce ya da binlerce çağrıda tasarruf katlanarak büyüyor. Bu yüzden prompt caching asıl değerini üretim ortamlarında gösteriyor, prototip aşamasında değil.

Nasıl Çalışır?

Teknik altyapı, transformer mimarisinin dikkat (attention) mekanizmasına dayanır. Her transformer katmanında girdi tokenları için key ve value vektörleri hesaplanır; bunlar bir sonraki token üretimi için kullanılır. KV cache, bu vektörleri bellekte tutarak yeniden hesaplamayı engeller.

Prompt caching bu mantığı API katmanına taşır. Modeli barındıran sunucu, bir promptun başından itibaren belirli bir uzunluğa kadar olan kısmın KV değerlerini saklar. Buna prefix caching denir. Aynı prefix ile gelen sonraki çağrı, bu kaydedilmiş değerleri doğrudan kullanır.

Caching mantığını anlamak kolay; ama sistemi kurarken dikkat edilmesi gereken üç pratik kısıt var:

• Minimum token eşiği: Anthropic’te 1.024 token, Google Gemini’de 2.048 token. Bu eşiğin altındaki bağlamlar önbelleklenemez.
• TTL (yaşam süresi): Anthropic’te 5 dakika, Gemini’de 1 saate kadar uzatılabilir. TTL dolduğunda önbellek silinir; bir sonraki çağrı yeniden cache write yapar.
• Prefix sabitliği: Önbelleğe alınan kısım byte-for-byte aynı olmalıdır. Sistem promptunun ortasındaki tek karakterlik değişiklik, o noktadan itibaren önbelleği geçersiz kılar.

Hangi Sağlayıcılar Destekliyor?

Anthropic Claude’da cache_control alanıyla hangi bloğun önbelleğe alınacağını siz belirliyorsunuz. En fazla 4 ayrı önbellek noktası tanımlanabilir; ephemeral (5 dakika) ve persistent (daha uzun ömürlü) olmak üzere iki TTL seçeneği var.

Google Gemini iki farklı yol sunuyor. Implicit caching’de model arka planda kendi kararını veriyor, geliştiricinin özel bir işlem yapması gerekmiyor. Explicit context cache’de ise bir bağlam nesnesi oluşturup TTL ve token limitini kendiniz belirliyorsunuz. Minimum 32.000 token eşiği var, bu da Anthropic’e göre daha kısıtlayıcı.

AWS Bedrock’ta prompt caching desteği 2025 başında Claude modelleri için genel kullanıma açıldı. Temel mantık Anthropic API ile aynı; fiyatlandırma AWS bölgesine göre değişiyor.

OpenAI’nin prefix caching mekanizması tamamen otomatik çalışıyor; hangi kısımların önbelleklendiğini siz göremiyorsunuz. Bu, optimizasyonu kör bir süreç haline getiriyor ve ne zaman tasarruf ettiğinizi anlamak güçleşiyor.

Ne Zaman Kullanmalısınız?

Prompt caching her senaryo için uygun değil. Temel kural şu: aynı bağlamı birden fazla çağrıda tekrar kullanıyorsanız, caching işe yarıyor. Kullanım kalıplarını şöyle gruplandırabiliriz:

Bunun tersine, her çağrıda farklı bir prefix gönderiyorsanız ya da kullanıcıya özgü dinamik içerik promptun başında yer alıyorsa caching faydası neredeyse sıfıra düşüyor. Bir kişiselleştirme motoru için her kullanıcıya özel bir sistem promptu yazıyorsanız, o promptları önbellekleyemezsiniz. Statik bölüm ne kadar uzunsa ve ne kadar sık tekrar ediliyorsa kazanım o kadar belirgin olur.

Anthropic ile Pratik Uygulama

Anthropic API’sinde cache_control alanını sistem bloğuna ya da user mesajlarına ekleyerek önbellekleme noktası tanımlarsınız. Tanımladığınız noktanın öncesindeki her şey önbelleğe alınıyor; sonrasındaki kısım her çağrıda normal şekilde işleniyor. En fazla 4 böyle nokta tanımlayabilirsiniz.

Python’da cache_control şöyle kullanılır:

import anthropic

client = anthropic.Anthropic()

system_prompt = """
[Uzun sistem talimatları, ürün kuralları, bilgi tabanı özeti...
Bu bölümün 1024 token'ı geçmesi gerekir.]
"""

# İlk çağrı — cache write
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": system_prompt,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "Kullanıcı sorusu 1"}]
)

print("Cache write tokens:", response.usage.cache_creation_input_tokens)
print("Cache read tokens:", response.usage.cache_read_input_tokens)

# İkinci çağrı — cache read (aynı sistem promptu)
response2 = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": system_prompt,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "Kullanıcı sorusu 2"}]
)

print("Cache write tokens:", response2.usage.cache_creation_input_tokens)  # 0
print("Cache read tokens:", response2.usage.cache_read_input_tokens)       # sistem prompt uzunluğu

Node.js SDK kullanıyorsanız yapı benzer:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const systemPrompt = `
[Uzun sistem talimatları...]
`;

async function callWithCache(userQuestion: string) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    system: [
      {
        type: "text",
        text: systemPrompt,
        cache_control: { type: "ephemeral" },
      },
    ],
    messages: [{ role: "user", content: userQuestion }],
  });

  const usage = response.usage;
  console.log(`Cache write: ${usage.cache_creation_input_tokens}`);
  console.log(`Cache read: ${usage.cache_read_input_tokens}`);

  return response;
}

await callWithCache("İlk soru");
await callWithCache("İkinci soru"); // Cache read devreye girer

cache_creation_input_tokens sıfırdan büyükse önbellek yazıldı demektir. cache_read_input_tokens sıfırdan büyükse önbellek okunuyor. İlk çağrıda birinci değer dolu, ikincisi sıfır olmasını bekliyorsunuz. Sonraki çağrılarda tam tersi. Bu iki sayıyı loglamak, caching’in gerçekten çalışıp çalışmadığını doğrulamanın en hızlı yolu.

Google Gemini Context Cache API

Gemini’de explicit context cache kullanmak için önce bir önbellek nesnesi oluşturursunuz. Bu nesne Anthropic’te olduğu gibi bir request header değil; bağımsız bir API kaynağı. Oluşturma, güncelleme ve silme işlemlerini ayrı ayrı yönetebilirsiniz:

import google.generativeai as genai
from google.generativeai import caching
import datetime

# Uzun doküman bağlamı oluştur
cache = caching.CachedContent.create(
    model="models/gemini-1.5-pro-001",
    display_name="Ürün dokümantasyonu",
    system_instruction="Sen bir ürün destek asistanısın...",
    contents=[large_document_content],
    ttl=datetime.timedelta(hours=1),
)

# Önbelleği kullanarak model çağrısı yap
model = genai.GenerativeModel.from_cached_content(cached_content=cache)
response = model.generate_content("Kullanıcı sorusu")

Gemini’de önbellek nesnesi TTL dolduğunda otomatik siliniyor; elle de güncelleyebilirsiniz. Depolama için saatlik küçük bir maliyet var, ama yeterli çağrı hacminde bu, önbelleksiz token maliyetinin çok altında kalıyor. 32.000 tokenlik minimum eşik nedeniyle küçük sistem promptları için Gemini explicit caching’i pek uygun değil; Anthropic’in 1.024 token eşiği burada avantaj sağlıyor.

Maliyet Hesaplaması: Gerçek Örnek

Bir müşteri destek uygulaması: 5.000 tokenlik sistem promptu, günde 1.000 API çağrısı, Claude Sonnet (input: 3 USD / 1M token).

Önbellek olmadan:

Prompt caching ile (ilk çağrı cache write, kalan 999 cache read):

Önbelleksiz senaryoya göre %90 maliyet düşüşü. Sistem promptu ne kadar uzun ve günlük çağrı hacmi ne kadar yüksekse tasarruf o kadar büyük. Ama asıl fark gecikme tarafında: cache read çok daha hızlı prefill anlamına geliyor.

En İyi Pratikler ve Yaygın Hatalar

Context engineering açısından prompt caching’i en çok etkileyen şey prompt yapısıdır.

Önbelleğe alınacak kısım prefix olduğu için statik bölümü başa, dinamik içeriği sona koyun. Kullanıcı adı, oturum bilgisi, güncel tarih gibi değerleri promptun sonuna taşıyın. Başı sabit tuttuğunuz sürece önbellek çalışır.

Cache TTL’ini iş yüküne göre değerlendirin. Anthropic’te 5 dakika. Düşük trafikli gece saatlerinde çağrılar arasındaki aralık bu süreyi geçerse önbellek sona ermiş olur; ilk yeni çağrı yeniden cache write yapar. Yüksek trafikli dönemlerde bu sorun olmuyor, ama seyrek servis edilen uygulamalarda her gece “ısınma maliyeti” çıkıyor.

1.024 tokenin altındaki sistem promptları için Anthropic önbellekleme yapmaz. Sistemin kısa kaldığı durumlarda few-shot örneklerini sistem bloğuna dahil ederek uzatabilirsiniz.

Her sağlayıcının cache_control noktası limiti var (Anthropic’te 4). Yalnızca gerçekten tekrar eden ve uzun olan blokları işaretleyin; her şeyi önbelleğe almaya çalışmak işe yaramıyor.

Son olarak: güncel zaman, kullanıcı kimliği veya oturum token’ı gibi değerleri önbelleğe alınan blokta bırakmayın. Bu değer değiştiğinde prefix farklılaşır ve önbellek geçersiz olur. Dinamik değişkenleri her zaman promptun sonuna taşıyın.

Prompt Caching ile Birlikte Kullanılan Teknikler

RAG pipeline’larında aynı doküman bağlamı birden fazla kullanıcı sorusu için tekrar kullanılır. Doküman içeriğini sistem bloğuna koyup önbellekleyin; kullanıcı sorgusunu user bloğuna taşıyın. Her yeni soru geldiğinde yalnızca kısa sorgu işlenir, uzun doküman bağlamı önbellekten okunur. Bu kombinasyon özellikle hukuk, tıp veya teknik destek gibi büyük doküman havuzu gerektiren uygulamalarda fark yaratıyor.

Milyonluk bağlam penceresi sunan modeller kendi başına pahalı. Bir kitabın tamamını ya da büyük bir kod tabanını bağlama yükleyip önbelleklediğinizde, sonraki analizler çok daha düşük maliyetle gerçekleşiyor. Kitap veya repo değişmediği sürece önbellek sürekli okunuyor.

Structured output çağrılarında şema tanımları ve JSON format talimatları her çağrıda aynı kalır. Bu kısımları önbellekleyerek hem gecikmeyi hem maliyeti düşürebilirsiniz.

Çok adımlı bir ajanın her turda araç tanımlarını ve önceki konuşma geçmişini yeniden göndermesi yaygındır. vLLM gibi sunucu tarafı çözümlerde prefix caching zaten otomatik çalışıyor, ama API düzeyinde de manuel caching ile bu tekrar maliyetini kontrol altına alabilirsiniz.

Sonuç

Prompt caching, kurması 30 dakika alan ama ay sonunda faturanızı ciddi ölçüde küçülten bir teknik. Mimarinizde büyük bir değişiklik gerektirmiyor; sadece statik bağlamı başa taşıyıp birkaç satır cache_control eklemeniz yeterli. Günlük 1.000 çağrıda %90 tasarruf, haftalık 10.000 çağrıda da aynı oran geçerli. Tek sınır minimum token eşiği ve TTL yönetimi. Her ikisini doğru yapılandırdıktan sonra sistem kendi kendine çalışıyor.