Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Um agente, um router e dois modelos a montante

Uma aplicação de agente que chega a dois modelos de fornecedores a montante através de um único router dentro do cluster, compilada para manifestos Kubernetes.

O agente pede um modelo por um único nome. Por trás desse nome está um router que contém um mapa de aliases, e por trás do mapa estão dois fornecedores. O agente nunca fica a saber que fornecedor respondeu, nunca detém uma credencial de um fornecedor e não muda quando o mapa é reapontado — que é precisamente a razão para colocar ali um router.

Este workspace não cria nenhuma entidade de catálogo própria. Cada Component, Feature e Recipe que nomeia é distribuído no catálogo da biblioteca standard; os três ficheiros de entidade aqui presentes — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.

O que constrói

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

O router tem duas entradas para pedidos — o agente alcança-o através da sua aresta model, e qualquer coisa no exterior alcança-o através do Ingress — e uma saída por entrada do mapa. Uma terceira porta serve as suas métricas a um scraper dentro do cluster.

Três componentes, e cada um faz um trabalho diferente:

instânciaComponent do catálogoo que é aqui
routercore/gateway/litellmo componente de encaminhamento: um endpoint, um mapa de aliases, dois fornecedores a montante. Publica o seu endereço e o alias que o agente pede
agentcore/ai-agent/langgrapha aplicação, que executa a sua própria imagem de grafo
checkpointercore/datastore/valkeyonde o agente guarda o estado das execuções, selecionado pela categoria datastore

Duas arestas uses, ambas para sockets que o Component do agente declara: model (obrigatório, que admite um componente de modelo ou um gateway que serve uma API de modelo — o router é o segundo caso) e checkpointer_db (obrigatório, que seleciona pela categoria datastore). Seis anexos de Feature sobre quatro tipos de Feature — cinco no router, um na ligação model do agente — cada um dos quais coloca algo na saída renderizada; a secção abaixo mostra o que cada um produz.

Gerar o exemplo

É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.

Escreva o exemplo numa nova pasta com o nome dele:

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

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

Compilação

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

Uma release precisa de um lockfile antes de ser compilada, e os lockfiles são gerados em vez de distribuídos, pelo que um clone novo não tem nenhum. aggrega build é apenas de leitura por predefinição: sem lockfile, é interrompido e indica os dois caminhos possíveis. Resolva-se um primeiro, ou deixe-se que a compilação o preencha:

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

Este workspace resolve as suas entidades a partir do registo predefinido que .aggrega-config.yaml indica, pelo que não é necessária nenhuma flag --catalog.

A realização do anexo selection do router executa um plugin que não é distribuído nem no compilador nem no catálogo, o passo de configuração do gateway pipeline-step/litellm-gateway-config, que a resolução obtém do registo que default_registry indica, hub.aggrega.ai.

Várias secções abaixo pedem que se altere uma linha e se volte a compilar. O lockfile fixa um digest para cada entidade que a release resolveu, incluindo o Aggregate e o Manifest deste diretório, e regista a própria Release pelo digest do seu conteúdo — pelo que editar qualquer um destes três ficheiros desatualiza o lockfile, e a compilação seguinte é interrompida em vez de renderizar com um pin obsoleto. A mensagem nomeia o que mudou — a Release pelo seu ficheiro, o Aggregate ou o Manifest pelo seu nome — e imprime o digest que registou ao lado do que encontrou. Um pull regista a alteração respeitando todos os outros pins:

Terminal window
aggrega pull --release release.yaml

Execute-o e volte a compilar, ou compile com --auto-pull, que executa primeiro o mesmo pull. Em qualquer dos casos, a interrupção é o objetivo e não um obstáculo: uma compilação não renderiza com um pin que consegue ver que está obsoleto.

A compilação imprime, com <workspace> a representar a pasta deste exemplo:

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

