Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

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

InstanzKatalog-Componentwas es hier ist
gatewaycore/gateway/apisixdas Gateway, das zwei Aliase bedient: assistant, aus dem Modell chat, und summarizer, aus dem Modell mini
chatcore/ai-model/openaiOpenAIs gpt-4o, als Referenz erreicht: Im Cluster läuft dafür nichts
minicore/ai-model/openaiOpenAIs 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:

Terminal window
aggrega scaffold --example apisix-token-budget

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd apisix-token-budget

Build

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

Ein 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:

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

Das 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>/dist

Mit 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.yaml

Das 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]
#END

Fü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: usd in 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 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
  • 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 ohne infra.callers ist 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 models verdrahtet, 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/apisix helm/apisix zu, und der Build bricht bei den models-Verbindungen ab und nennt helm/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: 3600

Das 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 users

Ein 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 slot

Mit 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: cache

wobei 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, oder completion_tokens für das, was sie schreiben.
  • Ein kürzeres oder längeres Fenster. Setzen Sie period im Release auf eine Anzahl von Sekunden, Minuten, Stunden oder Tagen, etwa 6h oder 30d.