Ein APISIX-Gateway, das seine Modelle an ein Token-Budget hält
Ein Team stellt zwei OpenAI-Modelle hinter ein Gateway und möchte eine Obergrenze dafür, was das Gateway jeden Tag für sie ausgibt, gezählt in Tokens. Dieser Workspace kompiliert ein solches Gateway zu Kubernetes-Manifesten: Apache APISIX vor den beiden Modellen, mit angebundenem core/period-budget.
Die Seite zeigt auch, was ein semantischer Cache von diesem Gateway braucht, bevor er sich bauen lässt: Aufrufer, die es auseinanderhalten kann, jeden anhand des Schlüssels, den er vorlegt, und einen Store für die Antworten.
Dieser Workspace schreibt keine eigene Katalogentität. Die drei Entitätsdateien hier — ein Aggregate, ein Manifest und ein Release — sind alles, was irgendjemand schreibt.
Was es baut
| Instanz | Katalog-Component | was es hier ist |
|---|---|---|
gateway | core/gateway/apisix | das Gateway, das zwei Aliase bedient: assistant, aus dem Modell chat, und summarizer, aus dem Modell mini |
chat | core/ai-model/openai | OpenAIs gpt-4o, als Referenz erreicht: Im Cluster läuft dafür nichts |
mini | core/ai-model/openai | OpenAIs gpt-4o-mini, auf dieselbe Weise erreicht |
Zwei uses-Kanten in den Socket models des Gateways, eine zu jedem Modell, jede mit dem Schlüssel als ihrem credential, den das Gateway diesem Modell vorlegt; beide lesen einen Parameter, openai_key, den das Release erfüllt. Eine Feature-Anbindung am Gateway, budget: Das Aggregate schreibt, was gezählt wird, total_tokens, und wessen Datenverkehr ein Limit abdeckt, gateway — alles, was das Gateway bedient —, und das Release schreibt, wie viel und über welchen Zeitraum: zwei Millionen Tokens pro Tag.
Das Manifest ordnet das Gateway apisix-chart zu, der Realisierung, die das eigene APISIX-Chart des Projekts in APISIX 3.18.0 rendert und die mit dem Gateway verdrahteten Modelle bedient. Mit einem verdrahteten Modell liest das Gateway seine Routen aus einer mit ihm gerenderten Datei, daher braucht es keine etcd-Verbindung und keinen Admin-API-Schlüssel; das Aggregate verdrahtet keines von beiden.
Das Beispiel generieren
Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example apisix-token-budgetDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd apisix-token-budgetBuild
aggrega build --release release.yaml --auto-pullEin Release braucht ein Lockfile, bevor es baut, und Lockfiles werden erzeugt statt mitgeliefert, daher hat ein frischer Klon keines. Lösen Sie zuerst eines auf, oder lassen Sie den Build es füllen:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildDas Auflösen heftet das APISIX-Chart an, das das Recipe des Gateways rendert, abgerufen aus dem eigenen Repository des Charts, daher braucht es das Netzwerk. Dieser Workspace löst die Katalogentitäten aus der Standard-Registry auf, die .aggrega-config.yaml nennt.
Der Build gibt aus, wobei <workspace> für den Ordner dieses Beispiels steht:
[… 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>/distMit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.
Verwenden Sie nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `apisix-token-budget` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `apisix-token-budget` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `apisix-token-budget`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `apisix-token-budget`, `release` auf `release.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `apisix-token-budget/dist/`.Der gerenderte Baum
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.yamlDas Budget bringt keine eigene Datei mit. Was es tut, wird in die Routen-Datei geschrieben, dist/helm/gateway/model-routes.yaml, eine ConfigMap, die das Gateway einhängt und aus der es seine gesamte Routing-Konfiguration liest. Jedes Modell rendert eine Datei, einen Service, der einen clusterinternen Namen auf den API-Host von OpenAI abbildet, und jede Zugangsdaten-Angabe an einer Modellverbindung rendert ein eigenes Secret, benannt nach dem Gateway und dem Alias der Verbindung.
Das Budget, wie das Gateway es liest
Hier ist der Schlüssel apisix.yaml dieser 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]#ENDFünf Dinge lohnt es sich daraus abzulesen.
Das Budget sitzt auf einem Service, den beide Routen nennen. Die Token-Ratenbegrenzung von APISIX, ai-rate-limiting, führt ihre Zählung unter dem Objekt, auf dem sie deklariert ist. Auf jede Route geschrieben, würde sie eine Zählung pro Route führen; einmal auf model-budget geschrieben, das jede Route über service_id nennt, führt sie eine Zählung für alles, was das Gateway bedient — den Geltungsbereich gateway, den die Anbindung angefordert hat. Mit scope: model schreibt das Recipe stattdessen einen Service pro Verbindung, model-assistant-budget und model-summarizer-budget, sodass jedes Modell ein eigenes Limit hat.
Der Zeitraum ist ein Fenster in Sekunden. 1d wird als 86400 geschrieben. Das Fenster öffnet sich mit der ersten Modellanfrage nach dem Schließen des vorherigen Fensters und dauert so lange; es beginnt nicht um Mitternacht. Ein Kalendermonat hat keine feste Anzahl von Sekunden, daher wird 1mo zurückgewiesen, wie unten gezeigt.
Die Einheit ist das, was gezählt wird. total_tokens sind die Tokens, die die Antwort jedes Modells als zusammen gelesen und geschrieben meldet; prompt_tokens und completion_tokens zählen eine Seite. Das Gateway zählt, was die Antwort meldet, und bepreist nichts, daher führt es kein Budget in US-Dollar.
Jedes Modell hat eine Chat-Route und keine Completion-Route. Ohne das Budget erhält jeder Alias außerdem /<alias>/v1/completions. APISIX liest die Tokens einer Antwort nur aus einer Anfrage, deren Protokoll es erkennt, und eine Completion-Anfrage, deren Body ein prompt statt messages trägt, ist keine solche: Sie würde beantwortet und nie gezählt. Solange das Budget angebunden ist, wird diese Route daher nicht geschrieben, und eine Completion-Anfrage wird mit 404 Route Not Found beantwortet.
Kein Schlüssel steht darin. Jede Route nennt die Variable, die das Bearer-Token ihrer Verbindung hält, über die $env://-Referenz von APISIX. Aus dist/helm/gateway-deployment-default-gateway.yaml, das env des Containers des Gateways:
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]Dasselbe Deployment betreibt ein Replikat, replicas: 1. Die Zählung wird im Speicher des Gateway-Prozesses gehalten, daher würde ein zweites Replikat eine eigene Zählung führen; solange ein Budget angebunden ist, hält das Recipe das Chart auf einem.
Was das Gateway zur Laufzeit tut
Bei jeder Modellanfrage prüft das Gateway die Zählung gegen limit. Sobald die Zählung es erreicht hat, antwortet das Gateway mit 503 Service Temporarily Unavailable, bis sich das Fenster schließt, ohne dass die Anfrage je an das Modell gesendet wird; die Antwort trägt die eigenen Header des Gateways X-AI-RateLimit-Limit-…, X-AI-RateLimit-Remaining-… und X-AI-RateLimit-Reset-…. Die Tokens einer Anfrage werden addiert, wenn ihre Antwort abgeschlossen ist, daher wird die Anfrage, die die Zählung auf das Limit bringt, bedient, ebenso jede Anfrage, die bereits daneben läuft.
Daraus folgen zwei Konsequenzen, und beide sind Verhalten des Gateways, keine Konfiguration:
- Ein Neustart beginnt ein neues Fenster. Die Zählung lebt im Speicher des Gateway-Prozesses, daher beginnt ein neu ausgerollter oder neu gestarteter Pod wieder bei null zu zählen.
- Eine Antwort, die keine Tokens meldet, zählt nichts. Die Zählung ist das, was jedes Modell meldet; das Gateway bittet eine gestreamte Chat-Anfrage, ihre Nutzung zu melden, und ein Modell, das keine meldet, addiert nichts.
Was den Build abbricht
Jeder dieser Fälle ist ein Satz, den der Build ausgibt und der nennt, was zu ändern ist:
-
Kosten in US-Dollar. Setzen Sie
unit: usdin der Anbindung, und der Build bricht ab, bevor irgendetwas gerendert wird:[… 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 -
Ein Budget pro Aufrufer,
scope: caller, während das Release keine Aufrufer deklariert. Das Gateway unterscheidet Aufrufer anhand des Schlüssels, den jeder vorlegt, und ohneinfra.callersist jede Route offen. Mit deklarierten Aufrufern, wie im nächsten Abschnitt, hat jeder eine eigene Zählung über alle Routen hinweg. -
Ein Kalendermonat,
period: 1mo, und ein Limit, das keine ganze Zahl von Tokens ist. -
Eine zweite
core/period-budget-Anbindung am Gateway, das auf einer Route nur eine Token-Ratenbegrenzung ausführt. -
Nichts mit dem Socket
modelsverdrahtet, was keine Modellroute zum Zählen übrig lässt. Entfernen Sie nur die beiden Verbindungen, und zuerst bricht die eigene Component des Gateways ab und verlangt den etcd-Store und den Admin-API-Schlüssel, über die ein Gateway ohne Modell seine Routen führt. -
Die andere Realisierung. Ordnen Sie im Manifest
core/gateway/apisixhelm/apisixzu, und der Build bricht bei denmodels-Verbindungen ab und nennthelm/apisix-chart: Diese Realisierung betreibt APISIX 3.17.0 mit ihren Routen in etcd und rendert keine. Sie bricht auch bei einer Budget-Anbindung ab, da sie keine Route hat, auf die sie eine schreiben könnte, und in 3.17.0 jeder Gateway-Prozess für sich zählt.
Ein semantischer Cache braucht Aufrufer
APISIX 3.18.0 bringt einen semantischen Cache mit, und core/semantic-caching lässt sich an dieses Gateway anbinden. Fügen Sie eine solche Anbindung zu den features des Gateways in aggregate.yaml hinzu:
answers: type: core/semantic-caching values: embedding_model: assistant similarity_threshold: 0.9 ttl_seconds: 3600Das Manifest leitet das Feature bereits an seine APISIX-Realisierung weiter, und der Build bricht ab:
[… 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 usersEin Cache bewahrt eine Antwort für jeden auf, der später etwas hinreichend Ähnliches fragt, daher entscheidet, wer sich einen Cache teilt, darüber, wem eine für jemand anderen erzeugte Antwort ausgeliefert werden kann. Dieses Gateway kann jeden Aufrufer anhand des Schlüssels auseinanderhalten, den er vorlegt und den es prüft, und nichts Feineres: Setzen Sie scope: key, und der Build bricht erneut ab, diesmal wegen der Aufrufer, die ihm nicht übergeben wurden:
[… 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 slotMit drei Ergänzungen lässt es sich bauen. Das Release nennt die Aufrufer und ihre Schlüssel:
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]Das Aggregate verdrahtet das Modell, mit dem der Cache jeden Prompt in einen Vektor umwandelt, und einen Redis-Store für die Antworten, und nennt das Embedding-Modell in der Anbindung als embedding_model: embedder, mit 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: cachewobei die Komponente embeddings (core/ai-model/openai-embedding, ihr values.model auf text-embedding-3-small gesetzt) und die Komponente cache (core/datastore/redis) neben den Modellen deklariert und jeweils im Release platziert sind und das Manifest beide zuordnet sowie core/referenced-secret-set seiner Kubernetes-Realisierung helm/k8s-secret-set, die die Schlüssel direkt in ein gerendertes Secret schreibt und sich daher nur für ein Entwicklungsziel eignet. Die Routen-Datei deklariert dann jeden Aufrufer und prüft seinen Schlüssel auf jeder Route, und die Chat-Route trägt den 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]Kein Schlüssel eines Aufrufers steht darin: Jeder Consumer nennt eine Variable, die das Deployment aus dem Secret befüllt, das die Anbindung caller_keys rendert, unter dem eigenen Namen des Aufrufers, und setzt sie zum vollständigen Header zusammen:
- 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]Zur Laufzeit wird eine Anfrage, die keinen deklarierten Schlüssel vorlegt, als Authorization: Bearer <key>, mit HTTP 401 abgewiesen, und der Schlüssel wird aus der Anfrage entfernt, die das Gateway weiterleitet. Eine Antwort wird unter der Route und dem Aufrufer gespeichert, sodass der umformulierte Prompt eines Aufrufers die für diesen Aufrufer gespeicherte Antwort erhält und nie eine für einen anderen gespeicherte. Eine aus dem Cache ausgelieferte Antwort zählt nichts zum Budget und wird auch über sein Limit hinaus ausgeliefert. Die Verbindung embedder erhält eigene Routen, wie jede Verbindung am Socket models.
Wo der Compiler nicht interpretiert
Der Compiler leitet das Limit, das Fenster und die Einheit als Strings in die Routen-Datei weiter, und den Endpunkt und den Modellnamen jedes Modells aus dem, was dieses Modell veröffentlicht. Er erreicht OpenAI nicht, weiß nicht, ob eine Antwort ihre Tokens meldet, und zählt selbst nichts. Jeder Abbruch oben wird von den eigenen Entitäten des Katalogs deklariert, als Assertion in der Realisierung des Budgets oder des Caches oder im anderen Recipe des Gateways, und keiner davon beruht auf irgendeinem Verständnis des Datenverkehrs.
Anpassen
- Ein Limit pro Modell. Setzen Sie
scope: model: Jeder Alias erhält einen eigenen Service und eine eigene Zählung. - Ein Limit pro Aufrufer. Deklarieren Sie die Aufrufer und ihre Schlüssel im Release, wie oben in „Ein semantischer Cache braucht Aufrufer“, und setzen Sie
scope: caller: Jeder Aufrufer erhält eine eigene Zählung über alle Routen hinweg. - Eine Seite zählen. Setzen Sie
unit: prompt_tokens, um zu zählen, was die Modelle lesen, odercompletion_tokensfür das, was sie schreiben. - Ein kürzeres oder längeres Fenster. Setzen Sie
periodim Release auf eine Anzahl von Sekunden, Minuten, Stunden oder Tagen, etwa6hoder30d.