Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Une passerelle APISIX qui tient ses modèles à un budget de tokens

Une équipe place deux modèles OpenAI derrière une seule passerelle et veut un plafond sur ce que la passerelle dépense pour eux chaque jour, compté en tokens. Ce workspace compile une telle passerelle en manifestes Kubernetes : Apache APISIX devant les deux modèles, avec core/period-budget rattaché.

La page montre aussi ce dont un cache sémantique a besoin de la part de cette passerelle avant que le build aboutisse : des appelants qu’elle sait distinguer, chacun par la clé qu’il présente, et un magasin pour les réponses.

Ce workspace ne rédige aucune entité de catalogue qui lui soit propre. Les trois fichiers d’entité présents ici — un Aggregate, un Manifest et une Release — sont tout ce que quiconque écrit.

Ce qu’il construit

instanceComponent du cataloguece qu’il est ici
gatewaycore/gateway/apisixla passerelle, qui sert deux alias : assistant, issu du modèle chat, et summarizer, issu du modèle mini
chatcore/ai-model/openaile gpt-4o d’OpenAI, atteint comme référence : rien ne s’exécute pour lui dans le cluster
minicore/ai-model/openaile gpt-4o-mini d’OpenAI, atteint de la même manière

Deux arêtes uses vers le socket models de la passerelle, une vers chaque modèle, chacune portant comme credential la clé que la passerelle présente à ce modèle ; toutes deux lisent un même paramètre, openai_key, que la Release satisfait. Un rattachement de Feature sur la passerelle, budget : l’Aggregate écrit ce qui est compté, total_tokens, et le trafic de qui une limite couvre, gateway — tout ce que sert la passerelle — et la Release écrit combien et sur quelle durée : deux millions de tokens par jour.

Le Manifest associe la passerelle à apisix-chart, la réalisation qui rend le chart APISIX propre au projet, en APISIX 3.18.0, et sert les modèles câblés à la passerelle. Avec un modèle câblé, la passerelle lit ses routes depuis un fichier rendu avec elle, si bien qu’elle ne prend aucune connexion etcd ni aucune clé d’Admin API ; l’Aggregate ne câble ni l’une ni l’autre.

Générer l’exemple

Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

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

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd apisix-token-budget

Build

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

Une release a besoin d’un lockfile avant son build, et les lockfiles sont générés plutôt que livrés, de sorte qu’un clone neuf n’en contient aucun. Résolvez-en un d’abord, ou laissez le build le remplir :

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 résolution épingle le chart APISIX que rend la Recipe de la passerelle, récupéré depuis le dépôt propre au chart, si bien qu’elle a besoin du réseau. Ce workspace résout les entités du catalogue depuis le registre par défaut que nomme .aggrega-config.yaml.

Le build affiche, <workspace> désignant le dossier de cet exemple :

