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

Un gateway APISIX che mantiene i suoi modelli entro un budget di token

Un team mette due modelli OpenAI dietro un unico gateway e vuole un tetto a ciò che il gateway spende per essi ogni giorno, contato in token. Questo workspace compila un gateway del genere in manifest Kubernetes: Apache APISIX davanti ai due modelli, con core/period-budget associato.

La pagina mostra anche che cosa serve a una cache semantica da questo gateway prima che il build vada a buon fine: chiamanti che sappia distinguere, ciascuno in base alla chiave che presenta, e uno store per le risposte.

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
gatewaycore/gateway/apisixil gateway, che serve due alias: assistant, dal modello chat, e summarizer, dal modello mini
chatcore/ai-model/openaigpt-4o di OpenAI, raggiunto come riferimento: nel cluster non gira nulla per esso
minicore/ai-model/openaigpt-4o-mini di OpenAI, raggiunto allo stesso modo

Due archi uses verso il socket models del gateway, uno per ciascun modello, ognuno dei quali porta come sua credential la chiave che il gateway presenta a quel modello; entrambi leggono un unico parametro, openai_key, che la Release soddisfa. Un’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: due milioni di token al giorno.

Il Manifest mappa il gateway su apisix-chart, la realizzazione che renderizza il chart APISIX proprio del progetto, alla versione APISIX 3.18.0, e serve i modelli cablati al gateway. Con un modello cablato, il gateway legge le sue route da un file renderizzato insieme a esso, quindi non richiede alcuna connessione a etcd né alcuna chiave della Admin API; l’Aggregate non cabla né l’una né l’altra.

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 apisix-token-budget

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

Terminal window
cd apisix-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 # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

La risoluzione fissa il chart APISIX che la Recipe del gateway renderizza, scaricato dal repository del chart stesso, quindi richiede la rete. Questo workspace risolve le entità del catalogo dal registry predefinito nominato da .aggrega-config.yaml.

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

[… omitted: two warnings, one per model connection's credential, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping, the resolution's summary, a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]
Build completed: 8 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 stesso alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `apisix-token-budget`, chiama una sola volta lo strumento `scaffold` con `example` impostato su `apisix-token-budget` e senza `dir`: scrive l’esempio in una nuova cartella `apisix-token-budget`. Poi chiama lo strumento `build` con `workspace_root` impostato su `apisix-token-budget`, `release` impostato su `release.yaml`, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `apisix-token-budget/dist/`.

L’albero renderizzato

dist/helm/
├── chat-service.yaml
├── gateway--assistant-zdcredential--gateway-secret-gateway-assistant-credential.yaml
├── gateway--summarizer-zdcredential--gateway-secret-gateway-summarizer-credential.yaml
├── gateway-configmap-default-gateway.yaml
├── gateway-deployment-default-gateway.yaml
├── gateway-service-default-gateway-gateway.yaml
├── mini-service.yaml
└── gateway/
└── model-routes.yaml

Il budget non porta alcun file proprio. Ciò che fa è scritto nel file delle route, dist/helm/gateway/model-routes.yaml, una ConfigMap che il gateway monta e da cui legge l’intera configurazione di instradamento. Ogni modello renderizza un file, un Service che mappa un nome interno al cluster sull’host dell’API di OpenAI, e ogni credenziale su una connessione a un modello renderizza un proprio Secret, che prende il nome dal gateway e dall’alias della connessione.

Il budget, come lo legge il gateway

Ecco la chiave apisix.yaml di quella ConfigMap:

services:
- id: "model-budget"
plugins:
ai-rate-limiting:
limit: 2000000
time_window: 86400
limit_strategy: "total_tokens"
routes:
- id: "model-assistant-chat"
uri: "/assistant/v1/chat/completions"
service_id: "model-budget"
methods:
- POST
plugins:
ai-proxy:
provider: openai-compatible
auth:
header:
Authorization: "$env://AI_PROXY_ASSISTANT_AUTHORIZATION"
options:
model: "gpt-4o"
override:
endpoint: "https://api.openai.com/v1/chat/completions"
- id: "model-summarizer-chat"
uri: "/summarizer/v1/chat/completions"
service_id: "model-budget"
[… omitted: the same route for gpt-4o-mini, presenting AI_PROXY_SUMMARIZER_AUTHORIZATION]
#END