As entidades são verificadas em relação às convenções do catálogo uma vez enquanto o lockfile é resolvido e outra enquanto a release é compilada, e cada aviso que essas verificações levantam é impresso como uma linha lint:; esta release não levanta nenhum. Para executar as mesmas verificações por si só, e ler qualquer aviso por completo com o ficheiro de entidade de onde veio e o que o tornaria conforme:

Terminal window
aggrega lint --release release.yaml

que aqui reporta conventions checked: 19 entities, 0 advisory finding(s).

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.

Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta do espaço de trabalho ainda não contiver uma pasta `ai-agent-and-model-router`, chame a ferramenta `scaffold` uma única vez com `example` definido como `ai-agent-and-model-router` e sem `dir`: esta escreve o exemplo numa nova pasta `ai-agent-and-model-router`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `ai-agent-and-model-router`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me que ficheiros a compilação escreveu; encontram-se em `ai-agent-and-model-router/dist/`.

A árvore renderizada

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

Em router/ estão os ficheiros que a própria Recipe do router emite. Ambos provêm de bundles que a Recipe importa em vez de escrever, pelo que cada um fica sob a chave com que foi importado, litellm-gateway-config e request-guard.

Tudo o que um anexo trouxe fica no mesmo diretório que os manifestos próprios do componente, com duas coordenadas no nome do ficheiro: o componente a que foi anexado e o nome que o anexo recebeu. router--metrics-- é o anexo metrics em router. O que veio de onde continua legível na árvore, e cada ficheiro está onde uma ferramenta que lê um único diretório o encontrará — que é o que fazem os consumidores deste destino, a menos que lhes seja indicado o contrário.

As duas coordenadas são codificadas em vez de escritas tal como foram digitadas, porque partilham uma cadeia com o nome próprio do ficheiro. Um carácter que um nome de ficheiro não pode transportar com segurança passa a -z e uma letra: api_key é api-zukey; router_model.credential — o nome que o anexo na ligação router_model do agente recebe, ou seja, o alias da ligação, um ponto e o slot — é router-zumodel-zdcredential; e feature.aggrega.ai/monitoring — um nome de anexo que a própria anotação de uma Feature cunha — seria feature-zdaggrega-zdai-zsmonitoring. O nome próprio do ficheiro mantém todos os pontos que tiver, pelo que o sufixo .yaml continua a ler-se como um sufixo.

Quando uma página aqui mostra o que uma compilação produziu, o bloco é copiado de uma execução real — ver Ler a saída nestas páginas para a convenção e a marca que usa para as linhas omitidas.

A tabela de encaminhamento

A razão de ser do router é o seu mapa, e o mapa chega à saída renderizada em vez de ficar no ficheiro escrito pelo autor. Eis o bloco data completo de 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

e o bloco data do segundo ConfigMap, dist/helm/router/request-guard/request-guard.yaml, sem o texto dos ficheiros que contém:

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]

Há cinco coisas que vale a pena ler nestes blocos.

As duas entradas publicam o mesmo alias. É isso que dá ao router uma escolha a fazer em cada pedido, e os router_settings no fim do corpo dizem como a faz: latency-based-routing, escrito aí pelo anexo selection do router e não pela sua própria Recipe, como mostra mais abaixo a secção sobre esse anexo. Um mapa cujos aliases são todos distintos encaminha apenas pelo nome, e a estratégia não muda nada nisso. Partilhar um alias é também a razão pela qual ambas as entradas são escritas à mão em values.models em vez de servidas por componentes de modelo ligados ao socket models do router: um modelo ligado é servido sob o alias da sua própria ligação, que nenhuma outra entrada pode publicar, pelo que dois modelos ligados nunca partilham um. A segunda razão prende-se com a Anthropic: o router escreve a entrada de um modelo ligado apenas através da API da OpenAI, enquanto o modelo da Anthropic responde à sua própria API, pelo que ligar core/ai-model/anthropic interrompe a compilação, com uma mensagem a indicar que esse modelo a montante seja antes escrito no mapa.

