Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Một agent, một router và hai mô hình thượng nguồn

Một ứng dụng agent truy cập hai mô hình của nhà cung cấp thượng nguồn thông qua một router trong cụm, được biên dịch thành các manifest Kubernetes.

Agent yêu cầu một mô hình bằng một tên duy nhất. Đằng sau tên đó là một router giữ một bảng ánh xạ các bí danh, và đằng sau bảng ánh xạ là hai nhà cung cấp. Agent không bao giờ biết nhà cung cấp nào đã trả lời, không bao giờ giữ thông tin xác thực của nhà cung cấp, và không thay đổi khi bảng ánh xạ được trỏ lại — đó chính là lý do để đặt một router ở đó.

Workspace này không tự định nghĩa thực thể catalog nào. Mọi Component, Feature và Recipe mà nó nêu tên đều có sẵn trong catalog thư viện chuẩn; ba tệp thực thể ở đây — một Aggregate, một Manifest và một Release — là toàn bộ những gì cần viết.

Những gì ví dụ này xây dựng

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

Router có hai lối vào cho các yêu cầu — agent đến được nó qua cạnh model của mình, còn mọi thứ bên ngoài đến được nó qua Ingress — và một lối ra cho mỗi mục trong bảng ánh xạ. Một cổng thứ ba cung cấp metrics của nó cho một trình thu thập bên trong cluster.

Ba component, và mỗi cái đảm nhận một việc khác nhau:

instanceComponent trong catalogvai trò ở đây
routercore/gateway/litellmcomponent định tuyến: một endpoint, một bảng ánh xạ bí danh, hai provider phía thượng nguồn. Nó công bố địa chỉ của mình và bí danh mà agent yêu cầu
agentcore/ai-agent/langgraphứng dụng, chạy image đồ thị riêng của nó
checkpointercore/datastore/valkeynơi agent lưu trạng thái lần chạy, được chọn theo danh mục datastore

Hai cạnh uses, cả hai đều đi vào các socket mà Component của agent khai báo: model (bắt buộc, chấp nhận một component mô hình hoặc một gateway phục vụ API mô hình — router là loại thứ hai) và checkpointer_db (bắt buộc, chọn theo danh mục datastore). Sáu lần gắn Feature thuộc bốn loại Feature — năm trên router, một trên kết nối model của agent — mỗi lần gắn đều đưa một thứ gì đó vào đầu ra được render; phần bên dưới cho thấy mỗi lần gắn tạo ra gì.

Tạo ví dụ

Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.

Ghi ví dụ vào một thư mục mới đặt theo tên của nó:

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

Sau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:

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

Build

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

Một release cần một lockfile trước khi được xây dựng, và lockfile được sinh ra chứ không được phân phối kèm, nên một bản clone mới không có lockfile nào. aggrega build mặc định chỉ đọc: khi không có lockfile, nó dừng lại và nêu ra hai cách để tiếp tục. Hãy phân giải một lockfile trước, hoặc để bản build tự điền nó:

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 này phân giải các entity của nó từ registry mặc định mà .aggrega-config.yaml chỉ định, nên không cần cờ --catalog.

Việc hiện thực hóa attachment selection của router chạy một plugin không được phân phối kèm trong cả compiler lẫn catalog, đó là bước cấu hình gateway pipeline-step/litellm-gateway-config, mà quá trình phân giải tải về từ registry do default_registry chỉ định, hub.aggrega.ai.

Một số phần bên dưới yêu cầu bạn thay đổi một dòng và build lại. Lockfile ghim một digest cho mọi entity mà release đã phân giải, bao gồm cả Aggregate và Manifest trong thư mục này, và ghi lại chính Release theo digest của nội dung của nó — vì vậy việc chỉnh sửa bất kỳ tệp nào trong ba tệp này khiến lockfile lỗi thời, và lần build tiếp theo sẽ dừng lại thay vì kết xuất dựa trên một bản ghim cũ. Thông báo nêu điều gì đã thay đổi — Release theo tệp của nó, Aggregate hoặc Manifest theo tên — và in digest mà nó đã ghi lại bên cạnh digest mà nó tìm thấy. Một lệnh pull ghi lại thay đổi trong khi vẫn tôn trọng mọi bản ghim khác:

