Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Sebuah agen, sebuah router, dan dua model upstream

Sebuah aplikasi agen yang menjangkau dua model penyedia upstream melalui satu router di dalam klaster, dikompilasi menjadi manifest Kubernetes.

Agen meminta sebuah model dengan satu nama. Di balik nama itu terdapat router yang menyimpan peta alias, dan di balik peta itu terdapat dua penyedia. Agen tidak pernah mengetahui penyedia mana yang menjawab, tidak pernah memegang kredensial penyedia, dan tidak berubah ketika peta itu diarahkan ulang — dan itulah alasan untuk menempatkan router di sana.

Workspace ini tidak menulis entitas katalog sendiri. Setiap Component, Feature, dan Recipe yang disebutkannya tersedia dalam katalog pustaka standar; tiga berkas entitas di sini — sebuah Aggregate, sebuah Manifest, dan sebuah Release — adalah keseluruhan yang ditulis oleh siapa pun.

Apa yang dibangunnya

agent ───────────────────┐ ┌────► openai/gpt-4o
│ │ │
▼ ├────► router ──────┤
checkpointer │ (the alias map) └────► anthropic/claude-sonnet-4
(run state) │
│
an Ingress at ───────────┘
assistant.example.internal

Router memiliki dua jalur masuk untuk permintaan — agen mencapainya melalui edge model miliknya, dan apa pun dari luar mencapainya melalui Ingress — serta satu jalur keluar per entri peta. Port ketiga menyajikan metriknya kepada scraper di dalam kluster.

Tiga komponen, dan masing-masing menjalankan tugas yang berbeda:

instansComponent katalogperannya di sini
routercore/gateway/litellmkomponen perutean: satu endpoint, satu peta alias, dua penyedia upstream. Komponen ini memublikasikan alamatnya dan alias yang diminta oleh agen
agentcore/ai-agent/langgraphaplikasi, yang menjalankan image graph miliknya sendiri
checkpointercore/datastore/valkeytempat agen menyimpan status run, dipilih berdasarkan kategori datastore

Dua edge uses, keduanya menuju socket yang dideklarasikan oleh Component milik agen: model (wajib, menerima komponen model atau gateway yang menyajikan API model — router adalah yang kedua) dan checkpointer_db (wajib, memilih berdasarkan kategori datastore). Enam lampiran Feature dari empat jenis Feature — lima pada router, satu pada koneksi model milik agen — yang masing-masing menempatkan sesuatu dalam keluaran yang dirender; bagian di bawah menunjukkan apa yang dihasilkan oleh masing-masing.

Membuat contoh

Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.

Tulis contoh ke folder baru yang dinamai sesuai contoh itu:

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

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

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

Build

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

Sebuah release memerlukan lockfile sebelum dibangun, dan lockfile dibuat alih-alih dikirimkan, sehingga hasil clone yang baru tidak memilikinya. aggrega build secara default bersifat hanya-baca: tanpa lockfile, perintah ini berhenti dan menyebutkan dua cara untuk melanjutkan. Resolusikan lockfile terlebih dahulu, atau biarkan build mengisinya:

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

Workspace ini meresolusikan entitasnya dari registry default yang disebut .aggrega-config.yaml, sehingga flag --catalog tidak diperlukan.

Realisasi lampiran selection pada router menjalankan satu plugin yang tidak disertakan baik dalam compiler maupun dalam katalog, yaitu langkah konfigurasi gateway pipeline-step/litellm-gateway-config, yang diambil oleh proses resolusi dari registry yang disebutkan oleh default_registry, yaitu hub.aggrega.ai.

Beberapa bagian di bawah meminta Anda mengubah satu baris lalu membangun ulang. Lockfile mengunci digest untuk setiap entitas yang diresolusikan oleh release, termasuk Aggregate dan Manifest di direktori ini, dan mencatat Release itu sendiri berdasarkan digest kontennya — sehingga mengedit salah satu dari ketiga file ini membuat lockfile kedaluwarsa, dan build berikutnya berhenti alih-alih merender berdasarkan pin yang usang. Pesannya menyebutkan apa yang berubah — Release berdasarkan file-nya, Aggregate atau Manifest berdasarkan namanya — dan mencetak digest yang dicatat di samping digest yang ditemukan. Sebuah pull mencatat perubahan tersebut sambil tetap mematuhi setiap pin lainnya:

Terminal window
aggrega pull --release release.yaml

Jalankan perintah itu lalu bangun lagi, atau bangun dengan --auto-pull, yang menjalankan pull yang sama terlebih dahulu. Bagaimanapun juga, penghentian itu memang disengaja, bukan hambatan: build tidak merender berdasarkan pin yang dapat dilihatnya sudah usang.

Build mencetak keluaran berikut, dengan <workspace> mewakili folder contoh ini:

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

Entitas diperiksa terhadap konvensi katalog satu kali saat lockfile diresolusikan dan satu kali saat release dibangun, dan setiap peringatan yang dimunculkan oleh pemeriksaan tersebut dicetak sebagai baris lint:; release ini tidak memunculkan satu pun. Untuk menjalankan pemeriksaan yang sama secara tersendiri, dan membaca setiap peringatan secara lengkap beserta file entitas asalnya dan apa yang akan membuatnya sesuai:

Terminal window
aggrega lint --release release.yaml

yang di sini melaporkan conventions checked: 19 entities, 0 advisory finding(s).

Dengan asisten AI

Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.

Gunakan hanya tool Aggrega, dan jangan membuat folder apa pun sendiri. Jika folder workspace belum berisi folder `ai-agent-and-model-router`, panggil tool `scaffold` sekali dengan `example` diatur ke `ai-agent-and-model-router` dan tanpa `dir`: tool itu menulis contoh ke folder baru `ai-agent-and-model-router`. Lalu panggil tool `build` dengan `workspace_root` diatur ke `ai-agent-and-model-router`, `release` diatur ke `release.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana saja yang ditulis build; file-file itu berada di bawah `ai-agent-and-model-router/dist/`.

Pohon hasil render

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

Di bawah router/ terdapat berkas yang dikeluarkan sendiri oleh Recipe milik router. Keduanya berasal dari bundel yang diimpor oleh Recipe, bukan ditulisnya, sehingga masing-masing berada di bawah kunci tempat ia diimpor, yaitu litellm-gateway-config dan request-guard.

Semua yang dibawa oleh sebuah lampiran berada di direktori yang sama dengan manifes milik komponen itu sendiri, dengan dua koordinat dalam nama berkasnya: komponen tempat ia dilampirkan, dan nama yang diberikan kepada lampiran tersebut. router--metrics-- adalah lampiran metrics pada router. Asal setiap berkas tetap dapat dibaca dari pohon, dan setiap berkas berada di tempat yang akan ditemukan oleh alat yang membaca satu direktori — dan itulah yang dilakukan oleh konsumen target ini kecuali Anda menentukan lain.

Kedua koordinat tersebut dienkode, bukan ditulis seperti yang Anda ketik, karena keduanya berbagi satu string dengan nama berkas itu sendiri. Karakter yang tidak dapat dimuat dengan aman oleh nama berkas menjadi -z dan sebuah huruf: api_key menjadi api-zukey; router_model.credential — nama yang diambil oleh lampiran pada koneksi router_model milik agen, yaitu alias koneksi, sebuah titik, dan slotnya — menjadi router-zumodel-zdcredential; dan feature.aggrega.ai/monitoring — nama lampiran yang dicetak oleh anotasi milik sebuah Feature — akan menjadi feature-zdaggrega-zdai-zsmonitoring. Nama berkas itu sendiri mempertahankan titik apa pun yang dimilikinya, sehingga akhiran .yaml tetap terbaca sebagai akhiran.

Di mana sebuah halaman di sini menampilkan apa yang dihasilkan oleh sebuah build, bloknya disalin dari eksekusi nyata — lihat Membaca keluaran di halaman-halaman ini untuk konvensi tersebut dan tanda yang digunakannya untuk baris yang dihilangkan.

Tabel perutean

Alasan keberadaan router adalah petanya, dan peta itu sampai ke keluaran yang dirender alih-alih tetap berada di berkas yang ditulis. Berikut seluruh blok data dari dist/helm/router/litellm-gateway-config/configmap.yaml:

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

dan blok data dari ConfigMap kedua, dist/helm/router/request-guard/request-guard.yaml, dengan teks berkas-berkas yang dibawanya dihilangkan:

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]

Ada lima hal yang layak dibaca dari keduanya.

Kedua entri menerbitkan alias yang sama. Itulah yang memberi router pilihan yang harus dibuat pada setiap permintaan, dan router_settings di akhir isi menyatakan bagaimana pilihan itu dibuat: latency-based-routing, yang ditulis di sana oleh attachment selection milik router alih-alih oleh Recipe-nya sendiri, sebagaimana ditunjukkan bagian tentang attachment tersebut di bawah. Peta yang semua aliasnya berbeda merutekan berdasarkan nama saja, dan strategi tidak mengubah apa pun padanya. Berbagi satu alias juga merupakan alasan keduanya diketik secara manual ke dalam values.models alih-alih dilayani dari komponen model yang dihubungkan ke socket models milik router: model yang dihubungkan dilayani di bawah alias koneksinya sendiri, yang tidak boleh diterbitkan oleh entri lain, sehingga dua model yang dihubungkan tidak pernah berbagi satu alias. Alasan kedua berkaitan dengan Anthropic: router menulis entri model yang dihubungkan hanya melalui API OpenAI, sedangkan model Anthropic menjawab API-nya sendiri, sehingga menghubungkan core/ai-model/anthropic menghentikan build, dengan pesan agar upstream tersebut diketik ke dalam peta sebagai gantinya.

Target adalah string yang tidak ditafsirkan oleh kompiler. openai/gpt-4o adalah penunjuk deterministik: proxy yang berjalan menyelesaikannya ketika melayani permintaan. Kompiler tidak pernah menghubungi provider saat build, sehingga kompiler tidak dapat memberi tahu Anda bahwa suatu target ada, bahwa ejaannya benar, atau bahwa akun Anda dapat menjangkaunya. Ubah openai/gpt-4o menjadi openai/not-a-real-model dan build tetap berhasil — kegagalan baru muncul saat permintaan, dari provider.

Tidak ada nilai kredensial dalam berkas ini. Setiap entri justru menyebut sebuah variabel lingkungan, melalui indireksi milik proxy itu sendiri. Nilainya tiba di kontainer melalui jalur yang sama sekali lain, yang ditunjukkan di bawah.

Setiap permintaan terlebih dahulu bertemu penjaga. Entri callbacks pertama mendaftarkan modul request_field_filter melalui path lengkap berkasnya: ConfigMap kedua dipasang di kontainer router pada /etc/litellm-request-guard, sebuah direktori tersendiri di samping /etc/litellm, tempat ConfigMap pertama dipasang dan proxy membaca konfigurasinya. ConfigMap kedua itu berasal dari LiteLLMGuard#/artifacts/RequestGuard, sebuah bundel yang diimpor oleh setiap Recipe yang menjalankan proxy ini, sehingga penjaga dan allowlist di bawah memiliki satu teks di mana pun proxy berjalan. Recipe milik router menyertakan penjaga ini pada setiap Release, karena router memegang kredensial provider. Penjaga hanya meneruskan dari pemanggil kolom permintaan yang dideklarasikan proxy untuk rute yang diambil permintaan, ditambah kolom yang disebut Release dalam infra.admitted_request_fields milik router, dan menjawab kolom lain apa pun dengan galat yang menyebut kolom tersebut, tanpa meneruskan apa pun — sehingga pemanggil tidak dapat mengarahkan router ke alamat miliknya sendiri melalui daftar model di isi permintaan, atau mengirim kunci provider miliknya sendiri sebagai pengganti kunci router. Pemanggil juga tidak dapat menetapkan identitas yang ditulis router sendiri ke setiap permintaan — hash dari kunci yang diverifikasinya, tim dan organisasi kunci itu, serta pengguna akhir: pada permintaan responses atau messages, tempat router memisahkan metadata milik pemanggil dari miliknya sendiri, router menghapus kolom tim, organisasi, atau pengguna akhir apa pun yang ditulis pemanggil di sana dan penjaga menolak permintaan yang menyebut kunci di sana, metadata.user_api_key, dan pada setiap rute lain nilai router menggantikan nilai apa pun yang dikirim pemanggil. Release ini tidak mengizinkan kolom tambahan apa pun. Entri kedua, prometheus, adalah callback metrik milik proxy sendiri, yang diaktifkan oleh nilai metrics_enabled milik router; attachment metrics di bawah mengambil (scrape) apa yang direkamnya.

Hanya rute milik router sendiri yang dapat dijangkau. Penjaga hanya melihat rute yang menyerahkan permintaan kepadanya, sehingga berkas lain dalam ConfigMap kedua mengonfigurasi kontainer kedua pod, yang hanya memasang ConfigMap itu dan menjalankan image nginx resmi sebagai allowlist path. Router sendiri mendengarkan di alamat loopback pod, tempat tidak ada apa pun di luar pod yang dapat menjangkaunya, dan allowlist mendengarkan di port 4000, port yang ditargetkan Service di bawah. Allowlist meneruskan permintaan hanya jika metode dan path-nya merupakan salah satu rute yang dilayani router — rute permintaan model yang diperiksa penjaga, dalam ejaan yang dilayani router apa pun aliasnya, termasuk /v1/chat/completions dan /v1/messages; daftar model; pemeriksaan kesehatan; dan, dari rute administratifnya, manajemen kunci — dan menjawab setiap path lain dengan 403, tanpa meneruskan apa pun. Jadi rute penghitungan token milik proxy, rute pass-through-nya ke API milik provider, rute administratif lainnya, dan konsol administratifnya tidak dapat dijangkau melalui router, begitu pula rute model yang path-nya memuat nama model, seperti path yang dikirim klien Azure: di sana proxy membaca kata-kata dalam path, termasuk alias, untuk menentukan cara ia merekam permintaan, dan router akan menolak permintaan untuk assistant milik peta ini pada rute tersebut. Metrik proxy juga tidak termasuk dalam rute-rute itu: port 4000 menjawab /metrics dengan 403. Dengan metrics_enabled milik router bernilai true, seperti yang ditetapkan Aggregate, allowlist juga mendengarkan di port 9090 dan hanya meneruskan GET ke /metrics di sana, ke listener yang disediakan proxy untuk metriknya di alamat loopback, serta menjawab setiap permintaan lain dengan 403. Port itu tidak memeriksa pemanggil, dan metrik tersebut menyebut kunci yang di-hash, alias kunci, dan email pengguna yang menjadi atribusi pengeluaran oleh router.

Apa yang dipublikasikan router

Recipe milik router memublikasikan dua kunci yang dipublikasikan setiap komponen model: sebuah endpoint, URL dasar yang diberikan kepada pustaka klien, dan sebuah model, nama yang diminta oleh sebuah permintaan. Itulah yang memungkinkan soket model milik agen menerima router sebagai pengganti model. Selektor soket tersebut adalah component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: selektor ini menerima komponen dalam kategori model atau gateway yang membawa model.aggrega.ai/api, label yang menyebutkan API model mana yang menjawab di alamat yang dipublikasikan komponen tersebut. Router membawa model.aggrega.ai/api: openai. Sebuah gateway yang tidak melayani API model tidak membawa label tersebut, dan edge dari agen ke gateway semacam itu menghentikan build, dengan menyebutkan soket dan selektor yang tidak dipenuhi oleh target.

Alamatnya adalah Service yang dikeluarkan oleh Recipe milik router sendiri — seluruh spec dari dist/helm/router-default-service.yaml:

spec:
type: ClusterIP
selector:
app: router
ports:
- name: http
port: 4000
targetPort: http
- name: metrics
port: 9090
targetPort: metrics

Recipe menyusun endpoint yang dipublikasikannya, http://router-default:4000/v1, dari dua fakta yang sama yang menjadi dasar nama dan port Service: nama komponen itu sendiri dan infra.port-nya. Port yang dituju Service, http, adalah port tempat allowlist jalur router mendengarkan; metrics, port kedua, ada karena metrik router diaktifkan, dan hanya membawa metrik tersebut. Tidak ada satu pun dari ketiga file yang menuliskan router-default secara eksplisit. Ganti nama komponen router — kuncinya di Aggregate dan di Release, serta edge agen yang menyebutkannya — dan alamat yang diterima agen akan mengikutinya: jika dinamai ulang menjadi gateway, OPENAI_BASE_URL milik agen adalah http://gateway-default:4000/v1.

Namanya adalah alias yang dipublikasikan router sebagai modelnya. Peta ini memublikasikan satu alias, assistant, dari kedua entrinya, sehingga router memublikasikan alias tersebut dan values.model-nya dihilangkan. Berikan entri kedua alias tersendiri — misalnya summarizer — maka build berhenti sebelum apa pun dirender, karena router hanya dapat memublikasikan satu alias. Penghentian ini adalah E0033, sebuah asersi yang gagal pada Component router, dan pesannya diakhiri dengan kalimat aturan itu sendiri: 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 tidak disetel, tetapi values.models memublikasikan 2 alias (assistant, summarizer), sehingga gateway tidak dapat mengetahui alias mana yang diminta oleh komponen yang terhubung kepadanya; setel values.model ke salah satunya). Menyetel model: assistant di samping models akan mengatasinya, dan agen kembali diberi assistant. Pemanggil yang menginginkan summarizer memintanya dari endpoint yang sama berdasarkan nama.

Apa yang diterima agen

Recipe milik agen membaca kedua edge-nya serta nilai milik agen itu sendiri, lalu mengubahnya menjadi lingkungan kontainer. Berikut seluruh blok env dari dist/helm/agent-deployment.yaml:

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

Entri pertama berasal dari lampiran yang dibawa edge model, dan provider helm menulis entri semacam itu, yang dibaca dari sebuah Secret, sebelum entri-entri biasa. Batas rekursi adalah recursion_limit milik agen sendiri, di bawah variabel yang dibaca LangGraph dengan sendirinya; dua entri berikutnya berasal dari edge model, dua entri setelahnya dari edge checkpointer_db, dan entri terakhir adalah graph_entrypoint milik agen sendiri, di bawah nama default yang dibaca oleh kode aplikasi, yang akan digantikan oleh blok inject pada komponen itu sendiri. Perhatikan apa yang tidak perlu dinyatakan oleh Aggregate: tidak ada edge yang membawa blok inject, karena Recipe konsumen mengirimkan setiap koneksi dengan nama default, yang akan digantikan oleh blok inject pada edge. Pengembang menyatakan bahwa agen menggunakan sebuah model; variabel tempat endpoint-nya tiba adalah variabel yang dibaca oleh pustaka klien, dan variabel itu tetap seperti yang ditentukan edge.

Perhatikan juga LANGGRAPH_CHECKPOINTER_PORT: "6379". Release mendeklarasikan checkpointer: {} dan tidak mengonfigurasi apa pun, sehingga port tersebut adalah nilai bawaan skema milik Component cache itu sendiri, yang diwujudkan dan dialirkan melintasi edge.

Agen berkomunikasi dengan router persis dalam dialek yang akan digunakannya untuk berkomunikasi langsung dengan sebuah provider — sebuah URL dasar, sebuah nama model, dan sebuah kunci. Itulah yang memungkinkan router disisipkan, dipindahkan, atau diarahkan ulang tanpa mengubah aplikasi.

Enam lampiran, dan apa yang dirender masing-masing

Lampiran yang tidak mengubah apa pun dalam keluaran tidak mengajarkan apa pun. Masing-masing dari keenam lampiran ini menaruh sesuatu di sana.

api_key pada router — kunci yang diwajibkannya dari pemanggil

core/referenced-secret, mengisi slot yang dideklarasikan oleh Component router; kunci yang dipegangnya adalah yang disebut LiteLLM sebagai master key-nya. Lampiran ini merender Secret-nya sendiri, dan kontainer router mereferensikannya. Dari dist/helm/router--api-zukey--router-secret-router-api-key.yaml:

stringData:
master-key: "dev-router-admin-key-change-me"

dan dalam env kontainer router, dari dist/helm/router-deployment.yaml:

- name: LITELLM_MASTER_KEY
valueFrom:
secretKeyRef:
name: router-api-key
key: master-key

Kontainer membawa referensi, bukan nilainya. Nama Secret dipublikasikan oleh lampiran dan dibaca oleh konsumen, sehingga tidak ada pihak yang menurunkannya ulang.

provider_key pada router — kunci yang disajikannya ke hulu

Feature yang sama di slot yang berbeda, dan perbedaan antara kedua slot itulah inti dari router. Ini adalah satu-satunya kredensial bagi entri yang ditulis ke dalam values.models, keduanya di sini; model yang dihubungkan ke soket models router menyajikan kunci yang dibawa koneksinya sendiri, bukan kunci ini. Dari dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml:

stringData:
provider-key: "upstream-provider-key-change-me"

dan dalam env kontainer yang sama:

- name: LITELLM_PROVIDER_API_KEY
valueFrom:
secretKeyRef:
name: router-provider-key
key: provider-key

Lampiran ini juga mengubah tabel perutean. Lihat kembali blok data tabel perutean di atas: setiap entri peta membawa api_key: os.environ/LITELLM_PROVIDER_API_KEY, yang menamai variabel yang sama ini. Hapus lampiran provider_key dari Aggregate lalu bangun ulang. Build melaporkan sebelas file, bukan dua belas — Secret-nya hilang — dan ConfigMap tabel perutean berbeda tepat pada dua baris api_key itu dan tidak ada yang lain; ConfigMap guard tidak berubah. Bagian peta lainnya mempertahankan urutan dan format yang ditulis, router tetap melayani dan merutekan, dan permintaan yang dirutekan kini gagal di penyedia karena tidak ada kredensial untuk disajikan.

Nama variabel ditulis sekali dalam Recipe router dan dibaca dari sana oleh tabel perutean maupun lingkungan kontainer, sehingga sebuah tabel tidak mungkin menamai variabel yang tidak diatur oleh apa pun.

Kedua kredensial tetap terpisah, dan pemisahan itulah yang diberikan router: kunci hulu tetap berada di dalam router, dan aplikasi pemanggil tidak memegang apa pun selain kunci ke router.

credential pada koneksi model agen — kunci yang disajikannya ke router

core/referenced-secret lagi, di sisi lain dari percakapan yang sama. Soket model agen mendeklarasikan slot credential, sehingga kunci dilampirkan pada koneksi tempat kunci itu disajikan, di bawah edge dalam Aggregate:

uses:
model:
router_model:
target: router
features:
credential:
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.router_admin_key }}"

Dari dist/helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml:

stringData:
api-key: "dev-router-admin-key-change-me"

Itu adalah nilai yang sama dengan master-key router di atas, dan nilai itu tidak ditulis dua kali. Kedua lampiran membaca satu parameter yang diangkat:

origin: "{{ .parameters.router_admin_key }}"

Aggregate mendeklarasikan parameter dan Release memenuhinya, sehingga kunci memiliki satu tempat penulisan dan kedua Secret tidak dapat diedit secara terpisah. Ubah sekali di Release dan kedua Secret yang dirender berubah bersama.

Setiap lampiran tetap merender Secret miliknya sendiri, yang dinamai dari komponen yang mengonsumsinya — dan, untuk milik agen, dari koneksi tempat lampiran itu dipasang: agent-router-model.credential. Yang dibagikan oleh parameter bersama adalah nilainya, bukan sumber dayanya.

published pada router — alamat di luar klaster

core/public-ingress, yang tidak mengisi slot apa pun: lampiran ini diterima oleh selektornya sendiri, component.aggrega.ai/type=server, yang dibawa oleh router. Lampiran ini membawa sumber daya yang sama sekali tidak diketahui oleh Recipe router. Seluruh spec dari dist/helm/router--published--router-ingress-router-ingress.yaml:

spec:
rules:
- host: assistant.example.internal
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: router-default
port:
name: http

Pengembang melampirkannya dalam Aggregate dengan path, karena permintaan mana yang dilayani aplikasi adalah bagian dari hakikat aplikasi itu. Operator menulis host dan nama port pada entri Release untuk lampiran yang sama: host adalah nama lingkungan untuk router, sehingga operator menamainya per lingkungan, dalam Release setiap lingkungan. Service backend tidak disediakan oleh keduanya: service_name dibiarkan tidak diatur, dan realisasi lampiran kembali ke Service yang dihasilkan oleh Recipe router sendiri. Tidak ada bidang ingressClassName dalam keluaran, karena tidak ada yang mengaturnya dan realisasi menghilangkan apa yang tidak diberikan kepadanya, sehingga kelas default klaster yang mengklaim sumber daya tersebut.

metrics pada router — target scrape

core/prometheus-exporter, diterima oleh selektor yang sama, membawa sumber daya lain miliknya sendiri. Setiap input yang diterimanya adalah pengaturan ukuran oleh operator, bukan maksud aplikasi — seberapa sering platform melakukan scrape, serta port dan path mana yang dibacanya, adalah properti platform — sehingga operator melampirkannya, dalam Release, pada entri router, dengan jenisnya di samping infra-nya. Aggregate tidak menyebutkannya:

components:
router:
features:
metrics:
type: core/prometheus-exporter
infra:
interval: 30s
port: metrics
path: /metrics

Seluruh spec dari dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml:

spec:
selector:
matchLabels:
app.kubernetes.io/name: router
endpoints:
- port: metrics
interval: 30s
path: /metrics

port menamai port Service, bukan angka: metrics, yang dihasilkan oleh Recipe router karena Aggregate mengatur nilai metrics_enabled router, dan yang melayani metriknya. Itu juga nama port default Feature, yang ditulis di sini bersama dua pengaturan lainnya. Port http yang dirutekan oleh Ingress di atas menjawab /metrics dengan 403, sehingga scrape yang diarahkan ke sana tidak akan mengumpulkan apa pun. Apakah metrik dilayani sama sekali adalah pilihan pengembang, yang dibuat di Aggregate; seberapa sering dan pada port serta path mana platform melakukan scrape adalah pilihan operator, yang dibuat di sini.

selection pada router — cara router memilih di antara targetnya

core/target-selection, yang dilampirkan ke gateway yang membawa gateway.aggrega.ai/intelligence: semantic, seperti router ini. Cara router memilih adalah bagian dari apa yang diminta aplikasi darinya, sehingga pengembang melampirkannya dalam Aggregate, dengan strategy-nya sebagai nilai:

components:
router:
features:
selection:
type: core/target-selection
values:
strategy: latency

dan Manifest mengikatnya ke realisasi untuk router ini:

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

Lampiran ini tidak merender file sendiri. Realisasinya menulis satu pengaturan ke dalam tabel perutean yang dirender oleh Recipe router — dua baris terakhir blok data di atas:

router_settings:
routing_strategy: latency-based-routing

Dengan pengaturan ini, proxy mengirim setiap permintaan untuk assistant ke entri yang sepuluh balasan terakhirnya rata-rata memakan waktu paling sedikit, per token keluaran jika balasan melaporkan tokennya, dan entri yang belum dicoba dianggap tercepat, sehingga masing-masing dicoba sebelum rata-rata menentukan. Hapus lampiran dari Aggregate dan bangun ulang: build tetap melaporkan dua belas file, dan ConfigMap tabel perutean berbeda tepat pada dua baris itu. Recipe router tidak menulis strategi sendiri, dan tanpa strategi, proxy memilih di antara kedua entri secara acak.

Mintalah strategy: cost sebagai gantinya dan build berhenti, tanpa menulis apa pun. Penghentian itu adalah E0033, asersi realisasi yang gagal, dan pesannya diakhiri dengan kalimat aturan itu sendiri: 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 (lampiran core/target-selection “selection” pada “router” meminta strategi cost, tetapi core/gateway/litellm tidak dapat memilih di antara entri peta modelnya berdasarkan biaya: proxy mencari target setiap entri, persis seperti yang ditulis, dalam tabel harganya sendiri, yang menamai model OpenAI dan Anthropic tanpa prefiks penyedia yang dibawa target (gpt-4o, bukan openai/gpt-4o) dan yang dapat diambil ulang oleh proxy saat dimulai, dan proxy memberi harga entri yang tidak ditemukannya, dan yang tidak membawa harga sendiri, dengan nilai cadangan tetap, sehingga entri yang berbagi alias diberi harga sama dan pilihan jatuh pada urutannya. Mintalah strategi latency, atau hapus lampiran). Kedua target di sini ditulis dengan cara itu, sehingga proxy akan mengirim setiap permintaan ke yang pertama di antaranya, sementara Aggregate meminta biaya.

Bagian yang tidak ditafsirkan oleh kompiler

Alamat dan nama model milik agen dibaca dari apa yang dipublikasikan router, sehingga tidak ada pasangan nama di ketiga berkas yang harus diselaraskan secara manual. Yang memang diperiksa oleh build adalah aturan router itu sendiri bahwa alias yang dipublikasikannya adalah alias yang dipublikasikan oleh map-nya — sebuah aturan yang dideklarasikan oleh Component-nya dan dievaluasi oleh build, seperti asersi lain yang dibawa oleh sebuah entitas.

Selebihnya adalah string yang dialirkan dari satu tempat ke tempat lain. Kompiler meneruskan alamat dan alias tanpa membacanya: kompiler tidak tahu bahwa yang satu adalah nama host dan yang lain nama model, dan kompiler tidak memiliki akses ke klaster yang sedang berjalan untuk memeriksa bahwa ada sesuatu yang menjawab di router-default:4000. Label model.aggrega.ai/api yang menerima router adalah string sejenis — selektor soket mencocokkannya, dan tidak ada yang memeriksa API apa yang sebenarnya menjawab di sana. Dan setiap target di dalam map adalah penunjuk yang di-resolve oleh proxy yang sedang berjalan: ubah openai/gpt-4o menjadi openai/not-a-real-model dan build tetap berhasil, dengan kegagalan baru muncul saat permintaan dikirim.

Inilah sifat yang sama yang membuat bagian lain dari contoh ini berfungsi. Karena kompiler tidak menafsirkan apa yang dialirkannya, router dapat diarahkan ulang ke provider lain, agen dapat dihubungkan ke router lain, dan realisasi kredensial dapat diganti dengan realisasi yang didukung penyimpanan — semuanya tanpa kompiler perlu memahami satu pun darinya, dan tanpa agen berubah.

Menyesuaikannya

  • Arahkan ulang sebuah provider. Ubah sebuah target di peta router. Tidak ada hal lain yang berubah: bukan model, bukan agen, bukan Secret yang dirender.

  • Tambahkan provider ketiga. Tambahkan sebuah entri peta. Jika entri itu menerbitkan alias yang sudah ada, strategi mulai memilih di antara tiga. Jika entri itu menerbitkan alias baru, peta menerbitkan dua alias, dan values.model milik router menyebut alias yang diberikan kepada agen; pemanggil yang menginginkan alias lainnya memintanya berdasarkan nama. Model yang dimodelkan katalog dengan API berupa API OpenAI dapat sebagai gantinya dihubungkan ke soket models milik router, dengan alias tersendiri dan menyajikan kunci yang dibawa koneksinya; values.model kemudian menyebut alias yang diberikan kepada agen.

  • Ambil kredensial dari sebuah store sebagai gantinya. Ubah satu baris Manifest yang mengikat core/referenced-secret menjadi helm/k8s-external-secret lalu build ulang. Setiap Secret yang dirender menjadi ExternalSecret yang menyebut sebuah entri di secret store klaster, untuk direkonsiliasi oleh operator store — dan referensi yang dirender milik setiap konsumen tetap identik byte demi byte, karena locator diterbitkan oleh sisi produsen, bukan disepakati di antara keduanya. Tidak ada hal lain di ketiga berkas yang perlu diubah agar build berhasil.

    Namun, ada satu hal yang perlu ditulis ulang sebelum penukaran itu bermakna: origin berubah makna di antara kedua realisasi. Realisasi workspace ini membacanya sebagai nilai yang disimpan; realisasi lainnya membacanya sebagai kunci yang diambil. Jika baris itu ditukar tanpa meninjau ulang nilai origin, remoteRef.key yang dirender adalah placeholder apa pun yang menggantikan nilai tersebut — dev-router-admin-key-change-me di sini. Tidak ada apa pun di pohon keluaran yang kemudian menyimpan string itu sebagai materi, tetapi string itu masih ada sebagai kunci store yang menyebut entri yang tidak ada.

  • Hilangkan router. Arahkan edge model milik agen ke komponen model per provider sebagai gantinya. Agen kemudian memegang sendiri kredensial provider, yang merupakan kompromi yang ingin dihilangkan oleh keberadaan router.

  • Jangkau router yang tidak dimodelkan katalog. Arahkan edge model milik agen ke komponen core/ai-model/openai-compatible dan tuliskan alamat router tersebut ke dalam infra.endpoint miliknya di Release. Tidak ada yang berjalan di balik komponen itu di dalam klaster, sehingga alamat tersebut menjadi tanggung jawab operator untuk ditulis dan diselaraskan dengan layanan yang disebutnya.

Untuk berbagi satu kredensial di antara koneksi beberapa konsumen, lihat model-api-key-sharing. Untuk soket yang tidak dideklarasikan entitas katalog mana pun, lihat adhoc-uses-socket.