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.internalO 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ância | Component do catálogo | o que é aqui |
|---|---|---|
router | core/gateway/litellm | o 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 |
agent | core/ai-agent/langgraph | a aplicação, que executa a sua própria imagem de grafo |
checkpointer | core/datastore/valkey | onde 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:
aggrega scaffold --example ai-agent-and-model-routerDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd ai-agent-and-model-routerCompilação
aggrega build --release release.yaml --auto-pullUma 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:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste 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:
aggrega pull --release release.yamlExecute-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>/distAs 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:
aggrega lint --release release.yamlque 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.yamlEm 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-routinge 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: metricsA 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:graphA 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-keyO 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-keyEste 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: httpO 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: /metricsO 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: /metricsO 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: latencye o Manifest associa-a à realização para este router:
core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0Nã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-routingCom 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
targetno 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.modeldo 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 socketmodelsdo router, sob um alias próprio e apresentando a chave que a sua ligação transporta;values.modelnomeia então o alias entregue ao agente. -
Obter antes as credenciais de um repositório. Altere-se para
helm/k8s-external-secreta única linha do Manifest que vinculacore/referenced-secrete volte-se a compilar. CadaSecretrenderizado passa a ser umExternalSecretque 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:
originmuda 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 deorigin, oremoteRef.keyrenderizado é 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
modeldo 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
modeldo agente para um componentecore/ai-model/openai-compatiblee escreva-se o endereço desse router no seuinfra.endpointna 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.