Daha önce söylediklerinden yanıt veren bir AI ağ geçidi
Bir destek asistanına gün boyu aynı sorular biraz farklı sözcüklerle sorulur. Modelinin önündeki ağ geçidi, modeli yeniden çağırmak yerine bir soruyu, anlamca yeterince yakın olan daha önceki bir soruya verdiği yanıttan yanıtlayabilir. Bu çalışma alanı böyle bir ağ geçidini, bu yanıtları içinde tuttuğu depoyla birlikte Kubernetes manifestlerine derler.
Bunu yapan Feature core/semantic-caching’dir. Bir çağırana, başka bir çağıranın
isteğinin ürettiği hangi yanıtların sunulabileceği, bu sayfanın zamanının çoğunu
ayırdığı sorudur; çünkü yanlış çağıranlar arasında paylaşılan bir önbellek, bir
kişiye başka biri için üretilmiş bir yanıtı verir.
Bu çalışma alanı kendine ait hiçbir katalog varlığı yazmaz. Buradaki üç varlık dosyası — bir Aggregate, bir Manifest ve bir Release — herhangi birinin yazdığı şeylerin tamamıdır.
Ne oluşturur
| örnek | katalog Component’i | burada ne olduğu |
|---|---|---|
router | core/gateway/litellm | AI ağ geçidi: her biri models soketine bağlanan bir modelden sunulan bir sohbet takma adı, assistant, ve bir gömme takma adı, embedder |
chat | core/ai-model/openai | assistant arkasındaki sohbet modeli, OpenAI’ın kendi API’si; bir başvuru olarak erişilir: küme içinde onun için hiçbir şey çalışmaz |
embeddings | core/ai-model/openai-embedding | embedder arkasındaki gömme modeli; aynı şekilde erişilir |
cache | core/datastore/redis | ağ geçidinin yanıtlarını sakladığı depo |
Üç uses kenarı vardır: ikisi ağ geçidinin models soketine, her modele bir tane olmak üzere gider ve her biri credential olarak ağ geçidinin o modele sunduğu anahtarı taşır; biri de cache_store soketine gider ve credential olarak önbelleğin depoya sunduğu parolayı taşır. Ağ geçidinde iki Feature eki vardır:
api_key, yönetici anahtarı, ve answers, önbellek; depoda da bir tane vardır,
password, deponun gerektirdiği parola. Her iki parola eki de tek bir parametreyi, cache_password, her iki model kimlik bilgisi de bir başkasını, openai_key, okur;
Release her ikisini de karşılar. answers eki, her istemi bir vektöre dönüştüren gömme takma adını, iki istemin ne kadar benzer olması gerektiğini — kosinüs benzerliği olarak 0.9 — ve saklanan bir yanıtın ne kadar süre geçerli kalacağını, bir saat, belirtir. scope değerini dışarıda bırakır, bu nedenle varsayılanı, end_user, alır.
Örneği oluşturun
Bu örneği aşağıdaki komutlarla derleyebilir ya da yapay zekâ asistanınıza sizin için derletebilirsiniz.
Örneği, adını taşıyan yeni bir klasöre yazın:
aggrega scaffold --example ai-gateway-semantic-cacheArdından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:
cd ai-gateway-semantic-cacheDerleme
aggrega build --release release.yaml --auto-pullBir release, derlenmeden önce bir kilit dosyasına ihtiyaç duyar ve kilit dosyaları dağıtılmak yerine üretildiğinden yeni bir klonda hiç kilit dosyası bulunmaz. Önce bir tane çözümleyin ya da derlemenin onu doldurmasına izin verin:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildBu çalışma alanı, katalog varlıklarını .aggrega-config.yaml dosyasının adlandırdığı varsayılan kayıt defterinden çözümler. Önbelleğin gerçekleştirilmesi, ne derleyicide ne de katalogda bulunan bir plugin çalıştırır: çözümlemenin default_registry anahtarının belirttiği kayıt defterinden, hub.aggrega.ai’den getirdiği ağ geçidi yapılandırma adımı pipeline-step/litellm-gateway-config.
Derleme, <workspace> bu örneğin klasörünü temsil edecek şekilde şunu yazdırır:
[… omitted: a line reporting on the gateway configuration step's plugin, five warnings, one per credential attachment, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping, the resolution's summary and a total build time, which differ per run, and a notice that core/referenced-secret declares origin in both of its pillars]Build completed: 13 files written to <workspace>/distBir yapay zekâ asistanıyla
Aggrega araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.
Yalnızca Aggrega araçlarını kullanın ve kendiniz hiçbir klasör oluşturmayın. Çalışma alanı klasöründe henüz `ai-gateway-semantic-cache` klasörü yoksa `scaffold` aracını `example` değeri `ai-gateway-semantic-cache` olarak ayarlanmış ve `dir` olmadan bir kez çağırın: örneği yeni bir `ai-gateway-semantic-cache` klasörüne yazar. Ardından `build` aracını `workspace_root` değeri `ai-gateway-semantic-cache`, `release` değeri `release.yaml`, `auto_pull` değeri true ve `write` değeri true olarak ayarlanmış şekilde çağırın. Derlemenin hangi dosyaları yazdığını bana söyleyin; dosyalar `ai-gateway-semantic-cache/dist/` altındadır.Oluşturulan ağaç
dist/helm/├── cache--password--cache-secret-cache-password.yaml├── cache-default-service.yaml├── cache-deployment.yaml├── chat-service.yaml├── embeddings-service.yaml├── router--api-zukey--router-secret-router-api-key.yaml├── router--assistant-zdcredential--router-secret-router-assistant-credential.yaml├── router--embedder-zdcredential--router-secret-router-embedder-credential.yaml├── router--replies-zdcredential--router-secret-router-replies-credential.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlÖnbellek eklentisi kendine ait bir dosya getirmez. Yaptığı iş, ağ geçidinin yapılandırmasına yazılır. Her model, küme içi bir adı OpenAI’nin API ana bilgisayarına eşleyen bir Service olan tek bir dosya oluşturur ve bir model bağlantısındaki her kimlik bilgisi, ağ geçidinin ve bağlantının takma adının adını taşıyan kendine ait bir Secret oluşturur.
Sunduğu modeller
Gateway yapılandırma gövdesinin başlangıcı olan yönlendirme tablosunda, models soketindeki her bağlantı için bir girdi bulunur. Bu girdi, her modelin yayımladıklarından yazılır —
uç noktası, OpenAI’ın API temel URL’si ve model adı — ve gateway’in Recipe’sinin
o bağlantının anahtarını hangi değişken altında ilettiğini belirtir:
model_list: - model_name: "assistant" litellm_params: model: "openai/gpt-4o" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEY - model_name: "embedder" litellm_params: model: "openai/text-embedding-3-small" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_EMBEDDER_API_KEYAğ geçidinin okuduğu biçimiyle önbellek
Ağ geçidinin yapılandırma gövdesi, yani
dist/helm/router/litellm-gateway-config/configmap.yaml dosyasının config.yaml anahtarı,
litellm_settings bölümünden itibaren şöyledir:
[… omitted: the routing table]litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter cache: true cache_params: host: os.environ/SEMANTIC_CACHE_STORE_HOST port: os.environ/SEMANTIC_CACHE_STORE_PORT redis_semantic_cache_embedding_model: embedder redis_semantic_cache_index_name: router-answers semantic_cache_scope: end_user similarity_threshold: 0.9 supported_call_types: - acompletion - completion - aresponses - responses - aanthropic_messages - anthropic_messages ttl: 3600 type: redis-semanticBuradan okunmaya değer beş şey vardır.
Deponun adresi bunun içinde yoktur. host ve port, ağ geçidinin kendi dolaylama mekanizması aracılığıyla iki ortam
değişkenini adlandırır; ağ geçidinin Recipe’i de bunları cache_store kenarından ayarlar. dist/helm/router-deployment.yaml dosyasından,
ağ geçidinin konteynerinin env bölümü:
env: - name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-key - name: REDIS_PASSWORD valueFrom: secretKeyRef: name: router-replies.credential key: password - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: router-assistant.credential key: api-key - name: LITELLM_MODEL_EMBEDDER_API_KEY valueFrom: secretKeyRef: name: router-embedder.credential key: api-key - name: SEMANTIC_CACHE_STORE_HOST value: cache-default - name: SEMANTIC_CACHE_STORE_PORT value: "6379"cache-default, deponun kendi Recipe’inin ürettiği Service’tir ve o
Recipe’in yayımladıklarından okunur; 6379 ise yayımladığı porttur. Önbellek deponun
parolasını REDIS_PASSWORD değişkeninden okur; bu, cache_store kenarındaki credential
değerinin oluşturduğu Secret’a, router-replies.credential’a bir başvurudur, parolanın kendisi asla değildir. Depo aynı
parametreden, cache-password’den kendine ait bir Secret oluşturur ve ondan okunan --requirepass ile başlar; böylece
önbelleğin sunduğu parola ile deponun istediği parola tek bir değerdir ve
bir kez yazılır. cache_store kenarı olmadığında, deponun
adresinin ve parolasının geldiği üç değişkenin hiçbiri oluşturulmaz ve yanıtlarını saklayacak yeri olmayan önbellek, aşağıda anlatıldığı gibi derlemeyi durdurur. Üçüncü ve dördüncü girdiler
modellerin anahtarlarıdır; her biri kendi bağlantısının kimlik bilgisinin oluşturduğu Secret’tan, yönlendirme tablosundaki girdisinin adlandırdığı değişken altında başvurulur;
helm sağlayıcısı bir Secret’tan okuduğu her girdiyi düz girdilerden önce
yazar.
Gömme modeli, ağ geçidinin kendi eşlemesindeki bir takma addır. Ağ geçidi
her istemi, bir çağıranın isteğinin geçtiği aynı eşleme üzerinden embedder’a gönderir;
bu nedenle önbellek kendine ait hiçbir adres ya da kimlik bilgisi tutmaz. Eşlemenin
yayımlamadığı bir takma ad verirseniz derleme, yayımladıklarını listeleyerek durur.
Ömür, deponun ömrüdür. Her yanıt, son geçerlilik süresi olarak ttl ile
yazılır; böylece Redis onu saklandıktan bir saat sonra kaldırır. O istem için gelen
sonraki istek model tarafından yanıtlanır ve yeniden saklanır.
Yalnızca önbelleğin istemini okuduğu istek türleri adlandırılır. Akışlı olsun ya da olmasın sohbet istekleri ile responses ve messages API’leri önbelleğe alınır. Bir completions isteği alınmaz, bir embeddings isteği de alınmaz: kendi varsayılanına bırakılırsa ağ geçidi her embeddings isteğinin yanıtını saklar, bunu yapmak için her girdiyi ikinci kez gömer ve hiçbirini geri sunmaz.
Dizin, ağ geçidine ve eklentiye göre adlandırılır, router-answers; böylece
bir depoyu paylaşan tek bir Release’in iki ağ geçidi yanıtlarını ayrı
dizinlerde tutar.
Tek bir önbellek girdisinden kimlere yanıt verilir
Depolanan bir yanıt, sonraki bir isteğe yalnızca kovasını oluşturan her şey eşleştiğinde ve istem, yanıtladığı isteme en az 0.9 oranında benzer olduğunda sunulur:
- isteğin sunduğu anahtar, ağ geçidinin doğruladığı biçimiyle, o anahtarın ekibi ve kuruluşuyla birlikte;
end_useraltında, isteğin adını verdiği son kullanıcı;- isteğin istediği model ve isteğin diğer parametreleri — farklı bir sıcaklık farklı bir kovadır.
Ağ geçidi anahtarı, anahtarın ekibini ve kuruluşunu ve son kullanıcıyı isteğin kendisine yazar. Bir sohbet isteğinde bunları, çağıranın oraya gönderdiği her değerin üzerine yazarak isteğin metadata alanına yazar; bir responses ya da messages isteğinde bunları çağıranın metadata alanından ayrı tutar, çağıranın oraya yazdığı her ekip, kuruluş ya da son kullanıcı alanını oradan kaldırır ve Recipe’inin sağladığı istek koruyucusu, anahtarı orada, metadata.user_api_key alanında adlandıran bir isteği, alanı adlandıran HTTP 400 ile reddeder. Böylece hiçbir istek, ad vererek başka bir anahtarın kovasına giremez.
Bir isteğin kendi metadata alanı, isteği sunduğu anahtarın kovaları arasında yine de taşıyabilir. Bir responses isteğinde model_group, kovasında isteğin istediği modelin yerini alır. Bir responses ya da messages isteğinde caching_groups, aynı model takma adı grubunu adlandıran isteklerin bu takma adlar arasında yanıtları paylaşmasını sağlar. Bir responses ya da sohbet isteğinde redis_namespace, bir ad alanı adlandıran istekleri, hiçbirini adlandırmayanlardan ayrı kovalarda tutar. Bunların hiçbiri başka bir anahtarın kovasına ulaşmaz.
Bu ağ geçidinin anahtarı yönetici anahtarıdır ve her çağıran bu anahtarı tutar.
Bağlı bir kayıt veritabanı olmadığından kendine ait anahtar vermez: her çağıran api_key alanına bağlı anahtarı sunar ve anahtarı olmayan ya da ağ geçidinin vermediği bir anahtarla gelen bir istek, herhangi bir arama yapılmadan önce reddedilir. Dolayısıyla burada anahtar hiçbir çağıranı diğerinden ayırmaz ve varsayılan kapsamda iki çağıranı birbirinden ayıran, her isteğin adlandırdığı son kullanıcıdır.
Varsayılan olan end_user altında bir girdi, aynı son kullanıcıyı adlandıran isteklere sunulur. Ağ geçidi son kullanıcıyı istekten okur: bir x-litellm-end-user-id ya da x-litellm-customer-id başlığından veya gövdenin user, metadata.user_id, litellm_metadata.user ya da safety_identifier alanından. alice için depolanan bir yanıt, alice’in benzer biçimde ifade edilmiş sorusuna sunulur, bob’unkine sunulmaz.
Bundan iki şey çıkar ve ikisi de yapılandırma değil, ağ geçidinin davranışıdır:
- Ağ geçidi bu adların hiçbirini doğrulamaz. Anahtarı tutan herkes herhangi bir son kullanıcıyı adlandırabilir ve o son kullanıcı için depolananı alır. Anahtarı, son kullanıcılarının kim olduğunu bilen uygulamada tutun ve onları uygulamanın adlandırmasına izin verin; anahtarı son kullanıcıların kendilerine vermeyin.
- Hiçbir son kullanıcı adlandırmayan istekler tek bir önbelleği paylaşır. Aynı anahtarı sunan bu tür her istek, kimin gönderdiğinden bağımsız olarak aynı girdilerden yanıtlanır.
key altında, anahtarı sunan her çağıran tek bir önbellekten yanıtlanır. Bağlantının değerlerine scope: key ekleyip yeniden derleyin: yapılandırmanın semantic_cache_scope alanı key olur ve işlenmiş çıktıda başka hiçbir şey değişmez. Bu durumda bir başlığın adlandırdığı son kullanıcı kovanın parçası olmaz; böylece bir x-litellm-end-user-id başlığında adlandırılan alice için depolanan bir yanıt, araç çağrıları dahil, bob’un kendisini aynı biçimde adlandıran, benzer şekilde ifade edilmiş sorusuna sunulur. Ancak gövdenin user alanı isteğin diğer parametrelerinden biridir; bu nedenle orada farklı son kullanıcıları adlandıran iki istek, iki sıcaklığın olduğu gibi, yine farklı kovalara düşer. Bu, yalnızca herkes için aynı olan yanıtların önbelleğine uygundur.
Derlemeyi durduran durumlar
Bunların her biri, derlemenin yazdırdığı ve neyin değiştirileceğini belirten bir cümledir:
-
Yönetici anahtarı yok.
api_keyeklentisini kaldırın; derleme herhangi bir şey işlenmeden önce durur:[… omitted: a line reporting on the gateway configuration step's plugin, what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][CATALOG_ERROR E0033]Recipe/FeatureRecipe assertionscaused by: FeatureRecipe "semantic-caching-litellm" instance "router" assertion "gateway_checks_the_caller": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "router" needs core/gateway/litellm to check every caller's key before a cached reply is served, but its api_key credential slot is not attached, so the gateway checks no caller and a cache bucket would be made only of what each caller claims. Attach a credential to the api_key slot of "router" -
Depo yok.
cache_storekenarını kaldırın; derleme, bağlanması gereken soketi belirterek durur. -
vector_searchyayımlamayan bir depo. Soket anahtar-değer depolarını kabul eder ve ağ geçidinin Recipe’i, önbelleğin yanıtlarını aramak için kullandığı Redis sorgu motorunun vektör aramasını sunduğunu belirtmeyen bir depoda durur: 8.0 sürümünden önceki bir Redis ya da Valkey, her istek yine başarılı olurken hiçbir şeyi önbelleğe almazdı. -
Ağ geçidinde ikinci bir
core/semantic-cachingeklentisi; ağ geçidinin tek bir önbelleği vardır. -
Aynı ağ geçidinde
core/data-masking. İkisi bir çakışma bildirir, çünkü önbellek bir isteği maskelemeden sonra anahtarlar; bu nedenle yalnızca maskelemenin değiştirdiği kısımda farklılaşan iki istek, saklanan tek bir yanıtı paylaşırdı.
Depo kullanılamadığında
Ağ geçidi depoya başlatıldığında değil, ilk isteği sunduğunda bağlanır. Depoyu kullanamazsa (depo, ağ geçidine verilmemiş bir parola istiyorsa ya da verilen parolayı reddediyorsa) her arama ıskalanır ve hiçbir şey depolanmaz; bu sırada her istek yine de model tarafından yanıtlanır. Bunu yalnızca ağ geçidinin kendi günlüğü bildirir. Parolanın iki ucunun, yani deponun password yuvasının ve cache_store kenarındaki credential değerinin, tek bir parametreyi okumasının nedeni budur.
Derleyicinin yorumlamadığı yerler
Derleyici, deponun Service adını ve portunu deponun Recipe’inden ağ geçidinin ortamına dize olarak, takma adı ve sayıları ise ağ geçidinin yapılandırmasına aktarır. Depoya bağlanmaz, cache-default:6379 adresinde herhangi bir şeyin yanıt verip vermediğini bilmez ve son kullanıcının ne olduğunu bilmez. Yukarıdaki her durdurma, kataloğun kendi varlıkları tarafından bildirilir: gerçekleştirmedeki ya da ağ geçidinin Recipe’indeki bir doğrulama olarak veya iki Features’ın bildirdiği çakışma olarak; ve bunların hiçbiri trafiğe ilişkin herhangi bir anlayışa dayanmaz.
Uyarlama
- Anahtar başına tek bir önbellek paylaşın. Her çağıranın aynı yanıtlarla sunulması gereken durumlarda
answersekinescope: keyekleyin. - Depoyu parola olmadan çalıştırın. Deponun
passwordekini vecache_storekenarındakicredentialdeğerini, Aggregate ve Release içindekicache_passwordparametresiyle birlikte kaldırın; bu durumda ağ geçidininREDIS_PASSWORDdeğeri boş olarak oluşturulur ve bağlantı parola olmadan kurulur. İki ekten yalnızca birini kaldırmak, önbelleğin depoyu kullanamamasına yol açar. - Daha fazla ya da daha az istemi eşleştirin. Yalnızca daha yakın eşleşmeleri sunmak için
similarity_thresholddeğerini yükseltin, daha fazlasını sunmak için düşürün; hangi değerin uygun olduğu gömme modeline bağlıdır.