Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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ânciaComponent do catálogoo que é aqui
gatewaycore/gateway/apisixo gateway, servindo dois aliases: assistant, a partir do modelo chat, e summarizer, a partir do modelo mini
chatcore/ai-model/openaio gpt-4o da OpenAI, alcançado como referência: nada é executado para ele no cluster
minicore/ai-model/openaio 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:

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

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd apisix-token-budget

Build

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

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

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

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

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

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

Cinco 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: usd na 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 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
  • 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 sem infra.callers toda 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-budget no 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/apisix para helm/apisix no Manifest e o build é interrompido nas conexões models, nomeando helm/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: 3600

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

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

Trê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: cache

com 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_tokens para contar o que os modelos leem, ou completion_tokens para o que eles escrevem.
  • Uma janela mais curta ou mais longa. Defina period na Release como um número de segundos, minutos, horas ou dias, como em 6h ou 30d.