Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Un gateway APISIX que mantiene sus modelos dentro de un presupuesto de tokens

Un equipo pone dos modelos de OpenAI detrás de un solo gateway y quiere un tope a lo que el gateway gasta en ellos cada día, contado en tokens. Este workspace compila un gateway así a manifiestos de Kubernetes: Apache APISIX delante de los dos modelos, con core/period-budget vinculado.

La página también muestra lo que una caché semántica necesita de este gateway antes de que la compilación salga adelante: llamadores que pueda distinguir, cada uno por la clave que presenta, y un almacén para las respuestas.

Este workspace no crea ninguna entidad de catálogo propia. Los tres archivos de entidad de aquí — un Aggregate, un Manifest y una Release — son todo lo que se escribe.

Lo que construye

instanciaComponent del catálogoqué es aquí
gatewaycore/gateway/apisixel gateway, que sirve dos alias: assistant, del modelo chat, y summarizer, del modelo mini
chatcore/ai-model/openaigpt-4o de OpenAI, alcanzado como referencia: nada se ejecuta para él en el clúster
minicore/ai-model/openaigpt-4o-mini de OpenAI, alcanzado del mismo modo

Dos aristas uses hacia el socket models del gateway, una hacia cada modelo, y cada una lleva como su credential la clave que el gateway presenta a ese modelo; ambas leen un mismo parámetro, openai_key, que la Release satisface. Una vinculación de Feature en el gateway, budget: el Aggregate escribe qué se cuenta, total_tokens, y de quién es el tráfico que cubre un límite, gateway — todo lo que sirve el gateway —, y la Release escribe cuánto y durante cuánto tiempo: dos millones de tokens al día.

El Manifest asigna el gateway a apisix-chart, la realización que renderiza el chart de APISIX propio del proyecto, en APISIX 3.18.0, y sirve los modelos conectados al gateway. Con un modelo conectado, el gateway lee sus rutas de un archivo renderizado con él, así que no toma ninguna conexión a etcd ni ninguna clave de la Admin API; el Aggregate no conecta ninguna de las dos.

Generar el ejemplo

Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

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

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd apisix-token-budget

Compilación

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

Una release necesita un lockfile antes de compilarse, y los lockfiles se generan en lugar de distribuirse, así que un clon recién hecho no tiene ninguno. Resuelve uno primero, o deja que la compilación lo rellene:

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 resolución fija el chart de APISIX que renderiza la Recipe del gateway, obtenido del propio repositorio del chart, así que necesita la red. Este workspace resuelve las entidades del catálogo desde el registro predeterminado que nombra .aggrega-config.yaml.

La compilación imprime, con <workspace> en lugar de la carpeta de este ejemplo:

[… 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 asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta tú mismo. Si la carpeta del espacio de trabajo aún no contiene una carpeta `apisix-token-budget`, llama una sola vez a la herramienta `scaffold` con `example` establecido en `apisix-token-budget` y sin `dir`: escribe el ejemplo en una nueva carpeta `apisix-token-budget`. Después llama a la herramienta `build` con `workspace_root` establecido en `apisix-token-budget`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `apisix-token-budget/dist/`.

El árbol renderizado

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

El presupuesto no aporta ningún archivo propio. Lo que hace se escribe en el archivo de rutas, dist/helm/gateway/model-routes.yaml, un ConfigMap que el gateway monta y del que lee toda su configuración de enrutamiento. Cada modelo renderiza un archivo, un Service que asigna un nombre interno del clúster al host de la API de OpenAI, y cada credencial de una conexión de modelo renderiza un Secret propio, nombrado según el gateway y el alias de la conexión.

El presupuesto, tal como lo lee el gateway

Esta es la clave apisix.yaml de ese 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

Hay cinco cosas que vale la pena leer en él.

El presupuesto está en un servicio que nombran ambas rutas. La limitación de tasa de tokens de APISIX, ai-rate-limiting, guarda su recuento bajo el objeto en el que se declara. Escrita en cada ruta, guardaría un recuento por ruta; escrita una sola vez en model-budget, que cada ruta nombra mediante service_id, guarda un único recuento para todo lo que sirve el gateway — el ámbito gateway que pidió la vinculación. Con scope: model, la Recipe escribe en su lugar un servicio por conexión, model-assistant-budget y model-summarizer-budget, de modo que cada modelo tiene un límite propio.

El periodo es una ventana de segundos. 1d se escribe como 86400. La ventana se abre con la primera solicitud al modelo después de que se cierre la ventana anterior y dura ese tiempo; no empieza a medianoche. Un mes de calendario no tiene un número fijo de segundos, así que 1mo se rechaza, como se ve más abajo.

La unidad es lo que se cuenta. total_tokens son los tokens que la respuesta de cada modelo informa haber leído y escrito en conjunto; prompt_tokens y completion_tokens cuentan un solo lado. El gateway cuenta lo que informa la respuesta y no pone precio a nada, así que no lleva ningún presupuesto en dólares estadounidenses.

Cada modelo tiene una ruta de chat y ninguna ruta de completion. Sin el presupuesto, cada alias recibe también /<alias>/v1/completions. APISIX lee los tokens de una respuesta solo de una solicitud cuyo protocolo reconoce, y una solicitud de completion, cuyo cuerpo lleva un prompt en lugar de messages, no lo es: se respondería y nunca se contaría. Así que, mientras el presupuesto está vinculado, esa ruta no se escribe, y una solicitud de completion se responde con 404 Route Not Found.

No contiene ninguna clave. Cada ruta nombra la variable que guarda el bearer token de su conexión mediante la referencia $env:// de APISIX. De dist/helm/gateway-deployment-default-gateway.yaml, el env del contenedor 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]

El mismo Deployment ejecuta una réplica, replicas: 1. El recuento se guarda en la memoria del proceso del gateway, así que una segunda réplica llevaría un recuento propio; mientras haya un presupuesto vinculado, la Recipe mantiene el chart en una.

Qué hace el gateway en tiempo de ejecución

En cada solicitud al modelo, el gateway compara el recuento con limit. Una vez que el recuento lo ha alcanzado, el gateway responde 503 Service Temporarily Unavailable hasta que se cierra la ventana, sin enviar nunca la solicitud al modelo; la respuesta lleva los encabezados propios del gateway X-AI-RateLimit-Limit-…, X-AI-RateLimit-Remaining-… y X-AI-RateLimit-Reset-…. Los tokens de una solicitud se suman cuando su respuesta se completa, así que la solicitud que lleva el recuento al límite se sirve, y también cualquier solicitud que ya esté en curso junto a ella.

Se siguen dos consecuencias, y ambas son comportamiento del gateway y no configuración:

  • Un reinicio abre una nueva ventana. El recuento vive en la memoria del proceso del gateway, así que un pod renovado o reiniciado empieza a contar desde cero.
  • Una respuesta que no informa tokens no cuenta nada. El recuento es lo que informa cada modelo; el gateway pide a una solicitud de chat en streaming que informe su uso, y un modelo que no informa ninguno no suma nada.

Qué detiene la compilación

Cada uno de estos casos es una frase que imprime la compilación, y que nombra qué cambiar:

  • Un costo en dólares estadounidenses. Establece unit: usd en la vinculación y la compilación se detiene antes de renderizar nada:

    [… 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 presupuesto por llamador, scope: caller, mientras la Release no declara ningún llamador. El gateway distingue a los llamadores por la clave que presenta cada uno, y sin infra.callers todas las rutas están abiertas. Con llamadores declarados, como en la sección siguiente, cada uno tiene un recuento propio en todas las rutas.

  • Un mes de calendario, period: 1mo, y un límite que no es un número entero de tokens.

  • Una segunda vinculación de core/period-budget en el gateway, que solo ejecuta un límite de tasa de tokens por ruta.

  • Nada conectado al socket models, lo que no deja ninguna ruta de modelo que contar. Quita solo las dos conexiones y el propio Component del gateway se detiene primero, pidiendo el almacén etcd y la clave de la Admin API mediante los que un gateway sin modelo mantiene sus rutas.

  • La otra realización. Asigna core/gateway/apisix a helm/apisix en el Manifest y la compilación se detiene en las conexiones models, nombrando helm/apisix-chart: esa realización ejecuta APISIX 3.17.0 con sus rutas en etcd y no renderiza ninguna. También se detiene ante una vinculación de presupuesto, ya que no tiene ninguna ruta en la que escribirla y, en 3.17.0, cada proceso del gateway cuenta por su cuenta.

Una caché semántica necesita llamadores

APISIX 3.18.0 incluye una caché semántica, y core/semantic-caching se vincula a este gateway. Añádela a las features del gateway en aggregate.yaml:

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

El Manifest ya dirige la Feature a su realización de APISIX, y la compilación se detiene:

[… 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 caché guarda una respuesta para quien pregunte más tarde algo lo bastante parecido, así que quién comparte una caché decide a quién se le puede servir una respuesta generada para otra persona. Este gateway puede mantener separado a cada llamador por la clave que presenta, que verifica, y nada más fino: establece scope: key y la compilación se detiene de nuevo, ahora por los llamadores que no se le han dado:

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

Tres añadidos hacen que compile. La Release nombra a los llamadores y sus claves:

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]

El Aggregate conecta el modelo con el que la caché convierte cada prompt en un vector, y un almacén Redis para las respuestas, y nombra el modelo de embeddings en la vinculación como 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 el componente embeddings (core/ai-model/openai-embedding, con su values.model establecido en text-embedding-3-small) y el componente cache (core/datastore/redis) declarados junto a los modelos, cada uno colocado en la Release, y el Manifest asignando ambos, y core/referenced-secret-set a su realización de Kubernetes, helm/k8s-secret-set, que escribe las claves directamente en un Secret renderizado y por eso solo sirve para un destino de desarrollo. El archivo de rutas declara entonces cada llamador y comprueba su clave en todas las rutas, y la ruta de chat lleva la caché:

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]

No contiene la clave de ningún llamador: cada consumer nombra una variable que el Deployment rellena a partir del Secret que renderiza la vinculación caller_keys, bajo el nombre propio del llamador, y la compone en el encabezado 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]

