Um gateway APISIX que mantém os seus modelos dentro de um orçamento de tokens
Uma equipe coloca dois modelos da OpenAI atrás de um único gateway e quer um teto para o que o gateway gasta com eles a cada dia, contado em tokens. Este workspace compila um gateway assim para manifestos do Kubernetes: o Apache APISIX na frente dos dois modelos, com core/period-budget vinculado.
A página também mostra o que um cache semântico precisa deste gateway antes que o build seja concluído: 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 arquivos de entidade daqui — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.
O que ele constrói
| instância | Component do catálogo | o que é aqui |
|---|---|---|
gateway | core/gateway/apisix | o gateway, servindo 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 trazendo como seu credential a chave que o gateway apresenta a esse modelo; ambas leem um mesmo parâmetro, openai_key, que a Release satisfaz. Uma vinculação 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 de um arquivo renderizado com ele, então não recebe nenhuma conexão com o etcd nem nenhuma chave da Admin API; o Aggregate não liga nenhum dos dois.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example apisix-token-budgetEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd apisix-token-budgetBuild
aggrega build --release release.yaml --auto-pullUma release precisa de um lockfile antes de fazer o build, e os lockfiles são gerados em vez de distribuídos, então um clone recém-feito não tem nenhum. Resolva um primeiro, ou deixe o build preenchê-lo:
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 do próprio repositório do chart, então precisa da rede. Este workspace resolve as entidades do catálogo a partir do registro padrão que .aggrega-config.yaml nomeia.
O build imprime, com <workspace> representando 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 este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace 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`: ela escreve o exemplo em uma 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 quais arquivos o build escreveu; eles ficam 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 arquivo próprio. O que ele faz é escrito no arquivo de rotas, dist/helm/gateway/model-routes.yaml, um ConfigMap que o gateway monta e do qual lê toda a sua configuração de roteamento. Cada modelo renderiza um arquivo, um Service que mapeia um nome interno ao cluster para o host da API da OpenAI, e cada credencial em uma conexão de modelo renderiza um Secret próprio, nomeado a partir do gateway e do alias da conexão.
O orçamento, como o gateway o lê
Aqui está 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]#ENDCinco coisas valem a pena ser lidas nele.
O orçamento fica em um 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, ela manteria uma contagem por rota; escrita uma única vez em model-budget, que cada rota nomeia por meio de service_id, ela mantém uma única contagem para tudo o que o gateway serve — o escopo gateway que a vinculação pediu. Com scope: model, a Recipe escreve em vez disso um serviço por conexão, model-assistant-budget e model-summarizer-budget, de modo que cada modelo tem um limite próprio.
O período é uma janela de segundos. 1d é escrito como 86400. A janela se abre com a primeira requisição ao modelo depois que a janela anterior se fecha e dura esse tempo; ela não começa à meia-noite. Um mês de calendário não tem um número fixo de segundos, então 1mo é recusado, como mostrado abaixo.
A unidade é o que é contado. total_tokens são os tokens que a resposta de cada modelo informa ter lido e escrito juntos; prompt_tokens e completion_tokens contam um único lado. O gateway conta o que a resposta informa e não atribui preço a nada, então 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 também recebe /<alias>/v1/completions. O APISIX lê os tokens de uma resposta apenas de uma requisição cujo protocolo reconhece, e uma requisição de completion, cujo corpo traz um prompt em vez de messages, não é uma delas: ela seria respondida e nunca contada. Por isso, enquanto o orçamento está vinculado, essa rota não é escrita, e uma requisição de completion é respondida com 404 Route Not Found.
Nenhuma chave está nele. Cada rota nomeia a variável que guarda o bearer token da sua conexão por meio da referência $env:// do APISIX. De dist/helm/gateway-deployment-default-gateway.yaml, o env do contêiner 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, então uma segunda réplica manteria uma contagem própria; enquanto um orçamento está vinculado, a Recipe mantém o chart em uma.
O que o gateway faz em tempo de execução
A cada requisição ao modelo, o gateway compara a contagem com limit. Depois que a contagem o atinge, o gateway responde 503 Service Temporarily Unavailable até a janela se fechar, sem que a requisição jamais seja enviada 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 uma requisição são somados quando a sua resposta é concluída, então a requisição que leva a contagem ao limite é servida, assim como qualquer requisição já em andamento ao lado dela.
Seguem-se duas consequências, e ambas são comportamento do gateway, e não configuração:
- Uma reinicialização começa uma nova janela. A contagem vive na memória do processo do gateway, então um pod substituído ou reiniciado começa a contar do zero.
- Uma resposta que não informa tokens não conta nada. A contagem é o que cada modelo informa; o gateway pede a uma requisição de chat em streaming que informe o seu uso, e um modelo que não informa nenhum não soma nada.
O que interrompe o build
Cada um destes casos é uma frase que o build imprime, nomeando o que mudar:
-
Um custo em dólares americanos. Defina
unit: usdna vinculação e o build é interrompido antes que qualquer coisa seja 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.callerstoda rota fica aberta. Com chamadores declarados, como na próxima seção, 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. -
Uma segunda vinculação 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. Remova apenas as duas conexões e o próprio Component do gateway é interrompido primeiro, pedindo o repositório etcd e a chave da Admin API por meio dos quais um gateway sem modelo mantém as suas rotas. -
A outra realização. Mapeie
core/gateway/apisixparahelm/apisixno Manifest e o build é interrompido nas conexõesmodels, nomeandohelm/apisix-chart: essa realização executa o APISIX 3.17.0 com as suas rotas no etcd e não renderiza nenhuma. Ela também é interrompida em uma vinculação de orçamento, já que não tem nenhuma rota na qual escrevê-la e, no 3.17.0, cada processo do gateway conta por conta própria.
Um cache semântico precisa de chamadores
O APISIX 3.18.0 traz um cache semântico, e core/semantic-caching se vincula a este gateway. Adicione-a à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á direciona a Feature para a sua realização APISIX, e o build é interrompido:
[… 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 usersUm cache guarda uma resposta para quem perguntar mais tarde algo suficientemente parecido, então quem compartilha um cache decide a quem pode ser servida uma resposta gerada para outra pessoa. Este gateway consegue separar cada chamador pela chave que ele apresenta, que verifica, e nada mais fino: defina scope: key e o build é interrompido 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 fazem o build ser concluído. A Release nomeia os chamadores e as suas 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 o cache transforma cada prompt em um vetor, e um repositório Redis para as respostas, e nomeia o modelo de embeddings na vinculação 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 mapeando ambos, e core/referenced-secret-set para a sua realização no Kubernetes, helm/k8s-secret-set, que escreve as chaves diretamente em um Secret renderizado e por isso só serve para um destino de desenvolvimento. O arquivo de rotas então declara cada chamador e verifica a sua chave em todas as rotas, e a rota de chat traz o 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]Nenhuma chave de chamador está nele: cada consumer nomeia uma variável que o Deployment preenche a partir do Secret que a vinculação caller_keys renderiza, sob o próprio nome do chamador, e a compõe 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, uma requisição que não apresenta nenhuma chave declarada, como Authorization: Bearer <key>, é recusada com HTTP 401, e a chave é removida da requisição que o gateway encaminha. Uma resposta é armazenada sob a rota e o chamador, então o prompt reformulado de um chamador recebe a resposta armazenada para esse chamador e nunca uma armazenada para outro. Uma resposta servida do cache não conta nada para o orçamento, e é servida mesmo além do seu limite. A conexão embedder recebe rotas próprias, como toda conexão no socket models.
Onde o compilador não interpreta
O compilador canaliza o limite, a janela e a unidade para o arquivo de rotas como strings, e o endpoint e o nome de modelo de cada modelo a partir do que esse modelo publica. Ele não acessa a OpenAI, não sabe se uma resposta informa os seus tokens e não conta nada por si mesmo. Cada interrupção acima é declarada pelas próprias entidades do catálogo, como uma asserção na realização do orçamento ou do cache ou na outra Recipe do gateway, e nenhuma delas se apoia em qualquer compreensão do tráfego.
Adaptando-o
- Um limite por modelo. Defina
scope: model: cada alias recebe um serviço, e uma contagem, próprios. - Um limite por chamador. Declare os chamadores e as suas chaves na Release, como em “Um cache semântico precisa de chamadores” acima, e defina
scope: caller: cada chamador recebe uma contagem própria em todas as rotas. - Contar um único lado. Defina
unit: prompt_tokenspara contar o que os modelos leem, oucompletion_tokenspara o que eles escrevem. - Uma janela mais curta ou mais longa. Defina
periodna Release como um número de segundos, minutos, horas ou dias, como em6hou30d.