Pratikte prompt caching

Bu modül için tahmini süre: 7 dakika

Genel bakış

Bu derste prompt caching’i kodda nasıl etkinleştireceğini görüyoruz: tool schema’lara breakpoint eklemek, system prompt’u cache uyumlu yapmak ve cache_creation_input_tokens / cache_read_input_tokens üzerinden cache davranışını izlemek.

Prompt caching, Claude’a aynı içeriği tekrar tekrar gönderdiğinde API request’lerini hem daha hızlı hem de daha ucuz hale getiren güçlü bir optimization feature’dır. Uygulamalarında bunu etkili şekilde nasıl uygulayacağımıza bakalım.

Prompt caching nasıl çalışır

Prompt caching’i etkinleştirdiğinde, ilk request bir saat yaşayan bir cache’e içerik yazar. Follow-up request’ler aynı içeriği tekrar işlemek yerine bu cache’ten okuyabilir. Bu özellikle şunları gönderirken değerlidir:

• Büyük system prompt’lar (örn. 6K token’lık bir coding assistant prompt’u)
• Karmaşık tool schema’ları (çoklu tool’lar için yaklaşık 1.7K token)
• Tekrarlanan mesaj içerikleri

Temel fikir şu: caching yalnızca aynı içeriği tekrar tekrar gönderirsen yardımcı olur — ama birçok uygulamada bu son derece sık gerçekleşir.

Tool schema caching kurulumu

Tool schema’larını cache’lemek için tool listesindeki son tool’a cache control alanı eklemen gerekir. Orijinal tool tanımlarını değiştirmeden bunu yapmanın doğru yolu:

if tools:
    tools_clone = tools.copy()
    last_tool = tools_clone[-1].copy()
    last_tool["cache_control"] = {"type": "ephemeral"}
    tools_clone[-1] = last_tool
    params["tools"] = tools_clone

Bu yaklaşım, cache control alanını eklemeden önce hem tool listesinin hem de son tool schema’sının kopyalarını oluşturur. tools[-1]["cache_control"]’ü doğrudan değiştirebilirdin, ama kopyalama yaklaşımı daha sonra tool’larını yeniden sıraladığında problem çıkmasını önler.

System prompt caching

System prompt’lar için onları cache control’lü bir text block olarak yapılandırman gerekir:

if system:
    params["system"] = [
        {
            "type": "text",
            "text": system,
            "cache_control": {"type": "ephemeral"}
        }
    ]

Bu, system prompt’unu basit bir string’den caching’i destekleyen yapılandırılmış bir formata dönüştürür.

Cache davranışını anlamak

Caching etkin haliyle request’ler çalıştırdığında, response’da farklı usage pattern’leri göreceksin:

• İlk request: cache_creation_input_tokens=1772 — Claude cache’e yazar
• Follow-up request’ler: cache_read_input_tokens=1772 — Claude cache’ten okur
• Değişen içerik: Yeni cache creation token’ları görünür

Cache son derece hassastır — tool’larında veya system prompt’unda tek bir karakter bile değiştirmek o bileşen için tüm cache’i invalidate eder.

Cache sıralaması ve breakpoint’ler

Tek bir request’te birden fazla cache breakpoint ayarlayabilirsin. Sıra önemlidir:

1. Tools (sağlanmışsa)
2. System prompt (sağlanmışsa)
3. Messages

System prompt’unu değiştirip aynı tool’ları korursan, kısmi bir cache read (tool’lar için) ve bir cache write (yeni system prompt için) görürsün. Bu granular caching, yalnızca gerçekten değişen kısımları işlemenin bedelini ödediğin anlamına gelir.

Pratik düşünceler

Prompt caching en çok şu durumlarda etkilidir:

• Request’ler arası tutarlı tool schema’ları
• Stabil system prompt’lar
• Benzer context ile birden fazla request yapan uygulamalar

Cache’in yalnızca bir saat sürdüğünü unutma; long-term storage yerine görece sık API kullanan uygulamalar için tasarlanmıştır.

Temel çıkarımlar

• Tool caching için son tool’a cache_control: {"type": "ephemeral"} eklenir
• System prompt cache’lemek için string yerine text block formatına dönüştürülür
• Cache davranışı cache_creation_input_tokens ve cache_read_input_tokens ile izlenir
• Cache hassastır: tek karakter değişikliği cache’i invalidate eder
• İşleme sırası tools → system → messages; granular caching kısmi cache kullanımına olanak verir