Modellerini bir token bütçesiyle sınırlayan bir APISIX ağ geçidi
Bir ekip iki OpenAI modelini tek bir ağ geçidinin arkasına koyar ve ağ geçidinin
bunlara her gün harcadığı miktar için, token cinsinden sayılan bir üst sınır ister. Bu çalışma alanı
böyle bir ağ geçidini Kubernetes manifestlerine derler: iki modelin önünde Apache APISIX,
core/period-budget eklenmiş olarak.
Sayfa ayrıca bir anlamsal önbelleğin oluşturulmadan önce bu ağ geçidinden neye ihtiyaç duyduğunu da gösterir: her biri sunduğu anahtarla birbirinden ayırt edebileceği çağıranlar ve yanıtlar için bir depo.
Bu çalışma alanı kendine ait hiçbir katalog varlığı yazmaz. Buradaki üç varlık dosyası — bir Aggregate, bir Manifest ve bir Release — herhangi birinin yazdığı şeylerin tamamıdır.
Ne oluşturur
| örnek | katalog Component’i | burada ne olduğu |
|---|---|---|
gateway | core/gateway/apisix | iki takma ad sunan ağ geçidi: chat modelinden assistant ve mini modelinden summarizer |
chat | core/ai-model/openai | OpenAI’ın gpt-4o modeli, bir başvuru olarak erişilir: küme içinde onun için hiçbir şey çalışmaz |
mini | core/ai-model/openai | OpenAI’ın gpt-4o-mini modeli, aynı şekilde erişilir |
Ağ geçidinin models soketine giren, her modele birer tane olmak üzere iki uses kenarı; her biri credential olarak ağ geçidinin o modele sunduğu anahtarı taşır; ikisi de Release’in karşıladığı tek bir parametreyi, openai_key’i okur. Ağ geçidinde tek bir Feature eki, budget: Aggregate neyin sayıldığını, total_tokens’ı, ve tek bir sınırın kimin trafiğini kapsadığını, gateway’i — ağ geçidinin sunduğu her şeyi — yazar; Release ise ne kadar ve ne kadar süre boyunca olduğunu yazar: günde iki milyon token.
Manifest, ağ geçidini projenin kendi APISIX chart’ını APISIX 3.18.0 sürümünde oluşturan ve ağ geçidine bağlanan modelleri sunan gerçekleştirme olan apisix-chart’a eşler. Bir model bağlandığında ağ geçidi rotalarını kendisiyle birlikte oluşturulan bir dosyadan okur; bu nedenle etcd bağlantısı ve Admin API anahtarı almaz; Aggregate de ikisini de bağlamaz.
Örneği oluşturun
Bu örneği aşağıdaki komutlarla derleyebilir ya da yapay zekâ asistanınıza sizin için derletebilirsiniz.
Örneği, adını taşıyan yeni bir klasöre yazın:
aggrega scaffold --example apisix-token-budgetArdından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:
cd apisix-token-budgetDerleme
aggrega build --release release.yaml --auto-pullBir release, derlenmeden önce bir kilit dosyasına ihtiyaç duyar ve kilit dosyaları dağıtılmak yerine üretildiğinden yeni bir klonda hiç kilit dosyası bulunmaz. Önce bir tane çözümleyin ya da derlemenin onu doldurmasına izin verin:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildÇözümleme, gateway’in Recipe’inin oluşturduğu APISIX chart’ını chart’ın kendi deposundan alarak sabitler; bu nedenle ağ bağlantısı gerektirir. Bu çalışma alanı, katalog varlıklarını .aggrega-config.yaml dosyasının adlandırdığı varsayılan kayıt defterinden çözümler.
Derleme, <workspace> bu örneğin klasörünü temsil edecek şekilde şunu yazdırır:
[… 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>/distBir yapay zekâ asistanıyla
Aggrega araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.
Yalnızca Aggrega araçlarını kullanın ve kendiniz hiçbir klasör oluşturmayın. Çalışma alanı klasöründe henüz `apisix-token-budget` klasörü yoksa `scaffold` aracını `example` değeri `apisix-token-budget` olarak ayarlanmış ve `dir` olmadan bir kez çağırın: örneği yeni bir `apisix-token-budget` klasörüne yazar. Ardından `build` aracını `workspace_root` değeri `apisix-token-budget`, `release` değeri `release.yaml`, `auto_pull` değeri true ve `write` değeri true olarak ayarlanmış şekilde çağırın. Derlemenin hangi dosyaları yazdığını bana söyleyin; dosyalar `apisix-token-budget/dist/` altındadır.Oluşturulan ağaç
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.yamlBütçe kendine ait bir dosya getirmez. Yaptığı şey, rotalar dosyasına, dist/helm/gateway/model-routes.yaml’a yazılır; bu, ağ geçidinin bağladığı ve tüm yönlendirme yapılandırmasını okuduğu bir ConfigMap’tir. Her model tek bir dosya oluşturur: küme içi bir adı OpenAI’ın API ana makinesine eşleyen bir Service. Bir model bağlantısındaki her kimlik bilgisi de ağ geçidinin ve bağlantının takma adının adını taşıyan kendine ait bir Secret oluşturur.
Ağ geçidinin okuduğu biçimiyle bütçe
Bu ConfigMap’in apisix.yaml anahtarı şöyledir:
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]#ENDBuradan okunmaya değer beş şey vardır.
Bütçe, her iki rotanın da adını verdiği bir hizmette bulunur. APISIX’in token hız
sınırlaması ai-rate-limiting, sayımını bildirildiği nesnenin altında tutar.
Her rotaya yazılsaydı rota başına bir sayım tutardı; her rotanın service_id aracılığıyla adını verdiği
model-budget üzerine bir kez yazıldığında, ağ geçidinin sunduğu her şey için tek bir
sayım tutar: bağlamanın istediği gateway kapsamı. scope: model ile Recipe bunun yerine
bağlantı başına bir hizmet yazar, model-assistant-budget ve model-summarizer-budget; böylece her modelin
kendine ait bir sınırı olur.
Dönem, saniyelerden oluşan bir penceredir. 1d, 86400 olarak yazılır. Pencere,
önceki pencere kapandıktan sonraki ilk model isteğiyle açılır ve o süre boyunca sürer;
gece yarısında başlamaz. Bir takvim ayının sabit bir saniye sayısı yoktur,
bu nedenle 1mo aşağıda görüldüğü gibi reddedilir.
Birim, sayılan şeydir. total_tokens, her modelin yanıtının okuma ve yazma için
birlikte bildirdiği token’lardır; prompt_tokens ve
completion_tokens yalnızca bir tarafı sayar. Ağ geçidi yanıtın bildirdiğini sayar
ve hiçbir şeyi fiyatlandırmaz; bu nedenle ABD doları cinsinden bir bütçe tutmaz.
Her modelin bir sohbet rotası vardır, tamamlama rotası yoktur. Bütçe olmadan
her takma ad ayrıca /<alias>/v1/completions rotasını da alır. APISIX bir yanıtın token’larını
yalnızca protokolünü tanıdığı bir istekten okur; gövdesi messages yerine prompt
taşıyan bir tamamlama isteği bunlardan biri değildir: yanıtlanır ama hiç
sayılmazdı. Bu nedenle bütçe bağlıyken bu rota yazılmaz ve bir tamamlama isteği
404 Route Not Found ile yanıtlanır.
İçinde hiçbir anahtar yoktur. Her rota, bağlantısının bearer token’ını tutan değişkeni
APISIX’in $env:// başvurusuyla adlandırır.
dist/helm/gateway-deployment-default-gateway.yaml dosyasından, ağ geçidinin
kapsayıcısının env bölümü:
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]Aynı Deployment tek bir kopya çalıştırır, replicas: 1. Sayım ağ geçidi sürecinin
belleğinde tutulur; bu nedenle ikinci bir kopya kendi sayımını tutardı.
Bir bütçe bağlıyken Recipe chart’ı tek kopyada tutar.
Ağ geçidinin çalışma zamanında yaptıkları
Ağ geçidi her model isteğinde sayımı limit ile karşılaştırır. Sayım bu değere ulaştığında, ağ geçidi pencere kapanana kadar isteği modele hiç göndermeden 503 Service Temporarily Unavailable
yanıtını verir; yanıt, ağ geçidinin kendi X-AI-RateLimit-Limit-…,
X-AI-RateLimit-Remaining-… ve X-AI-RateLimit-Reset-… başlıklarını taşır. Bir isteğin
token’ları yanıtı tamamlandığında eklenir; bu nedenle sayımı sınıra ulaştıran istek
yanıtlanır, onunla birlikte o sırada işlenmekte olan her istek de yanıtlanır.
Bundan iki sonuç çıkar ve ikisi de yapılandırma değil, ağ geçidinin davranışıdır:
- Yeniden başlatma yeni bir pencere başlatır. Sayım ağ geçidi sürecinin belleğinde tutulur; bu nedenle yeniden dağıtılan ya da yeniden başlatılan bir pod saymaya sıfırdan başlar.
- Hiç token bildirmeyen bir yanıt hiçbir şey saymaz. Sayım, her modelin bildirdiği değerdir; ağ geçidi akışlı bir sohbet isteğinden kullanımını bildirmesini ister ve hiçbir şey bildirmeyen bir model sayıma hiçbir şey eklemez.
Derlemeyi durduran durumlar
Bunların her biri, derlemenin yazdırdığı ve neyin değiştirileceğini belirten bir cümledir:
-
ABD doları cinsinden bir maliyet. Eklentide
unit: usdayarlandığında derleme herhangi bir şey işlenmeden önce durur:[… 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 -
Çağıran başına bir bütçe,
scope: caller, Release hiçbir çağıran bildirmediği hâlde. Ağ geçidi çağıranları her birinin sunduğu anahtarla ayırt eder veinfra.callersolmadığında her rota açıktır. Bir sonraki bölümde olduğu gibi çağıranlar bildirildiğinde, her birinin tüm rotalar genelinde kendine ait bir sayacı olur. -
Bir takvim ayı,
period: 1mo, ve tam sayı olmayan bir token sınırı. -
Ağ geçidinde ikinci bir
core/period-budgeteklentisi; ağ geçidi bir rotada tek bir token hız sınırı çalıştırır. -
modelssoketine hiçbir şey bağlı değil; bu durumda sayılacak model rotası kalmaz. Yalnızca iki bağlantıyı kaldırırsanız, önce ağ geçidinin kendi Component’i derlemeyi durdurur ve modeli olmayan bir ağ geçidinin rotalarını aracılığıyla tuttuğu etcd deposunu ve Admin API anahtarını ister. -
Diğer gerçekleştirim. Manifest’te
core/gateway/apisixöğesinihelm/apisixile eşlediğinizde derlememodelsbağlantılarında durur vehelm/apisix-chartadını verir: bu gerçekleştirim APISIX 3.17.0’ı rotaları etcd’de olacak şekilde çalıştırır ve hiç rota işlemez. Bir bütçe eklentisinde de durur, çünkü eklentiyi yazabileceği bir rota yoktur ve 3.17.0’da her ağ geçidi süreci kendi başına sayar.
Anlamsal önbellek çağıranlara ihtiyaç duyar
APISIX 3.18.0 bir anlamsal önbellek içerir ve core/semantic-caching bu ağ geçidine eklenir. aggregate.yaml dosyasında ağ geçidinin features listesine bir tane ekleyin:
answers: type: core/semantic-caching values: embedding_model: assistant similarity_threshold: 0.9 ttl_seconds: 3600Manifest, Feature’ı zaten APISIX gerçekleştirimine yönlendirir ve derleme durur:
[… 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Önbellek, bir yanıtı daha sonra yeterince yakın bir şey soran herkes için saklar; bu nedenle bir önbelleği kimin paylaştığı, başkası için üretilmiş bir yanıtın kime sunulabileceğini belirler. Bu ağ geçidi her çağıranı, doğruladığı ve çağıranın sunduğu anahtara göre ayrı tutabilir, daha ince bir ayrım yapamaz: scope: key ayarlayın; derleme yeniden durur, bu kez kendisine verilmemiş çağıranlar nedeniyle:
[… 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 slotDerlemenin başarılı olması için üç ekleme gerekir. Release, çağıranları ve anahtarlarını adlandırır:
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, önbelleğin her istemi vektöre dönüştürmek için kullandığı modeli ve yanıtlar için bir Redis deposunu bağlar, eklentide gömme modelini scope: key ile birlikte embedding_model: embedder olarak adlandırır:
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: cachebunun için embeddings bileşeni (core/ai-model/openai-embedding, values.model değeri text-embedding-3-small olarak ayarlanmış) ve cache bileşeni (core/datastore/redis) modellerin yanında bildirilir, her biri Release’e yerleştirilir ve Manifest ikisini de ve core/referenced-secret-set’i Kubernetes gerçekleştirimine, helm/k8s-secret-set’e eşler; bu gerçekleştirim anahtarları doğrudan işlenmiş bir Secret’a yazdığından yalnızca bir geliştirme hedefine uygundur. Ardından rotalar dosyası her çağıranı bildirir ve anahtarını her rotada denetler; sohbet rotası da önbelleği taşır:
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]İçinde hiçbir çağıranın anahtarı yoktur: her tüketici, Deployment’ın caller_keys eklentisinin işlediği Secret’tan çağıranın kendi adı altında doldurduğu bir değişkeni adlandırır ve bunu başlığın tamamına dönüştürür:
- 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]Çalışma zamanında, bildirilmiş bir anahtarı Authorization: Bearer <key> olarak sunmayan bir istek HTTP 401 ile reddedilir ve anahtar, ağ geçidinin ilettiği istekten kaldırılır. Bir yanıt rota ve çağıran altında saklanır; böylece bir çağıranın yeniden ifade edilmiş istemine o çağıran için saklanan yanıt sunulur, asla başka biri için saklanan yanıt sunulmaz. Önbellekten sunulan bir yanıt bütçeye hiçbir şey saymaz ve sınırın aşılmasından sonra da sunulur. embedder bağlantısı, models soketindeki her bağlantı gibi kendine ait rotalar alır.
Derleyicinin yorumlamadığı yerler
Derleyici limiti, pencereyi ve birimi routes dosyasına dize olarak aktarır; her modelin uç noktasını ve model adını da o modelin yayımladıklarından alır. OpenAI’ye ulaşmaz, bir yanıtın token sayısını bildirip bildirmediğini bilmez ve kendisi hiçbir şey saymaz. Yukarıdaki her durdurma, katalogun kendi varlıkları tarafından, bütçenin veya önbelleğin gerçekleştirmesinde ya da ağ geçidinin diğer Recipe’sinde bir doğrulama olarak bildirilir ve hiçbiri trafiğin herhangi bir şekilde anlaşılmasına dayanmaz.
Uyarlama
- Model başına bir sınır.
scope: modelayarlayın: her takma ad kendine ait bir hizmet ve bir sayaç alır. - Çağıran başına bir sınır. Yukarıdaki “Anlamsal önbellek çağıranlara ihtiyaç duyar” bölümünde olduğu gibi çağıranları ve anahtarlarını Release’te bildirin ve
scope: callerayarlayın: her çağıran, tüm yollar genelinde kendine ait bir sayaç alır. - Tek bir tarafı sayma. Modellerin okuduğunu saymak için
unit: prompt_tokens, yazdıklarını saymak içincompletion_tokensayarlayın. - Daha kısa veya daha uzun bir pencere. Release’te
perioddeğerini saniye, dakika, saat veya gün cinsinden bir sayıya ayarlayın; örneğin6hveya30d.