[… 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

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.

Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `apisix-token-budget`, appelez une seule fois l’outil `scaffold` avec `example` défini sur `apisix-token-budget` et sans `dir` : il écrit l’exemple dans un nouveau dossier `apisix-token-budget`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `apisix-token-budget`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `apisix-token-budget/dist/`.

L’arborescence rendue

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

Le budget n’apporte aucun fichier à lui. Ce qu’il fait est écrit dans le fichier des routes, dist/helm/gateway/model-routes.yaml, une ConfigMap que la passerelle monte et depuis laquelle elle lit toute sa configuration de routage. Chaque modèle rend un fichier, un Service qui associe un nom interne au cluster à l’hôte de l’API d’OpenAI, et chaque information d’identification sur une connexion de modèle rend un Secret qui lui est propre, nommé d’après la passerelle et l’alias de la connexion.

Le budget, tel que la passerelle le lit

Voici la clé apisix.yaml de cette 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

Cinq choses méritent d’y être lues.

Le budget se trouve sur un service que nomment les deux routes. La limitation de débit en tokens d’APISIX, ai-rate-limiting, tient son compteur sous l’objet sur lequel elle est déclarée. Écrite sur chaque route, elle tiendrait un compteur par route ; écrite une seule fois sur model-budget, que chaque route nomme via service_id, elle tient un seul compteur pour tout ce que sert la passerelle — la portée gateway que le rattachement a demandée. Avec scope: model, la Recipe écrit à la place un service par connexion, model-assistant-budget et model-summarizer-budget, si bien que chaque modèle a une limite qui lui est propre.

La période est une fenêtre en secondes. 1d s’écrit 86400. La fenêtre s’ouvre avec la première requête de modèle après la fermeture de la fenêtre précédente et dure ce temps-là ; elle ne commence pas à minuit. Un mois calendaire n’a pas de nombre fixe de secondes, si bien que 1mo est refusé, comme ci-dessous.

L’unité est ce qui est compté. total_tokens correspond aux tokens que la réponse de chaque modèle déclare avoir lus et écrits ensemble ; prompt_tokens et completion_tokens comptent un seul côté. La passerelle compte ce que la réponse déclare et ne met de prix sur rien, si bien qu’elle ne tient aucun budget en dollars américains.

Chaque modèle a une route de chat et aucune route de complétion. Sans le budget, chaque alias reçoit aussi /<alias>/v1/completions. APISIX ne lit les tokens d’une réponse que depuis une requête dont il reconnaît le protocole, et une requête de complétion, dont le corps porte un prompt plutôt que des messages, n’en est pas une : elle recevrait une réponse et ne serait jamais comptée. Ainsi, tant que le budget est rattaché, cette route n’est pas écrite, et une requête de complétion reçoit la réponse 404 Route Not Found.

Aucune clé n’y figure. Chaque route nomme la variable contenant le bearer token de sa connexion via la référence $env:// d’APISIX. Depuis dist/helm/gateway-deployment-default-gateway.yaml, l’env du conteneur de la passerelle :

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]

Le même Deployment exécute une seule réplique, replicas: 1. Le compteur est tenu dans la mémoire du processus de la passerelle, si bien qu’une seconde réplique tiendrait son propre compteur ; tant qu’un budget est rattaché, la Recipe maintient le chart à une réplique.

Ce que fait la passerelle à l’exécution

À chaque requête de modèle, la passerelle compare le compteur à limit. Une fois que le compteur l’a atteinte, la passerelle répond 503 Service Temporarily Unavailable jusqu’à la fermeture de la fenêtre, sans que la requête soit jamais envoyée au modèle ; la réponse porte les en-têtes propres à la passerelle X-AI-RateLimit-Limit-…, X-AI-RateLimit-Remaining-… et X-AI-RateLimit-Reset-…. Les tokens d’une requête sont ajoutés lorsque sa réponse se termine, si bien que la requête qui porte le compteur à la limite est servie, tout comme toute requête déjà en cours à côté d’elle.

Il en découle deux conséquences, et toutes deux relèvent du comportement de la passerelle plutôt que de la configuration :

  • Un redémarrage ouvre une nouvelle fenêtre. Le compteur vit dans la mémoire du processus de la passerelle, si bien qu’un pod remplacé ou redémarré recommence à compter à partir de zéro.
  • Une réponse qui ne déclare aucun token ne compte rien. Le compteur correspond à ce que déclare chaque modèle ; la passerelle demande à une requête de chat en streaming de déclarer son utilisation, et un modèle qui n’en déclare aucune n’ajoute rien.

Ce qui arrête le build

