Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Envoy Gateway davanti a OpenAI, con un budget mensile di token

Un team mette gpt-4o-mini di OpenAI dietro un gateway interno al cluster, vuole un tetto ai token che il gateway spende per esso ogni mese di calendario, e indirizza il suo agente al gateway anziché a OpenAI. Questo workspace compila tutto ciò in manifest Kubernetes: Envoy Gateway che serve il modello tramite Envoy AI Gateway, con core/period-budget associato, un Redis che tiene il conteggio, e un agente CrewAI che invia le sue richieste al modello tramite il gateway.

La pagina mostra anche che cosa questo gateway si rifiuta di contare: un budget in dollari statunitensi fa arrestare il build, e lo stesso fa un budget per chiamante.

Questo workspace non scrive alcuna entità di catalogo propria. I tre file di entità qui presenti — un Aggregate, un Manifest e una Release — sono tutto ciò che chiunque scrive.

Che cosa costruisce

istanzaComponent del catalogoche cosa è qui
edgecore/gateway/envoy-gatewayil gateway, che serve un alias, assistant, dal modello chat
ai-controllercore/gateway/envoy-ai-gateway-operatoril controller di Envoy AI Gateway, che il gateway chiama come suo server di estensione, installato con le sei definizioni di risorse di AI Gateway
chatcore/ai-model/openaigpt-4o-mini di OpenAI, raggiunto come riferimento: nel cluster non gira nulla per esso
counterscore/datastore/redislo store in cui il servizio di rate limiting del gateway tiene il conteggio del budget
assistantcore/ai-agent/crewaiun agente le cui richieste al modello vanno al gateway
certscore/security/cert-managercert-manager, che emette il certificato servito dal webhook del controller

Gli archi uses del gateway partono dal suo socket extension, verso il controller; da models, verso il modello, portando come sua credential la chiave che il gateway presenta a OpenAI; e da cache, verso lo store, portando la password che il servizio di rate limiting gli presenta. L’arco model dell’agente punta al gateway, non al modello. Un’unica associazione di Feature sul gateway, budget: l’Aggregate scrive che cosa viene contato, total_tokens, e il traffico di chi è coperto da un unico limite, gateway — tutto ciò che il gateway serve — e la Release scrive quanto e su quale durata: venti milioni di token per mese di calendario.

Il Manifest vincola ogni credenziale a k8s-existing-secret, che indirizza un carico di lavoro a un Secret già presente nel suo namespace e non ne renderizza alcuno, così nessuna chiave o password si trova nell’Aggregate, nella Release o nell’output renderizzato. I nomi dei Secret sono due parametri che la Release soddisfa, e lo slot password dello store legge lo stesso parametro della connessione cache del gateway, così lo store e il servizio che gli presenta la password nominano un unico Secret.

La Release dichiara dove gira ciascun carico di lavoro: cert-manager in cert-manager, il controller in envoy-ai-gateway-system, l’agente in assistant e il gateway in envoy-gateway-system — il controller cerca lì il piano di controllo del gateway, e il build si arresta se il gateway è collocato altrove — con lo store accanto a esso. Il modello non esegue nulla: il suo unico file, un Service che mappa un nome interno al cluster sull’host di OpenAI, non nomina alcun namespace, e il gateway raggiunge OpenAI all’endpoint che il modello pubblica anziché attraverso quel Service.

cert-manager è dichiarato, non presunto

Il webhook del controller serve un certificato emesso da cert-manager: la sua Recipe renderizza un Certificate di cert-manager e l’Issuer autofirmato che lo firma, che solo un cert-manager in esecuzione riconcilia. Il compilatore non può esaminare un cluster per vedere se lì ne gira uno, quindi il workspace dichiara cert-manager anziché presumerlo: certs si trova nell’Aggregate accanto al controller, e il build renderizza cert-manager insieme a tutto il resto.

Un cluster esegue un solo cert-manager. Se il tuo ne esegue già uno, rimuovi certs dall’Aggregate e dalla Release prima del build; il build renderizza allora gli stessi file, meno quelli di cert-manager.

Generare l’esempio

Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example envoy-ai-gateway-token-budget

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd envoy-ai-gateway-token-budget

Build

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

Una release ha bisogno di un lockfile prima di eseguire il build, e i lockfile sono generati anziché distribuiti, quindi un clone appena creato non ne ha nessuno. Risolvine prima uno, oppure lascia che sia il build a crearlo:

Terminal window
aggrega pull --release release.yaml --pin-sources # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

La risoluzione fissa i tre chart che le Recipes renderizzano — quello di Envoy Gateway e quello di Envoy AI Gateway da Docker Hub, quello di cert-manager da quay.io — quindi richiede la rete. Questo workspace risolve le entità del catalogo dal registry predefinito nominato da .aggrega-config.yaml.

Il build con --auto-pull stampa, con <workspace> al posto della cartella di questo esempio:

Pull complete: release.lock (entities=26, source_artifacts=3, external_inputs=0)
[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and the total build time, which differs per run]
Build completed: 113 files written to <workspace>/dist

Con un assistente AI

Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.

Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella dell’area di lavoro non contiene ancora una cartella `envoy-ai-gateway-token-budget`, chiama una volta lo strumento `scaffold` con `example` impostato a `envoy-ai-gateway-token-budget` e senza `dir`: scrive l’esempio in una nuova cartella `envoy-ai-gateway-token-budget`. Poi chiama lo strumento `build` con `workspace_root` impostato a `envoy-ai-gateway-token-budget`, `release` impostato a `release.yaml`, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto la build; si trovano in `envoy-ai-gateway-token-budget/dist/`.

L’albero renderizzato

dist/helm/
├── ai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yaml
[… omitted: the controller's two cluster roles and their bindings]
├── ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml
├── ai-controller-issuer-envoy-ai-gateway-system-self-signed-issuer-for-mutating-webhook.yaml
├── ai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yaml
├── ai-controller-service-envoy-ai-gateway-system-ai-controller.yaml
[… omitted: the controller's service account]
├── ai-controller/
│ ├── aigateway.envoyproxy.io_aigatewayroutes.yaml
[… omitted: the other five AI Gateway resource definitions]
├── assistant-deployment.yaml
[… omitted: the files cert-manager's chart renders, each named certs-…]
├── chat-service.yaml
├── counters-default-service.yaml
├── counters-deployment.yaml
[… omitted: Envoy Gateway's cluster roles and their bindings]
├── edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml
[… omitted: the resource definitions Envoy Gateway's chart installs]
├── edge-deployment-envoy-gateway-system-envoy-gateway.yaml
[… omitted: the rest of Envoy Gateway's chart — its certificate job, admission configurations, roles, bindings, Service and service accounts]
└── edge/
├── gateway.yaml
├── gatewayclass.yaml
└── models.yaml

Il budget non porta alcun file proprio. Ciò che fa è scritto in due dei file del gateway: dist/helm/edge/models.yaml, che contiene la route AI e le risorse che raggiungono il modello, e la configurazione del piano di controllo, dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml.

Il budget, come lo legge il gateway

Da models.yaml, la route AI:

apiVersion: aigateway.envoyproxy.io/v1beta1
kind: AIGatewayRoute
metadata:
[… omitted: the labels and annotations every rendered resource carries]
name: edge-models
namespace: "envoy-gateway-system"
spec:
parentRefs:
- name: edge
kind: Gateway
group: gateway.networking.k8s.io
llmRequestCosts:
- metadataKey: llm_total_token
type: TotalToken
rules:
- matches:
- headers:
- type: Exact
name: x-ai-eg-model
value: "assistant"
backendRefs:
- name: edge-assistant
modelNameOverride: "gpt-4o-mini"

e, dallo stesso file, la policy di traffico che la limita, chiamata come la route a cui si applica:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
[… omitted: the labels and annotations every rendered resource carries]
name: edge-models
namespace: "envoy-gateway-system"
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: edge-models
rateLimit:
global:
rules:
- limit:
requests: 20000000
unit: Month
shared: true
cost:
request:
from: Number
number: 0
response:
from: Metadata
metadata:
namespace: io.envoy.ai_gateway
key: llm_total_token

Ecco la chiave envoy-gateway.yaml della configurazione del piano di controllo:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyGateway
extensionApis:
enableBackend: true
enableEnvoyPatchPolicy: true
extensionManager:
hooks:
xdsTranslator:
post:
- Translation
- Cluster
- Route
translation:
cluster:
includeAll: true
listener:
includeAll: true
route:
includeAll: true
secret:
includeAll: true
service:
fqdn:
hostname: ai-controller.envoy-ai-gateway-system.svc.cluster.local
port: 1063
gateway:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
logging:
level:
default: info
provider:
kubernetes:
rateLimitDeployment:
container:
env:
- name: REDIS_AUTH
valueFrom:
secretKeyRef:
key: password
name: counter-store-password
- name: USE_CALENDAR_MONTH_RATE_LIMIT
value: "true"
image: docker.io/envoyproxy/ratelimit:8fe6ea42
patch:
type: StrategicMerge
value:
spec:
template:
spec:
containers:
- imagePullPolicy: IfNotPresent
name: envoy-ratelimit
shutdownManager:
image: docker.io/envoyproxy/gateway:v1.9.1
type: Kubernetes
rateLimit:
backend:
redis:
url: counters-default.envoy-gateway-system.svc.cluster.local:6379
type: Redis
failClosed: true

Che cosa leggervi:

Il costo sta sulla route AI, il limite sulla route in cui essa si trasforma. Envoy AI Gateway legge i total_tokens che ogni risposta del modello riporta e li scrive nei metadati della richiesta sotto llm_total_token: è ciò che dichiara llmRequestCosts. Il controller trasforma la route AI in una route HTTP con lo stesso nome, edge-models, e la policy di traffico si applica a quella route, così il budget copre il traffico verso il modello e nessun’altra route collegata al gateway.

Una risposta viene addebitata quando si completa. cost.request non addebita nulla all’arrivo di una richiesta; cost.response addebita i token della risposta una volta che la risposta è completa. Una richiesta viene rifiutata quando il conteggio addebitato fino a quel momento supera limit.

Un unico conteggio per l’intero gateway. shared: true mantiene un unico conteggio su tutte le regole della route — l’ambito gateway richiesto dall’associazione. Con scope: model la Recipe scrive una regola per connessione sul socket models, ciascuna corrispondente al nome del modello che una richiesta porta in x-ai-eg-model, così ogni modello viene contato a parte.

Il periodo è un’unità sull’orologio. 1mo viene scritto come unit: Month, e la configurazione indica al servizio di rate limiting di Envoy Gateway, tramite USE_CALENDAR_MONTH_RATE_LIMIT, di contare un Month dal primo giorno di un mese di calendario all’ultimo. Quell’impostazione appartiene al servizio, quindi si applica a ogni rate limit Month che questa installazione di Envoy Gateway mantiene, quello del budget e qualsiasi altro. Ogni finestra inizia in un punto fisso dell’orologio UTC anziché con una prima richiesta: un giorno alle 00:00 UTC, una settimana di giovedì.

Il conteggio risiede nello store sul socket cache. Il blocco rateLimit attiva il servizio di rate limiting proprio di Envoy Gateway, che il piano di controllo crea nel suo namespace e attiva per ogni gateway che serve, e lo indirizza al Redis che il socket cache del gateway raggiunge. Lo store pubblica il proprio host senza namespace, quindi il gateway lo qualifica con quello in cui la Release colloca lo store.

Un controllo che non riceve risposta rifiuta la richiesta. failClosed: true fa sì che Envoy rifiuti una richiesta al modello con HTTP 500 mentre lo store o il servizio di rate limiting non sono raggiungibili, o un controllo impiega più del timeout di rate limiting di Envoy, 20 ms per impostazione predefinita, anziché servirla senza contarla. Quell’impostazione appartiene al piano di controllo, quindi vale per ogni rate limit che questa installazione di Envoy Gateway mantiene, e anche un rate limit applicato a mano all’installazione fallisce in modo chiuso. La configurazione la porta solo mentre il budget è associato.

Non contiene alcuna password. Il servizio legge la password dello store come REDIS_AUTH, dal Secret che nomina la credenziale della connessione cache, counter-store-password, che risolve nel proprio namespace, quello del gateway. Lo store, counters-deployment.yaml, si avvia con --requirepass letto dallo stesso Secret.

Il percorso dall’agente al modello

Da assistant-deployment.yaml, l’env del container dell’agente:

env:
- name: OPENAI_BASE_URL
value: http://envoy-envoy-gateway-system-edge-06431a46.envoy-gateway-system.svc.cluster.local:80/v1
- name: MODEL
value: assistant
- name: CREWAI_ALLOW_DELEGATION
value: "false"
- name: CREWAI_BACKSTORY
value: a help-desk agent answering customers
- name: CREWAI_GOAL
value: answer questions about the product
- name: CREWAI_LOG_LEVEL
value: DEBUG
- name: CREWAI_ROLE
value: support assistant

L’agente legge le due chiavi che il gateway pubblica, che sono le due che pubblica un modello, quindi la sua Recipe le legge come leggerebbe quelle di un modello. Le variabili CREWAI_ portano i valori propri dell’agente, con i nomi che il Component CrewAI assegna loro per impostazione predefinita. L’indirizzo è il Service che Envoy Gateway crea per il piano dati del gateway, con un nome ricavato dal namespace del gateway, dal suo nome e da un hash dei due, e qualificato con envoy-gateway-system, così si risolve dal namespace dell’agente. Il nome del modello è l’alias assistant; la route invia una richiesta che lo nomina al backend del modello, chiedendo invece gpt-4o-mini.

Il backend raggiunge OpenAI all’endpoint che il modello pubblica: models.yaml contiene un Backend di Envoy Gateway per api.openai.com sulla porta 443, una policy TLS che verifica il suo certificato rispetto alle trust anchor del sistema, un AIServiceBackend per l’API di OpenAI sotto /v1, e la policy di sicurezza che presenta la chiave, edge-assistant, il cui spec è:

spec:
targetRefs:
- group: aigateway.envoyproxy.io
kind: AIServiceBackend
name: edge-assistant
type: APIKey
apiKey:
secretRef:
name: "openai-api-key"

Il controller legge la chiave da quel Secret, nel namespace del gateway, sotto la chiave dati apiKey, e la invia a OpenAI come bearer token, così nessun file renderizzato la contiene e l’agente non la detiene mai. Il gateway chiama il controller all’indirizzo che il controller pubblica, qualificato con il namespace in cui la Release lo colloca — il blocco extensionManager sopra. Mentre è cablato un modello, il gateway riceve anche la policy del traffico client di Envoy AI Gateway, edge-client-buffer-limit in models.yaml, che porta a 50Mi il buffer consentito a ogni connessione in ingresso; si applica al gateway, quindi vale per ogni route collegata a esso.

Che cosa fa il gateway in fase di esecuzione

A ogni richiesta al modello il gateway chiede al servizio di rate limiting se i token addebitati finora in questo mese superano limit. Una volta che li superano, risponde alle richieste al modello con HTTP 429 fino alla fine del mese. I token di una richiesta vengono aggiunti una volta che la sua risposta è completa, quindi la richiesta che supera il limite viene servita, e così qualsiasi richiesta a cui si risponde accanto a essa. Mentre lo store o il servizio di rate limiting non sono raggiungibili, o un controllo impiega più del timeout di rate limiting di Envoy, rifiuta le richieste al modello con HTTP 500, in base all’impostazione failClosed sopra, così nessuna richiesta al modello viene ammessa mentre il suo conteggio non può essere controllato.

Ciò che ne consegue è comportamento del prodotto anziché configurazione:

  • Una richiesta ammessa appena prima di un’interruzione viene comunque servita e non contata. I suoi token vengono addebitati dopo la risposta, quindi una risposta che si completa mentre lo store o il servizio non sono raggiungibili non aggiunge nulla al conteggio.
  • Uno store che tiene il conteggio in memoria fa ripartire ogni finestra quando si riavvia. core/datastore/redis tiene le sue voci in memoria per impostazione predefinita, quindi uno store riavviato perde il conteggio tenuto fino a quel momento, e il resto del mese viene contato da zero.
  • Una risposta che non riporta alcun utilizzo non aggiunge nulla. Il conteggio è ciò che riporta ciascuna risposta; Envoy AI Gateway chiede al modello di riportare il proprio utilizzo anche alla fine di una risposta in streaming.

Che cosa arresta il build

Ognuno di questi casi è una frase che il build stampa, e che nomina che cosa cambiare:

  • Un costo in dollari statunitensi. Imposta unit: usd nell’associazione e il build si arresta prima che venga renderizzato qualsiasi cosa:

    [… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars]
    [CATALOG_ERROR E0033]
    Recipe/FeatureRecipe assertions
    caused by: FeatureRecipe "period-budget-envoy-gateway" instance "edge" assertion "unit_is_a_token_count": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/period-budget attachment "budget" on "edge" asks for unit usd, but core/gateway/envoy-gateway, which declares dataplane.aggrega.ai/period-budget: tokens, counts the tokens each model's reply reports and prices nothing, so it keeps no budget in US dollars; set unit to total_tokens, prompt_tokens or completion_tokens, or attach the Feature to a gateway that counts cost
  • Un budget per chiamante, scope: caller. Il gateway distingue i chiamanti solo in base a un header che il chiamante scrive da sé, e nulla su questo percorso verifica chi sia il chiamante, quindi un chiamante che invia un nuovo valore avvierebbe un budget nuovo e uno che non ne invia alcuno non verrebbe contato.

  • Qualsiasi periodo per cui il gateway non ha una finestra. Il gateway tiene un’unità intera del suo rate limit: 1s, 1m, 1h, 1d, 7d, 30d, 365d oppure 1mo, o la stessa durata scritta in altro modo, come 24h. Con 2h, 14d o 2mo il build si arresta.

  • Un limite che non è un numero intero di token, o uno superiore a 4294967295.

  • Una seconda associazione di core/period-budget sul gateway, che scrive un unico budget sulla route che serve i suoi modelli.

  • Nulla cablato al socket models, il che non lascia alcuna route di modello da contare, o al socket cache, il che non lascia al conteggio alcun luogo in cui risiedere. Rimuovi solo la connessione del modello e ad arrestarsi per primo è il Component stesso del gateway, perché values.model nomina un alias che nulla serve.

  • Uno store sul socket cache che non parla il protocollo Redis — uno che pubblica un protocollo diverso da redis o valkey.

  • Il gateway collocato fuori da envoy-gateway-system mentre il controller è cablato al suo socket extension.

Prima di applicarlo

L’albero non contiene alcun Namespace né alcun Secret, quindi un cluster che riceve dist/helm/ ha bisogno di:

  • I namespace cert-manager, envoy-ai-gateway-system, envoy-gateway-system e assistant.
  • I Secret, in envoy-gateway-system: openai-api-key, che contiene la chiave di OpenAI sotto la chiave dati apiKey, e counter-store-password, che contiene la password dello store sotto password. Un carico di lavoro che fa riferimento a un Secret inesistente non si avvia.
  • Un apply lato server per due delle definizioni di AI Gateway, aigateway.envoyproxy.io_backendsecuritypolicies.yaml e aigateway.envoyproxy.io_mcproutes.yaml, che sono più grandi della copia dell’oggetto applicato che un apply lato client registra, quindi un apply lato client le rifiuta.
  • Un’immagine per l’agente. La Release nomina registry.example/crew-assistant:1.0.0; il catalogo confeziona il runtime dell’agente, e la crew che esegue è codice tuo.

Dove il compilatore non interpreta

Il compilatore convoglia nelle risorse del gateway il limite, l’unità e il costo in token come stringhe, e l’endpoint del modello, l’indirizzo dello store e l’indirizzo del controller a partire da ciò che ciascuno pubblica. Non raggiunge OpenAI, non sa se una risposta riporta i propri token e non conta nulla da sé; non verifica che i Secret esistano né che cert-manager sia in esecuzione. Ciascun arresto descritto sopra è dichiarato dalle entità proprie del catalogo, come un’asserzione nella realizzazione del budget o nel Component o nella Recipe del gateway, e nessuno di essi si basa su una qualche comprensione del traffico.

Adattarlo

  • Un limite per modello. Cabla altri modelli al socket models e imposta scope: model: ciascuno riceve una propria regola, e un proprio conteggio.
  • Contare un solo lato. Imposta unit: prompt_tokens per contare ciò che il modello legge, oppure completion_tokens per ciò che scrive.
  • Inviare di nuovo una richiesta non riuscita. Associa core/retry-policy al gateway con max_attempts e mappala nel Manifest su helm/retry-policy-envoy-gateway: la stessa policy di traffico, edge-models, acquisisce un retry accanto al rate limit, perché Envoy Gateway associa una sola policy di traffico a una route.
  • Una finestra più breve o di lunghezza fissa. Imposta period nella Release su una delle durate indicate sopra: 1d è un giorno a partire dalle 00:00 UTC, e 30d sono 30 giorni contati dal 1º gennaio 1970 anziché un mese di calendario. Con qualsiasi periodo diverso da 1mo la configurazione lascia non impostata l’impostazione del mese di calendario.
  • Route MCP. Il controller cifra gli identificatori di sessione MCP con una chiave derivata dal seed contenuto nel Secret che infra.mcp_session_seed_secret nomina su ai-controller; se non ne è nominato alcuno, come qui, il seed è il valore predefinito pubblicato dal suo chart, quindi nominane uno prima di servire una route MCP attraverso di esso.