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

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.internal

Yö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:

örnekkatalog Component’iburada ne olduğu
routercore/gateway/litellmyö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
agentcore/ai-agent/langgraphkendi grafik imajını çalıştıran uygulama
checkpointercore/datastore/valkeyajanı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:

Terminal window
aggrega scaffold --example ai-agent-and-model-router

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

Terminal window
cd ai-agent-and-model-router

Derleme

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

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

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

Terminal window
aggrega pull --release release.yaml

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

Varlı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:

Terminal window
aggrega lint --release release.yaml

bu 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.yaml

router/ 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-routing

ve 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: metrics

Recipe, 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-key

Kapsayı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-key

Bu 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: http

Geliş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: /metrics

dist/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: /metrics

port 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: latency

ve Manifest onu bu router için gerçekleştirime bağlar:

core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0

Kendine 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-routing

Bununla 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 target değ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.model değ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önlendiricinin models soketine, kendine ait bir takma ad altında ve bağlantısının taşıdığı anahtarı sunarak bağlanabilir; bu durumda values.model ajana verilen takma adı belirtir.

  • Kimlik bilgilerini bunun yerine bir depodan alın. core/referenced-secret öğesini helm/k8s-external-secret öğesine bağlayan tek Manifest satırını değiştirin ve yeniden derleyin. Oluşturulan her Secret, bir küme gizli bilgi deposundaki bir girdiyi adlandıran ve bir depo operatörünün uzlaştıracağı bir ExternalSecret olur; 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ı origin değerlerini gözden geçirmeden değiştirirseniz, oluşturulan remoteRef.key, değerin yerinde duran yer tutucu neyse o olur — burada dev-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 model kenarı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 model kenarını bir core/ai-model/openai-compatible bileşenine yönlendirin ve o yönlendiricinin adresini Release içinde bileşenin infra.endpoint alanı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.