Cinque cose meritano di essere lette da esso.

Il budget si trova su un servizio che entrambe le route nominano. Il rate limiting dei token di APISIX, ai-rate-limiting, tiene il proprio conteggio sotto l’oggetto su cui è dichiarato. Scritto su ciascuna route, terrebbe un conteggio per route; scritto una sola volta su model-budget, che ogni route nomina tramite service_id, tiene un unico conteggio per tutto ciò che il gateway serve — l’ambito gateway richiesto dall’associazione. Con scope: model la Recipe scrive invece un servizio per connessione, model-assistant-budget e model-summarizer-budget, così ogni modello ha un proprio limite.

Il periodo è una finestra di secondi. 1d viene scritto come 86400. La finestra si apre con la prima richiesta al modello dopo la chiusura della finestra precedente e dura altrettanto; non inizia a mezzanotte. Un mese di calendario non ha un numero fisso di secondi, quindi 1mo viene rifiutato, come si vede più sotto.

L’unità è ciò che viene contato. total_tokens sono i token che la risposta di ciascun modello riporta di aver letto e scritto insieme; prompt_tokens e completion_tokens contano un solo lato. Il gateway conta ciò che la risposta riporta e non attribuisce un prezzo a nulla, quindi non tiene alcun budget in dollari statunitensi.

Ogni modello ha una route di chat e nessuna route di completion. Senza il budget, ogni alias riceve anche /<alias>/v1/completions. APISIX legge i token di una risposta solo da una richiesta di cui riconosce il protocollo, e una richiesta di completion, il cui corpo porta un prompt anziché messages, non lo è: riceverebbe risposta e non verrebbe mai contata. Così, mentre il budget è associato, quella route non viene scritta, e a una richiesta di completion si risponde 404 Route Not Found.

Non contiene alcuna chiave. Ogni route nomina la variabile che contiene il bearer token della sua connessione tramite il riferimento $env:// di APISIX. Da dist/helm/gateway-deployment-default-gateway.yaml, l’env del container del gateway:

env:
- name: AI_PROXY_ASSISTANT_API_KEY
valueFrom:
secretKeyRef:
key: api-key
name: gateway-assistant.credential
- name: AI_PROXY_ASSISTANT_AUTHORIZATION
value: Bearer $(AI_PROXY_ASSISTANT_API_KEY)
[… omitted: the same two variables for summarizer]

Lo stesso Deployment esegue una sola replica, replicas: 1. Il conteggio è tenuto nella memoria del processo del gateway, quindi una seconda replica terrebbe un proprio conteggio; mentre è associato un budget, la Recipe mantiene il chart a una replica.

Che cosa fa il gateway in fase di esecuzione

A ogni richiesta al modello il gateway confronta il conteggio con limit. Una volta che il conteggio lo ha raggiunto, il gateway risponde 503 Service Temporarily Unavailable fino alla chiusura della finestra, senza che la richiesta venga mai inviata al modello; la risposta porta gli header propri del gateway X-AI-RateLimit-Limit-…, X-AI-RateLimit-Remaining-… e X-AI-RateLimit-Reset-…. I token di una richiesta vengono aggiunti quando la sua risposta si completa, quindi la richiesta che porta il conteggio al limite viene servita, e così anche qualsiasi richiesta già in corso accanto a essa.

