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.internalRouter 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:
| instancja | encja Component z katalogu | czym jest tutaj |
|---|---|---|
router | core/gateway/litellm | komponent 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 |
agent | core/ai-agent/langgraph | aplikacja, uruchamiająca własny obraz grafu |
checkpointer | core/datastore/valkey | miejsce, 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:
aggrega scaffold --example ai-agent-and-model-routerNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd ai-agent-and-model-routerKompilacja
aggrega build --release release.yaml --auto-pullWydanie 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:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildTen 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:
aggrega pull --release release.yamlNależ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>/distEncje 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:
aggrega lint --release release.yamlco 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.yamlW 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-routingoraz 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: metricsRecipe 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:graphPierwszy 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-keyKontener 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-keyTen 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: httpDeweloper 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: /metricsCał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: /metricsport 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: latencya encja Manifest wiąże go z realizacją dla tego routera:
core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0Nie 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-routingDzię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ć
targetw 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.modelroutera 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 gniazdamodelsroutera, pod własnym aliasem i z kluczem, który niesie jego połączenie;values.modelwskazuje wtedy alias, który otrzymuje agent. -
Pobieranie poświadczeń z magazynu. Należy zmienić jedyny wiersz w encji Manifest wiążący
core/referenced-secretnahelm/k8s-external-secreti przebudować. Każdy wyrenderowanySecretstaje sięExternalSecretwskazują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:
originzmienia 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ściorigin, wyrenderowanyremoteRef.keybędzie tym symbolem zastępczym, który stał w miejscu wartości — tutajdev-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ź
modelagenta 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ź
modelagenta na komponentcore/ai-model/openai-compatiblei wpisać adres tego routera w jegoinfra.endpointw 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.