Os destinos são strings que o compilador não interpreta. openai/gpt-4o é um ponteiro determinístico: o proxy em execução resolve-o quando serve um pedido. O compilador nunca contacta um fornecedor durante a compilação, pelo que não pode indicar se um destino existe, se está corretamente escrito ou se a conta do utilizador o consegue alcançar. Ao alterar openai/gpt-4o para openai/not-a-real-model, a compilação continua a ter êxito — a falha chega no momento do pedido, vinda do fornecedor.

Nenhum valor de credencial está neste ficheiro. Cada entrada nomeia, em vez disso, uma variável de ambiente, através da indireção própria do proxy. O valor chega ao contentor por um caminho totalmente diferente, mostrado abaixo.

Todos os pedidos passam primeiro por uma guarda. A primeira entrada de callbacks regista o módulo request_field_filter pelo caminho completo do seu ficheiro: o segundo ConfigMap está montado no contentor do router em /etc/litellm-request-guard, um diretório próprio ao lado de /etc/litellm, onde o primeiro está montado e onde o proxy lê a sua configuração. Esse segundo ConfigMap provém de LiteLLMGuard#/artifacts/RequestGuard, um bundle que cada Recipe que executa este proxy importa, de modo que a guarda e a lista de permissões abaixo têm um único texto onde quer que o proxy seja executado. A Recipe do router entrega esta guarda em cada Release, porque o router detém a credencial do fornecedor. Ela reencaminha de um chamador apenas os campos do pedido que o proxy declara para a rota que o pedido tomou, mais os que a Release nomeia em infra.admitted_request_fields do router, e responde a qualquer outro campo com um erro que o nomeia, sem reencaminhar nada — assim, um chamador não pode apontar o router para um endereço seu através de uma lista de modelos no corpo do pedido, nem enviar uma chave de fornecedor sua em vez da do router. Também não pode um chamador definir a identidade que o próprio router escreve em cada pedido — o hash da chave que verificou, a equipa e a organização dessa chave, e o utilizador final: num pedido responses ou messages, em que o router mantém os metadata do chamador separados dos seus, remove qualquer campo de equipa, organização ou utilizador final que o chamador aí tenha escrito e a guarda recusa um pedido que aí nomeie a chave, metadata.user_api_key, e em qualquer outra rota o valor do router substitui qualquer um que o chamador tenha enviado. Esta Release não admite mais nada. A segunda entrada, prometheus, é o callback de métricas próprio do proxy, que o valor metrics_enabled do router ativa; o anexo metrics abaixo recolhe o que ele regista.

Só as rotas próprias do router são alcançáveis. A guarda só vê as rotas que lhe entregam o pedido, pelo que o outro ficheiro do segundo ConfigMap configura o segundo contentor do pod, que monta apenas esse ConfigMap e executa a imagem oficial do nginx como lista de permissões de caminhos. O próprio router escuta no endereço de loopback do pod, onde nada fora do pod o alcança, e a lista de permissões escuta na porta 4000, a porta que o Service abaixo tem como alvo. Só reencaminha um pedido quando o seu método e o seu caminho correspondem a uma das rotas que o router serve — as rotas de pedidos de modelo que a guarda verifica, nas grafias que o router serve qualquer que seja o alias, entre elas /v1/chat/completions e /v1/messages; a listagem de modelos; as verificações de estado; e, das suas rotas administrativas, a gestão de chaves — e responde 403 a qualquer outro caminho, sem reencaminhar nada. Assim, as rotas de contagem de tokens do proxy, as suas rotas de passagem direta para as APIs próprias dos fornecedores, as suas outras rotas administrativas e a sua consola administrativa não podem ser alcançadas através do router, nem uma rota de modelo cujo caminho contém o nome do modelo, como acontece com os caminhos que o cliente do Azure envia: aí o proxy lê palavras no caminho, alias incluído, para decidir como regista um pedido, e o router recusaria nela um pedido para o assistant próprio deste mapa. As métricas do proxy também não estão entre essas rotas: a porta 4000 responde 403 a /metrics. Com metrics_enabled do router a true, como o Aggregate o define, a lista de permissões também escuta na porta 9090 e aí reencaminha apenas um GET de /metrics, para o listener que o proxy mantém para as suas métricas no endereço de loopback, respondendo 403 a qualquer outro pedido. Essa porta não verifica nenhum chamador, e as métricas nomeiam as chaves com hash, os aliases de chaves e os e-mails de utilizadores a quem o router atribui a despesa.