Ne seguono due conseguenze, ed entrambe sono comportamento del gateway anziché configurazione:

  • Un riavvio apre una nuova finestra. Il conteggio risiede nella memoria del processo del gateway, quindi un pod aggiornato o riavviato ricomincia a contare da zero.
  • Una risposta che non riporta token non conta nulla. Il conteggio è ciò che ciascun modello riporta; il gateway chiede a una richiesta di chat in streaming di riportare il proprio utilizzo, e un modello che non ne riporta alcuno non aggiunge nulla.

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-apisix" instance "gateway" 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 "gateway" asks for unit usd, but core/gateway/apisix, 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, mentre la Release non dichiara alcun chiamante. Il gateway distingue i chiamanti in base alla chiave che ciascuno presenta, e senza infra.callers ogni route è aperta. Con i chiamanti dichiarati, come nella sezione successiva, ciascuno ha un proprio conteggio su tutte le route.

  • Un mese di calendario, period: 1mo, e un limite che non è un numero intero di token.

  • Una seconda associazione di core/period-budget sul gateway, che esegue un unico rate limit dei token su una route.

  • Nulla cablato al socket models, il che non lascia alcuna route di modello da contare. Rimuovi solo le due connessioni e ad arrestarsi per primo è il Component stesso del gateway, che chiede lo store etcd e la chiave della Admin API attraverso cui un gateway senza modelli mantiene le sue route.

  • L’altra realizzazione. Mappa core/gateway/apisix su helm/apisix nel Manifest e il build si arresta sulle connessioni models, nominando helm/apisix-chart: quella realizzazione esegue APISIX 3.17.0 con le sue route in etcd e non ne renderizza alcuna. Si arresta anche su un’associazione di budget, poiché non ha alcuna route su cui scriverne una e, alla 3.17.0, ogni processo del gateway conta per conto proprio.

Una cache semantica ha bisogno di chiamanti

APISIX 3.18.0 include una cache semantica, e core/semantic-caching si associa a questo gateway. Aggiungine un’associazione alle features del gateway in aggregate.yaml:

answers:
type: core/semantic-caching
values:
embedding_model: assistant
similarity_threshold: 0.9
ttl_seconds: 3600

Il Manifest instrada già la Feature verso la sua realizzazione APISIX, e il build si arresta:

[… 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 "semantic-caching-apisix" instance "gateway" assertion "scope_is_one_the_gateway_keeps": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "gateway" asks for scope end_user, which keeps each end user the gateway identifies apart, but core/gateway/apisix tells its callers apart only by the key each presents, and cannot tell apart the end users behind one key: a value a request names for one is whatever the caller sent, which the gateway does not verify. Set scope to key, which keeps each caller infra.callers declares apart, or attach the Feature to a gateway that identifies end users

Una cache conserva una risposta per chiunque chieda in seguito qualcosa di abbastanza simile, quindi chi condivide una cache decide a chi può essere servita una risposta generata per qualcun altro. Questo gateway può tenere separato ciascun chiamante in base alla chiave che presenta, che verifica, e nulla di più fine: imposta scope: key e il build si arresta di nuovo, ora sui chiamanti che non gli sono stati forniti:

[… 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 "semantic-caching-apisix" instance "gateway" assertion "callers_are_declared": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "gateway" asks for scope key, but infra.callers of "gateway" declares no caller, so the gateway authenticates no key and every request on a route would share one cache, a reply generated for one caller served to another; declare the callers in infra.callers, with their keys through the caller_keys slot

Tre aggiunte permettono al build di andare a buon fine. La Release nomina i chiamanti e le loro chiavi:

gateway:
infra:
callers: [support-agent, billing-agent]
features:
caller_keys:
type: core/referenced-secret-set
infra:
entries:
- key: support-agent
value: support-agent-key-change-me
- key: billing-agent
value: billing-agent-key-change-me
budget:
[… omitted: the budget's size, as above]

L’Aggregate cabla il modello con cui la cache trasforma ogni prompt in un vettore e uno store Redis per le risposte, e nomina il modello di embedding nell’associazione come embedding_model: embedder, con scope: key:

models:
[… omitted: assistant and summarizer, as above]
embedder:
target: embeddings
features:
credential:
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.openai_key }}"
cache_store:
replies:
target: cache

con il componente embeddings (core/ai-model/openai-embedding, con il suo values.model impostato a text-embedding-3-small) e il componente cache (core/datastore/redis) dichiarati accanto ai modelli, ciascuno collocato nella Release, e il Manifest che mappa entrambi, e core/referenced-secret-set sulla sua realizzazione Kubernetes, helm/k8s-secret-set, che scrive le chiavi direttamente in un Secret renderizzato e quindi è adatta solo a una destinazione di sviluppo. Il file delle route dichiara poi ciascun chiamante e ne verifica la chiave su ogni route, e la route di chat porta la cache:

consumers:
- username: "support-agent"
plugins:
key-auth:
key: "$env://CALLER_SUPPORT_AGENT_AUTHORIZATION"
[… omitted: billing-agent, the same way]
routes:
- id: "model-assistant-chat"
uri: "/assistant/v1/chat/completions"
service_id: "model-budget"
methods:
- POST
plugins:
key-auth:
header: Authorization
hide_credentials: true
ai-proxy:
[… omitted: the route to gpt-4o, as above]
ai-cache:
layers:
- exact
- semantic
exact:
ttl: 3600
cache_key:
share_across_routes: false
include_consumer: true
policy: redis
redis_host: "cache-default"
redis_port: 6379
semantic:
similarity_threshold: 0.9
ttl: 3600
embedding:
openai:
endpoint: "https://api.openai.com/v1/embeddings"
model: "text-embedding-3-small"
api_key: "$env://AI_PROXY_EMBEDDER_API_KEY"
vector_search:
redis:
index: "gateway-answers"
[… omitted: the same for the other connections]

Non contiene la chiave di alcun chiamante: ogni consumer nomina una variabile che il Deployment riempie dal Secret renderizzato dall’associazione caller_keys, sotto il nome proprio del chiamante, e la compone nell’header completo:

- name: CALLER_SUPPORT_AGENT_KEY
valueFrom:
secretKeyRef:
key: support-agent
name: gateway-caller-keys
- name: CALLER_SUPPORT_AGENT_AUTHORIZATION
value: Bearer $(CALLER_SUPPORT_AGENT_KEY)
[… omitted: the same two variables for billing-agent]

In fase di esecuzione una richiesta che non presenta alcuna chiave dichiarata, come Authorization: Bearer <key>, viene rifiutata con HTTP 401, e la chiave viene rimossa dalla richiesta che il gateway inoltra. Una risposta viene memorizzata sotto la route e il chiamante, quindi a un prompt riformulato di un chiamante viene servita la risposta memorizzata per quel chiamante e mai una memorizzata per un altro. Una risposta servita dalla cache non conta nulla ai fini del budget, e viene servita anche oltre il suo limite. La connessione embedder riceve route proprie, come ogni connessione sul socket models.

Dove il compilatore non interpreta

Il compilatore convoglia nel file delle route il limite, la finestra e l’unità come stringhe, e l’endpoint e il nome di ciascun modello a partire da ciò che quel modello pubblica. Non raggiunge OpenAI, non sa se una risposta riporta i propri token e non conta nulla da sé. Ciascun arresto descritto sopra è dichiarato dalle entità proprie del catalogo, come un’asserzione nella realizzazione del budget o della cache o nell’altra Recipe del gateway, e nessuno di essi si basa su una qualche comprensione del traffico.

Adattarlo

  • Un limite per modello. Imposta scope: model: ogni alias riceve un proprio servizio, e un proprio conteggio.
  • Un limite per chiamante. Dichiara i chiamanti e le loro chiavi nella Release, come in «Una cache semantica ha bisogno di chiamanti» più sopra, e imposta scope: caller: ogni chiamante riceve un proprio conteggio su tutte le route.
  • Contare un solo lato. Imposta unit: prompt_tokens per contare ciò che i modelli leggono, oppure completion_tokens per ciò che scrivono.
  • Una finestra più breve o più lunga. Imposta period nella Release a un numero di secondi, minuti, ore o giorni, come in 6h o 30d.