Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Agent, router i dwa modele nadrzędne

Aplikacja agenta, która łączy się z dwoma nadrzędnymi modelami dostawców przez jeden router działający w klastrze, skompilowana do manifestów Kubernetes.

Agent prosi o model pod jedną nazwą. Za tą nazwą stoi router przechowujący mapę aliasów, a za mapą stoi dwóch dostawców. Agent nigdy nie dowiaduje się, który dostawca odpowiedział, nigdy nie przechowuje poświadczeń dostawcy i nie zmienia się, gdy mapa zostaje przekierowana — i właśnie dlatego w ogóle warto umieścić tam router.

Ten obszar roboczy nie definiuje żadnej własnej encji katalogu. Każda encja Component, Feature i Recipe, do której się odwołuje, jest dostarczana w katalogu biblioteki standardowej; trzy pliki encji w tym miejscu — Aggregate, Manifest i Release — to wszystko, co trzeba napisać.

Co powstaje

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

Router ma dwie drogi wejścia dla żądań — agent dociera do niego przez swoją krawędź model, a wszystko spoza klastra przez Ingress — oraz jedną drogę wyjścia na każdy wpis mapy. Trzeci port udostępnia jego metryki scraperowi wewnątrz klastra.

Trzy komponenty, a każdy z nich wykonuje inne zadanie:

instancjaencja Component z kataloguczym jest tutaj
routercore/gateway/litellmkomponent routingu: jeden punkt końcowy, mapa aliasów, dwóch dostawców nadrzędnych. Publikuje swój adres oraz alias, o który prosi agent
agentcore/ai-agent/langgraphaplikacja, uruchamiająca własny obraz grafu
checkpointercore/datastore/valkeymiejsce, w którym agent przechowuje stan przebiegów, wybrane według kategorii magazynu danych

Dwie krawędzie uses, obie do gniazd deklarowanych przez encję Component agenta: model (wymagane, dopuszczające komponent modelu lub bramę udostępniającą API modelu — router jest tym drugim) oraz checkpointer_db (wymagane, wybierające według kategorii magazynu danych). Sześć dołączeń encji Feature w czterech rodzajach Feature — pięć na routerze, jedno na połączeniu model agenta — z których każde umieszcza coś w wyrenderowanym wyniku; sekcja poniżej pokazuje, co wytwarza każde z nich.

Generowanie przykładu

Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

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

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

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

Kompilacja

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

Wydanie wymaga pliku blokady przed zbudowaniem, a pliki blokady są generowane, a nie dostarczane, więc świeży klon nie ma żadnego. aggrega build domyślnie działa tylko do odczytu: bez pliku blokady zatrzymuje się i wskazuje dwie drogi dalej. Należy najpierw rozwiązać plik blokady albo pozwolić, by uzupełniło go budowanie:

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

Ten obszar roboczy rozwiązuje swoje encje z domyślnego rejestru wskazanego w .aggrega-config.yaml, więc flaga --catalog nie jest potrzebna.

Realizacja załącznika selection routera uruchamia jeden plugin, który nie jest dostarczany ani z kompilatorem, ani z katalogiem: krok konfiguracji bramy pipeline-step/litellm-gateway-config, który rozwiązywanie pobiera z rejestru wskazanego przez default_registry, hub.aggrega.ai.

Kilka sekcji poniżej prosi o zmianę wiersza i ponowne zbudowanie. Plik blokady przypina skrót dla każdej encji rozwiązanej przez wydanie, w tym encji Aggregate i encji Manifest w tym katalogu, a samą encję Release zapisuje według skrótu jej treści — więc edycja dowolnego z tych trzech plików unieważnia plik blokady, a następne budowanie zatrzymuje się, zamiast renderować względem nieaktualnego przypięcia. Komunikat wskazuje, co się zmieniło — encję Release przez jej plik, encję Aggregate lub Manifest przez jej nazwę — i wypisuje zapisany skrót obok znalezionego. Polecenie pull zapisuje zmianę, zachowując wszystkie pozostałe przypięcia:

Terminal window
aggrega pull --release release.yaml

Należy je uruchomić i zbudować ponownie albo zbudować z --auto-pull, co najpierw wykonuje ten sam pull. Tak czy inaczej zatrzymanie jest celowe, a nie jest przeszkodą: budowanie nie renderuje względem przypięcia, o którym wie, że jest nieaktualne.

Budowanie wypisuje (<workspace> oznacza folder tego przykładu):

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

Encje są sprawdzane pod kątem konwencji katalogu raz podczas rozwiązywania pliku blokady i raz podczas budowania wydania, a każde ostrzeżenie zgłoszone przez te kontrole jest wypisywane jako wiersz lint:; to wydanie nie zgłasza żadnego. Aby uruchomić te same kontrole osobno i przeczytać każde ostrzeżenie w całości wraz z plikiem encji, z którego pochodzi, oraz informacją, co by je uzgodniło:

Terminal window
aggrega lint --release release.yaml

co tutaj zgłasza conventions checked: 19 entities, 0 advisory finding(s).

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `ai-agent-and-model-router`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `ai-agent-and-model-router` i bez `dir`: zapisze ono przykład w nowym folderze `ai-agent-and-model-router`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `ai-agent-and-model-router`, `release` ustawionym na `release.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, które pliki zapisało budowanie; znajdują się w `ai-agent-and-model-router/dist/`.

Wyrenderowane drzewo

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

W router/ znajdują się pliki, które emituje sama encja Recipe routera. Oba pochodzą z pakietów, które Recipe importuje, a nie pisze, więc każdy leży pod kluczem, pod którym został zaimportowany: litellm-gateway-config i request-guard.

Wszystko, co wniósł załącznik, leży w tym samym katalogu co własne manifesty komponentu i niesie w nazwie pliku dwie współrzędne: komponent, do którego został dołączony, oraz nazwę nadaną załącznikowi. router--metrics-- to załącznik metrics na router. Z drzewa nadal można odczytać, co skąd pochodzi, a każdy plik znajduje się tam, gdzie znajdzie go narzędzie czytające jeden katalog — i tak właśnie postępują odbiorcy tego celu, o ile nie wskaże im się inaczej.

Obie współrzędne są kodowane, a nie zapisywane tak, jak je wpisano, ponieważ dzielą jeden ciąg z własną nazwą pliku. Znak, którego nazwa pliku nie może bezpiecznie zawierać, staje się -z i literą: api_key to api-zukey; router_model.credential — nazwa, jaką przyjmuje załącznik na połączeniu router_model agenta, czyli alias połączenia, kropka i slot — to router-zumodel-zdcredential; a feature.aggrega.ai/monitoring — nazwa załącznika, którą tworzy własna adnotacja encji Feature — byłaby zapisana jako feature-zdaggrega-zdai-zsmonitoring. Własna nazwa pliku zachowuje wszystkie swoje kropki, więc przyrostek .yaml nadal czyta się jako przyrostek.

Tam, gdzie strona tutaj pokazuje wynik kompilacji, blok jest skopiowany z rzeczywistego uruchomienia — zob. Czytanie wyników na tych stronach, gdzie opisano konwencję i znacznik używany dla pominiętych wierszy.

Tablica routingu

Racją bytu routera jest jego mapa, a mapa trafia do wyrenderowanego wyniku, zamiast pozostać w pliku źródłowym. Oto cały blok data pliku 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

oraz blok data drugiej mapy ConfigMap, dist/helm/router/request-guard/request-guard.yaml, z pominięciem treści plików, które zawiera:

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]

Warto z nich odczytać pięć rzeczy.

Oba wpisy publikują ten sam alias. To właśnie daje routerowi wybór przy każdym żądaniu, a router_settings na końcu treści mówi, jak go dokonuje: latency-based-routing, wpisane tam przez załącznik selection routera, a nie przez jego własną encję Recipe, jak pokazuje sekcja o tym załączniku poniżej. Mapa, której aliasy są wszystkie różne, kieruje żądania wyłącznie po nazwie, a strategia nic w tym nie zmienia. Wspólny alias jest też powodem, dla którego oba wpisy są wpisane ręcznie w values.models, a nie obsługiwane przez komponenty modeli podłączone do gniazda models routera: podłączony model jest obsługiwany pod aliasem własnego połączenia, którego żaden inny wpis nie może publikować, więc dwa podłączone modele nigdy nie mają wspólnego aliasu. Drugi powód dotyczy Anthropic: router zapisuje wpis podłączonego modelu wyłącznie przez API OpenAI, podczas gdy model Anthropic odpowiada przez własne API, więc podłączenie core/ai-model/anthropic zatrzymuje kompilację z komunikatem, by zamiast tego wpisać ten model źródłowy do mapy.

Cele są ciągami znaków, których kompilator nie interpretuje. openai/gpt-4o jest deterministycznym wskaźnikiem: działający proxy rozwiązuje go, gdy obsługuje żądanie. Kompilator nigdy nie kontaktuje się z dostawcą w czasie kompilacji, więc nie może stwierdzić, czy cel istnieje, czy jest poprawnie zapisany ani czy dane konto ma do niego dostęp. Po zmianie openai/gpt-4o na openai/not-a-real-model kompilacja nadal się powiedzie — błąd pojawi się w czasie żądania, od dostawcy.

W tym pliku nie ma żadnej wartości poświadczenia. Każdy wpis zamiast tego wskazuje zmienną środowiskową, przez własny mechanizm pośredni proxy. Wartość trafia do kontenera zupełnie inną drogą, pokazaną poniżej.

Każde żądanie najpierw trafia na strażnika. Pierwszy wpis callbacks rejestruje moduł request_field_filter przez pełną ścieżkę jego pliku: druga mapa ConfigMap jest montowana w kontenerze routera w /etc/litellm-request-guard, osobnym katalogu obok /etc/litellm, gdzie montowana jest pierwsza i skąd proxy odczytuje swoją konfigurację. Ta druga ConfigMap pochodzi z LiteLLMGuard#/artifacts/RequestGuard, pakietu importowanego przez każdą encję Recipe uruchamiającą ten proxy, więc strażnik i opisana niżej lista dozwolonych mają jedną treść wszędzie, gdzie proxy działa. Encja Recipe routera dostarcza tego strażnika w każdej encji Release, ponieważ to router przechowuje poświadczenie dostawcy. Przekazuje od wywołującego tylko te pola żądania, które proxy deklaruje dla trasy, którą poszło żądanie, oraz te, które encja Release wymienia w infra.admitted_request_fields routera, a na każde inne pole odpowiada błędem z jego nazwą, niczego nie przekazując — dzięki temu wywołujący nie może skierować routera na własny adres przez listę modeli w treści żądania ani wysłać własnego klucza dostawcy w miejsce klucza routera. Wywołujący nie może też ustawić tożsamości, którą router sam wpisuje do każdego żądania — skrótu zweryfikowanego klucza, zespołu i organizacji tego klucza oraz użytkownika końcowego: w żądaniu responses lub messages, gdzie router trzyma metadata wywołującego oddzielnie od własnych, usuwa wszelkie pola zespołu, organizacji lub użytkownika końcowego, które wywołujący tam wpisał, a strażnik odrzuca żądanie wskazujące tam klucz, metadata.user_api_key, zaś na każdej innej trasie wartość routera zastępuje wartość wysłaną przez wywołującego. Ta encja Release nie dopuszcza niczego więcej. Drugi wpis, prometheus, to własny callback metryk proxy, włączany przez wartość metrics_enabled routera; załącznik metrics opisany niżej zbiera to, co on rejestruje.

Osiągalne są tylko własne trasy routera. Strażnik widzi tylko trasy, które przekazują mu żądanie, dlatego drugi plik drugiej mapy ConfigMap konfiguruje drugi kontener poda, który montuje wyłącznie tę ConfigMap i uruchamia oficjalny obraz nginx jako listę dozwolonych ścieżek. Sam router nasłuchuje na adresie pętli zwrotnej poda, gdzie nic spoza poda do niego nie dociera, a lista dozwolonych nasłuchuje na porcie 4000, na który kieruje opisany niżej Service. Przekazuje żądanie tylko wtedy, gdy jego metoda i ścieżka należą do tras obsługiwanych przez router — tras żądań modeli sprawdzanych przez strażnika, w zapisach obsługiwanych przez router niezależnie od aliasu, w tym /v1/chat/completions i /v1/messages; listy modeli; kontroli stanu; oraz, spośród jego tras administracyjnych, zarządzania kluczami — a na każdą inną ścieżkę odpowiada 403, niczego nie przekazując. Dlatego trasy liczenia tokenów proxy, jego trasy przelotowe do własnych API dostawców, pozostałe trasy administracyjne i konsola administracyjna nie są osiągalne przez router, podobnie jak trasa modelu, której ścieżka zawiera nazwę modelu, jak ścieżki wysyłane przez klienta Azure: tam proxy odczytuje słowa ze ścieżki, w tym alias, by zdecydować, jak rejestruje żądanie, a router odrzuciłby na niej żądanie dotyczące własnego aliasu tej mapy, assistant. Wśród tych tras nie ma też metryk proxy: port 4000 odpowiada na /metrics kodem 403. Gdy metrics_enabled routera ma wartość true, jak ustawia to encja Aggregate, lista dozwolonych nasłuchuje też na porcie 9090 i przekazuje tam wyłącznie GET /metrics do nasłuchu, który proxy utrzymuje dla swoich metryk na adresie pętli zwrotnej, odpowiadając 403 na każde inne żądanie. Ten port nie sprawdza wywołującego, a metryki wymieniają zahaszowane klucze, aliasy kluczy i adresy e-mail użytkowników, którym router przypisuje wydatki.

Co publikuje router

Recipe routera publikuje dwa klucze, które publikuje każdy komponent modelu: endpoint, czyli bazowy URL przekazywany bibliotece klienckiej, oraz model, czyli nazwę, o którą prosi żądanie. Dzięki temu gniazdo model agenta może przyjąć router zamiast modelu. Selektor gniazda to component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: dopuszcza on komponent z kategorii modelu lub bramy, który ma etykietę model.aggrega.ai/api, określającą, które API modelu odpowiada pod adresem publikowanym przez komponent. Router ma etykietę model.aggrega.ai/api: openai. Brama, która nie obsługuje żadnego API modelu, nie ma takiej etykiety, a krawędź od agenta do niej zatrzymuje kompilację z komunikatem wskazującym gniazdo i selektor, którego cel nie spełnia.

Adresem jest Service emitowany przez własny Recipe routera — cały blok spec z pliku 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 składa publikowany endpoint, http://router-default:4000/v1, z tych samych dwóch faktów, od których pochodzą nazwa i port Service: własnej nazwy komponentu i jego infra.port. Port docelowy Service, http, to ten, na którym nasłuchuje lista dozwolonych ścieżek routera; drugi, metrics, istnieje, ponieważ metryki routera są włączone, i przenosi wyłącznie je. Nic w trzech plikach nie zapisuje wprost router-default. Po zmianie nazwy komponentu router — jego klucza w encji Aggregate i w encji Release oraz krawędzi agenta, która go wskazuje — adres otrzymywany przez agenta podąża za nią: po zmianie nazwy na gateway zmienna OPENAI_BASE_URL agenta ma wartość http://gateway-default:4000/v1.

Nazwą jest alias, który router publikuje jako swój model. Ta mapa publikuje jeden alias, assistant, z obu swoich wpisów, więc router publikuje właśnie ten, a jego values.model jest pominięte. Jeśli drugiemu wpisowi nada się własny alias — na przykład summarizer — kompilacja zatrzyma się, zanim cokolwiek zostanie wyrenderowane, ponieważ router może publikować tylko jeden. Zatrzymanie to E0033, niespełniona asercja encji Component routera, a jego komunikat kończy się zdaniem samej reguły: 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 nie jest ustawione, ale values.models publikuje 2 aliasy (assistant, summarizer), więc brama nie może określić, o który prosi podłączony do niej komponent; należy ustawić values.model na jeden z nich). Ustawienie model: assistant obok models usuwa błąd, a agent znów otrzymuje assistant. Wywołujący, który chce użyć summarizer, prosi o niego ten sam endpoint po nazwie.

Co otrzymuje agent

Recipe agenta odczytuje obie jego krawędzie oraz własne wartości agenta i zamienia je na środowisko kontenera. Oto cały blok env pliku 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

Pierwszy wpis pochodzi z załącznika, który niesie krawędź model, a dostawca helm zapisuje taki wpis, odczytywany z obiektu Secret, przed zwykłymi wpisami. Limit rekurencji to własny recursion_limit agenta, pod zmienną, którą LangGraph odczytuje samodzielnie; kolejne dwa pochodzą z krawędzi model, następne dwa z krawędzi checkpointer_db, a ostatni to własny graph_entrypoint agenta, pod domyślną nazwą odczytywaną przez kod aplikacji, którą zastąpiłby blok inject na samym komponencie. Warto zauważyć, czego Aggregate nie musiał określać: żadna krawędź nie niesie bloku inject, ponieważ konsumujący Recipe dostarcza każde połączenie pod domyślnymi nazwami, które blok inject na krawędzi by zastąpił. Programista deklaruje, że agent używa modelu; zmienna, pod którą dociera jego punkt końcowy, jest tą, którą odczytuje biblioteka klienta, i pozostaje taka, jaką narzuca krawędź.

Warto też zwrócić uwagę na LANGGRAPH_CHECKPOINTER_PORT: "6379". Release deklaruje checkpointer: {} i niczego nie konfiguruje, więc ten port jest domyślną wartością z własnego schematu encji Component pamięci podręcznej, zmaterializowaną i przekazaną przez krawędź.

Agent komunikuje się z routerem dokładnie w tym samym dialekcie, którego użyłby, rozmawiając bezpośrednio z dostawcą — bazowy URL, nazwa modelu i klucz. Dzięki temu router można wstawić, przenieść lub przekierować bez zmian w aplikacji.

Sześć załączników i to, co każdy z nich renderuje

Załącznik, który niczego nie zmienia w wyniku, niczego nie uczy. Każdy z tych sześciu coś tam umieszcza.

api_key na routerze — klucz, którego wymaga od wywołujących

core/referenced-secret, wypełniający slot zadeklarowany przez encję Component routera; przechowywany w nim klucz to ten, który LiteLLM nazywa kluczem głównym. Renderuje on własny Secret, a kontener routera się do niego odwołuje. Z pliku dist/helm/router--api-zukey--router-secret-router-api-key.yaml:

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

oraz w env kontenera routera, z pliku dist/helm/router-deployment.yaml:

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

Kontener zawiera odwołanie, a nie wartość. Nazwę Secretu publikuje załącznik, a odczytuje ją konsument, więc żadna ze stron nie wyprowadza jej ponownie.

provider_key na routerze — klucz, który przedstawia dostawcom nadrzędnym

Ta sama encja Feature w innym slocie, a różnica między tymi dwoma slotami stanowi sens istnienia routera. Jest to jedyne poświadczenie wpisów wprowadzonych do values.models, tutaj obu; model podłączony do gniazda models routera przedstawia zamiast niego klucz, który niesie jego własne połączenie, nigdy ten. Z pliku dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml:

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

oraz w tym samym env kontenera:

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

Ten załącznik zmienia także tablicę routingu. Wróćmy do bloku data tablicy routingu powyżej: każdy wpis mapy zawiera api_key: os.environ/LITELLM_PROVIDER_API_KEY, wskazujące tę samą zmienną. Należy usunąć załącznik provider_key z encji Aggregate i ponownie zbudować. Build zgłasza jedenaście plików zamiast dwunastu — Secret znika — a ConfigMap tablicy routingu różni się dokładnie tymi dwoma wierszami api_key i niczym więcej; ConfigMap strażnika pozostaje bez zmian. Reszta mapy zachowuje autorską kolejność i formatowanie, router nadal działa i trasuje, a trasowane żądanie kończy się teraz błędem u dostawcy, ponieważ nie ma poświadczenia do przedstawienia.

Nazwa zmiennej jest zapisana raz w encji Recipe routera i stamtąd odczytywana zarówno przez tablicę routingu, jak i przez środowisko kontenera, więc tablica nie może zacząć wskazywać zmiennej, której nic nie ustawia.

Oba poświadczenia pozostają rozdzielone i właśnie to rozdzielenie daje router: klucz nadrzędny pozostaje wewnątrz routera, a wywołująca aplikacja przechowuje jedynie klucz do routera.

credential na połączeniu model agenta — klucz, który przedstawia routerowi

Ponownie core/referenced-secret, po drugiej stronie tej samej rozmowy. Gniazdo model agenta deklaruje slot credential, więc klucz jest dołączany do połączenia, na którym jest przedstawiany, pod krawędzią w encji Aggregate:

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

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

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

To ta sama wartość co master-key routera powyżej i nie jest zapisana dwukrotnie. Oba załączniki odczytują jeden wyniesiony parametr:

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

Encja Aggregate deklaruje parametr, a encja Release go wypełnia, więc klucz ma jedno miejsce zapisu, a obu Secretów nie da się edytować rozbieżnie. Wystarczy zmienić go raz w encji Release, a oba wyrenderowane Secrety zmienią się razem.

Każdy załącznik nadal renderuje własny Secret, nazwany od komponentu, który go konsumuje — a w przypadku agenta także od połączenia, do którego jest dołączony: agent-router-model.credential. Wspólny parametr współdzieli wartość, a nie zasób.

published na routerze — adres poza klastrem

core/public-ingress, który nie wypełnia żadnego slotu: jest dopuszczany przez własny selektor, component.aggrega.ai/type=server, który router posiada. Wnosi on zasób, o którym encja Recipe routera nic nie wie. Cały spec pliku 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

Deweloper dołącza go w encji Aggregate z path, ponieważ to, które żądania aplikacja obsługuje, jest częścią tego, czym aplikacja jest. Operator zapisuje host i nazwę portu we wpisie encji Release dla tego samego załącznika: host to nazwa routera w danym środowisku, więc operator nadaje ją osobno dla każdego środowiska, w encji Release każdego z nich. Usługi backendu nie dostarczył żaden z nich: service_name pozostaje nieustawione, a realizacja załącznika wraca do Service emitowanego przez własną encję Recipe routera. W wyniku nie ma pola ingressClassName, ponieważ nic go nie ustawiło, a realizacja pomija to, czego nie otrzymała, pozostawiając zasób domyślnej klasie klastra.

metrics na routerze — cel scrapowania

core/prometheus-exporter, dopuszczany przez ten sam selektor, wnoszący kolejny własny zasób. Każde przyjmowane przez niego wejście to wymiarowanie operatorskie, a nie intencja aplikacji — to, jak często platforma scrapuje oraz który port i ścieżkę odczytuje, to właściwości platformy — dlatego dołącza go operator, w encji Release, we wpisie routera, z typem obok infra. Encja Aggregate go nie wspomina:

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

Cały spec pliku 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 wskazuje port Service, a nie numer: metrics, który emituje encja Recipe routera, ponieważ encja Aggregate ustawia wartość metrics_enabled routera, i który udostępnia jego metryki. Jest to także domyślna nazwa portu encji Feature, wypisana tu razem z dwoma pozostałymi ustawieniami. Port http, do którego trasuje powyższy Ingress, odpowiada na /metrics kodem 403, więc skierowane tam scrapowanie niczego by nie zebrało. To, czy metryki są w ogóle udostępniane, jest wyborem dewelopera, dokonanym w encji Aggregate; to, jak często oraz na jakim porcie i ścieżce platforma je scrapuje, jest wyborem operatora, dokonanym tutaj.

selection na routerze — jak wybiera między swoimi celami

core/target-selection, który dołącza się do bramy oznaczonej gateway.aggrega.ai/intelligence: semantic, tak jak router. Sposób, w jaki router wybiera, jest częścią tego, czego aplikacja od niego oczekuje, więc deweloper dołącza go w encji Aggregate, z strategy jako wartością:

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

a encja Manifest wiąże go z realizacją dla tego routera:

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

Nie renderuje własnego pliku. Jego realizacja zapisuje jedno ustawienie w tablicy routingu renderowanej przez encję Recipe routera — dwa ostatnie wiersze bloku data powyżej:

router_settings:
routing_strategy: latency-based-routing

Dzięki temu proxy wysyła każde żądanie dla assistant do wpisu, którego ostatnie dziesięć odpowiedzi zajęło średnio najmniej czasu, w przeliczeniu na token wyjściowy tam, gdzie odpowiedź raportuje swoje tokeny, a wpis jeszcze niewypróbowany liczy się jako najszybszy, więc każdy jest wypróbowany, zanim zdecydują średnie. Należy usunąć załącznik z encji Aggregate i ponownie zbudować: build nadal zgłasza dwanaście plików, a ConfigMap tablicy routingu różni się dokładnie tymi dwoma wierszami. Encja Recipe routera nie zapisuje własnej strategii, a bez niej proxy wybiera między dwoma wpisami losowo.

Jeśli zamiast tego zażąda się strategy: cost, build zostaje zatrzymany i niczego nie zapisuje. Zatrzymanie to E0033, niespełniona asercja realizacji, a jego komunikat kończy się własnym zdaniem reguły: 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 (załącznik core/target-selection „selection” na „router” żąda strategii cost, ale core/gateway/litellm nie potrafi wybierać między wpisami swojej mapy modeli według kosztu: proxy wyszukuje cel każdego wpisu, dokładnie tak, jak został zapisany, we własnej tabeli cen, która nazywa modele OpenAI i Anthropic bez prefiksu dostawcy zawartego w celu (gpt-4o, a nie openai/gpt-4o) i którą proxy może pobrać na nowo przy starcie, a wpis, którego nie znajdzie i który nie ma własnej ceny, wycenia według stałej wartości zastępczej, więc wpisy współdzielące alias są wyceniane jednakowo, a wybór zależy od ich kolejności. Należy zażądać strategii latency lub usunąć załącznik). Oba cele są tu zapisane w ten sposób, więc proxy wysyłałoby każde żądanie do pierwszego z nich, podczas gdy encja Aggregate żądała kosztu.

Gdzie kompilator nie interpretuje

Adres agenta i nazwa modelu są odczytywane z tego, co publikuje router, więc żadnej pary nazw w trzech plikach nie trzeba ręcznie utrzymywać w zgodności. To, co build faktycznie sprawdza, to własna reguła routera, zgodnie z którą publikowany przez niego alias jest jednym z aliasów publikowanych przez jego mapę — reguła, którą deklaruje jego encja Component, a build ją ewaluuje, jak każdą inną asercję, którą niesie encja.

Reszta to ciągi znaków przekazywane z jednego miejsca do drugiego. Kompilator przekazuje adres i alias, nie odczytując ich: nie wie, że jeden jest nazwą hosta, a drugi nazwą modelu, i nie ma dostępu do działającego klastra, by sprawdzić, czy cokolwiek odpowiada pod router-default:4000. Etykieta model.aggrega.ai/api, która dopuściła router, jest tego samego rodzaju ciągiem znaków — dopasowuje ją selektor gniazda i nic nie sprawdza, jakie API faktycznie tam odpowiada. A każdy target w mapie jest wskaźnikiem, który rozwiązuje działające proxy: wystarczy zmienić openai/gpt-4o na openai/not-a-real-model, a build nadal się powiedzie, a błąd pojawi się dopiero w czasie obsługi żądania.

To ta sama właściwość, dzięki której działa reszta przykładu. Ponieważ kompilator nie interpretuje tego, co przekazuje, router można przekierować na innego dostawcę, agenta można podłączyć do innego routera, a realizację poświadczeń można zamienić na opartą na magazynie — wszystko to bez potrzeby rozumienia czegokolwiek z tego przez kompilator i bez zmian w agencie.

Dostosowywanie przykładu

  • Przekierowanie dostawcy. Należy zmienić target w mapie routera. Nic innego się nie zmienia: ani model, ani agent, ani wyrenderowany Secret.

  • Dodanie trzeciego dostawcy. Należy dodać wpis do mapy. Jeśli publikuje on istniejący alias, strategia zaczyna wybierać spośród trzech. Jeśli publikuje nowy, mapa publikuje dwa aliasy, a values.model routera wskazuje ten, który otrzymuje agent; wywołujący, który chce drugiego, prosi o niego po nazwie. Model, który katalog modeluje i którego API jest API OpenAI, można zamiast tego podłączyć do gniazda models routera, pod własnym aliasem i z kluczem, który niesie jego połączenie; values.model wskazuje wtedy alias, który otrzymuje agent.

  • Pobieranie poświadczeń z magazynu. Należy zmienić jedyny wiersz w encji Manifest wiążący core/referenced-secret na helm/k8s-external-secret i przebudować. Każdy wyrenderowany Secret staje się ExternalSecret wskazującym wpis w magazynie sekretów klastra, który uzgadnia operator magazynu — a wyrenderowane odwołanie każdego konsumenta pozostaje identyczne bajt w bajt, ponieważ lokalizator publikuje strona produkująca, a nie uzgadniają go obie strony. Nic więcej w trzech plikach nie musi się zmienić, aby budowanie się powiodło.

    Jedna rzecz wymaga jednak ponownego napisania, zanim zamiana będzie miała sens: origin zmienia znaczenie między obiema realizacjami. Realizacja w tym obszarze roboczym odczytuje go jako wartość do zapisania; druga — jako klucz do pobrania. Jeśli zamieni się wiersz bez przejrzenia wartości origin, wyrenderowany remoteRef.key będzie tym symbolem zastępczym, który stał w miejscu wartości — tutaj dev-router-admin-key-change-me. Nic w drzewie wyjściowym nie przechowuje wtedy tego ciągu jako materiału, ale nadal występuje on jako klucz magazynu wskazujący wpis, który nie istnieje.

  • Usunięcie routera. Należy skierować krawędź model agenta na komponent modelu danego dostawcy. Agent przechowuje wtedy sam poświadczenie dostawcy, czyli właśnie to, czego router ma oszczędzić.

  • Połączenie z routerem, którego katalog nie modeluje. Należy skierować krawędź model agenta na komponent core/ai-model/openai-compatible i wpisać adres tego routera w jego infra.endpoint w encji Release. Za tym komponentem nic nie działa w klastrze, więc wpisanie adresu i utrzymywanie go w zgodzie z usługą, którą wskazuje, należy do operatora.

Współdzielenie jednego poświadczenia między połączeniami kilku konsumentów opisuje model-api-key-sharing. Gniazdo, którego nie deklaruje żadna encja katalogu, opisuje adhoc-uses-socket.