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 ve korumaların çalışmasından sonra, yönlendirme aşamasında — sağlayıcı ve model kesinleştikten sonra — ancak model çağrılmadan önce kontrol edilir:
İstek → RAG (bağlam ekleme) → Korumalar → Yönlendirme (sağlayıcı ve model kesinleşir) → Semantik Önbellek → Model
İsabet varsa model çağrılmaz. 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 (varsayılan: 0.95) 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 — Proxy İzole stratejisinde (varsayılan) bir aday yalnız aynı model, aynı API proxy ve aynı kimlik kapsamındaysa kabul edilir; Global stratejisinde proxy anahtar içinde yer almadığından farklı proxy'lerden adaylar da eşleşebilir. Farklı bir kimlik kapsamındaki daha yüksek skorlu kayıt bilerek elenir; aksi halde bir çağıranın yanıtı başkasına dönerdi. LLM Gateway'in İstemci "stream" alanı ayarı İstemcinin değerini kullan olduğunda yanıt kipi (streaming veya tek seferlik yanıt) de kapsama dahildir: streaming bir istek için kaydedilen yanıt, tek seferlik yanıt isteyen bir isteğe benzerlik isabeti olarak hiçbir zaman dönmez; tersi de geçerlidir. Proxy ayarıyla üzerine yaz seçiliyken kapsam değişmez.
- 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 Top-K Sorgu Sayısı değerini 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 Header'ını Onurlandır 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.
Önbellek araması yönlendirme aşamasında, sağlayıcı ve model kesinleştikten ve model erişim listesi çağıranı geçirdikten sonra çalışır. Modeli kullanma yetkisi olmayan çağıran önbellekteki cevabı alamaz; 403 model_access_denied alır. Arama her zaman kimlik doğrulama politikasının bulduğu çağıranı görür.
Kimliği Olmayan (Anonim) İstekler
Önbellek anahtarı her zaman model ve çağıranın kimliğini içerir; Proxy İzole stratejisinde (varsayılan) buna API proxy de eklenir — 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.
Maskeleme ve Önbellek Güvenliği
Proxy'de aşağıdaki politikaların herhangi biri yanıt tarafında etkinse, semantik önbellek yazma işlemini tamamen atlar (hem birebir hem streaming yanıtlar için):
- Tespit dışı en az bir kural (Tespit Et dışındaki herhangi bir kural) içeren etkin bir PII Mask politikası. Yalnızca Tespit Et kuralları önbelleklemeyi devre dışı bırakmaz.
- En az bir Engelle veya Maskele kuralı içeren, ya da dosya imzası tespiti etkinleştirilmiş etkin bir DLP Guard politikası — tüm kurallar yalnızca İşaretle olsa bile. Dosya imzası tespiti olmadan yalnızca İşaretle kuralları önbelleklemeyi devre dışı bırakmaz.
Bu kontroller, politika gruplarının içine yerleştirilmiş politikalar için de geçerlidir.
Yazma atlandığında yanıt önbelleğe hiç yazılmaz — ne ham ne de işlenmiş bir sürüm saklanır. Çıkış aşamasında yanıt tarafı politikaları yine de çalışır.
Bu davranış, maskeleme olmadan kaydedilen bir önbellek girişinin sonraki bir isabet sırasında maskelenmeden sunulacağı senaryoyu önler.
Cache Anahtar Stratejisi
Cache Anahtar Stratejisi alanı, API proxy'nin önbellek anahtarının parçası olup olmayacağını belirler:
| Strateji | Anahtar bileşenleri | İzolasyon |
|---|---|---|
| Proxy İzole (varsayılan) | Model + API proxy + tüketici | Her proxy'nin kendi önbellek kovası vardır |
| Global | Model + tüketici | Aynı çağıran için, aynı soru farklı proxy'lere gelse de aynı yanıt paylaşılabilir |
Global stratejisinde, aynı çağırandan farklı proxy'lere gelen aynı soruya ait istekler önbellekteki yanıtı paylaşabilir — proxy anahtar içinde yer almaz. Global'ı yalnızca proxy'ler arası yanıt paylaşımının kasıtlı ve güvenli olduğu tek-kiracılı kurulumlar için kullanın.
Global stratejisinde, bir proxy tarafından önbelleğe alınan yanıt aynı çağırana farklı bir proxy üzerinden döndürülebilir. Bu seçeneği yalnızca proxy'ler arası yanıt paylaşımının bilinçli olduğu ve kiracı izolasyonu gerekmediği ortamlarda kullanın.
Anahtarda proje boyutu yoktur. Global stratejisinde, bir proxy'de önbelleğe alınan yanıt farklı bir projedeki proxy üzerinden de sunulabilir — çağıran kimliği her zaman anahtara dahildir ama proje sınırları önbellek girdilerini ayırmaz.
TTL ve Otomatik Temizlik
Önbellek girdileri sınırsız süre saklanmaz; her girdi yapılandırılabilir bir TTL (sn) ile oluşturulur (varsayılan: 3600 saniye) ve süresi dolan girdiler otomatik olarak temizlenir. Bu sayede önbellek eski/güncelliğini yitirmiş yanıtlarla şişmez. TTL'yi 0 olarak ayarlamak önbelleği tamamen atlar — her istek sağlayıcıya gider.
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 (Manager'ın saat diliminde) ç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. Ö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 içindeki kayıtların tamamı silinebilir. Koleksiyonun kendisini değil, kayıtları silin; bkz. aşağıdaki not.
Apinizer vektör koleksiyonunu politikanın ona ilk ihtiyaç duyduğu anda oluşturur ve sonrasında varlığını bir daha denetlemez. Koleksiyon Apinizer dışından silinirse, worker'lar yeniden başlatılana veya vektör veritabanı bağlantısı yeniden yüklenene kadar yeniden oluşturulmaz; o zamana kadar bu koleksiyondaki benzerlik aramaları ve yazmalar başarısız olur.
İ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
APIops ile Yapılandırma
Semantic Cache politikası, her politika tipinin paylaştığı aynı genel politika ucu üzerinden bir API proxy'sine eklenebilir, güncellenebilir ya da kaldırılabilir:
POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/
PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/
policy.type alanını ai-semantic-cache yapın. Vektör-benzerlik eşleşmesi açıldığında (vectorEnabled: true), vectorDbName ve embeddingProviderName alanları sunucu tarafında ada göre çözülür — her APIops kaynağının izlediği ada-dayalı-referans kuralıyla aynıdır, hiçbir zaman iç kimlikle değil — bu sayede aynı istek gövdesi, referans verilen bağlantılar orada da mevcut olduğu sürece ortamlar arasında taşınabilir.
Tam alan listesi, istek/yanıt örnekleri ve hata kodları için bkz. API Referansı: Semantic Cache Policy.
Yapılandırma Referansı
| Ayar | Varsayılan | Notlar |
|---|---|---|
| TTL (sn) | 3600 | 0 önbelleği atlar — tüm istekler sağlayıcıya gider |
| Cache Bağlantı Timeout (sn) | 3 | En az 1; timeout'ta istek sağlayıcıya geçer |
| Maks. Cache'lenebilir Boyut (byte) | 262144 (256 KB) | 0 = limitsiz (önerilmez); hem birebir hem streaming yanıtlar için geçerlidir |
| Vektör Cache Etkin | Kapalı | Vektör-benzerlik eşleşmesini açar. Aşağıdaki alanlar yalnızca açıkken geçerlidir |
| Vector DB Bağlantısı | — | Zorunlu. İstek embedding'lerinin saklandığı vektör veritabanı bağlantısı |
| Embedding Sağlayıcısı | — | Zorunlu. Yalnızca embedding destekleyen sağlayıcılar listelenir |
| Embedding Model ID | text-embedding-3-small | Seçilen sağlayıcının etkin embedding modelleri arasından seçilir; ya da bir model kimliği yazılır |
| Embedding Boyutu | 1536 | Embedding modelinin ürettiği boyutla eşleşmelidir |
| Koleksiyon Adı | — | Zorunlu. İstek embedding'lerini tutan koleksiyon |
| Benzerlik Eşiği | 0.95 | Vektör eşleşmesinin isabet sayılması için gereken minimum skor |
| Top-K Sorgu Sayısı | 1 | Kapsam filtrelemesi ve skorlama için vektör veritabanından getirilen aday sayısı |
| Cache-Control Header'ını Onurlandır | Kapalı | Bkz. Cache-Control Başlığına Uyma |