Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Brama APISIX, która utrzymuje swoje modele w budżecie tokenów

Zespół umieszcza dwa modele OpenAI za jedną bramą i chce ustalić górny limit tego, co brama wydaje na nie każdego dnia, liczony w tokenach. Ten obszar roboczy kompiluje taką bramę do manifestów Kubernetes: Apache APISIX przed dwoma modelami, z dołączonym core/period-budget.

Strona pokazuje też, czego semantyczna pamięć podręczna potrzebuje od tej bramy, zanim zostanie zbudowana: wywołujących, których potrafi odróżnić, każdego po kluczu, który przedstawia, oraz magazynu na odpowiedzi.

Ten obszar roboczy nie definiuje żadnej własnej encji katalogu. Trzy pliki encji w nim — encja Aggregate, encja Manifest i encja Release — to całość tego, co ktokolwiek pisze.

Co powstaje

instancjaencja Component z kataloguczym jest tutaj
gatewaycore/gateway/apisixbrama obsługująca dwa aliasy: assistant z modelu chat oraz summarizer z modelu mini
chatcore/ai-model/openaigpt-4o od OpenAI, osiągany jako odwołanie: nic nie działa dla niego w klastrze
minicore/ai-model/openaigpt-4o-mini od OpenAI, osiągany w ten sam sposób

Dwie krawędzie uses prowadzące do gniazda models bramy, po jednej do każdego modelu, z których każda niesie jako credential klucz, który brama przedstawia temu modelowi; obie odczytują jeden parametr, openai_key, który wypełnia encja Release. Jedno dołączenie encji Feature do bramy, budget: encja Aggregate określa, co jest liczone (total_tokens), oraz czyj ruch obejmuje jeden limit (gateway — wszystko, co brama obsługuje), a encja Release określa, ile i w jakim okresie: dwa miliony tokenów dziennie.

Encja Manifest mapuje bramę na apisix-chart, realizację, która renderuje własny chart APISIX projektu w wersji APISIX 3.18.0 i obsługuje modele podłączone do bramy. Gdy model jest podłączony, brama odczytuje swoje trasy z pliku renderowanego wraz z nią, więc nie potrzebuje połączenia z etcd ani klucza Admin API; encja Aggregate nie podłącza żadnego z nich.

Generowanie przykładu

Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

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

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

Terminal window
cd apisix-token-budget

Kompilacja

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

Wydanie wymaga pliku blokady (lockfile), zanim zostanie zbudowane, a pliki blokady są generowane, a nie dostarczane, więc świeży klon nie ma żadnego. Należy najpierw go rozwiązać albo pozwolić, by budowanie go uzupełniło:

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

Rozwiązywanie przypina wersję chartu APISIX renderowanego przez encję Recipe bramy, pobieranego z własnego repozytorium chartu, dlatego wymaga dostępu do sieci. Ten obszar roboczy rozwiązuje encje katalogu z domyślnego rejestru wskazanego w pliku .aggrega-config.yaml.

