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

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ânciaComponent do catálogoo que é aqui
gatewaycore/gateway/apisixo gateway, que serve 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 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:

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd apisix-token-budget

Compilação

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

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

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

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

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

Há 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: usd no 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 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 todas 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-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. 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/apisix para helm/apisix no Manifest, a compilação é interrompida nas ligaçõ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. 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: 3600

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

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

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