Chacun de ces cas est une phrase qu’affiche le build, nommant ce qu’il faut changer :

  • Un coût en dollars américains. Définissez unit: usd dans le rattachement et le build s’arrête avant que quoi que ce soit ne soit rendu :

    [… 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 par appelant, scope: caller, alors que la Release ne déclare aucun appelant. La passerelle distingue les appelants par la clé que chacun présente, et sans infra.callers chaque route est ouverte. Avec des appelants déclarés, comme dans la section suivante, chacun a son propre compteur sur toutes les routes.

  • Un mois calendaire, period: 1mo, et une limite qui n’est pas un nombre entier de tokens.

  • Un second rattachement de core/period-budget sur la passerelle, qui n’exécute qu’une seule limite de débit en tokens par route.

  • Rien de câblé au socket models, ce qui ne laisse aucune route de modèle à compter. Retirez seulement les deux connexions, et c’est le Component propre à la passerelle qui s’arrête en premier, en demandant le magasin etcd et la clé d’Admin API par lesquels une passerelle sans modèle tient ses routes.

  • L’autre réalisation. Associez core/gateway/apisix à helm/apisix dans le Manifest et le build s’arrête sur les connexions models, en nommant helm/apisix-chart : cette réalisation exécute APISIX 3.17.0 avec ses routes dans etcd et n’en rend aucune. Elle s’arrête aussi sur un rattachement de budget, puisqu’elle n’a aucune route sur laquelle en écrire un et que, en 3.17.0, chaque processus de passerelle compte de son côté.

Un cache sémantique a besoin d’appelants

APISIX 3.18.0 intègre un cache sémantique, et core/semantic-caching se rattache à cette passerelle. Ajoutez-en un aux features de la passerelle dans aggregate.yaml :

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

Le Manifest achemine déjà la Feature vers sa réalisation APISIX, et le build s’arrête :

[… 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

Un cache conserve une réponse pour quiconque demande plus tard quelque chose d’assez proche, si bien que savoir qui partage un cache décide de qui peut se voir servir une réponse générée pour quelqu’un d’autre. Cette passerelle peut séparer chaque appelant par la clé qu’il présente, qu’elle vérifie, et rien de plus fin : définissez scope: key et le build s’arrête de nouveau, cette fois sur les appelants qui ne lui ont pas été donnés :

[… 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

Trois ajouts permettent au build d’aboutir. La Release nomme les appelants et leurs clés :

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 câble le modèle avec lequel le cache transforme chaque prompt en vecteur, ainsi qu’un magasin Redis pour les réponses, et nomme le modèle d’embeddings dans le rattachement sous la forme embedding_model: embedder, avec 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

avec le composant embeddings (core/ai-model/openai-embedding, son values.model défini à text-embedding-3-small) et le composant cache (core/datastore/redis) déclarés à côté des modèles, chacun placé dans la Release, et le Manifest qui associe les deux, ainsi que core/referenced-secret-set à sa réalisation Kubernetes, helm/k8s-secret-set, laquelle écrit les clés directement dans un Secret rendu et ne convient donc qu’à une cible de développement. Le fichier des routes déclare alors chaque appelant et vérifie sa clé sur chaque route, et la route de chat porte le 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]

Aucune clé d’appelant n’y figure : chaque consumer nomme une variable que le Deployment remplit à partir du Secret que rend le rattachement caller_keys, sous le nom propre de l’appelant, et la compose en l’en-tête complet :

- 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]

À l’exécution, une requête qui ne présente aucune clé déclarée, sous la forme Authorization: Bearer <key>, est refusée avec HTTP 401, et la clé est retirée de la requête que la passerelle transmet. Une réponse est stockée sous la route et l’appelant, si bien qu’au prompt reformulé d’un appelant est servie la réponse stockée pour cet appelant et jamais une réponse stockée pour un autre. Une réponse servie depuis le cache ne compte rien dans le budget, et elle est servie même au-delà de sa limite. La connexion embedder reçoit ses propres routes, comme toute connexion sur le socket models.

Là où le compilateur n’interprète pas

Le compilateur achemine la limite, la fenêtre et l’unité dans le fichier des routes sous forme de chaînes, ainsi que le point de terminaison et le nom de modèle de chaque modèle à partir de ce que ce modèle publie. Il n’atteint pas OpenAI, ne sait pas si une réponse déclare ses tokens et ne compte rien lui-même. Chaque arrêt ci-dessus est déclaré par les entités propres au catalogue, sous forme d’assertion dans la réalisation du budget ou du cache ou dans l’autre Recipe de la passerelle, et aucun ne repose sur une quelconque compréhension du trafic.

L’adapter

  • Une limite par modèle. Définissez scope: model : chaque alias reçoit un service, et un compteur, qui lui sont propres.
  • Une limite par appelant. Déclarez les appelants et leurs clés dans la Release, comme dans « Un cache sémantique a besoin d’appelants » ci-dessus, et définissez scope: caller : chaque appelant reçoit son propre compteur sur toutes les routes.
  • Compter un seul côté. Définissez unit: prompt_tokens pour compter ce que lisent les modèles, ou completion_tokens pour ce qu’ils écrivent.
  • Une fenêtre plus courte ou plus longue. Définissez period dans la Release à un nombre de secondes, de minutes, d’heures ou de jours, comme 6h ou 30d.