Budowanie wypisuje (<workspace> oznacza folder tego przykładu):

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

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `apisix-token-budget`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `apisix-token-budget` i bez `dir`: zapisze ono przykład w nowym folderze `apisix-token-budget`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `apisix-token-budget`, `release` ustawionym na `release.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, które pliki zapisało budowanie; znajdują się w `apisix-token-budget/dist/`.

Wyrenderowane drzewo

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

Budżet nie wnosi własnego pliku. To, co robi, jest zapisywane w pliku tras, dist/helm/gateway/model-routes.yaml, czyli w ConfigMap, którą bramka montuje i z której odczytuje całą swoją konfigurację routingu. Każdy model renderuje jeden plik, Service mapujący nazwę wewnątrz klastra na host API OpenAI, a każde poświadczenie w połączeniu z modelem renderuje własny Secret, nazwany od bramki i od aliasu połączenia.

Budżet w postaci, w jakiej odczytuje go brama

Oto klucz apisix.yaml tej ConfigMapy:

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

Warto z niej odczytać pięć rzeczy.

Budżet znajduje się w usłudze, którą wskazują obie trasy. Ograniczanie liczby tokenów w APISIX, ai-rate-limiting, prowadzi licznik w obiekcie, w którym zostało zadeklarowane. Zapisane w każdej trasie, prowadziłoby jeden licznik na trasę; zapisane raz w model-budget, które każda trasa wskazuje przez service_id, prowadzi jeden licznik dla wszystkiego, co obsługuje brama — zakres gateway, o który prosiło powiązanie. Przy scope: model encja Recipe zapisuje zamiast tego jedną usługę na połączenie, model-assistant-budget i model-summarizer-budget, dzięki czemu każdy model ma własny limit.

Okres to okno liczone w sekundach. 1d zapisuje się jako 86400. Okno otwiera się wraz z pierwszym żądaniem do modelu po zamknięciu poprzedniego okna i trwa tyle czasu; nie zaczyna się o północy. Miesiąc kalendarzowy nie ma stałej liczby sekund, dlatego 1mo jest odrzucane, jak opisano poniżej.

Jednostka określa, co jest liczone. total_tokens to tokeny, które według odpowiedzi każdego modelu zostały łącznie odczytane i zapisane; prompt_tokens i completion_tokens liczą jedną stronę. Brama liczy to, co zgłasza odpowiedź, i niczego nie wycenia, więc nie prowadzi budżetu w dolarach amerykańskich.

Każdy model ma trasę czatu i nie ma trasy uzupełnień. Bez budżetu każdy alias otrzymuje także /<alias>/v1/completions. APISIX odczytuje tokeny odpowiedzi tylko z żądania, którego protokół rozpoznaje, a żądanie uzupełnienia, którego treść zawiera prompt zamiast messages, do nich nie należy: zostałoby obsłużone, ale nigdy nie policzone. Dlatego gdy budżet jest powiązany, ta trasa nie jest zapisywana, a na żądanie uzupełnienia brama odpowiada 404 Route Not Found.

Nie ma w nim żadnego klucza. Każda trasa wskazuje zmienną przechowującą token typu bearer swojego połączenia przez odwołanie $env:// w APISIX. Z pliku dist/helm/gateway-deployment-default-gateway.yaml — env kontenera bramy:

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]

Ten sam Deployment uruchamia jedną replikę, replicas: 1. Licznik jest przechowywany w pamięci procesu bramy, więc druga replika prowadziłaby własny licznik; gdy budżet jest powiązany, encja Recipe utrzymuje chart przy jednej replice.

Co bramka robi w czasie działania

Przy każdym żądaniu do modelu bramka porównuje licznik z limit. Gdy licznik go osiągnie, bramka odpowiada 503 Service Temporarily Unavailable aż do zamknięcia okna, a żądanie nigdy nie trafia do modelu; odpowiedź zawiera własne nagłówki bramki X-AI-RateLimit-Limit-…, X-AI-RateLimit-Remaining-… i X-AI-RateLimit-Reset-…. Tokeny żądania są doliczane po zakończeniu odpowiedzi, więc żądanie, które doprowadza licznik do limitu, zostaje obsłużone, podobnie jak każde żądanie przetwarzane równolegle z nim.

Wynikają z tego dwie konsekwencje i obie są zachowaniem bramki, a nie konfiguracją:

  • Restart rozpoczyna nowe okno. Licznik jest przechowywany w pamięci procesu bramki, więc pod po aktualizacji lub restarcie zaczyna liczyć od zera.
  • Odpowiedź niezgłaszająca tokenów niczego nie dolicza. Licznik to to, co zgłasza każdy model; bramka prosi strumieniowane żądanie czatu o zgłoszenie zużycia, a model, który go nie zgłasza, niczego nie dodaje.

Co zatrzymuje kompilację

Każda z tych sytuacji to zdanie, które wypisuje kompilacja, wskazując, co należy zmienić:

  • Koszt w dolarach amerykańskich. Po ustawieniu unit: usd w dołączeniu kompilacja zatrzymuje się, zanim cokolwiek zostanie wyrenderowane:

    [… 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
  • Budżet na wywołującego, scope: caller, gdy encja Release nie deklaruje wywołujących. Bramka rozróżnia wywołujących po kluczu, który każdy z nich przedstawia, a bez infra.callers każda trasa jest otwarta. Gdy wywołujący są zadeklarowani, jak w następnej sekcji, każdy ma własny licznik obejmujący wszystkie trasy.

  • Miesiąc kalendarzowy, period: 1mo, oraz limit, który nie jest całkowitą liczbą tokenów.

  • Drugie dołączenie core/period-budget na bramce, która na danej trasie stosuje jeden limit szybkości tokenów.

  • Nic nie jest podłączone do gniazda models, przez co nie zostaje żadna trasa modelu do liczenia. Jeśli usunie się same dwa połączenia, kompilację najpierw zatrzyma własna encja Component bramy, żądając magazynu etcd i klucza Admin API, za pomocą których brama bez modelu przechowuje swoje trasy.

  • Druga realizacja. Po zmapowaniu core/gateway/apisix na helm/apisix w encji Manifest kompilacja zatrzymuje się na połączeniach models, wskazując helm/apisix-chart: ta realizacja uruchamia APISIX 3.17.0 z trasami w etcd i nie renderuje żadnej. Zatrzymuje się również na dołączeniu budżetu, ponieważ nie ma trasy, na której mogłaby je zapisać, a w wersji 3.17.0 każdy proces bramki liczy osobno.

Pamięć podręczna semantyczna wymaga wywołujących

APISIX 3.18.0 zawiera pamięć podręczną semantyczną, a core/semantic-caching można dołączyć do tej bramy. Należy dodać ją do features bramy w aggregate.yaml:

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

Manifest już kieruje encję Feature do jej realizacji APISIX, a kompilacja zostaje zatrzymana:

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

Pamięć podręczna przechowuje odpowiedź dla każdego, kto później zapyta o coś wystarczająco podobnego, więc to, kto współdzieli jedną pamięć podręczną, decyduje, komu może zostać podana odpowiedź wygenerowana dla kogoś innego. Ta brama potrafi oddzielić każdego wywołującego po kluczu, który przedstawia i który brama weryfikuje, i nic dokładniej: po ustawieniu scope: key kompilacja znów się zatrzymuje, tym razem na wywołujących, których brama nie otrzymała:

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

Trzy uzupełnienia pozwalają ją zbudować. Release wymienia wywołujących i ich klucze:

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]

Aggregate podłącza model, za pomocą którego pamięć podręczna zamienia każdy prompt na wektor, oraz magazyn Redis na odpowiedzi, a w dołączeniu wskazuje model embeddingów jako embedding_model: embedder, z 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

przy czym komponent embeddings (core/ai-model/openai-embedding, z values.model ustawionym na text-embedding-3-small) i komponent cache (core/datastore/redis) są zadeklarowane obok modeli, każdy umieszczony w encji Release, a Manifest mapuje oba oraz core/referenced-secret-set na jego realizację dla Kubernetes, helm/k8s-secret-set, która zapisuje klucze bezpośrednio w renderowanym obiekcie Secret, więc nadaje się wyłącznie do środowiska deweloperskiego. Plik tras deklaruje następnie każdego wywołującego i sprawdza jego klucz na każdej trasie, a trasa czatu zawiera pamięć podręczną:

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]

Nie ma w nim klucza żadnego wywołującego: każdy konsument wskazuje zmienną, którą Deployment wypełnia z obiektu Secret renderowanego przez dołączenie caller_keys, pod własną nazwą wywołującego, i składa z niej cały nagłówek:

- 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]

W czasie działania żądanie, które nie przedstawia zadeklarowanego klucza w postaci Authorization: Bearer <key>, jest odrzucane z kodem HTTP 401, a klucz jest usuwany z żądania, które brama przekazuje dalej. Odpowiedź jest przechowywana według trasy i wywołującego, więc przeformułowany prompt jednego wywołującego otrzymuje odpowiedź zapisaną dla tego wywołującego, a nigdy zapisaną dla innego. Odpowiedź podana z pamięci podręcznej nie jest wliczana do budżetu i jest podawana także po przekroczeniu limitu. Połączenie embedder otrzymuje własne trasy, jak każde połączenie na gnieździe models.

Gdzie kompilator nie interpretuje

Kompilator przekazuje limit, okno i jednostkę do pliku tras jako ciągi znaków, a punkt końcowy i nazwę modelu każdego modelu — z tego, co ten model publikuje. Nie łączy się z OpenAI, nie wie, czy odpowiedź podaje liczbę swoich tokenów, i sam niczego nie zlicza. Każde z powyższych zatrzymań jest zadeklarowane przez własne encje katalogu, jako asercja w realizacji budżetu lub pamięci podręcznej albo w drugiej encji Recipe bramy, i żadne z nich nie opiera się na jakimkolwiek rozumieniu ruchu.

Dostosowywanie przykładu

  • Limit na model. Należy ustawić scope: model: każdy alias otrzymuje własną usługę i własny licznik.
  • Limit na wywołującego. Należy zadeklarować wywołujących i ich klucze w encji Release, jak w sekcji „A semantic cache needs callers” powyżej, i ustawić scope: caller: każdy wywołujący otrzymuje własny licznik obejmujący wszystkie trasy.
  • Liczenie jednej strony. Należy ustawić unit: prompt_tokens, aby liczyć to, co modele czytają, lub completion_tokens, aby liczyć to, co piszą.
  • Krótsze lub dłuższe okno. Należy ustawić period w encji Release na liczbę sekund, minut, godzin lub dni, np. 6h lub 30d.