O que o router publica

A Recipe do router publica as duas chaves que qualquer componente de modelo publica: um endpoint, o URL base entregue a uma biblioteca cliente, e um model, o nome que um pedido solicita. É isso que permite ao socket model do agente aceitar o router em vez de um modelo. O seletor do socket é component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: admite um componente da categoria de modelo ou de gateway que tenha model.aggrega.ai/api, o rótulo que nomeia que API de modelo responde no endereço que o componente publica. O router tem model.aggrega.ai/api: openai. Um gateway que não serve nenhuma API de modelo não tem esse rótulo, e uma aresta do agente para um deles interrompe a compilação, nomeando o socket e o seletor que o destino não satisfaz.

O endereço é o Service que a própria Recipe do router emite — o spec completo de 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

A Recipe compõe o endpoint que publica, http://router-default:4000/v1, a partir dos mesmos dois factos de que o Service tira o nome e a porta: o nome próprio do componente e o seu infra.port. A porta que o Service tem como alvo, http, é aquela em que a lista de permissões de caminhos do router escuta; metrics, a segunda, existe porque as métricas do router estão ativadas, e transporta apenas essas. Nada nos três ficheiros escreve router-default por extenso. Ao mudar o nome do componente router — a sua chave no Aggregate e na Release, e a aresta do agente que o nomeia —, o endereço que o agente recebe acompanha: com o nome gateway, a OPENAI_BASE_URL do agente é http://gateway-default:4000/v1.

O nome é o alias que o router publica como o seu modelo. Este mapa publica um único alias, assistant, a partir das suas duas entradas, pelo que o router publica esse e o seu values.model fica de fora. Ao dar à segunda entrada um alias próprio — summarizer, por exemplo —, a compilação é interrompida antes de qualquer coisa ser renderizada, porque o router só pode publicar um. A interrupção é E0033, uma asserção falhada do Component do router, e a sua mensagem termina com a frase própria da regra: 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 não está definido, mas values.models publica 2 aliases (assistant, summarizer), pelo que o gateway não consegue saber qual deles pede um componente ligado a ele; defina values.model como um deles). Definir model: assistant ao lado de models resolve-o, e o agente volta a receber assistant. Um chamador que queira summarizer pede-o pelo nome ao mesmo endpoint.

O que o agente recebe

A Recipe do agente lê as suas duas arestas e os valores próprios do agente, e transforma-os no ambiente do contentor. Eis o bloco env completo de 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

A primeira veio do anexo que a aresta model transporta, e o fornecedor helm escreve uma entrada assim, lida de um Secret, antes das simples. O limite de recursão é o próprio recursion_limit do agente, sob a variável que o LangGraph lê por si; as duas seguintes vieram da aresta model, as duas a seguir a essas da aresta checkpointer_db, e a última é o próprio graph_entrypoint do agente, sob um nome predefinido que o código da aplicação lê, e que um bloco inject no próprio componente substituiria. Repare-se no que o Aggregate não teve de dizer: nenhuma das arestas tem um bloco inject, porque a Recipe consumidora entrega cada ligação sob nomes predefinidos, que um bloco inject na aresta substituiria. O programador declara que o agente usa um modelo; a variável sob a qual chega o seu endpoint é a que a biblioteca cliente lê, e continua a ser a que a aresta determinar.

Repare-se também em LANGGRAPH_CHECKPOINTER_PORT: "6379". A Release declara checkpointer: {} e não configura nada, pelo que essa porta é o valor predefinido do esquema próprio do Component de cache, materializado e canalizado através da aresta.