Terminal window
aggrega pull --release release.yaml

Hãy chạy lệnh đó rồi build lại, hoặc build với --auto-pull, cờ này chạy cùng lệnh pull đó trước. Dù theo cách nào, việc dừng lại chính là mục đích chứ không phải trở ngại: một bản build không kết xuất dựa trên một bản ghim mà nó có thể thấy là đã cũ.

Bản build in ra như sau, với <workspace> đại diện cho thư mục của ví dụ này:

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

Các entity được kiểm tra theo các quy ước của catalog một lần khi lockfile được phân giải và một lần khi release được build, và mỗi khuyến nghị mà các lượt kiểm tra đó đưa ra được in thành một dòng lint:; release này không có khuyến nghị nào. Để chạy riêng các lượt kiểm tra đó, và đọc đầy đủ bất kỳ khuyến nghị nào cùng với tệp entity mà nó xuất phát và điều gì sẽ khiến nó phù hợp:

Terminal window
aggrega lint --release release.yaml

lệnh này ở đây báo cáo conventions checked: 19 entities, 0 advisory finding(s).

Với trợ lý AI

Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.

Chỉ dùng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục workspace chưa có thư mục `ai-agent-and-model-router`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `ai-agent-and-model-router` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `ai-agent-and-model-router` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `ai-agent-and-model-router`, `release` đặt thành `release.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Hãy cho tôi biết bản build đã ghi những tệp nào; chúng nằm trong `ai-agent-and-model-router/dist/`.

Cây thư mục được kết xuất

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

Trong router/ là các tệp mà Recipe của router tự phát ra. Cả hai đều đến từ các gói mà Recipe nhập vào chứ không tự viết, nên mỗi tệp nằm dưới khóa mà nó được nhập vào, litellm-gateway-config và request-guard.

Mọi thứ mà một attachment mang đến đều nằm cùng thư mục với các manifest riêng của component, mang hai tọa độ trong tên tệp: component mà nó được gắn vào, và tên được đặt cho attachment. router--metrics-- là attachment metrics trên router. Nguồn gốc của từng thứ vẫn đọc được từ cây thư mục, và mọi tệp đều nằm ở nơi một công cụ đọc một thư mục sẽ tìm thấy nó — đó chính là điều các bên tiêu thụ của target này làm, trừ khi bạn chỉ định khác.

Hai tọa độ được mã hóa chứ không được ghi đúng như bạn đã gõ, vì chúng dùng chung một chuỗi với tên riêng của tệp. Một ký tự mà tên tệp không thể mang một cách an toàn sẽ trở thành -z và một chữ cái: api_key thành api-zukey; router_model.credential — tên mà attachment trên kết nối router_model của agent nhận, gồm bí danh của kết nối, một dấu chấm và slot — thành router-zumodel-zdcredential; và feature.aggrega.ai/monitoring — một tên attachment do annotation riêng của một Feature tạo ra — sẽ thành feature-zdaggrega-zdai-zsmonitoring. Tên riêng của tệp giữ nguyên mọi dấu chấm nó có, nên hậu tố .yaml vẫn được đọc như một hậu tố.

Ở những chỗ một trang tại đây in ra kết quả một lần build tạo ra, khối đó được sao chép từ một lần chạy thật — xem Đọc kết quả đầu ra trên các trang này để biết quy ước và ký hiệu dùng cho các dòng bị lược bỏ.

Bảng định tuyến

Lý do tồn tại của router là bản đồ của nó, và bản đồ này đi tới đầu ra đã render chứ không nằm lại trong tệp được viết. Đây là toàn bộ khối data của 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

và khối data của ConfigMap thứ hai, dist/helm/router/request-guard/request-guard.yaml, với nội dung của các tệp mà nó mang được lược bỏ:

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]

Có năm điều đáng đọc ra từ những khối đó.

Cả hai mục đều công bố cùng một alias. Chính điều đó cho router một lựa chọn cần đưa ra trên mỗi yêu cầu, và router_settings ở cuối phần thân cho biết nó đưa ra lựa chọn ấy thế nào: latency-based-routing, được ghi ở đó bởi attachment selection của router chứ không phải bởi Recipe của chính nó, như phần về attachment đó bên dưới cho thấy. Một bản đồ mà mọi alias đều khác nhau thì chỉ định tuyến theo tên, và chiến lược không thay đổi gì ở đó. Việc dùng chung một alias cũng là lý do cả hai được gõ tay vào values.models thay vì được phục vụ từ các component mô hình nối vào socket models của router: một mô hình được nối sẽ được phục vụ dưới alias của chính kết nối của nó, alias mà không mục nào khác được công bố, nên hai mô hình được nối không bao giờ dùng chung một alias. Lý do thứ hai thuộc về Anthropic: router ghi mục của một mô hình được nối chỉ qua API của OpenAI, trong khi mô hình của Anthropic trả lời qua API riêng của nó, nên việc nối core/ai-model/anthropic sẽ dừng bản build, kèm thông báo yêu cầu gõ upstream đó vào bản đồ thay vào đó.

Các đích là những chuỗi mà trình biên dịch không diễn giải. openai/gpt-4o là một con trỏ tất định: proxy đang chạy phân giải nó khi phục vụ một yêu cầu. Trình biên dịch không bao giờ liên hệ với nhà cung cấp khi build, nên nó không thể cho bạn biết một đích có tồn tại, có được viết đúng chính tả, hay tài khoản của bạn có truy cập được nó không. Đổi openai/gpt-4o thành openai/not-a-real-model và bản build vẫn thành công — lỗi xuất hiện lúc gửi yêu cầu, từ phía nhà cung cấp.

Không có giá trị thông tin xác thực nào trong tệp này. Thay vào đó, mỗi mục nêu tên một biến môi trường, thông qua cơ chế gián tiếp của chính proxy. Giá trị đi vào container bằng một con đường hoàn toàn khác, được trình bày bên dưới.

Mọi yêu cầu đều gặp một lớp bảo vệ trước. Mục callbacks đầu tiên đăng ký module request_field_filter theo đường dẫn đầy đủ của tệp của nó: ConfigMap thứ hai được mount vào container của router tại /etc/litellm-request-guard, một thư mục riêng bên cạnh /etc/litellm, nơi ConfigMap thứ nhất được mount và proxy đọc cấu hình của nó. ConfigMap thứ hai đó đến từ LiteLLMGuard#/artifacts/RequestGuard, một bundle mà mọi Recipe chạy proxy này đều import, nên lớp bảo vệ và danh sách cho phép bên dưới có cùng một nội dung ở bất cứ đâu proxy chạy. Recipe của router đưa lớp bảo vệ này vào mọi Release, vì router giữ thông tin xác thực của nhà cung cấp. Nó chỉ chuyển tiếp từ bên gọi những trường yêu cầu mà proxy khai báo cho route mà yêu cầu đi qua, cộng với các trường mà Release nêu trong infra.admitted_request_fields của router, và trả lời mọi trường khác bằng một lỗi nêu tên trường đó, không chuyển tiếp gì — nên bên gọi không thể trỏ router tới một địa chỉ của riêng mình qua danh sách mô hình trong thân yêu cầu, hay gửi một khóa nhà cung cấp của riêng mình thay cho khóa của router. Bên gọi cũng không thể đặt danh tính mà router tự ghi vào mọi yêu cầu — mã băm của khóa mà nó đã xác minh, nhóm và tổ chức của khóa đó, và người dùng cuối: trên một yêu cầu responses hoặc messages, nơi router giữ metadata của bên gọi tách biệt với của chính nó, nó loại bỏ mọi trường nhóm, tổ chức hoặc người dùng cuối mà bên gọi ghi vào đó và lớp bảo vệ từ chối yêu cầu nêu khóa ở đó, metadata.user_api_key, còn trên mọi route khác, giá trị của router thay thế bất kỳ giá trị nào bên gọi gửi. Release này không chấp nhận thêm gì. Mục thứ hai, prometheus, là callback số liệu riêng của proxy, được bật bởi giá trị metrics_enabled của router; attachment metrics bên dưới thu thập những gì nó ghi lại.

Chỉ các route riêng của router là truy cập được. Lớp bảo vệ chỉ thấy các route trao yêu cầu cho nó, nên tệp còn lại của ConfigMap thứ hai cấu hình container thứ hai của pod, container chỉ mount ConfigMap đó và chạy image nginx chính thức làm danh sách cho phép theo đường dẫn. Bản thân router lắng nghe trên địa chỉ loopback của pod, nơi không gì bên ngoài pod chạm tới được, và danh sách cho phép lắng nghe trên cổng 4000, cổng mà Service bên dưới nhắm tới. Nó chỉ chuyển tiếp một yêu cầu khi phương thức và đường dẫn của yêu cầu là một trong các route mà router phục vụ — các route yêu cầu mô hình mà lớp bảo vệ kiểm tra, theo các cách viết mà router phục vụ bất kể alias, trong đó có /v1/chat/completions và /v1/messages; route liệt kê mô hình; các route kiểm tra sức khỏe; và, trong số các route quản trị, phần quản lý khóa — và trả lời 403 cho mọi đường dẫn khác, không chuyển tiếp gì. Vì vậy các route đếm token của proxy, các route pass-through tới API riêng của các nhà cung cấp, các route quản trị khác và console quản trị của nó không thể truy cập qua router, và một route mô hình có đường dẫn chứa tên mô hình cũng vậy, như các đường dẫn mà client của Azure gửi: ở đó proxy đọc các từ trong đường dẫn, kể cả alias, để quyết định cách nó ghi nhận một yêu cầu, và router sẽ từ chối một yêu cầu cho chính assistant của bản đồ này trên route đó. Số liệu của proxy cũng không nằm trong các route đó: cổng 4000 trả lời 403 cho /metrics. Khi metrics_enabled của router là true, như Aggregate đặt, danh sách cho phép còn lắng nghe trên cổng 9090 và chỉ chuyển tiếp yêu cầu GET tới /metrics ở đó, tới listener mà proxy giữ cho số liệu của nó trên địa chỉ loopback, và trả lời 403 cho mọi yêu cầu khác. Cổng đó không kiểm tra bên gọi nào, và các số liệu nêu tên các khóa đã băm, alias khóa và email người dùng mà router quy chi phí cho.

Những gì router công bố

Recipe của router công bố hai khóa mà mọi component mô hình đều công bố: một endpoint, URL gốc được trao cho thư viện client, và một model, tên mà một yêu cầu đòi hỏi. Chính điều đó cho phép socket model của agent nhận router thay cho một mô hình. Bộ chọn của socket là component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: nó chấp nhận một component thuộc nhóm mô hình hoặc nhóm gateway có mang model.aggrega.ai/api, nhãn cho biết API mô hình nào trả lời tại địa chỉ mà component công bố. Router mang model.aggrega.ai/api: openai. Một gateway không phục vụ API mô hình nào thì không mang nhãn đó, và một cạnh từ agent tới gateway như vậy sẽ dừng bản build, nêu tên socket và bộ chọn mà đích không thỏa mãn.

Địa chỉ là Service do chính Recipe của router phát ra — toàn bộ spec của 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 tạo endpoint mà nó công bố, http://router-default:4000/v1, từ cùng hai dữ kiện dùng để đặt tên và cổng cho Service: tên riêng của component và infra.port của nó. Cổng mà Service nhắm tới, http, là cổng mà danh sách cho phép đường dẫn của router lắng nghe; metrics, cổng thứ hai, có mặt vì metrics của router được bật, và chỉ mang metrics. Không chỗ nào trong ba tệp viết ra router-default. Đổi tên component router — khóa của nó trong Aggregate và trong Release, cùng cạnh của agent nêu tên nó — thì địa chỉ mà agent nhận được sẽ thay đổi theo: khi đổi tên thành gateway, OPENAI_BASE_URL của agent là http://gateway-default:4000/v1.

Tên là alias mà router công bố làm mô hình của nó. Bảng ánh xạ này công bố một alias, assistant, từ cả hai mục, nên router công bố alias đó và values.model của nó được bỏ trống. Hãy đặt cho mục thứ hai một alias riêng — chẳng hạn summarizer — và bản build dừng lại trước khi bất cứ thứ gì được render, vì router chỉ có thể công bố một alias. Lần dừng này là E0033, một assertion thất bại của Component của router, và thông báo của nó kết thúc bằng chính câu của quy tắc: 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 chưa được đặt, nhưng values.models công bố 2 alias (assistant, summarizer), nên gateway không thể biết một component nối tới nó yêu cầu alias nào; hãy đặt values.model thành một trong số đó). Đặt model: assistant bên cạnh models sẽ khắc phục lỗi, và agent lại được trao assistant. Một caller muốn summarizer thì yêu cầu nó theo tên tại cùng endpoint đó.

Những gì agent nhận được

Recipe của agent đọc cả hai cạnh của nó cùng các giá trị riêng của agent, và biến chúng thành môi trường của container. Đây là toàn bộ khối env của 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

Mục đầu tiên đến từ attachment mà cạnh model mang theo, và provider helm ghi một mục như vậy, được đọc từ một Secret, trước các mục thông thường. Giới hạn đệ quy là recursion_limit riêng của agent, dưới biến mà LangGraph tự đọc; hai mục tiếp theo đến từ cạnh model, hai mục sau đó từ cạnh checkpointer_db, và mục cuối là graph_entrypoint riêng của agent, dưới một tên mặc định mà mã của ứng dụng đọc, và một khối inject trên chính component sẽ thay thế tên đó. Hãy lưu ý điều mà Aggregate không phải nói: không cạnh nào mang một khối inject, vì Recipe tiêu thụ phân phối mỗi kết nối dưới các tên mặc định, mà một khối inject trên cạnh sẽ thay thế. Nhà phát triển khai báo rằng agent dùng một mô hình; biến mà endpoint của nó được đưa đến là biến mà thư viện client đọc, và nó giữ nguyên như cạnh quy định.

Cũng hãy lưu ý LANGGRAPH_CHECKPOINTER_PORT: "6379". Release khai báo checkpointer: {} và không cấu hình gì, nên cổng đó là giá trị mặc định trong schema riêng của Component cache, được hiện thực hóa và truyền qua cạnh.

Agent nói chuyện với router bằng đúng phương ngữ mà nó sẽ dùng để nói chuyện trực tiếp với một provider — một base URL, một tên mô hình và một khóa. Chính điều đó cho phép chèn, di chuyển hoặc trỏ lại router mà ứng dụng không phải thay đổi.

Sáu attachment, và những gì mỗi attachment render ra

Một attachment không thay đổi gì trong đầu ra thì không dạy được gì. Mỗi attachment trong sáu attachment này đều đặt một thứ gì đó vào đó.

api_key trên router — khóa mà nó yêu cầu ở bên gọi

core/referenced-secret, lấp đầy một slot mà Component của router khai báo; khóa mà nó giữ là khóa mà LiteLLM gọi là master key. Nó render Secret riêng của mình, và container của router tham chiếu đến Secret đó. Trích từ dist/helm/router--api-zukey--router-secret-router-api-key.yaml:

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

và trong env của container router, trích từ dist/helm/router-deployment.yaml:

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

Container mang một tham chiếu, không phải giá trị. Tên của Secret được attachment công bố và được bên tiêu thụ đọc, nên không bên nào phải tự suy ra lại tên đó.

provider_key trên router — khóa mà nó xuất trình cho upstream

Cùng Feature đó nhưng ở một slot khác, và sự khác biệt giữa hai slot chính là mục đích của router. Đây là credential duy nhất của các mục được nhập vào values.models, ở đây là cả hai mục; một mô hình được nối vào socket models của router thì thay vào đó xuất trình khóa mà kết nối riêng của nó mang theo, không bao giờ là khóa này. Trích từ dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml:

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

và trong cùng env của container đó:

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

Attachment này cũng thay đổi bảng định tuyến. Hãy xem lại khối data của bảng định tuyến ở trên: mọi mục trong map đều mang api_key: os.environ/LITELLM_PROVIDER_API_KEY, gọi tên chính biến này. Hãy gỡ attachment provider_key khỏi Aggregate và build lại. Bản build báo cáo mười một tệp thay vì mười hai — Secret đã biến mất — và ConfigMap của bảng định tuyến chỉ khác đúng ở hai dòng api_key đó và không gì khác; ConfigMap của guard không thay đổi. Phần còn lại của map giữ nguyên thứ tự và định dạng đã được viết, router vẫn phục vụ và định tuyến, và giờ đây một yêu cầu được định tuyến sẽ thất bại tại provider vì không có credential nào để xuất trình.

Tên biến được viết một lần trong Recipe của router và được cả bảng định tuyến lẫn môi trường của container đọc từ đó, nên một bảng không thể đi đến chỗ gọi tên một biến mà không gì thiết lập.

Hai credential được giữ tách biệt, và sự tách biệt đó là thứ mà router mang lại: khóa upstream nằm bên trong router, còn ứng dụng gọi không giữ gì ngoài khóa để vào router.

credential trên kết nối model của agent — khóa mà nó xuất trình cho router

Lại là core/referenced-secret, ở phía bên kia của cùng cuộc trao đổi. Socket model của agent khai báo một slot credential, nên khóa được gắn trên kết nối mà nó được xuất trình, dưới cạnh trong Aggregate:

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

Trích từ dist/helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml:

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

Đó là cùng một giá trị với master-key của router ở trên, và nó không được viết hai lần. Cả hai attachment đều đọc một tham số đã được nâng lên:

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

Aggregate khai báo tham số và Release đáp ứng nó, nên khóa có một nơi được viết duy nhất và hai Secret không thể bị sửa lệch nhau. Thay đổi nó một lần trong Release và cả hai Secret được render sẽ thay đổi cùng nhau.

Mỗi attachment vẫn render Secret riêng của nó, được đặt tên theo component tiêu thụ nó — và, với attachment của agent, theo kết nối mà nó được gắn trên đó: agent-router-model.credential. Thứ mà tham số dùng chung chia sẻ là giá trị, không phải tài nguyên.

published trên router — một địa chỉ bên ngoài cluster

core/public-ingress, attachment không lấp đầy slot nào: nó được chấp nhận nhờ selector riêng của nó, component.aggrega.ai/type=server, mà router mang theo. Nó mang đến một tài nguyên mà Recipe của router không hề biết đến. Toàn bộ spec của 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

Nhà phát triển gắn nó trong Aggregate cùng với path, vì việc ứng dụng phục vụ những yêu cầu nào là một phần của bản chất ứng dụng. Người vận hành viết host và tên cổng trên mục của Release dành cho cùng attachment đó: host là tên của router trong môi trường, nên người vận hành đặt nó theo từng môi trường, trong Release của mỗi môi trường. Service backend không do bên nào cung cấp: service_name được để trống, và realization của attachment quay về dùng Service mà chính Recipe của router phát ra. Không có trường ingressClassName trong đầu ra, vì không gì thiết lập nó và realization bỏ qua những gì nó không được cung cấp, để class mặc định của cluster nhận tài nguyên đó.

metrics trên router — một mục tiêu scrape

core/prometheus-exporter, được chấp nhận nhờ cùng selector đó, mang đến một tài nguyên khác của riêng nó. Mọi đầu vào nó nhận đều là việc định cỡ của người vận hành chứ không phải ý định của ứng dụng — tần suất một nền tảng scrape, và cổng cùng đường dẫn mà nó đọc, là các thuộc tính của nền tảng — nên người vận hành gắn nó, trong Release, trên mục của router, với kiểu của nó bên cạnh infra. Aggregate không nhắc đến nó:

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

Toàn bộ spec của 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 gọi tên một cổng của Service chứ không phải một con số: metrics, cổng mà Recipe của router phát ra vì Aggregate thiết lập giá trị metrics_enabled của router, và là cổng phục vụ metrics của nó. Đó cũng là tên cổng mặc định của Feature, được viết rõ ra ở đây cùng với hai tham số điều chỉnh còn lại. Cổng http mà Ingress ở trên định tuyến tới trả về 403 cho /metrics, nên một lần scrape trỏ vào đó sẽ không thu được gì. Việc metrics có được phục vụ hay không là lựa chọn của nhà phát triển, được đưa ra trong Aggregate; còn tần suất cùng cổng và đường dẫn mà một nền tảng scrape chúng là lựa chọn của người vận hành, được đưa ra ở đây.

selection trên router — cách nó chọn giữa các mục tiêu của mình

core/target-selection, attachment gắn vào một gateway mang gateway.aggrega.ai/intelligence: semantic, như router. Cách router lựa chọn là một phần của những gì ứng dụng yêu cầu ở nó, nên nhà phát triển gắn nó trong Aggregate, với strategy của nó là một giá trị:

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

và Manifest gắn nó với realization dành cho router này:

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

Nó không render tệp nào của riêng mình. Realization của nó ghi một thiết lập vào bảng định tuyến mà Recipe của router render — hai dòng cuối của khối data ở trên:

router_settings:
routing_strategy: latency-based-routing

Với nó, proxy gửi mỗi yêu cầu cho assistant tới mục có mười phản hồi gần nhất tốn ít thời gian nhất tính trung bình, theo mỗi token đầu ra nếu phản hồi báo cáo số token của nó, và một mục chưa được thử được tính là nhanh nhất, nên mỗi mục đều được thử trước khi các giá trị trung bình quyết định. Hãy gỡ attachment khỏi Aggregate và build lại: bản build vẫn báo cáo mười hai tệp, và ConfigMap của bảng định tuyến chỉ khác đúng ở hai dòng đó. Recipe của router không tự ghi chiến lược nào, và khi không có chiến lược thì proxy chọn ngẫu nhiên giữa hai mục.

Thay vào đó, nếu yêu cầu strategy: cost thì bản build dừng lại, không ghi gì. Việc dừng này là E0033, một assertion thất bại của realization, và thông báo của nó kết thúc bằng chính câu của quy tắc: 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 (attachment core/target-selection “selection” trên “router” yêu cầu chiến lược cost, nhưng core/gateway/litellm không thể chọn giữa các mục trong model map của nó theo chi phí: proxy tra cứu target của mỗi mục, đúng như được viết, trong bảng giá riêng của nó, bảng này gọi tên các mô hình của OpenAI và Anthropic mà không có tiền tố provider mà một target mang (gpt-4o, không phải openai/gpt-4o) và proxy có thể tải lại bảng này khi khởi động, và nó định giá một mục mà nó không tìm thấy, và không mang giá riêng, theo một mức dự phòng cố định, nên các mục dùng chung một alias được định giá như nhau và lựa chọn rơi vào thứ tự của chúng. Hãy yêu cầu chiến lược latency, hoặc gỡ attachment). Cả hai target ở đây đều được viết theo cách đó, nên proxy sẽ gửi mọi yêu cầu tới target đầu tiên trong khi Aggregate yêu cầu theo chi phí.

Nơi trình biên dịch không diễn giải

Địa chỉ và tên mô hình của agent được đọc từ những gì router công bố, nên không có cặp tên nào trong ba tệp phải được giữ đồng bộ thủ công. Điều mà bản build thực sự kiểm tra là quy tắc riêng của router rằng alias nó công bố là một alias mà map của nó công bố — một quy tắc do Component của nó khai báo và bản build đánh giá, giống như mọi assertion khác mà một thực thể mang theo.

Phần còn lại là các chuỗi được chuyển từ nơi này sang nơi khác. Trình biên dịch định tuyến địa chỉ và alias mà không đọc chúng: nó không biết rằng một cái là hostname và cái kia là tên mô hình, và nó không có quyền truy cập vào một cluster đang chạy để kiểm tra rằng có thứ gì trả lời tại router-default:4000. Nhãn model.aggrega.ai/api đã chấp nhận router cũng là cùng loại chuỗi — selector của socket khớp với nó, và không có gì kiểm tra API nào thực sự trả lời ở đó. Và mỗi target trong map là một con trỏ mà proxy đang chạy phân giải: đổi openai/gpt-4o thành openai/not-a-real-model và bản build vẫn thành công, còn lỗi chỉ xuất hiện lúc gửi yêu cầu.

Đây cũng chính là thuộc tính khiến phần còn lại của ví dụ hoạt động. Vì trình biên dịch không diễn giải những gì nó chuyển đi, router có thể được trỏ lại tới một nhà cung cấp khác, agent có thể được nối tới một router khác, và realization của thông tin xác thực có thể được thay bằng một realization dựa trên kho lưu trữ — tất cả mà trình biên dịch không cần hiểu bất kỳ điều gì trong đó, và agent không phải thay đổi.

Điều chỉnh ví dụ

  • Trỏ lại một provider. Sửa một target trong map của router. Không có gì khác thay đổi: không phải model, không phải agent, không phải một Secret đã được render.

  • Thêm một provider thứ ba. Thêm một mục vào map. Nếu nó publish alias hiện có, chiến lược bắt đầu chọn giữa ba mục. Nếu nó publish một alias mới, map publish hai alias, và values.model của router chỉ định alias được trao cho agent; một bên gọi muốn dùng alias kia thì yêu cầu nó theo tên. Một model mà catalog mô hình hóa và có API là OpenAI API có thể thay vào đó được nối vào socket models của router, dưới một alias riêng và trình ra khóa mà kết nối của nó mang theo; khi đó values.model chỉ định alias được trao cho agent.

  • Thay vào đó, lấy thông tin xác thực từ một kho lưu trữ. Đổi dòng duy nhất trong Manifest gắn core/referenced-secret thành helm/k8s-external-secret rồi build lại. Mỗi Secret đã render trở thành một ExternalSecret chỉ định một mục trong một kho secret của cluster, để một operator của kho đối soát — và tham chiếu đã render của mọi bên tiêu thụ vẫn giống hệt từng byte, vì locator được publish bởi phía sản xuất thay vì được hai phía thỏa thuận. Không có gì khác trong ba tệp phải thay đổi để build thành công.

    Tuy vậy, có một điều cần được viết lại trước khi việc hoán đổi có ý nghĩa: origin đổi nghĩa giữa hai cách hiện thực. Cách hiện thực của workspace này đọc nó là giá trị cần lưu; cách kia đọc nó là khóa cần lấy. Nếu hoán đổi dòng đó mà không xem lại các giá trị origin, thì remoteRef.key đã render sẽ là bất kỳ placeholder nào đang đứng thay cho giá trị — ở đây là dev-router-admin-key-change-me. Khi đó không có gì trong cây đầu ra giữ chuỗi đó như dữ liệu bí mật, nhưng nó vẫn ở đó dưới dạng một khóa kho chỉ định một mục không tồn tại.

  • Bỏ router. Thay vào đó, trỏ cạnh model của agent tới một component model riêng cho từng provider. Khi đó agent tự giữ một thông tin xác thực của provider, đó chính là sự đánh đổi mà router tồn tại để loại bỏ.

  • Kết nối tới một router mà catalog không mô hình hóa. Trỏ cạnh model của agent tới một component core/ai-model/openai-compatible và ghi địa chỉ của router đó vào infra.endpoint của nó trong Release. Không có gì chạy phía sau component đó trong cluster, nên việc ghi địa chỉ và giữ nó khớp với dịch vụ mà nó chỉ định là việc của operator.

Để chia sẻ một thông tin xác thực giữa kết nối của nhiều bên tiêu thụ, xem model-api-key-sharing. Với một socket mà không thực thể catalog nào khai báo, xem adhoc-uses-socket.