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.internalRouter 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:
| instance | Component trong catalog | vai trò ở đây |
|---|---|---|
router | core/gateway/litellm | component đị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 |
agent | core/ai-agent/langgraph | ứng dụng, chạy image đồ thị riêng của nó |
checkpointer | core/datastore/valkey | nơ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ó:
aggrega scaffold --example ai-agent-and-model-routerSau đó 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:
cd ai-agent-and-model-routerBuild
aggrega build --release release.yaml --auto-pullMộ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ó:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildWorkspace 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:
aggrega pull --release release.yamlHã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>/distCá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:
aggrega lint --release release.yamllệ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.yamlTrong 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-routingvà 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: metricsRecipe 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:graphMụ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-keyContainer 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-keyAttachment 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: httpNhà 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: /metricsToà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: /metricsport 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: latencyvà 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.0Nó 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-routingVớ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
targettrong 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.modelcủ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 socketmodelscủ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.modelchỉ đị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-secretthànhhelm/k8s-external-secretrồi build lại. MỗiSecretđã render trở thành mộtExternalSecretchỉ đị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
modelcủ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
modelcủa agent tới một componentcore/ai-model/openai-compatiblevà ghi địa chỉ của router đó vàoinfra.endpointcủ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.