Mühendislikte sık sık söylenir ki "Cache Her Şeyi Yönetir" ve aynı kural ajanlar için de geçerlidir.
Claude Code gibi uzun süreli ajan ürünleri, prompt önbellekleme sayesinde mümkün hale gelir; bu, önceki isteklerden elde edilen hesaplamaları yeniden kullanmamızı sağlayarak gecikmeyi ve maliyeti önemli ölçüde azaltır.
Prompt önbellekleme nedir, nasıl çalışır ve teknik olarak nasıl uygulanır? @RLanceMartin'in prompt önbellekleme ve yeni otomatik önbellekleme lansmanı hakkındaki yazısını okuyun.
Claude Code'da tüm altyapımızı prompt önbellekleme etrafında inşa ettik. Yüksek bir prompt önbellek isabet oranı maliyetleri düşürür ve abonelik planlarımız için daha cömert hız sınırları oluşturmamıza yardımcı olur; bu nedenle prompt önbellek isabet oranımızla ilgili uyarılar çalıştırırız ve çok düşük olursa SEV bildiririz.
Bunlar, prompt önbelleklemeyi ölçekte optimize etmekten öğrendiğimiz (çoğu zaman sezgisel olmayan) derslerdir.
Önbellekleme İçin Prompt'unuzu Düzenleyin
Prompt önbellekleme, önek eşleştirmesiyle çalışır — API, isteğin başından her cache_control kesme noktasına kadar her şeyi önbelleğe alır. Bu, öğeleri koyma sırasının son derece önemli olduğu anlamına gelir; mümkün olduğunca çok isteğin aynı öneki paylaşmasını istersiniz.
Bunu yapmanın en iyi yolu, önce statik içerik, en son dinamik içerik koymaktır. Claude Code için bu şöyle görünür:
- Statik sistem prompt'u ve Araçlar (genel olarak önbelleğe alınır)
- Claude.MD (bir proje içinde önbelleğe alınır)
- Oturum bağlamı (bir oturum içinde önbelleğe alınır)
- Konuşma mesajları
Bu şekilde, kaç oturumun önbellek isabetlerini paylaştığını maksimize ederiz.
Ancak bu şaşırtıcı derecede kırılgan olabilir! Daha önce bu sıralamayı bozduğumuz nedenlere örnekler: statik sistem prompt'una ayrıntılı bir zaman damgası koymak, araç sıralama tanımlarını deterministik olmayan bir şekilde karıştırmak, araçların parametrelerini güncellemek (örneğin AgentTool'un hangi ajanları çağırabileceği) vb.
Güncellemeler İçin Mesajları Kullanın
Prompt'unuza koyduğunuz bilgilerin güncelliğini yitirdiği zamanlar olabilir, örneğin saati veya kullanıcının bir dosyayı değiştirmesi gibi. Prompt'u güncellemek cazip gelebilir, ancak bu bir önbellek isabetsizliğine neden olur ve kullanıcı için oldukça maliyetli olabilir.
Bunun yerine, bu bilgileri bir sonraki turda mesajlar aracılığıyla iletebilir misiniz, bunu değerlendirin. Claude Code'da, model için güncellenmiş bilgilerle (örneğin, şimdi Çarşamba) bir sonraki kullanıcı mesajına veya araç sonucuna bir <system-reminder> etiketi ekliyoruz, bu da önbelleğin korunmasına yardımcı olur.
Oturum Ortasında Model Değiştirmeyin
Prompt önbellekleri modellere özeldir ve bu, prompt önbelleklemenin matematiğini oldukça sezgisel olmaktan çıkarabilir.
Opus ile 100k tokenlik bir konuşmanın içindeyseniz ve oldukça kolay cevaplanabilecek bir soru sormak istiyorsanız, Haiku'ya geçmek aslında Opus'un cevaplamasından daha pahalı olacaktır, çünkü Haiku için prompt önbelleğini yeniden oluşturmamız gerekir.
Model değiştirmeniz gerekiyorsa, bunu yapmanın en iyi yolu alt ajanlar kullanmaktır; burada Opus, yapılması gereken görevle ilgili başka bir modele bir "devir teslim" mesajı hazırlar. Bunu Claude Code'daki Haiku kullanan Explore ajanlarıyla sık sık yaparız.
Oturum Ortasında Asla Araç Ekleme veya Kaldırma
Konuşmanın ortasında araç setini değiştirmek, insanların prompt önbelleklemesini bozmasının en yaygın yollarından biridir. Sezgisel görünüyor — modele yalnızca şu anda ihtiyacı olduğunu düşündüğünüz araçları vermelisiniz. Ancak araçlar önbelleğe alınmış önekin bir parçası olduğu için, bir araç eklemek veya çıkarmak tüm konuşma için önbelleği geçersiz kılar.
Plan Modu — Önbellek Etrafında Tasarım Yapın
Plan modu, özellikleri önbellekleme kısıtlamaları etrafında tasarlamanın harika bir örneğidir. Sezgisel yaklaşım şöyle olurdu: kullanıcı plan moduna girdiğinde, araç setini yalnızca salt okunur araçları içerecek şekilde değiştir. Ancak bu önbelleği bozar.
Bunun yerine, tüm araçları her zaman istekte tutuyoruz ve EnterPlanMode ile ExitPlanMode'u araçlar olarak kullanıyoruz. Kullanıcı plan modunu açtığında, ajan, plan modunda olduğunu ve talimatların ne olduğunu açıklayan bir sistem mesajı alır — kodu keşfet, dosyaları düzenleme, plan tamamlandığında ExitPlanMode'u çağır. Araç tanımları asla değişmez.
Bunun ek bir faydası vardır: EnterPlanMode, modelin kendi kendine çağırabileceği bir araç olduğu için, önbelleği bozmadan, zor bir problem algıladığında otonom olarak plan moduna girebilir.
Araç Arama — Kaldırmak Yerine Ertele
Aynı prensip, araç arama özelliğimiz için de geçerlidir. Claude Code, düzinelerce MCP aracı yüklenmiş olabilir ve bunların hepsini her isteğe dahil etmek pahalı olurdu. Ancak bunları konuşma ortasında kaldırmak önbelleği bozardı.
Çözümümüz: defer_loading. Araçları kaldırmak yerine, hafif saplamalar gönderiyoruz — yalnızca araç adı, defer_loading: true ile — modelin ihtiyaç duyduğunda bir ToolSearch aracı aracılığıyla "keşfedebileceği". Tam araç şemaları yalnızca model bunları seçtiğinde yüklenir. Bu, önbelleğe alınmış öneki sabit tutar: aynı saplamalar her zaman aynı sırada bulunur.
Neyse ki bunu basitleştirmek için API'miz aracılığıyla araç arama aracını kullanabilirsiniz.
Bağlam Çatallama — Sıkıştırma
Sıkıştırma, bağlam pencereniz dolduğunda gerçekleşen şeydir. O ana kadarki konuşmayı özetleriz ve bu özetle yeni bir oturuma devam ederiz.
Şaşırtıcı bir şekilde, sıkıştırma, prompt önbellekleme ile sezgisel olmayan birçok uç duruma sahiptir.
Özellikle, sıkıştırma yaptığımızda, bir özet oluşturmak için modelin tamamına tüm konuşmayı göndermemiz gerekir. Bu, farklı bir sistem prompt'u ve hiçbir aracı olmayan ayrı bir API çağrısıysa (ki basit uygulama budur), ana konuşmadaki önbelleğe alınmış önek hiç eşleşmez. Tüm bu girdi token'ları için tam fiyat ödersiniz ve bu da kullanıcının maliyetini büyük ölçüde artırır.
Çözüm — Önbellek Güvenli Çatallama
Sıkıştırma çalıştırdığımızda, ana konuşmayla tamamen aynı sistem prompt'unu, kullanıcı bağlamını, sistem bağlamını ve araç tanımlarını kullanırız. Ana konuşmanın mesajlarını başa ekleriz, ardından sıkıştırma prompt'unu sonuna yeni bir kullanıcı mesajı olarak ekleriz.
API'nin bakış açısından, bu istek ana konuşmanın son isteğine neredeyse aynı görünür — aynı önek, aynı araçlar, aynı geçmiş — bu nedenle önbelleğe alınmış önek yeniden kullanılır. Yeni token'lar yalnızca sıkıştırma prompt'unun kendisidir.
Ancak bu, sıkıştırma mesajını ve özet çıktı token'larını dahil etmek için bağlam penceresinde yeterli alana sahip olmak amacıyla bir "sıkıştırma tamponu" kaydetmemiz gerektiği anlamına gelir.
Sıkıştırma zordur ancak neyse ki, bu dersleri kendiniz öğrenmeniz gerekmez — Claude Code'dan öğrendiklerimize dayanarak, sıkıştırmayı doğrudan API'ye inşa ettik, böylece bu kalıpları kendi uygulamalarınızda uygulayabilirsiniz.
Öğrenilen Dersler
- Prompt önbellekleme bir önek eşlemesidir. Önekteki herhangi bir değişiklik, ondan sonraki her şeyi geçersiz kılar. Tüm sisteminizi bu kısıtlama etrafında tasarlayın. Sıralamayı doğru yapın ve önbelleklemenin çoğu kendiliğinden çalışacaktır.
- Sistem prompt'u değişiklikleri yerine mesajları kullanın. Plan moduna girme, tarihi değiştirme vb. için sistem prompt'unu düzenlemek cazip gelebilir, ancak bunları konuşma sırasında mesajlara eklemek daha iyi olacaktır.
- Konuşma ortasında araçları veya modelleri değiştirmeyin. Araç setini değiştirmek yerine durum geçişlerini (plan modu gibi) modellemek için araçları kullanın. Araçları kaldırmak yerine yüklemeyi erteleyin.
- Önbellek isabet oranınızı, çalışma süresini izlediğiniz gibi izleyin. Önbellek kırılmaları konusunda uyarı veriyor ve bunları olay olarak ele alıyoruz. Birkaç puanlık önbellek isabetsizlik oranı, maliyeti ve gecikmeyi önemli ölçüde etkileyebilir.
- Çatallama işlemlerinin ana konuşmanın önekiyle paylaşması gerekir. Yan hesaplama (sıkıştırma, özetleme, beceri yürütme) çalıştırmanız gerekiyorsa, ana konuşmanın önekinde önbellek isabetleri almak için aynı önbellek güvenli parametreleri kullanın.
Claude Code, ilk günden itibaren prompt önbellekleme etrafında inşa edilmiştir, eğer bir ajan geliştiriyorsanız siz de aynısını yapmalısınız.
