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
| istanza | Component del catalogo | che cosa è qui |
|---|---|---|
gateway | core/gateway/apisix | il gateway, che serve due alias: assistant, dal modello chat, e summarizer, dal modello mini |
chat | core/ai-model/openai | gpt-4o di OpenAI, raggiunto come riferimento: nel cluster non gira nulla per esso |
mini | core/ai-model/openai | gpt-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:
aggrega scaffold --example apisix-token-budgetPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd apisix-token-budgetBuild
aggrega build --release release.yaml --auto-pullUna 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:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildLa 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>/distCon 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.yamlIl 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]#ENDCinque 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: usdnell’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 assertionscaused 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 senzainfra.callersogni 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-budgetsul 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/apisixsuhelm/apisixnel Manifest e il build si arresta sulle connessionimodels, nominandohelm/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: 3600Il 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 usersUna 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 slotTre 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: cachecon 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_tokensper contare ciò che i modelli leggono, oppurecompletion_tokensper ciò che scrivono. - Una finestra più breve o più lunga. Imposta
periodnella Release a un numero di secondi, minuti, ore o giorni, come in6ho30d.