En tiempo de ejecución, una solicitud que no presenta ninguna clave declarada, como Authorization: Bearer <key>, se rechaza con HTTP 401, y la clave se elimina de la solicitud que el gateway reenvía. Una respuesta se guarda bajo la ruta y el llamador, así que al prompt reformulado de un llamador se le sirve la respuesta guardada para ese llamador y nunca una guardada para otro. Una respuesta servida desde la caché no cuenta nada para el presupuesto, y se sirve aun superado su límite. La conexión embedder recibe rutas propias, como toda conexión del socket models.

Dónde el compilador no interpreta

El compilador canaliza el límite, la ventana y la unidad al archivo de rutas como cadenas, y el endpoint y el nombre de modelo de cada modelo a partir de lo que ese modelo publica. No llega a OpenAI, no sabe si una respuesta informa sus tokens y no cuenta nada por sí mismo. Cada detención anterior la declaran las propias entidades del catálogo, como una aserción en la realización del presupuesto o de la caché o en la otra Recipe del gateway, y ninguna se basa en comprensión alguna del tráfico.

Adaptarlo

  • Un límite por modelo. Establece scope: model: cada alias recibe un servicio, y un recuento, propios.
  • Un límite por llamador. Declara los llamadores y sus claves en la Release, como en «Una caché semántica necesita llamadores» más arriba, y establece scope: caller: cada llamador recibe un recuento propio en todas las rutas.
  • Contar un solo lado. Establece unit: prompt_tokens para contar lo que leen los modelos, o completion_tokens para lo que escriben.
  • Una ventana más corta o más larga. Establece period en la Release en un número de segundos, minutos, horas o días, como 6h o 30d.