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.internalRouter 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:
| instans | Component katalog | perannya di sini |
|---|---|---|
router | core/gateway/litellm | komponen perutean: satu endpoint, satu peta alias, dua penyedia upstream. Komponen ini memublikasikan alamatnya dan alias yang diminta oleh agen |
agent | core/ai-agent/langgraph | aplikasi, yang menjalankan image graph miliknya sendiri |
checkpointer | core/datastore/valkey | tempat 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:
aggrega scaffold --example ai-agent-and-model-routerKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd ai-agent-and-model-routerBuild
aggrega build --release release.yaml --auto-pullSebuah 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:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildWorkspace 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:
aggrega pull --release release.yamlJalankan 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>/distEntitas 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:
aggrega lint --release release.yamlyang 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.yamlDi 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-routingdan 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: metricsRecipe 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:graphEntri 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-keyKontainer 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-keyLampiran 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: httpPengembang 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: /metricsSeluruh 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: /metricsport 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: latencydan Manifest mengikatnya ke realisasi untuk router ini:
core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0Lampiran 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-routingDengan 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
targetdi 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.modelmilik 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 soketmodelsmilik router, dengan alias tersendiri dan menyajikan kunci yang dibawa koneksinya;values.modelkemudian menyebut alias yang diberikan kepada agen. -
Ambil kredensial dari sebuah store sebagai gantinya. Ubah satu baris Manifest yang mengikat
core/referenced-secretmenjadihelm/k8s-external-secretlalu build ulang. SetiapSecretyang dirender menjadiExternalSecretyang 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:
originberubah 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 nilaiorigin,remoteRef.keyyang dirender adalah placeholder apa pun yang menggantikan nilai tersebut —dev-router-admin-key-change-medi 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
modelmilik 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
modelmilik agen ke komponencore/ai-model/openai-compatibledan tuliskan alamat router tersebut ke dalaminfra.endpointmiliknya 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.