O agente fala com o router exatamente no dialeto que usaria para falar diretamente com um fornecedor — um URL base, um nome de modelo e uma chave. É isso que permite inserir, mover ou reapontar o router sem que a aplicação mude.

Os seis anexos, e o que cada um renderiza

Um anexo que não muda nada na saída não ensina nada. Cada um destes seis coloca aí alguma coisa.

api_key no router — a chave que exige aos chamadores

core/referenced-secret, a preencher um slot que o Component do router declara; a chave que contém é a que o LiteLLM chama a sua master key. Renderiza o seu próprio Secret, e o contentor do router faz-lhe referência. De dist/helm/router--api-zukey--router-secret-router-api-key.yaml:

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

e no env do contentor do router, de dist/helm/router-deployment.yaml:

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

O contentor tem uma referência, não o valor. O nome do Secret é publicado pelo anexo e lido pelo consumidor, pelo que nenhum dos lados o volta a derivar.

provider_key no router — a chave que apresenta a montante

A mesma Feature num slot diferente, e a diferença entre os dois slots é a razão de ser do router. É a única credencial das entradas escritas em values.models, aqui ambas; um modelo ligado ao socket models do router apresenta, em vez disso, a chave que a sua própria ligação transporta, nunca esta. De dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml:

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

e no mesmo env do contentor:

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

Este anexo também altera a tabela de encaminhamento. Volte-se ao bloco data da tabela de encaminhamento acima: cada entrada do mapa tem api_key: os.environ/LITELLM_PROVIDER_API_KEY, que nomeia esta mesma variável. Remova-se o anexo provider_key do Aggregate e volte-se a compilar. A compilação reporta onze ficheiros em vez de doze — o Secret desapareceu — e o ConfigMap da tabela de encaminhamento difere exatamente nessas duas linhas api_key e em nada mais; o ConfigMap da guarda fica inalterado. O resto do mapa mantém a ordem e a formatação escritas pelo autor, o router continua a servir e a encaminhar, e um pedido encaminhado falha agora no fornecedor porque não há credencial a apresentar.

O nome da variável é escrito uma única vez na Recipe do router e lido a partir daí tanto pela tabela de encaminhamento como pelo ambiente do contentor, pelo que uma tabela não pode chegar a nomear uma variável que nada define.

As duas credenciais mantêm-se separadas, e essa separação é o que o router proporciona: a chave a montante fica dentro do router, e a aplicação chamadora não detém mais nada além da chave do router.

credential na ligação model do agente — a chave que apresenta ao router

core/referenced-secret de novo, do outro lado da mesma conversa. O socket model do agente declara um slot credential, pelo que a chave é anexada na ligação em que é apresentada, sob a aresta no Aggregate:

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

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

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

É o mesmo valor que a master-key do router acima, e não é escrito duas vezes. Ambos os anexos leem um único parâmetro elevado:

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

O Aggregate declara o parâmetro e a Release cumpre-o, pelo que a chave tem um único sítio onde é escrita e os dois Secrets não podem ser editados separadamente. Alterando-a uma vez na Release, ambos os Secrets renderizados mudam em conjunto.

Cada anexo continua a renderizar o seu próprio Secret, cujo nome deriva do componente que o consome — e, no caso do agente, da ligação em que está anexado: agent-router-model.credential. O que o parâmetro partilhado partilha é o valor, não o recurso.

published no router — um endereço fora do cluster

core/public-ingress, que não preenche nenhum slot: é admitida pelo seu próprio seletor, component.aggrega.ai/type=server, que o router tem. Traz um recurso de que a Recipe do router nada sabe. O spec completo de 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

