Gateway APISIX yang membatasi model-modelnya dengan anggaran token
Sebuah tim menempatkan dua model OpenAI di belakang satu gateway dan menginginkan batas atas
atas apa yang dibelanjakan gateway untuk model-model tersebut setiap hari, dihitung dalam token. Workspace ini mengompilasi
gateway semacam itu menjadi manifest Kubernetes: Apache APISIX di depan kedua model,
dengan core/period-budget terpasang.
Halaman ini juga menunjukkan apa yang dibutuhkan semantic cache dari gateway ini sebelum cache tersebut dapat dibangun: pemanggil yang dapat dibedakannya, masing-masing melalui kunci yang ditunjukkannya, dan penyimpanan untuk balasan.
Workspace ini tidak menulis entitas katalog sendiri. Tiga berkas entitas di sini — sebuah Aggregate, sebuah Manifest, dan sebuah Release — adalah seluruh hal yang ditulis siapa pun.
Apa yang dibangunnya
| instans | Component katalog | perannya di sini |
|---|---|---|
gateway | core/gateway/apisix | gateway, yang melayani dua alias: assistant, dari model chat, dan summarizer, dari model mini |
chat | core/ai-model/openai | gpt-4o milik OpenAI, dijangkau sebagai referensi: tidak ada yang berjalan untuknya di dalam klaster |
mini | core/ai-model/openai | gpt-4o-mini milik OpenAI, dijangkau dengan cara yang sama |
Dua edge uses ke soket models milik gateway, satu ke masing-masing model, masing-masing
membawa sebagai credential-nya kunci yang diberikan gateway kepada model tersebut; keduanya
membaca satu parameter, openai_key, yang dipenuhi oleh Release. Satu lampiran Feature
pada gateway, budget: Aggregate menuliskan apa yang dihitung,
total_tokens, dan lalu lintas siapa yang dicakup oleh satu batas, gateway — semua yang
dilayani gateway — dan Release menuliskan berapa banyak dan dalam jangka waktu berapa lama: dua juta
token per hari.
Manifest memetakan gateway ke apisix-chart, realisasi yang merender
chart APISIX milik proyek itu sendiri, pada APISIX 3.18.0, dan melayani model-model yang terhubung ke
gateway. Dengan adanya model yang terhubung, gateway membaca rutenya dari sebuah berkas
yang dirender bersamanya, sehingga gateway tidak memerlukan koneksi etcd maupun kunci Admin API;
Aggregate tidak menghubungkan keduanya.
Membuat contoh
Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example apisix-token-budgetKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd apisix-token-budgetBuild
aggrega build --release release.yaml --auto-pullSebuah release memerlukan lockfile sebelum di-build, dan lockfile dihasilkan alih-alih disertakan, sehingga clone baru tidak memilikinya. Resolusikan satu terlebih dahulu, atau biarkan build mengisinya:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildResolusi mengunci chart APISIX yang dirender oleh Recipe milik gateway, yang diambil dari repositori chart itu sendiri, sehingga memerlukan jaringan. Workspace ini meresolusi entitas katalog dari registry default yang disebut .aggrega-config.yaml.
Build mencetak keluaran berikut, dengan <workspace> mewakili folder contoh ini:
[… 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>/distDengan asisten AI
Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.
Gunakan hanya tool Aggrega, dan jangan membuat folder apa pun sendiri. Jika folder workspace belum berisi folder `apisix-token-budget`, panggil tool `scaffold` sekali dengan `example` diatur ke `apisix-token-budget` dan tanpa `dir`: tool itu menulis contoh ke folder baru `apisix-token-budget`. Lalu panggil tool `build` dengan `workspace_root` diatur ke `apisix-token-budget`, `release` diatur ke `release.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana saja yang ditulis build; file-file itu berada di bawah `apisix-token-budget/dist/`.Pohon hasil render
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.yamlAnggaran ini tidak membawa berkas sendiri. Apa yang dilakukannya ditulis ke dalam berkas rute,
dist/helm/gateway/model-routes.yaml, sebuah ConfigMap yang dipasang oleh gateway dan
menjadi sumber seluruh konfigurasi peruteannya. Setiap model merender satu berkas, yaitu sebuah
Service yang memetakan nama di dalam kluster ke host API OpenAI, dan setiap kredensial
pada koneksi model merender Secret tersendiri, yang dinamai sesuai gateway dan
alias koneksi tersebut.
Anggaran, sebagaimana dibaca oleh gateway
Berikut adalah kunci apisix.yaml dari ConfigMap tersebut:
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]#ENDAda lima hal yang patut dibaca darinya.
Anggaran ditempatkan pada service yang dirujuk oleh kedua route. Pembatasan laju token APISIX, ai-rate-limiting, menyimpan hitungannya di bawah objek tempat ia dideklarasikan. Jika ditulis pada setiap route, ia akan menyimpan satu hitungan per route; jika ditulis sekali pada
model-budget, yang dirujuk oleh setiap route melalui service_id, ia menyimpan satu hitungan untuk semua yang dilayani gateway — cakupan gateway yang diminta oleh lampiran tersebut. Dengan scope: model, Recipe justru menulis satu service per koneksi, model-assistant-budget dan model-summarizer-budget, sehingga setiap model memiliki batasnya sendiri.
Periode adalah jendela dalam detik. 1d ditulis sebagai 86400. Jendela dibuka dengan permintaan model pertama setelah jendela sebelumnya ditutup dan berlangsung selama itu; jendela tidak dimulai pada tengah malam. Satu bulan kalender tidak memiliki jumlah detik yang tetap, sehingga 1mo ditolak, seperti dijelaskan di bawah.
Satuan adalah apa yang dihitung. total_tokens adalah token yang dilaporkan oleh balasan setiap model sebagai gabungan token yang dibaca dan ditulis; prompt_tokens dan
completion_tokens menghitung satu sisi saja. Gateway menghitung apa yang dilaporkan balasan dan tidak menetapkan harga apa pun, sehingga gateway tidak menyimpan anggaran dalam dolar AS.
Setiap model memiliki route chat dan tidak memiliki route completion. Tanpa anggaran, setiap alias juga mendapatkan /<alias>/v1/completions. APISIX membaca token sebuah balasan hanya dari permintaan yang protokolnya dikenalinya, dan permintaan completion, yang body-nya membawa prompt alih-alih messages, bukan termasuk di dalamnya: permintaan tersebut akan dijawab tetapi tidak pernah dihitung. Karena itu, selama anggaran terlampir, route tersebut tidak ditulis, dan permintaan completion dijawab dengan 404 Route Not Found.
Tidak ada kunci di dalamnya. Setiap route merujuk variabel yang menyimpan bearer token koneksinya melalui referensi $env:// APISIX. Dari
dist/helm/gateway-deployment-default-gateway.yaml, env dari container 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]Deployment yang sama menjalankan satu replika, replicas: 1. Hitungan disimpan di memori proses gateway, sehingga replika kedua akan menyimpan hitungannya sendiri; selama anggaran terlampir, Recipe menahan chart pada satu replika.
Apa yang dilakukan gateway saat run time
Pada setiap permintaan model, gateway memeriksa hitungan terhadap limit. Setelah
hitungan mencapainya, gateway menjawab 503 Service Temporarily Unavailable
hingga jendela ditutup, tanpa permintaan itu pernah dikirim ke model;
respons tersebut membawa header X-AI-RateLimit-Limit-…,
X-AI-RateLimit-Remaining-… dan X-AI-RateLimit-Reset-… milik gateway sendiri. Token sebuah
permintaan ditambahkan ketika balasannya selesai, sehingga permintaan yang membawa hitungan
ke batas tetap dilayani, demikian pula setiap permintaan yang sudah berjalan bersamaan dengannya.
Dua konsekuensi menyusul, dan keduanya merupakan perilaku gateway, bukan konfigurasi:
- Restart memulai jendela baru. Hitungan disimpan di memori proses gateway, sehingga pod yang di-roll atau di-restart mulai menghitung dari nol.
- Balasan yang tidak melaporkan token tidak menghitung apa pun. Hitungan adalah apa yang dilaporkan setiap model; gateway meminta permintaan chat yang di-stream untuk melaporkan penggunaannya, dan model yang tidak melaporkan apa pun tidak menambahkan apa pun.
Yang menghentikan build
Masing-masing berikut adalah kalimat yang dicetak oleh build, yang menyebutkan apa yang perlu diubah:
-
Biaya dalam dolar AS. Tetapkan
unit: usdpada lampiran dan build berhenti sebelum apa pun dirender:[… 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 -
Anggaran per pemanggil,
scope: caller, sementara Release tidak mendeklarasikan pemanggil. Gateway membedakan pemanggil berdasarkan kunci yang diberikan masing-masing, dan tanpainfra.callerssetiap rute terbuka. Dengan pemanggil yang dideklarasikan, seperti pada bagian berikutnya, masing-masing memiliki hitungan sendiri di seluruh rute. -
Satu bulan kalender,
period: 1mo, dan batas yang bukan bilangan bulat token. -
Lampiran
core/period-budgetkedua pada gateway, yang menjalankan satu batas laju token pada sebuah rute. -
Tidak ada yang dihubungkan ke socket
models, sehingga tidak tersisa rute model untuk dihitung. Jika hanya kedua koneksi itu yang dihapus, Component milik gateway sendiri akan menghentikan build lebih dulu, meminta store etcd dan kunci Admin API yang menjadi tempat gateway tanpa model menyimpan rutenya. -
Realisasi yang lain. Petakan
core/gateway/apisixkehelm/apisixdalam Manifest dan build berhenti pada koneksimodels, dengan menyebuthelm/apisix-chart: realisasi tersebut menjalankan APISIX 3.17.0 dengan rutenya di etcd dan tidak merender rute apa pun. Build juga berhenti pada lampiran anggaran, karena realisasi itu tidak memiliki rute untuk menuliskannya dan, pada 3.17.0, setiap proses gateway menghitung sendiri-sendiri.
Cache semantik memerlukan pemanggil
APISIX 3.18.0 menyertakan cache semantik, dan core/semantic-caching dapat dilampirkan ke
gateway ini. Tambahkan satu ke features milik gateway di aggregate.yaml:
answers: type: core/semantic-caching values: embedding_model: assistant similarity_threshold: 0.9 ttl_seconds: 3600Manifest sudah merutekan Feature tersebut ke realisasi APISIX-nya, dan build terhenti:
[… 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 usersCache menyimpan balasan untuk siapa pun yang kemudian menanyakan sesuatu yang cukup mirip, sehingga siapa
yang berbagi satu cache menentukan siapa yang dapat dilayani balasan yang dihasilkan untuk orang lain.
Gateway ini dapat memisahkan setiap pemanggil berdasarkan kunci yang diberikannya, yang
diverifikasinya, dan tidak lebih halus dari itu: tetapkan scope: key dan build terhenti lagi, kini karena
pemanggil yang belum diberikan kepadanya:
[… 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 slotTiga tambahan membuatnya dapat di-build. Release menyebutkan para pemanggil beserta kuncinya:
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 menghubungkan model yang digunakan cache untuk mengubah setiap prompt menjadi vektor,
serta penyimpanan Redis untuk balasan, dan menyebutkan model embeddings di
lampiran sebagai embedding_model: embedder, dengan 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: cachedengan komponen embeddings (core/ai-model/openai-embedding, dengan values.model diatur ke text-embedding-3-small) dan komponen cache (core/datastore/redis) dideklarasikan di samping model-model, masing-masing ditempatkan di Release, dan Manifest memetakan keduanya serta core/referenced-secret-set ke realisasi Kubernetes-nya, helm/k8s-secret-set, yang menulis kunci langsung ke dalam Secret yang dirender sehingga hanya cocok untuk target pengembangan. File rute kemudian mendeklarasikan setiap pemanggil dan memeriksa kuncinya di setiap rute, dan rute chat membawa 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]Tidak ada kunci pemanggil di dalamnya: setiap consumer menyebutkan variabel yang diisi Deployment
dari Secret yang dirender oleh lampiran caller_keys, dengan nama pemanggil itu sendiri,
lalu menyusunnya menjadi header lengkap:
- 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]Saat run time, permintaan yang tidak menyertakan kunci yang dideklarasikan, sebagai Authorization: Bearer <key>, ditolak dengan HTTP 401, dan kunci dihapus dari permintaan yang
diteruskan gateway. Balasan disimpan berdasarkan rute dan pemanggil, sehingga prompt yang diubah susunan katanya oleh seorang
pemanggil dilayani dengan balasan yang disimpan untuk pemanggil tersebut dan tidak pernah
dengan balasan yang disimpan untuk pemanggil lain. Balasan yang dilayani dari cache tidak dihitung terhadap
anggaran, dan tetap dilayani meskipun batasnya terlampaui. Koneksi embedder mendapatkan rute
sendiri, sebagaimana setiap koneksi pada soket models.
Bagian yang tidak ditafsirkan oleh kompiler
Compiler menyalurkan batas, jendela, dan satuan ke dalam berkas rute sebagai string, serta endpoint dan nama model setiap model dari apa yang dipublikasikan model tersebut. Compiler tidak menghubungi OpenAI, tidak mengetahui apakah sebuah balasan melaporkan token-nya, dan tidak menghitung apa pun sendiri. Setiap penghentian di atas dideklarasikan oleh entitas katalog itu sendiri, sebagai asersi dalam realisasi anggaran atau cache, atau dalam Recipe lain milik gateway, dan tidak satu pun bergantung pada pemahaman apa pun tentang lalu lintas.
Menyesuaikannya
- Batas per model. Tetapkan
scope: model: setiap alias mendapatkan layanan dan hitungannya sendiri. - Batas per pemanggil. Deklarasikan para pemanggil beserta kuncinya di Release, seperti pada “A semantic cache needs callers” di atas, lalu tetapkan
scope: caller: setiap pemanggil mendapatkan hitungannya sendiri di seluruh rute. - Hitung satu sisi. Tetapkan
unit: prompt_tokensuntuk menghitung apa yang dibaca model, ataucompletion_tokensuntuk apa yang ditulisnya. - Jendela yang lebih pendek atau lebih panjang. Tetapkan
periodke sejumlah detik, menit, jam, atau hari di Release, seperti6hatau30d.