İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

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

örnekkatalog Component’iburada ne olduğu
routercore/gateway/litellmAI ağ geçidi: her biri models soketine bağlanan bir modelden sunulan bir sohbet takma adı, assistant, ve bir gömme takma adı, embedder
chatcore/ai-model/openaiassistant 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
embeddingscore/ai-model/openai-embeddingembedder arkasındaki gömme modeli; aynı şekilde erişilir
cachecore/datastore/redisağ 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:

Terminal window
aggrega scaffold --example ai-gateway-semantic-cache

Ardından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:

Terminal window
cd ai-gateway-semantic-cache

Derleme

Terminal window
aggrega build --release release.yaml --auto-pull

Bir 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:

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Bu ç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>/dist

Bir 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_KEY

Ağ 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-semantic

Buradan 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_user altı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_key eklentisini 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 assertions
    caused 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_store kenarını kaldırın; derleme, bağlanması gereken soketi belirterek durur.

  • vector_search yayı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-caching eklentisi; 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 answers ekine scope: key ekleyin.
  • Depoyu parola olmadan çalıştırın. Deponun password ekini ve cache_store kenarındaki credential değerini, Aggregate ve Release içindeki cache_password parametresiyle birlikte kaldırın; bu durumda ağ geçidinin REDIS_PASSWORD değ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_threshold değ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.