O programador anexa-a no Aggregate com o path, porque os pedidos que uma aplicação serve fazem parte do que a aplicação é. O operador escreve o host e o nome da porta na entrada da Release para o mesmo anexo: o host é o nome que o ambiente dá ao router, pelo que o operador o nomeia por ambiente, na Release de cada ambiente. O Service de backend não foi fornecido por nenhum dos dois: service_name fica por definir, e a realização do anexo recorre ao Service que a própria Recipe do router emite. Não há nenhum campo ingressClassName na saída, porque nada definiu um e a realização omite o que não lhe foi dado, deixando que a classe predefinida do cluster reclame o recurso.

metrics no router — um alvo de scraping

core/prometheus-exporter, admitida pelo mesmo seletor, a trazer outro recurso próprio. Cada parâmetro que recebe é dimensionamento do operador e não intenção da aplicação — com que frequência uma plataforma faz scraping, e que porta e que caminho lê, são propriedades da plataforma — pelo que é o operador que a anexa, na Release, na entrada do router, com o seu tipo ao lado da sua infra. O Aggregate não a menciona:

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

O spec completo de dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml:

spec:
selector:
matchLabels:
app.kubernetes.io/name: router
endpoints:
- port: metrics
interval: 30s
path: /metrics

O port nomeia uma porta do Service em vez de um número: metrics, que a Recipe do router emite porque o Aggregate define o valor metrics_enabled do router, e que serve as suas métricas. É também o nome de porta predefinido da Feature, aqui escrito por extenso com os outros dois parâmetros de ajuste. A porta http para a qual o Ingress acima encaminha responde 403 a /metrics, pelo que um scraping apontado para aí não recolheria nada. Se as métricas são servidas ou não é escolha do programador, feita no Aggregate; com que frequência e em que porta e caminho uma plataforma as recolhe é escolha do operador, feita aqui.

selection no router — como escolhe entre os seus destinos

core/target-selection, que se anexa a um gateway que tenha gateway.aggrega.ai/intelligence: semantic, como o router tem. A forma como o router escolhe faz parte do que a aplicação lhe pede, pelo que o programador a anexa no Aggregate, com a sua strategy como valor:

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

e o Manifest associa-a à realização para este router:

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

Não renderiza nenhum ficheiro próprio. A sua realização escreve uma definição na tabela de encaminhamento que a Recipe do router renderiza — as duas últimas linhas do bloco data acima:

router_settings:
routing_strategy: latency-based-routing

Com ela, o proxy envia cada pedido para assistant à entrada cujas dez últimas respostas demoraram, em média, menos tempo, por token de saída quando uma resposta indica os seus tokens, e uma entrada ainda não experimentada conta como a mais rápida, pelo que cada uma é experimentada antes de as médias decidirem. Remova-se o anexo do Aggregate e volte-se a compilar: a compilação continua a reportar doze ficheiros, e o ConfigMap da tabela de encaminhamento difere exatamente nessas duas linhas. A Recipe do router não escreve nenhuma estratégia própria, e sem uma o proxy escolhe ao acaso entre as duas entradas.

Ao pedir strategy: cost em vez disso, a compilação é interrompida, sem escrever nada. A interrupção é E0033, uma asserção falhada da realização, e a sua mensagem termina com a frase própria da regra: 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 (o anexo core/target-selection “selection” em “router” pede a estratégia cost, mas core/gateway/litellm não consegue escolher entre as entradas do seu mapa de modelos pelo custo: o proxy procura o destino de cada entrada, exatamente como está escrito, na sua própria tabela de preços, que nomeia os modelos da OpenAI e da Anthropic sem o prefixo de fornecedor que um destino tem (gpt-4o, não openai/gpt-4o) e que o proxy pode voltar a obter ao arrancar, e atribui a uma entrada que não encontra, e que não tem preço próprio, um preço de recurso fixo, pelo que as entradas que partilham um alias recebem o mesmo preço e a escolha recai sobre a sua ordem. Peça a estratégia latency, ou remova o anexo). Ambos os destinos aqui estão escritos dessa forma, pelo que o proxy enviaria todos os pedidos ao primeiro deles enquanto o Aggregate pedia o custo.

Onde o compilador não interpreta

