Claude API Prompt Caching: Token Maliyetini %90 Azaltma Rehberi

Prompt caching nedir?

Prompt caching, Claude API'nin tekrar eden bağlam blokları için ödeme yapma zorunluluğunu ortadan kaldıran bir maliyet optimizasyon mekanizmasıdır. Uzun sistem prompt'ları, doküman bağlamları veya few-shot örnek setleri ilk çağrıda işlenerek bellekte tutulur; sonraki çağrılarda aynı blok yeniden işlenmez ve bu kısım için token maliyeti belirgin ölçüde düşer.

Nasıl çalışır?

Cache_control parametresi, önbelleğe alınacak mesajın sonuna ephemeral tipiyle eklenir. Anthropic API bu noktaya kadar olan içeriği önbelleğe alır ve 5 dakikalık TTL penceresi içinde aynı içeriğe yapılan çağrılarda önbellekten okur. Önbellek okuması yeni token işlemekten çok daha düşük maliyetle gerçekleşir.

• Cache write: İlk çağrıda bağlam yazılır, standart token ücreti uygulanır.
• Cache read: Sonraki çağrılarda önbellekten okunur, input token ücretinin küçük bir fraksiyonu ödenir.
• TTL: Önbellek 5 dakika boyunca geçerliliğini korur; bu süre uzatılabilir.

cache_control nasıl eklenir?

Python SDK üzerinden sistem mesajına eklemek için mesaj içeriğini liste formatına çevirip son bloğa "cache_control": {"{"}"type": "ephemeral"{"}"} eklenir. TypeScript SDK'da sözdizimi aynıdır. Doküman bağlamını önbelleğe almak için user mesajına, sistem prompt'unu önbelleğe almak için system mesajına uygulanabilir.

En iyi kullanım senaryoları

Prompt caching en yüksek tasarrufu şu durumlarda sağlar: uzun kod tabanı veya doküman analizi, büyük few-shot örnek kümesiyle çalışma, aynı sistem prompt'unu paylaşan çok kullanıcılı uygulamalar ve sohbet geçmişi büyüdükçe yeniden işlem maliyetinin arttığı uzun konuşmalar.

• RAG uygulamaları: Bağlama eklenen dokümanlar önbelleğe alınarak her sorguda yeniden gönderilmesi engellenir.
• Claude Code entegrasyonları: Büyük CLAUDE.md ve proje bağlamı önbelleğe alınabilir.
• Batch işlemler: Aynı talimat setiyle binlerce satır işlemede dramatik maliyet düşüşü sağlar.

Dikkat edilecekler

Önbellek geçerliliği model sürümüne ve tam içerik eşleşmesine bağlıdır; küçük değişiklikler cache miss yaratır. Bu nedenle önbelleğe alınan bölümü sabit tutmak, değişken kısımları sonuna taşımak gerekir. Haiku 4.5 ve Sonnet 4.6 için prompt caching varsayılan olarak destekleniyor; Opus 4.7 için de etkinleştirilebilir.

Kaynaklar

Bu rehber Anthropic prompt caching dokümantasyonu temel alınarak hazırlanmıştır.