Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

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

instansComponent katalogperannya di sini
gatewaycore/gateway/apisixgateway, yang melayani dua alias: assistant, dari model chat, dan summarizer, dari model mini
chatcore/ai-model/openaigpt-4o milik OpenAI, dijangkau sebagai referensi: tidak ada yang berjalan untuknya di dalam klaster
minicore/ai-model/openaigpt-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:

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

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

Terminal window
cd apisix-token-budget

Build

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

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

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

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

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

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

Ada 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: usd pada 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 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
  • Anggaran per pemanggil, scope: caller, sementara Release tidak mendeklarasikan pemanggil. Gateway membedakan pemanggil berdasarkan kunci yang diberikan masing-masing, dan tanpa infra.callers setiap 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-budget kedua 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/apisix ke helm/apisix dalam Manifest dan build berhenti pada koneksi models, dengan menyebut helm/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: 3600

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

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

Tiga 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: cache

dengan 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_tokens untuk menghitung apa yang dibaca model, atau completion_tokens untuk apa yang ditulisnya.
  • Jendela yang lebih pendek atau lebih panjang. Tetapkan period ke sejumlah detik, menit, jam, atau hari di Release, seperti 6h atau 30d.