O endereço e o nome de modelo do agente são lidos daquilo que o router publica, pelo que nenhum par de nomes nos três ficheiros tem de ser mantido em sintonia à mão. O que a compilação verifica de facto é a regra própria do router de que o alias que publica é um dos que o seu mapa publica — uma regra que o seu Component declara e a compilação avalia, como qualquer outra asserção que uma entidade tenha.

O resto são strings canalizadas de um sítio para outro. O compilador encaminha o endereço e o alias sem os ler: não sabe que um é um nome de anfitrião e o outro um nome de modelo, e não tem acesso a um cluster em execução para verificar se algo responde em router-default:4000. O rótulo model.aggrega.ai/api que admitiu o router é o mesmo tipo de string — o seletor do socket compara-o, e nada verifica que API responde de facto aí. E cada target no mapa é um ponteiro que o proxy em execução resolve: ao alterar openai/gpt-4o para openai/not-a-real-model, a compilação continua a ter êxito, com a falha a chegar no momento do pedido.

É a mesma propriedade que faz funcionar o resto do exemplo. Como o compilador não interpreta o que canaliza, o router pode ser reapontado para um fornecedor diferente, o agente pode ser ligado a um router diferente e a realização da credencial pode ser trocada por uma apoiada num repositório — tudo sem que o compilador precise de compreender nada disso, e sem que o agente mude.

Adaptá-lo

  • Reapontar um fornecedor. Edite-se um target no mapa do router. Nada mais muda: nem o modelo, nem o agente, nem um Secret renderizado.

  • Acrescentar um terceiro fornecedor. Acrescente-se uma entrada ao mapa. Se publicar o alias existente, a estratégia passa a escolher entre três. Se publicar um novo, o mapa publica dois aliases, e o values.model do router nomeia aquele que é entregue ao agente; um chamador que queira o outro pede-o pelo nome. Um modelo que o catálogo modela e cuja API é a API da OpenAI pode, em vez disso, ser ligado ao socket models do router, sob um alias próprio e apresentando a chave que a sua ligação transporta; values.model nomeia então o alias entregue ao agente.

  • Obter antes as credenciais de um repositório. Altere-se para helm/k8s-external-secret a única linha do Manifest que vincula core/referenced-secret e volte-se a compilar. Cada Secret renderizado passa a ser um ExternalSecret que nomeia uma entrada num repositório de segredos do cluster, para um operador do repositório reconciliar — e a referência renderizada de cada consumidor fica idêntica byte a byte, porque o localizador é publicado pelo lado produtor em vez de ser acordado entre ambos. Nada mais nos três ficheiros tem de mudar para que a compilação tenha êxito.

    Uma coisa, no entanto, tem de ser reescrita antes de a troca fazer sentido: origin muda de significado entre as duas realizações. A realização deste workspace lê-o como o valor a guardar; a outra lê-o como a chave a obter. Ao trocar a linha sem rever os valores de origin, o remoteRef.key renderizado é o marcador de posição, qualquer que fosse, que estava no lugar do valor — aqui, dev-router-admin-key-change-me. Nada na árvore de saída guarda então essa string como material secreto, mas ela continua lá como uma chave do repositório que nomeia uma entrada que não existe.

  • Prescindir do router. Aponte-se antes a aresta model do agente para um componente de modelo específico de um fornecedor. O agente passa então a deter ele próprio uma credencial de fornecedor, que é precisamente a contrapartida que o router existe para eliminar.

  • Alcançar um router que o catálogo não modela. Aponte-se a aresta model do agente para um componente core/ai-model/openai-compatible e escreva-se o endereço desse router no seu infra.endpoint na Release. Nada é executado por trás desse componente dentro do cluster, pelo que cabe ao operador escrever o endereço e mantê-lo em sintonia com o serviço que nomeia.

Para partilhar uma credencial entre as ligações de vários consumidores, ver model-api-key-sharing. Para um socket que nenhuma entidade do catálogo declara, ver adhoc-uses-socket.