İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

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

örnekkatalog Component’iburada ne olduğu
gatewaycore/gateway/apisixiki takma ad sunan ağ geçidi: chat modelinden assistant ve mini modelinden summarizer
chatcore/ai-model/openaiOpenAI’ın gpt-4o modeli, bir başvuru olarak erişilir: küme içinde onun için hiçbir şey çalışmaz
minicore/ai-model/openaiOpenAI’ı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:

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

Ardından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:

Terminal window
cd apisix-token-budget

Derleme

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

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

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

Çö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>/dist

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

Bü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]
#END

Buradan 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: usd ayarlandığı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 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
  • Ç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 ve infra.callers olmadığı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-budget eklentisi; ağ geçidi bir rotada tek bir token hız sınırı çalıştırır.

  • models soketine 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 öğesini helm/apisix ile eşlediğinizde derleme models bağlantılarında durur ve helm/apisix-chart adı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: 3600

Manifest, 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 slot

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

bunun 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: model ayarlayı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: caller ayarlayı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çin completion_tokens ayarlayın.
  • Daha kısa veya daha uzun bir pencere. Release’te period değerini saniye, dakika, saat veya gün cinsinden bir sayıya ayarlayın; örneğin 6h veya 30d.