Um gateway APISIX que mantém os seus modelos dentro de um orçamento de tokens
Uma equipa coloca dois modelos da OpenAI atrás de um único gateway e quer um teto para o que o gateway gasta com eles por dia, contado em tokens. Este workspace compila um gateway desse tipo em manifestos do Kubernetes: o Apache APISIX à frente dos dois modelos, com core/period-budget anexado.
A página mostra também aquilo de que uma cache semântica precisa deste gateway antes de a compilação ser bem-sucedida: chamadores que ele consiga distinguir, cada um pela chave que apresenta, e um repositório para as respostas.
Este workspace não cria nenhuma entidade de catálogo própria. Os três ficheiros de entidade aqui presentes — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.
O que constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
gateway | core/gateway/apisix | o gateway, que serve dois aliases: assistant, a partir do modelo chat, e summarizer, a partir do modelo mini |
chat | core/ai-model/openai | o gpt-4o da OpenAI, alcançado como referência: nada é executado para ele no cluster |
mini | core/ai-model/openai | o gpt-4o-mini da OpenAI, alcançado da mesma forma |
Duas arestas uses para o socket models do gateway, uma para cada modelo, cada uma com a chave que o gateway apresenta a esse modelo como o seu credential; ambas leem um mesmo parâmetro, openai_key, que a Release satisfaz. Um anexo de Feature no gateway, budget: o Aggregate escreve o que é contado, total_tokens, e de quem é o tráfego que um limite cobre, gateway — tudo o que o gateway serve —, e a Release escreve quanto e ao longo de quanto tempo: dois milhões de tokens por dia.
O Manifest mapeia o gateway para apisix-chart, a realização que renderiza o chart APISIX próprio do projeto, no APISIX 3.18.0, e serve os modelos ligados ao gateway. Com um modelo ligado, o gateway lê as suas rotas a partir de um ficheiro renderizado com ele, pelo que não recebe nenhuma ligação ao etcd nem nenhuma chave da Admin API; o Aggregate não liga nenhuma das duas.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example apisix-token-budgetDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd apisix-token-budgetCompilação
aggrega build --release release.yaml --auto-pullUma release precisa de um lockfile antes de ser compilada, e os lockfiles são gerados em vez de distribuídos, pelo que um clone novo não tem nenhum. Resolva-se um primeiro, ou deixe-se que a compilação o preencha:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildA resolução fixa o chart APISIX que a Recipe do gateway renderiza, obtido a partir do próprio repositório do chart, pelo que precisa da rede. Este workspace resolve as entidades do catálogo a partir do registo predefinido que .aggrega-config.yaml nomeia.
A compilação imprime, com <workspace> a representar a pasta deste exemplo:
[… 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>/distCom um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta do espaço de trabalho ainda não contiver uma pasta `apisix-token-budget`, chame a ferramenta `scaffold` uma única vez com `example` definido como `apisix-token-budget` e sem `dir`: esta escreve o exemplo numa nova pasta `apisix-token-budget`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `apisix-token-budget`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me que ficheiros a compilação escreveu; encontram-se em `apisix-token-budget/dist/`.A árvore renderizada
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.yamlO orçamento não traz nenhum ficheiro próprio. O que faz é escrito no ficheiro de rotas, dist/helm/gateway/model-routes.yaml, um ConfigMap que o gateway monta e a partir do qual lê toda a sua configuração de encaminhamento. Cada modelo renderiza um ficheiro, um Service que mapeia um nome interno ao cluster para o host da API da OpenAI, e cada credencial numa ligação a um modelo renderiza um Secret próprio, com o nome do gateway e do alias da ligação.
O orçamento, tal como o gateway o lê
Eis a chave apisix.yaml desse 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]#ENDHá cinco coisas que vale a pena ler nele.
O orçamento está num serviço que ambas as rotas nomeiam. A limitação de taxa de tokens do APISIX, ai-rate-limiting, mantém a sua contagem sob o objeto em que é declarada. Escrita em cada rota, manteria uma contagem por rota; escrita uma única vez em model-budget, que cada rota nomeia através de service_id, mantém uma única contagem para tudo o que o gateway serve — o âmbito gateway que o anexo pediu. Com scope: model, a Recipe escreve em vez disso um serviço por ligação, model-assistant-budget e model-summarizer-budget, pelo que cada modelo tem um limite próprio.
O período é uma janela de segundos. 1d é escrito como 86400. A janela abre-se com o primeiro pedido ao modelo depois de a janela anterior se fechar e dura esse tempo; não começa à meia-noite. Um mês de calendário não tem um número fixo de segundos, pelo que 1mo é recusado, como se vê abaixo.
A unidade é aquilo que é contado. total_tokens são os tokens que a resposta de cada modelo indica ter lido e escrito em conjunto; prompt_tokens e completion_tokens contam um único lado. O gateway conta o que a resposta indica e não atribui preço a nada, pelo que não mantém nenhum orçamento em dólares americanos.
Cada modelo tem uma rota de chat e nenhuma rota de completion. Sem o orçamento, cada alias recebe também /<alias>/v1/completions. O APISIX lê os tokens de uma resposta apenas de um pedido cujo protocolo reconhece, e um pedido de completion, cujo corpo traz um prompt em vez de messages, não é um deles: seria respondido e nunca contado. Por isso, enquanto o orçamento estiver anexado, essa rota não é escrita, e um pedido de completion recebe a resposta 404 Route Not Found.
Não contém nenhuma chave. Cada rota nomeia a variável que guarda o bearer token da sua ligação através da referência $env:// do APISIX. De dist/helm/gateway-deployment-default-gateway.yaml, o env do contentor do 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]O mesmo Deployment executa uma réplica, replicas: 1. A contagem é mantida na memória do processo do gateway, pelo que uma segunda réplica manteria uma contagem própria; enquanto estiver anexado um orçamento, a Recipe mantém o chart numa.
O que o gateway faz em tempo de execução
Em cada pedido ao modelo, o gateway compara a contagem com limit. Assim que a contagem o atinge, o gateway responde 503 Service Temporarily Unavailable até a janela se fechar, sem que o pedido seja alguma vez enviado ao modelo; a resposta traz os cabeçalhos próprios do gateway X-AI-RateLimit-Limit-…, X-AI-RateLimit-Remaining-… e X-AI-RateLimit-Reset-…. Os tokens de um pedido são somados quando a sua resposta termina, pelo que o pedido que leva a contagem ao limite é servido, tal como qualquer pedido já em curso ao lado dele.
Daí decorrem duas consequências, e ambas são comportamento do gateway, e não configuração:
- Um reinício abre uma nova janela. A contagem vive na memória do processo do gateway, pelo que um pod substituído ou reiniciado começa a contar a partir do zero.
- Uma resposta que não indique tokens não conta nada. A contagem é aquilo que cada modelo indica; o gateway pede a um pedido de chat em streaming que indique a sua utilização, e um modelo que não indique nenhuma não soma nada.
O que interrompe a compilação
Cada um destes casos é uma frase que a compilação imprime, a nomear o que alterar:
-
Um custo em dólares americanos. Ao definir
unit: usdno anexo, a compilação é interrompida antes de qualquer coisa ser renderizada:[… 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 -
Um orçamento por chamador,
scope: caller, enquanto a Release não declara nenhum chamador. O gateway distingue os chamadores pela chave que cada um apresenta, e seminfra.callerstodas as rotas ficam abertas. Com chamadores declarados, como na secção seguinte, cada um tem uma contagem própria em todas as rotas. -
Um mês de calendário,
period: 1mo, e um limite que não é um número inteiro de tokens. -
Um segundo anexo de
core/period-budgetno gateway, que executa apenas um limite de taxa de tokens por rota. -
Nada ligado ao socket
models, o que não deixa nenhuma rota de modelo para contar. Ao remover apenas as duas ligações, é o próprio Component do gateway que é interrompido primeiro, pedindo o repositório etcd e a chave da Admin API através dos quais um gateway sem modelo mantém as suas rotas. -
A outra realização. Ao mapear
core/gateway/apisixparahelm/apisixno Manifest, a compilação é interrompida nas ligaçõesmodels, nomeandohelm/apisix-chart: essa realização executa o APISIX 3.17.0 com as suas rotas no etcd e não renderiza nenhuma. Também é interrompida perante um anexo de orçamento, já que não tem nenhuma rota onde o escrever e, na 3.17.0, cada processo do gateway conta por si.
Uma cache semântica precisa de chamadores
O APISIX 3.18.0 inclui uma cache semântica, e core/semantic-caching anexa-se a este gateway. Basta acrescentá-la às features do gateway em aggregate.yaml:
answers: type: core/semantic-caching values: embedding_model: assistant similarity_threshold: 0.9 ttl_seconds: 3600O Manifest já encaminha a Feature para a sua realização APISIX, e a compilação é interrompida:
[… 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 usersUma cache guarda uma resposta para quem perguntar mais tarde algo suficientemente próximo, pelo que quem partilha uma cache decide a quem pode ser servida uma resposta gerada para outra pessoa. Este gateway consegue separar cada chamador pela chave que apresenta, que verifica, e nada mais fino: ao definir scope: key, a compilação é interrompida de novo, agora nos chamadores que não lhe foram fornecidos:
[… 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 slotTrês acréscimos permitem que a compilação seja bem-sucedida. A Release nomeia os chamadores e as respetivas chaves:
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]O Aggregate liga o modelo com o qual a cache transforma cada prompt num vetor, e um repositório Redis para as respostas, e nomeia o modelo de embeddings no anexo como embedding_model: embedder, com 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: cachecom o componente embeddings (core/ai-model/openai-embedding, com o seu values.model definido como text-embedding-3-small) e o componente cache (core/datastore/redis) declarados ao lado dos modelos, cada um colocado na Release, e o Manifest a mapear ambos, e core/referenced-secret-set para a respetiva realização no Kubernetes, helm/k8s-secret-set, que escreve as chaves diretamente num Secret renderizado e por isso só é adequada a um destino de desenvolvimento. O ficheiro de rotas declara então cada chamador e verifica a sua chave em todas as rotas, e a rota de chat traz a 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]Não contém nenhuma chave de chamador: cada consumer nomeia uma variável que o Deployment preenche a partir do Secret que o anexo caller_keys renderiza, sob o próprio nome do chamador, e compõe-na no cabeçalho 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]Em tempo de execução, um pedido que não apresente nenhuma chave declarada, como Authorization: Bearer <key>, é recusado com HTTP 401, e a chave é removida do pedido que o gateway reencaminha. Uma resposta é guardada sob a rota e o chamador, pelo que ao prompt reformulado de um chamador é servida a resposta guardada para esse chamador e nunca uma guardada para outro. Uma resposta servida a partir da cache não conta nada para o orçamento, e é servida mesmo depois de atingido o seu limite. A ligação embedder recebe rotas próprias, como todas as ligações no socket models.
Onde o compilador não interpreta
O compilador canaliza o limite, a janela e a unidade para o ficheiro de rotas como strings, e o endpoint e o nome de modelo de cada modelo a partir do que esse modelo publica. Não contacta a OpenAI, não sabe se uma resposta indica os seus tokens e não conta nada por si. Cada interrupção acima é declarada pelas próprias entidades do catálogo, como uma asserção na realização do orçamento ou da cache ou na outra Recipe do gateway, e nenhuma delas assenta em qualquer compreensão do tráfego.
Adaptá-lo
- Um limite por modelo. Com
scope: model, cada alias recebe um serviço, e uma contagem, próprios. - Um limite por chamador. Declaram-se os chamadores e as respetivas chaves na Release, como em «Uma cache semântica precisa de chamadores» acima, e define-se
scope: caller: cada chamador recebe uma contagem própria em todas as rotas. - Contar um único lado. Define-se
unit: prompt_tokenspara contar o que os modelos leem, oucompletion_tokenspara o que escrevem. - Uma janela mais curta ou mais longa. Define-se
periodna Release como um número de segundos, minutos, horas ou dias, como em6hou30d.