Semantik Önbellek
Genel Bakış
Semantik önbellek, daha önce yanıtlanmış bir isteğe yeniden (veya anlamca çok benzer bir isteğe) rastlandığında, modeli tekrar çağırmadan önbellekteki yanıtı döner. Bu, hem gecikmeyi hem de maliyeti düşürür.
Vektör-benzerlik kavramının temel tanımı için Yapay Zeka Temel Kavramları sayfasına bakabilirsiniz.
Semantik önbellek; Prompt Şablonu, Prompt Süsleyici ve RAG politikalarından sonra çalışmalıdır. Önbellek anahtarı prompt'un tam kurulmuş hâlinden üretilir; bu politikalardan önce çalışırsa anahtar eksik bir metinden hesaplanır ve birbirinden farklı istekler aynı yanıtı paylaşabilir.
Politika listesini bu kurala aykırı bir sırayla kaydederseniz Apinizer sırayı kayıt anında otomatik olarak düzeltir ve neyi neden taşıdığını bir bilgi notuyla bildirir. Böylece Develop ekranında gördüğünüz sıra ile izleme ekranındaki gerçek çalışma sırası her zaman aynı kalır.
Eşleşme Modları
İki eşleşme modu desteklenir:
- Birebir eşleşme — İstek, önbellekte daha önce görülen bir isteğin aynısıysa eşleşir
- Vektör-benzerlik (isteğe bağlı) — İstek birebir aynı olmasa da, vektör veritabanı üzerinden anlamca yeterince benzer bulunursa eşleşir (örn. aynı soru farklı kelimelerle sorulduğunda da isabet alınır)
Ne Zaman Devreye Girer?
Semantik önbellek, isteğin RAG ile bağlam eklenmesinden sonra, ancak modele iletilmeden önce kontrol edilir:
İstek → Korumalar → RAG (bağlam ekleme) → Semantik Önbellek → Yönlendirme → Model
Bağlamlı isteğin önbelleğe bakılması, doğru (bağlamı da hesaba katan) bir eşleşme sağlar.
Benzerlik Eşiği
Vektör-benzerlik modunda bir adayın isabet sayılması için gereken en düşük benzerlik skoru benzerlik eşiği ile belirlenir. Eşiği düşürmek daha çok isabet, yükseltmek daha kesin isabet demektir.
Eşik 0 verildiğinde eşik gerçekten devre dışı kalır — hiçbir aday skoru yüzünden elenmez. Ancak bu "her istek eşleşir" anlamına gelmez; eşikten önce üç filtre daha çalışır:
- Kapsam izolasyonu — bir aday yalnız aynı model, aynı API proxy ve aynı kimlik kapsamındaysa kabul edilir. Başka bir kapsamdaki daha yüksek skorlu kayıt bilerek elenir; aksi halde bir çağıranın yanıtı başkasına dönerdi.
- Aday sayısı — vektör veritabanından yalnız en yakın belirli sayıda kayıt çekilir. Koleksiyon büyükse aynı kapsamdaki doğru kayıt bu listenin dışında kalabilir; böyle bir durumda en yakın komşu sayısını artırın.
- Girdinin ömrü — vektör eşleşmesi bulunsa bile yanıt gövdesi birebir önbellek girdisinden okunur. O girdi TTL ile düşmüşse sonuç yine ıskadır.
Beklediğiniz isabeti alamıyorsanız sırayla bunları kontrol edin; eşiği daha da düşürmek yardımcı olmaz.
Vektör-Benzerlik Girdisini İnce Ayarlama
Varsayılan olarak vektör-benzerlik modu, embedding'e girdi olarak yalnızca isteğin son kullanıcı mesajını alır. Çok turlu bir konuşmada önceki turların bağlamı önemliyse, hangi mesajların embedding girdisine dahil edileceğini ayarlayabilirsiniz:
| Ayar | Davranış |
|---|---|
| Geriye dönük mesaj sayısı | Mesaj listesinin sonundan başlayarak kaç mesajın embedding girdisine dahil edileceği. Varsayılan/boş = 1 (yalnız son mesaj — önceki davranışla birebir aynı). |
| Sistem mesajlarını dahil et | Geriye dönük pencereye giren system rollü mesajları da embedding girdisine katar. |
| Asistan mesajlarını dahil et | Geriye dönük pencereye giren assistant rollü mesajları da embedding girdisine katar. |
| Araç mesajlarını dahil et | Geriye dönük pencereye giren tool rollü mesajları da embedding girdisine katar. |
Bu dört ayar yalnızca vektör-benzerlik eşleşmesinin embedding girdisini değiştirir. Birebir eşleşme anahtarı — isteğin tam gövdesinin özeti — bu ayarlardan bağımsız olarak her zaman değişmeden hesaplanır; bir ayarı değiştirmek, mevcut birebir-eşleşme önbellek girdilerini geçersiz kılmaz.
Cache-Control Başlığına Uyma
Cache-Control başlığına uy açıldığında, istemcinin Cache-Control isteği başlığı önbellek davranışını etkiler:
| Başlık değeri | Davranış |
|---|---|
no-store | Bu istek için önbellek ne okunur ne de yazılır — yanıt sağlayıcıdan taze alınır ve sonucu önbelleğe yazılmaz |
no-cache | Okuma atlanır (yanıt her zaman sağlayıcıdan taze alınır) ama yazma normal şekilde devam eder — sonraki isteklerin isabet alabilmesi için önbellek güncellenir |
Bu ayar varsayılan olarak kapalıdır — kapalıyken başlık hiç okunmaz, davranış bu ayar eklenmeden önceki ile birebir aynıdır.
Kimliği Olmayan (Anonim) İstekler
Önbellek anahtarı; model, API proxy ve çağıranın kimliği ile kurulur — böylece bir kiracının yanıtı başka bir kiracıya dönmez. Kimlik doğrulaması olmayan bir API proxy'de istek böyle bir kimlik taşımaz ve ne yapılacağı politikada seçilir:
| Seçenek | Davranış |
|---|---|
| Politikayı uygulama (varsayılan) | Önbellek atlanır, istek doğrudan sağlayıcıya gider |
| Ortak havuzdan tüket | Tüm anonim istekler tek bir ortak önbellek kovasında toplanır |
| İsteği reddet | Anonim istek HTTP 401 ile geri çevrilir |
Varsayılan seçenek, bu ayar eklenmeden önceki davranışla birebir aynıdır. "Ortak havuzdan tüket" seçildiğinde kiracı izolasyonu beklenmez — bir çağıranın yanıtı diğerine dönebilir; yalnızca anonim erişimin bilinçli olarak açıldığı ve yanıtların paylaşılmasında sakınca görülmeyen kurulumlar için uygundur.
Aynı üç seçenek Tekrar-Fırtınası korumasında da vardır; bkz. Gelişmiş Korumalar.
Kişisel Veri ile Güvenli Etkileşim (Maske-Kapısı)
Bir yanıt, kişisel veri (PII) maskeleme politikasından geçiyorsa, semantik önbelleğe hiçbir zaman maskelemeden önceki ham hali yazılmaz — yalnızca maskelenmiş hâli önbelleğe alınır. Böylece bir sonraki önbellek isabetinde maskelenmemiş veri sızması söz konusu olmaz.
TTL ve Otomatik Temizlik
Önbellek girdileri sınırsız süre saklanmaz; her girdi bir TTL (yaşam süresi) ile oluşturulur ve süresi dolan girdiler otomatik olarak temizlenir. Bu sayede önbellek eski/güncelliğini yitirmiş yanıtlarla şişmez.
Vektör katmanının temizliği
Vektör-benzerlik modu açıkken her önbellek girdisinin bir de vektör veritabanında karşılığı tutulur: isteğin embedding'i ve onu yanıt girdisine bağlayan bir işaretçi. Yanıt girdisi TTL ile düştüğünde bu vektör kaydı kendiliğinden kaybolmaz — geride işaret ettiği yanıt artık var olmayan bir kayıt kalır.
Bu artık kayıtlar yanlış yanıt döndürmez (işaretçi boşa çıktığında istek normal şekilde sağlayıcıya gider), ancak birikmeye bırakılırsa iki soruna yol açar: koleksiyon büyüdükçe en yakın komşu listesini doldurup geçerli eşleşmelerin isabet oranını düşürürler, ve istem metinlerinden türetilen embedding'ler saklama süresi olmaksızın kalmaya devam eder.
Apinizer bunu otomatik olarak yönetir:
- PostgreSQL (pgvector) ve Qdrant — Manager, her gün 04:45'te çalışan bir bakım görevi ile süresi geçmiş semantik önbellek kayıtlarını siler. Görev, yalnızca semantik önbelleğin yazdığı kayıtları hedefler; aynı koleksiyonu paylaşan bilgi tabanı (RAG) verilerine hiçbir koşulda dokunmaz.
- Redis — Kayıtlar yazıldıkları anda kendi sona erme sürelerini alır; süresi dolduğunda Redis tarafından kendiliğinden silinirler, ayrı bir bakım görevi çalışmaz.
Bakım görevi, Manager ortamında SETTING_AI_SEMANTIC_CACHE_VECTOR_PURGE_ENABLED değişkeni false yapılarak kapatılabilir. Kapatmanız gerekmiyorsa varsayılan (açık) hâlinde bırakın.
Otomatik temizlik, kayıtların üzerindeki sona erme damgasına bakar. Bu özellikten önceki sürümlerde yazılmış vektör kayıtlarında bu damga bulunmadığı için bakım görevi onları görmez ve silmez. Bu, bilinçli bir güvenlik tercihidir: damgası olmayan bir kaydın kime ait olduğu kesin bilinemediğinden, silinmesindense yerinde bırakılması tercih edilir. Söz konusu kayıtlar zamanla azalır — aynı istem tekrar sorulduğunda kayıt yeni damgasıyla üzerine yazılır. Eski kayıtları hemen temizlemek isterseniz sistem yöneticinizle görüşün; koleksiyon başka bir amaçla paylaşılmıyorsa koleksiyonun tamamı boşaltılabilir (ilk ıskada yeniden oluşturulur).
İzleme
Önbelleğin ne kadar isabet aldığı (HIT oranı) ve bu isabetler sayesinde tasarruf edilen maliyet, Raporlar ve Analitik ekranında izlenebilir.
Yapılandırma
Semantik önbellek, bir API proxy'sine eklenen Semantic Cache politikasıyla etkinleştirilir:
- İlgili API proxy'sinin politika listesine Semantic Cache politikasını ekleyin
- Eşleşme modunu (birebir veya vektör-benzerlik) seçin; vektör-benzerlik için kullanılacak vektör veritabanı bağlantısını belirleyin
- TTL süresini ayarlayın
- Kaydedin ve deploy edin