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
| instancja | encja Component z katalogu | czym jest tutaj |
|---|---|---|
gateway | core/gateway/apisix | brama obsługująca dwa aliasy: assistant z modelu chat oraz summarizer z modelu mini |
chat | core/ai-model/openai | gpt-4o od OpenAI, osiągany jako odwołanie: nic nie działa dla niego w klastrze |
mini | core/ai-model/openai | gpt-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:
aggrega scaffold --example apisix-token-budgetNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd apisix-token-budgetKompilacja
aggrega build --release release.yaml --auto-pullWydanie 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:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildRozwią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>/distZ 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.yamlBudż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]#ENDWarto 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: usdw 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 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 -
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 bezinfra.callerskaż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-budgetna 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/apisixnahelm/apisixw encji Manifest kompilacja zatrzymuje się na połączeniachmodels, wskazująchelm/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: 3600Manifest 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 usersPamięć 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 slotTrzy 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: cacheprzy 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ą, lubcompletion_tokens, aby liczyć to, co piszą. - Krótsze lub dłuższe okno. Należy ustawić
periodw encji Release na liczbę sekund, minut, godzin lub dni, np.6hlub30d.