Bir ajan, bir yönlendirici ve iki üst akış modeli
İki üst akış sağlayıcı modeline küme içindeki tek bir yönlendirici üzerinden ulaşan, Kubernetes manifestlerine derlenmiş bir ajan uygulaması.
Ajan bir modeli tek bir adla ister. Bu adın arkasında bir takma ad eşlemesi tutan bir yönlendirici, eşlemenin arkasında ise iki sağlayıcı bulunur. Ajan hangi sağlayıcının yanıt verdiğini hiçbir zaman öğrenmez, hiçbir zaman bir sağlayıcı kimlik bilgisi tutmaz ve eşleme yeniden yönlendirildiğinde değişmez — oraya bir yönlendirici koymanın nedeni de budur.
Bu çalışma alanı kendine ait hiçbir katalog varlığı tanımlamaz. Adını verdiği her Component, Feature ve Recipe standart kitaplık kataloğuyla birlikte gelir; buradaki üç varlık dosyası — bir Aggregate, bir Manifest ve bir Release — herhangi birinin yazdığı şeylerin tamamıdır.
Ne oluşturur
agent ───────────────────┐ ┌────► openai/gpt-4o │ │ │ ▼ ├────► router ──────┤ checkpointer │ (the alias map) └────► anthropic/claude-sonnet-4 (run state) │ │ an Ingress at ───────────┘ assistant.example.internalYönlendiricinin istekler için iki girişi vardır — ajan ona model kenarı üzerinden ulaşır, küme dışındaki her şey ise Ingress üzerinden ulaşır — ve her eşleme girdisi için bir çıkışı vardır. Üçüncü bir bağlantı noktası, ölçümlerini küme içindeki bir toplayıcıya sunar.
Üç bileşen vardır ve her biri farklı bir iş yapar:
| örnek | katalog Component’i | burada ne olduğu |
|---|---|---|
router | core/gateway/litellm | yönlendirme bileşeni: tek bir uç nokta, bir takma ad eşlemesi, iki yukarı akış sağlayıcısı. Adresini ve ajanın istediği takma adı yayımlar |
agent | core/ai-agent/langgraph | kendi grafik imajını çalıştıran uygulama |
checkpointer | core/datastore/valkey | ajanın çalışma durumunu tuttuğu yer; veri deposu kategorisiyle seçilir |
İkisi de ajanın Component’inin bildirdiği soketlere giden iki uses kenarı vardır: model (zorunlu; bir model bileşenini ya da bir model API’si sunan bir ağ geçidini kabul eder — yönlendirici ikincisidir) ve checkpointer_db (zorunlu; veri deposu kategorisine göre seçer). Dört Feature türü üzerinde altı Feature eki vardır — beşi yönlendiricide, biri ajanın model bağlantısında — ve her biri oluşturulan çıktıya bir şey ekler; aşağıdaki bölüm her birinin ne ürettiğini gösterir.
Ö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-agent-and-model-routerArdından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:
cd ai-agent-and-model-routerDerleme
aggrega build --release release.yaml --auto-pullBir release derlenmeden önce bir kilit dosyasına ihtiyaç duyar ve kilit dosyaları birlikte dağıtılmaz, üretilir; bu nedenle yeni bir klonda kilit dosyası yoktur. aggrega build varsayılan olarak salt okunurdur:
kilit dosyası yoksa durur ve ilerlemenin iki yolunu belirtir. Önce bir kilit dosyası çö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ı varlıklarını .aggrega-config.yaml dosyasının adlandırdığı varsayılan kayıt defterinden çözümler, bu nedenle --catalog bayrağına gerek yoktur.
Router’ın selection ekinin gerçekleştirilmesi, ne derleyiciyle ne de katalogla birlikte gelen bir plugin çalıştırır: ağ geçidi yapılandırma adımı pipeline-step/litellm-gateway-config. Çözümleme bu adımı default_registry değerinin belirttiği kayıt defterinden, hub.aggrega.ai adresinden getirir.
Aşağıdaki birkaç bölüm sizden bir satırı değiştirip yeniden derlemenizi ister. Kilit dosyası, release’in çözümlediği her varlık için bir özeti sabitler; buna bu dizindeki Aggregate ve Manifest de dahildir. Release’in kendisini ise içeriğinin özetiyle kaydeder; bu nedenle bu üç dosyadan herhangi birini düzenlemek kilit dosyasını güncelliğini yitirmiş hâle getirir ve sonraki derleme eskimiş bir sabitlemeye göre işlemek yerine durur. İleti neyin değiştiğini adlandırır — Release’i dosyasıyla, Aggregate’i veya Manifest’i adıyla — ve kaydettiği özeti bulduğu özetin yanında yazdırır. Bir pull işlemi, diğer tüm sabitlemelere uyarak değişikliği kaydeder:
aggrega pull --release release.yamlBunu çalıştırıp yeniden derleyin ya da önce aynı pull işlemini çalıştıran --auto-pull ile derleyin.
Her iki durumda da durma bir engel değil, amaçlanan davranıştır: bir derleme, eskidiğini görebildiği bir sabitlemeye göre işleme yapmaz.
Derleme, <workspace> bu örneğin klasörünü temsil edecek şekilde şunu yazdırır:
verify: plugin pipeline-step/litellm-gateway-config:1.0.0 host functions match the published .wasm[… omitted: three 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]Pull complete: release.lock (entities=24, source_artifacts=0, external_inputs=0)[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]Build completed: 12 files written to <workspace>/distVarlıklar, kilit dosyası çözümlenirken bir kez ve release derlenirken bir kez kataloğun uzlaşımlarına göre denetlenir; bu denetimlerin ortaya çıkardığı her öneri bir lint: satırı olarak yazdırılır; bu release hiçbir öneri ortaya çıkarmaz. Aynı denetimleri tek başına çalıştırmak ve herhangi bir öneriyi, geldiği varlık dosyası ve onu uyumlu hâle getirecek şeyle birlikte tam olarak okumak için:
aggrega lint --release release.yamlbu komut burada conventions checked: 19 entities, 0 advisory finding(s) bildirir.
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-agent-and-model-router` klasörü yoksa `scaffold` aracını `example` değeri `ai-agent-and-model-router` olarak ayarlanmış ve `dir` olmadan bir kez çağırın: örneği yeni bir `ai-agent-and-model-router` klasörüne yazar. Ardından `build` aracını `workspace_root` değeri `ai-agent-and-model-router`, `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-agent-and-model-router/dist/` altındadır.Oluşturulan ağaç
dist/helm/├── agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml├── agent-deployment.yaml├── checkpointer-default-service.yaml├── checkpointer-deployment.yaml├── router--api-zukey--router-secret-router-api-key.yaml├── router--metrics--router-servicemonitor-router-scrape.yaml├── router--provider-zukey--router-secret-router-provider-key.yaml├── router--published--router-ingress-router-ingress.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlrouter/ altında, router’ın Recipe’inin kendisinin ürettiği dosyalar bulunur. İkisi de Recipe’in yazmak yerine içe aktardığı paketlerden gelir; bu yüzden her biri içe aktarıldığı anahtarın, litellm-gateway-config ve request-guard anahtarlarının altında yer alır.
Bir eklentinin getirdiği her şey, bileşenin kendi manifest dosyalarıyla aynı dizinde durur ve dosya adında iki koordinat taşır: eklendiği bileşen ve eklentiye verilen ad. router--metrics--, router üzerindeki metrics eklentisidir. Neyin nereden geldiği ağaçtan hâlâ okunabilir ve her dosya, tek bir dizini okuyan bir aracın onu bulacağı yerdedir; aksini belirtmediğiniz sürece bu hedefin tüketicileri de bunu yapar.
Bu iki koordinat, dosyanın kendi adıyla tek bir dizgeyi paylaştıkları için sizin yazdığınız gibi değil, kodlanmış olarak yazılır. Bir dosya adının güvenle taşıyamayacağı bir karakter -z ve bir harfe dönüşür: api_key, api-zukey olur; router_model.credential (ajanın router_model bağlantısındaki eklentinin aldığı ad: bağlantının takma adı, bir nokta ve yuva) router-zumodel-zdcredential olur; feature.aggrega.ai/monitoring (bir Feature’ın kendi ek açıklamasının ürettiği bir eklenti adı) ise feature-zdaggrega-zdai-zsmonitoring olurdu. Dosyanın kendi adı taşıdığı noktaları korur; böylece .yaml soneki hâlâ bir sonek olarak okunur.
Buradaki bir sayfa bir derlemenin ürettiğini gösterdiğinde, blok gerçek bir çalıştırmadan kopyalanmıştır; uzlaşım ve dışarıda bırakılan satırlar için kullandığı işaret için Bu sayfalardaki çıktıyı okumak bölümüne bakın.
Yönlendirme tablosu
Yönlendiricinin var olma nedeni haritasıdır ve bu harita yazılan dosyada kalmak yerine işlenmiş çıktıya ulaşır. İşte
dist/helm/router/litellm-gateway-config/configmap.yaml dosyasının data bloğunun tamamı:
data: config.yaml: | model_list: - model_name: assistant litellm_params: model: openai/gpt-4o api_key: os.environ/LITELLM_PROVIDER_API_KEY - model_name: assistant litellm_params: model: anthropic/claude-sonnet-4 api_key: os.environ/LITELLM_PROVIDER_API_KEY litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter - prometheus router_settings: routing_strategy: latency-based-routingve ikinci ConfigMap’in,
dist/helm/router/request-guard/request-guard.yaml, taşıdığı dosyaların metni dışarıda bırakılmış data bloğu:
data: request_field_filter.py: | [… omitted: the text of the router's request guard, a Python module described below] path-allowlist.conf: | [… omitted: the configuration of the router's path allowlist, described below]Bunlardan okunmaya değer beş şey var.
İki girdi de aynı takma adı yayımlar. Yönlendiriciye her istekte yapacağı bir seçim veren budur ve gövdenin sonundaki router_settings bu seçimi nasıl yaptığını söyler: latency-based-routing; aşağıdaki ilgili bölümün gösterdiği gibi, bunu oraya yönlendiricinin kendi Recipe’i değil, yönlendiricinin selection eki yazar. Takma adlarının hepsi farklı olan bir harita yalnızca ada göre yönlendirir ve strateji bu konuda hiçbir şeyi değiştirmez. Tek bir takma adın paylaşılması, iki girdinin yönlendiricinin models soketine bağlanmış model bileşenlerinden sunulmak yerine neden values.models içine elle yazıldığının da nedenidir: bağlanmış bir model kendi bağlantısının takma adı altında sunulur ve bu takma adı başka hiçbir girdi yayımlayamaz, dolayısıyla bağlanmış iki model asla bir takma adı paylaşmaz. İkinci neden Anthropic’e özgüdür: yönlendirici bağlanmış bir modelin girdisini yalnızca OpenAI API’si üzerinden yazar, Anthropic’in modeli ise kendi API’sine yanıt verir; bu yüzden core/ai-model/anthropic bağlanırsa derleme durur ve bu üst kaynağın bunun yerine haritaya yazılması gerektiğini söyler.
Hedefler, derleyicinin yorumlamadığı dizelerdir.
openai/gpt-4o deterministik bir işaretçidir: çalışan proxy bunu bir isteği sunarken çözümler. Derleyici derleme zamanında hiçbir sağlayıcıyla iletişim kurmaz; bu nedenle size bir hedefin var olduğunu, doğru yazıldığını ya da hesabınızın ona erişebildiğini söyleyemez. openai/gpt-4o değerini openai/not-a-real-model olarak değiştirdiğinizde derleme yine başarılı olur; hata istek zamanında, sağlayıcıdan gelir.
Bu dosyada hiçbir kimlik bilgisi değeri yoktur. Her girdi bunun yerine, proxy’nin kendi dolaylama mekanizmasıyla bir ortam değişkenini adlandırır. Değer kapsayıcıya tamamen başka bir yoldan ulaşır; bu yol aşağıda gösterilmiştir.
Her istek önce bir korumayla karşılaşır. İlk callbacks girdisi request_field_filter modülünü dosyasının tam yoluyla kaydeder: ikinci ConfigMap, yönlendiricinin kapsayıcısına /etc/litellm-request-guard konumunda bağlanır; bu, ilk ConfigMap’in bağlandığı ve proxy’nin yapılandırmasını okuduğu /etc/litellm dizininin yanında kendine ait bir dizindir. Bu ikinci ConfigMap, bu proxy’yi çalıştıran her Recipe’in içe aktardığı bir paket olan LiteLLMGuard#/artifacts/RequestGuard kaynağından gelir; böylece koruma ve aşağıdaki izin listesi, proxy nerede çalışırsa çalışsın tek bir metne sahiptir. Yönlendiricinin Recipe’i bu korumayı her Release’te teslim eder, çünkü sağlayıcı kimlik bilgisini yönlendirici tutar. Koruma, bir çağırandan yalnızca proxy’nin isteğin izlediği rota için bildirdiği istek alanlarını ve buna ek olarak Release’in yönlendiricinin infra.admitted_request_fields değerinde adlandırdıklarını iletir; başka her alana o alanı adlandıran bir hatayla yanıt verir ve hiçbir şey iletmez. Böylece bir çağıran, istek gövdesindeki bir model listesiyle yönlendiriciyi kendi adresine yönlendiremez ya da yönlendiricinin anahtarı yerine kendi sağlayıcı anahtarını gönderemez. Bir çağıran, yönlendiricinin her isteğe kendisinin yazdığı kimliği de belirleyemez: doğruladığı anahtarın özeti, o anahtarın ekibi ve kuruluşu ve son kullanıcı. Yönlendiricinin çağıranın metadata alanını kendisininkinden ayrı tuttuğu bir responses ya da messages isteğinde, çağıranın oraya yazdığı her ekip, kuruluş ya da son kullanıcı alanını kaldırır ve koruma, orada anahtarı adlandıran bir isteği, metadata.user_api_key, reddeder; diğer her rotada ise yönlendiricinin değeri, çağıranın gönderdiği her değerin yerini alır. Bu Release başka hiçbir şeye izin vermez. İkinci girdi olan prometheus, proxy’nin kendi metrik geri çağrısıdır ve yönlendiricinin metrics_enabled değeri bunu etkinleştirir; aşağıdaki metrics eki bunun kaydettiklerini toplar.
Yalnızca yönlendiricinin kendi rotalarına erişilebilir. Koruma yalnızca isteği kendisine ileten rotaları görür; bu nedenle ikinci ConfigMap’in diğer dosyası, pod’un ikinci kapsayıcısını yapılandırır. Bu kapsayıcı yalnızca o ConfigMap’i bağlar ve resmi nginx imajını bir yol izin listesi olarak çalıştırır. Yönlendiricinin kendisi pod’un geri döngü adresinde dinler; pod’un dışındaki hiçbir şey ona orada ulaşamaz. İzin listesi ise aşağıdaki Service’in hedeflediği port olan 4000 portunda dinler. Bir isteği yalnızca yöntemi ve yolu yönlendiricinin sunduğu rotalardan biriyse iletir: korumanın denetlediği model istek rotaları, takma ad ne olursa olsun yönlendiricinin sunduğu yazımlarla (aralarında /v1/chat/completions ve /v1/messages); model listeleme; sağlık denetimleri; ve yönetim rotalarından anahtar yönetimi. Diğer her yola 403 ile yanıt verir ve hiçbir şey iletmez. Böylece proxy’nin token sayma rotalarına, sağlayıcıların kendi API’lerine geçiş rotalarına, diğer yönetim rotalarına ve yönetim konsoluna yönlendirici üzerinden erişilemez; Azure istemcisinin gönderdiği yollarda olduğu gibi yolu model adını taşıyan bir model rotasına da erişilemez: orada proxy, bir isteği nasıl kaydedeceğine karar vermek için yoldaki sözcükleri, takma ad dahil, okur ve yönlendirici bu haritanın kendi assistant takma adı için bu rotadan gelen bir isteği reddeder. Proxy’nin metrikleri de bu rotalar arasında değildir: 4000 portu /metrics isteğine 403 ile yanıt verir. Yönlendiricinin metrics_enabled değeri, Aggregate’in ayarladığı gibi true olduğunda, izin listesi 9090 portunda da dinler ve orada yalnızca /metrics için bir GET isteğini, proxy’nin metrikleri için geri döngü adresinde tuttuğu dinleyiciye iletir; diğer her isteğe 403 ile yanıt verir. Bu port hiçbir çağıranı denetlemez ve metrikler, yönlendiricinin harcamayı ilişkilendirdiği özetlenmiş anahtarları, anahtar takma adlarını ve kullanıcı e-postalarını adlandırır.
Yönlendiricinin yayımladıkları
Yönlendiricinin Recipe’i, her model bileşeninin yayımladığı iki anahtarı yayımlar: bir istemci kitaplığına verilen temel URL olan bir endpoint ve bir isteğin talep ettiği ad olan bir model. Ajanın model soketinin bir model yerine yönlendiriciyi kabul etmesini sağlayan budur. Soketin seçicisi
component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api şeklindedir: model ya da ağ geçidi kategorisinde olup model.aggrega.ai/api etiketini taşıyan bir bileşeni kabul eder; bu etiket, bileşenin yayımladığı adreste hangi model API’sinin yanıt verdiğini adlandırır. Yönlendirici model.aggrega.ai/api: openai etiketini taşır. Hiçbir model API’si sunmayan bir ağ geçidi böyle bir etiket taşımaz ve ajandan böyle bir ağ geçidine giden bir kenar, soketi ve hedefin karşılamadığı seçiciyi adlandırarak derlemeyi durdurur.
Adres, yönlendiricinin kendi Recipe’inin ürettiği Service’tir — dist/helm/router-default-service.yaml dosyasının spec bölümünün tamamı:
spec: type: ClusterIP selector: app: router ports: - name: http port: 4000 targetPort: http - name: metrics port: 9090 targetPort: metricsRecipe, yayımladığı http://router-default:4000/v1 uç noktasını, Service’in adını ve bağlantı noktasını aldığı aynı iki olgudan oluşturur: bileşenin kendi adı ve infra.port değeri. Service’in hedeflediği bağlantı noktası http, yönlendiricinin yol izin listesinin dinlediği bağlantı noktasıdır; ikincisi olan metrics, yönlendiricinin metrikleri açık olduğu için oradadır ve yalnızca onları taşır. Üç dosyanın hiçbirinde router-default açıkça yazılmaz. router bileşenini yeniden adlandırın — Aggregate’teki ve Release’teki anahtarını ve ajanın onu adlandıran kenarını — ajanın aldığı adres de buna uyar: gateway olarak yeniden adlandırıldığında ajanın OPENAI_BASE_URL değeri http://gateway-default:4000/v1 olur.
Ad, yönlendiricinin model olarak yayımladığı takma addır. Bu eşleme, her iki girdisinden tek bir takma ad, assistant, yayımlar; bu nedenle yönlendirici bunu yayımlar ve values.model değeri belirtilmez. İkinci girdiye kendine ait bir takma ad verin — örneğin summarizer — ve yönlendirici yalnızca bir tane yayımlayabildiği için derleme hiçbir şey işlenmeden durur. Bu durma, yönlendiricinin Component’inin başarısız bir doğrulaması olan E0033’tür ve iletisi kuralın kendi cümlesiyle biter:
values.model is not set, but values.models publishes 2 aliases (assistant,
summarizer), so the gateway cannot tell which one a component wired to it asks
for; set values.model to one of them (values.model ayarlanmamış, ancak values.models 2 takma ad yayımlıyor (assistant, summarizer); bu nedenle ağ geçidi, kendisine bağlanan bir bileşenin hangisini istediğini belirleyemez; values.model değerini bunlardan birine ayarlayın). models yanına model: assistant ayarlamak bunu giderir ve ajana yeniden assistant verilir. summarizer isteyen bir çağıran, aynı uç noktadan onu adıyla ister.
Ajanın aldıkları
Ajanın Recipe’i her iki kenarını ve ajanın kendi değerlerini okur ve bunları konteyner ortamına dönüştürür. dist/helm/agent-deployment.yaml dosyasının env bloğunun tamamı şöyledir:
env: - name: OPENAI_API_KEY valueFrom: secretKeyRef: name: agent-router-model.credential key: api-key - name: LANGGRAPH_DEFAULT_RECURSION_LIMIT value: "25" - name: OPENAI_BASE_URL value: http://router-default:4000/v1 - name: OPENAI_MODEL value: assistant - name: LANGGRAPH_CHECKPOINTER_HOST value: checkpointer-default - name: LANGGRAPH_CHECKPOINTER_PORT value: "6379" - name: LANGGRAPH_GRAPH_ENTRYPOINT value: app.graph:graphİlki model kenarının taşıdığı ekten geldi ve helm provider’ı bir Secret’tan okunan böyle bir girdiyi düz girdilerden önce yazar. Özyineleme sınırı, ajanın kendi recursion_limit değeridir ve LangGraph’ın kendiliğinden okuduğu değişken altında verilir; sonraki ikisi model kenarından, onlardan sonraki ikisi checkpointer_db kenarından geldi, sonuncusu ise ajanın kendi graph_entrypoint değeridir ve uygulamanın kodunun okuduğu varsayılan bir ad altında verilir; bileşenin kendisindeki bir inject bloğu bu adın yerini alırdı. Aggregate’in neyi söylemek zorunda kalmadığına dikkat edin: kenarların hiçbiri bir inject bloğu taşımaz, çünkü tüketen Recipe her bağlantıyı varsayılan adlar altında teslim eder ve kenardaki bir inject bloğu bu adların yerini alırdı. Geliştirici ajanın bir model kullandığını bildirir; uç noktasının geldiği değişken istemci kitaplığının okuduğu değişkendir ve kenar ne belirlerse öyle kalır.
LANGGRAPH_CHECKPOINTER_PORT: "6379" değerine de dikkat edin. Release checkpointer: {} bildirir ve hiçbir şey yapılandırmaz; dolayısıyla bu port, önbellek Component’inin kendi şema varsayılanıdır, somutlaştırılmış ve kenar boyunca aktarılmıştır.
Ajan, yönlendiriciyle tam olarak bir sağlayıcıyla doğrudan konuşurken kullanacağı lehçeyle konuşur: bir temel URL, bir model adı ve bir anahtar. Yönlendiricinin, uygulama değişmeden araya eklenebilmesini, taşınabilmesini veya yeniden yönlendirilebilmesini sağlayan budur.
Altı ek ve her birinin oluşturduğu çıktı
Çıktıda hiçbir şeyi değiştirmeyen bir ek hiçbir şey öğretmez. Bu altı ekin her biri çıktıya bir şey koyar.
Router üzerindeki api_key — çağıranlardan istediği anahtar
core/referenced-secret, router’ın Component’inin bildirdiği bir yuvayı doldurur; tuttuğu
anahtar, LiteLLM’in master key dediği anahtardır. Kendi Secret’ını oluşturur ve router’ın
kapsayıcısı ona başvurur.
dist/helm/router--api-zukey--router-secret-router-api-key.yaml dosyasından:
stringData: master-key: "dev-router-admin-key-change-me"ve router’ın kapsayıcısının env bloğunda, dist/helm/router-deployment.yaml dosyasından:
- name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-keyKapsayıcı değeri değil, bir başvuruyu taşır. Secret’ın adı ek tarafından yayımlanır ve tüketici tarafından okunur; böylece iki taraftan hiçbiri onu yeniden türetmez.
Router üzerindeki provider_key — yukarı akışa sunduğu anahtar
Aynı Feature farklı bir yuvada; iki yuva arasındaki fark da router’ın asıl amacıdır.
values.models içine yazılan girdilerin, burada ikisinin de, tek kimlik bilgisi budur;
router’ın models soketine bağlanan bir model ise bunun yerine kendi bağlantısının taşıdığı
anahtarı sunar, asla bunu değil.
dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml dosyasından:
stringData: provider-key: "upstream-provider-key-change-me"ve aynı kapsayıcının env bloğunda:
- name: LITELLM_PROVIDER_API_KEY valueFrom: secretKeyRef: name: router-provider-key key: provider-keyBu ek yönlendirme tablosunu da değiştirir. Yukarıdaki yönlendirme tablosunun data
bloğuna dönüp bakın: her eşleme girdisi, aynı değişkeni adlandıran
api_key: os.environ/LITELLM_PROVIDER_API_KEY satırını taşır.
provider_key ekini Aggregate’ten kaldırıp yeniden derleyin. Derleme on iki yerine on bir
dosya bildirir — Secret ortadan kalkmıştır — ve yönlendirme tablosunun ConfigMap’i tam olarak
o iki api_key satırı kadar farklılaşır, başka hiçbir şey değişmez; guard’ın ConfigMap’i
değişmez. Eşlemenin geri kalanı yazıldığı sırayı ve biçimi korur, router hâlâ hizmet verir
ve yönlendirir, ancak yönlendirilen bir istek artık sunulacak kimlik bilgisi olmadığı için
sağlayıcıda başarısız olur.
Değişken adı router’ın Recipe’inde bir kez yazılır ve hem yönlendirme tablosu hem de kapsayıcının ortamı onu oradan okur; böylece bir tablo, hiçbir şeyin ayarlamadığı bir değişkeni adlandırır hâle gelemez.
İki kimlik bilgisi birbirinden ayrı kalır ve router’ın sağladığı şey bu ayrımdır: yukarı akış anahtarı router’ın içinde kalır, çağıran uygulama ise router’ın anahtarından başka bir şey tutmaz.
Ajanın model bağlantısı üzerindeki credential — router’a sunduğu anahtar
Yine core/referenced-secret, aynı konuşmanın öbür tarafında. Ajanın model soketi bir
credential yuvası bildirir; bu yüzden anahtar, sunulduğu bağlantıya, Aggregate’teki
kenarın altında eklenir:
uses: model: router_model: target: router features: credential: type: core/referenced-secret values: key: api-key origin: "{{ .parameters.router_admin_key }}"dist/helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml
dosyasından:
stringData: api-key: "dev-router-admin-key-change-me"Bu, yukarıdaki router’ın master-key değeriyle aynı değerdir ve iki kez yazılmaz. İki ek de
yukarı taşınmış tek bir parametreyi okur:
origin: "{{ .parameters.router_admin_key }}"Aggregate parametreyi bildirir ve Release onu karşılar; böylece anahtarın yazıldığı tek bir yer olur ve iki Secret birbirinden ayrı düzenlenemez. Release’te bir kez değiştirin, oluşan iki Secret birlikte değişir.
Her ek yine de kendi Secret’ını oluşturur; bu Secret, onu tüketen bileşenden — ajanınki
için de eklendiği bağlantıdan — adlandırılır: agent-router-model.credential. Paylaşılan
parametrenin paylaştığı şey kaynak değil, değerdir.
Router üzerindeki published — küme dışındaki bir adres
core/public-ingress hiçbir yuvayı doldurmaz: router’ın taşıdığı kendi seçicisi
component.aggrega.ai/type=server ile kabul edilir. Router’ın Recipe’inin hiçbir şey
bilmediği bir kaynak getirir.
dist/helm/router--published--router-ingress-router-ingress.yaml dosyasının tüm spec
bölümü:
spec: rules: - host: assistant.example.internal http: paths: - path: / pathType: Prefix backend: service: name: router-default port: name: httpGeliştirici onu Aggregate’te path ile ekler, çünkü bir uygulamanın hangi isteklere hizmet
verdiği, uygulamanın ne olduğunun bir parçasıdır. Operatör host değerini ve port adını
aynı ekin Release’teki girdisine yazar: host, ortamın router için kullandığı addır; bu
yüzden operatör onu ortam başına, her ortamın Release’inde adlandırır. Arka uç Service’i
ikisinden hiçbiri sağlamadı: service_name ayarlanmadan bırakılır ve ekin gerçekleştirimi,
router’ın kendi Recipe’inin ürettiği Service’e geri döner. Çıktıda ingressClassName alanı
yoktur, çünkü hiçbir şey onu ayarlamadı ve gerçekleştirim kendisine verilmeyeni çıkarır;
kaynağı kümenin varsayılan sınıfı üstlenir.
Router üzerindeki metrics — bir kazıma hedefi
core/prometheus-exporter, aynı seçiciyle kabul edilir ve kendine ait başka bir kaynak
getirir. Aldığı her girdi uygulama amacı değil operatör boyutlandırmasıdır — bir platformun
ne sıklıkla kazıdığı, hangi portu ve yolu okuduğu platformun özellikleridir — bu yüzden
operatör onu Release’te, router’ın girdisinde, türü infra değerinin yanında olacak
şekilde ekler. Aggregate ondan söz etmez:
components: router: features: metrics: type: core/prometheus-exporter infra: interval: 30s port: metrics path: /metricsdist/helm/router--metrics--router-servicemonitor-router-scrape.yaml dosyasının tüm
spec bölümü:
spec: selector: matchLabels: app.kubernetes.io/name: router endpoints: - port: metrics interval: 30s path: /metricsport bir sayı değil bir Service portu adlandırır: metrics; router’ın Recipe’i bunu,
Aggregate router’ın metrics_enabled değerini ayarladığı için üretir ve metrikler bu porttan
sunulur. Bu aynı zamanda Feature’ın varsayılan port adıdır ve burada diğer iki ayarla
birlikte açıkça yazılmıştır. Yukarıdaki Ingress’in yönlendirdiği http portu /metrics
isteğine 403 ile yanıt verir; bu yüzden oraya yöneltilen bir kazıma hiçbir şey toplamaz.
Metriklerin sunulup sunulmayacağı geliştiricinin Aggregate’te yaptığı seçimdir; bir
platformun onları ne sıklıkla, hangi port ve yoldan kazıyacağı ise operatörün burada yaptığı
seçimdir.
Router üzerindeki selection — hedefleri arasında nasıl seçim yaptığı
core/target-selection, router’ın yaptığı gibi
gateway.aggrega.ai/intelligence: semantic taşıyan bir ağ geçidine eklenir. Router’ın
hangi yolla seçim yapacağı, uygulamanın ondan istediği şeyin bir parçasıdır; bu yüzden
geliştirici onu Aggregate’te, strategy bir değer olacak şekilde ekler:
components: router: features: selection: type: core/target-selection values: strategy: latencyve Manifest onu bu router için gerçekleştirime bağlar:
core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0Kendine ait bir dosya oluşturmaz. Gerçekleştirimi, router’ın Recipe’inin oluşturduğu
yönlendirme tablosuna tek bir ayar yazar — yukarıdaki data bloğunun son iki satırı:
router_settings: routing_strategy: latency-based-routingBununla proxy, assistant için gelen her isteği, son on yanıtı ortalamada en kısa sürede
veren girdiye gönderir; bir yanıt token’larını bildiriyorsa bu süre çıktı token’ı başına
hesaplanır. Henüz denenmemiş bir girdi en hızlı sayılır; böylece ortalamalar karar vermeden
önce her biri denenir. Eki Aggregate’ten kaldırıp yeniden derleyin: derleme yine on iki
dosya bildirir ve yönlendirme tablosunun ConfigMap’i tam olarak o iki satır kadar farklılaşır.
Router’ın Recipe’i kendine ait bir strateji yazmaz ve strateji olmadan proxy iki girdi
arasında rastgele seçim yapar.
Bunun yerine strategy: cost isteyin; derleme hiçbir şey yazmadan durur. Durma E0033’tür,
gerçekleştirimin başarısız bir doğrulamasıdır ve mesajı kuralın kendi cümlesiyle biter:
core/target-selection attachment “selection” on
“router” asks for strategy cost, but core/gateway/litellm cannot choose between
the entries of its model map by cost: the proxy looks each entry’s target up,
exactly as written, in its own price table, which names OpenAI’s and Anthropic’s
models without the provider prefix a target carries (gpt-4o, not
openai/gpt-4o) and which the proxy may fetch afresh when it starts, and it
prices an entry it does not find, and that carries no price of its own, at a
fixed fallback, so the entries sharing an alias are priced alike and the choice
falls to their order. Ask for strategy latency, or remove the attachment (“router” üzerindeki “selection” core/target-selection eki maliyet stratejisi istiyor, ancak core/gateway/litellm model eşlemesinin girdileri arasında maliyete göre seçim yapamaz: proxy her girdinin hedefini, tam yazıldığı gibi, kendi fiyat tablosunda arar; bu tablo OpenAI ve Anthropic modellerini bir hedefin taşıdığı sağlayıcı öneki olmadan adlandırır (openai/gpt-4o değil, gpt-4o) ve proxy onu başlarken yeniden indirebilir; bulamadığı ve kendi fiyatını taşımayan bir girdiyi sabit bir yedek fiyatla fiyatlandırır; bu yüzden bir takma adı paylaşan girdiler aynı fiyatı alır ve seçim sıralarına kalır. Gecikme stratejisini isteyin ya da eki kaldırın). Buradaki iki hedef de bu şekilde yazılmıştır; bu yüzden Aggregate maliyet isterken proxy her isteği bunlardan ilkine gönderirdi.
Derleyicinin yorumlamadığı yerler
Ajanın adresi ve model adı, router’ın yayımladıklarından okunur; böylece üç dosyadaki hiçbir ad çiftinin elle uyumlu tutulması gerekmez. Derlemenin gerçekten denetlediği şey, router’ın kendi kuralıdır: yayımladığı takma ad, eşlemesinin yayımladığı bir takma ad olmalıdır — bu, Component’inin bildirdiği ve derlemenin, bir varlığın taşıdığı diğer her doğrulama gibi değerlendirdiği bir kuraldır.
Geri kalanı, bir yerden başka bir yere aktarılan dizgelerdir. Derleyici adresi ve takma adı
okumadan yönlendirir: birinin bir ana makine adı, diğerinin bir model adı olduğunu bilmez ve
router-default:4000 adresinde bir şeyin yanıt verdiğini denetlemek için çalışan bir kümeye
erişimi yoktur. Router’ı kabul eden
model.aggrega.ai/api etiketi de aynı türden bir dizgedir — soketin seçicisi onunla eşleşir ve
orada gerçekte hangi API’nin yanıt verdiğini hiçbir şey denetlemez. Eşlemedeki her target de
çalışan proxy’nin çözümlediği bir göstericidir: openai/gpt-4o değerini openai/not-a-real-model
olarak değiştirin; derleme yine başarılı olur ve hata istek anında ortaya çıkar.
Örneğin geri kalanını çalıştıran da aynı özelliktir. Derleyici aktardığını yorumlamadığı için router farklı bir sağlayıcıya yöneltilebilir, ajan farklı bir router’a bağlanabilir ve kimlik bilgisi gerçekleştirimi depo destekli bir gerçekleştirimle değiştirilebilir — bunların hiçbiri derleyicinin herhangi birini anlamasını gerektirmez ve ajan değişmez.
Uyarlama
-
Bir sağlayıcıyı yeniden yönlendirin. Yönlendiricinin eşlemesindeki bir
targetdeğerini düzenleyin. Başka hiçbir şey değişmez: ne model, ne ajan, ne de oluşturulmuş bir Secret. -
Üçüncü bir sağlayıcı ekleyin. Bir eşleme girdisi ekleyin. Mevcut takma adı yayımlıyorsa, strateji üçü arasında seçim yapmaya başlar. Yeni bir takma ad yayımlıyorsa, eşleme iki takma ad yayımlar ve yönlendiricinin
values.modeldeğeri ajana verilen takma adı belirtir; diğerini isteyen bir çağıran onu adıyla ister. Kataloğun modellediği ve API’si OpenAI API’si olan bir model bunun yerine yönlendiricininmodelssoketine, kendine ait bir takma ad altında ve bağlantısının taşıdığı anahtarı sunarak bağlanabilir; bu durumdavalues.modelajana verilen takma adı belirtir. -
Kimlik bilgilerini bunun yerine bir depodan alın.
core/referenced-secretöğesinihelm/k8s-external-secretöğesine bağlayan tek Manifest satırını değiştirin ve yeniden derleyin. Oluşturulan herSecret, bir küme gizli bilgi deposundaki bir girdiyi adlandıran ve bir depo operatörünün uzlaştıracağı birExternalSecretolur; ve her tüketicinin oluşturulan başvurusu bayt düzeyinde aynı kalır, çünkü konum belirteci iki taraf arasında kararlaştırılmak yerine üreten tarafça yayımlanır. Derlemenin başarılı olması için üç dosyada başka hiçbir şeyin değişmesi gerekmez.Yine de değişimin bir anlam taşıması için önce bir şeyin yeniden yazılması gerekir:
origin, iki gerçekleştirme arasında anlam değiştirir. Bu çalışma alanının gerçekleştirmesi onu saklanacak değer olarak okur; diğeri ise alınacak anahtar olarak okur. Satırıorigindeğerlerini gözden geçirmeden değiştirirseniz, oluşturulanremoteRef.key, değerin yerinde duran yer tutucu neyse o olur — buradadev-router-admin-key-change-me. Bu durumda çıktı ağacındaki hiçbir şey bu dizeyi gizli malzeme olarak tutmaz, ancak dize, var olmayan bir girdiyi adlandıran bir depo anahtarı olarak yine oradadır. -
Yönlendiriciyi kaldırın. Ajanın
modelkenarını bunun yerine sağlayıcıya özgü bir model bileşenine yönlendirin. Bu durumda ajan bir sağlayıcı kimlik bilgisini kendisi tutar; bu da yönlendiricinin ortadan kaldırmak için var olduğu ödünleşimdir. -
Kataloğun modellemediği bir yönlendiriciye ulaşın. Ajanın
modelkenarını bircore/ai-model/openai-compatiblebileşenine yönlendirin ve o yönlendiricinin adresini Release içinde bileşenininfra.endpointalanına yazın. Bu bileşenin arkasında küme içinde hiçbir şey çalışmaz; bu nedenle adresi yazmak ve adlandırdığı hizmetle uyumlu tutmak operatöre kalır.
Tek bir kimlik bilgisini birden çok tüketicinin bağlantıları arasında paylaşmak için model-api-key-sharing bölümüne bakın. Hiçbir katalog varlığının bildirmediği bir soket için adhoc-uses-socket bölümüne bakın.