モデルをトークン予算内に収める APISIX ゲートウェイ
あるチームが 2 つの OpenAI モデルを 1 つのゲートウェイの背後に置き、
ゲートウェイがそれらに費やす量の 1 日あたりの上限を、トークン数で設けたいと考えています。このワークスペースは、
そのようなゲートウェイを Kubernetes マニフェストにコンパイルします。2 つのモデルの前段に Apache APISIX を置き、
core/period-budget をアタッチしたものです。
このページでは、セマンティックキャッシュがビルドされる前にこのゲートウェイに何を必要とするかも示します。 それは、提示するキーによってそれぞれを区別できる呼び出し元と、 応答を保存するストアです。
このワークスペースは独自のカタログエンティティを一切作成しません。 ここにある 3 つのエンティティファイル — Aggregate、Manifest、Release — が、 誰かが書くもののすべてです。
構築されるもの
| インスタンス | カタログの Component | ここでの役割 |
|---|---|---|
gateway | core/gateway/apisix | ゲートウェイ。2 つのエイリアスを提供します: モデル chat からの assistant と、モデル mini からの summarizer |
chat | core/ai-model/openai | OpenAI の gpt-4o。参照として到達します: クラスタ内ではこのために何も実行されません |
mini | core/ai-model/openai | OpenAI の gpt-4o-mini。同じ方法で到達します |
ゲートウェイの models ソケットへの 2 本の uses エッジがあり、それぞれが一方のモデルにつながり、
ゲートウェイがそのモデルに提示するキーを credential として運びます。どちらも
1 つのパラメータ openai_key を読み、それを Release が満たします。ゲートウェイには 1 つの Feature
アタッチメント budget があります。Aggregate は何を数えるか (total_tokens) と、1 つの上限がどのトラフィックを対象とするか (gateway —
ゲートウェイが提供するすべて) を書き、Release はどれだけの量をどの期間で数えるかを書きます: 1 日あたり 200 万
トークンです。
Manifest はゲートウェイを apisix-chart にマッピングします。これは
プロジェクト独自の APISIX チャートを APISIX 3.18.0 でレンダリングし、ゲートウェイに接続されたモデルを提供する realization です。
モデルが接続されている場合、ゲートウェイはそれとともにレンダリングされたファイルからルートを読むため、
etcd 接続も Admin API キーも必要としません。
Aggregate はどちらも接続しません。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example apisix-token-budgetその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd apisix-token-budgetビルド
aggrega build --release release.yaml --auto-pullrelease はビルドの前に lockfile を必要とします。lockfile は同梱されるのではなく生成されるため、クローンした直後には存在しません。先に解決するか、ビルドに作成させてください:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the build解決すると、gateway の Recipe がレンダリングする APISIX chart が固定されます。この chart は chart 自身のリポジトリから取得されるため、ネットワーク接続が必要です。このワークスペースは、.aggrega-config.yaml が指定するデフォルトレジストリからカタログのエンティティを解決します。
ビルドは次のように出力します。<workspace> はこの例のフォルダを表します。
[… 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>/distAI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーを自分で作成しないでください。ワークスペースフォルダーにまだ `apisix-token-budget` フォルダーがない場合は、`example` を `apisix-token-budget` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、サンプルが新しい `apisix-token-budget` フォルダーに書き出されます。次に、`workspace_root` を `apisix-token-budget`、`release` を `release.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き出したファイルを教えてください。ファイルは `apisix-token-budget/dist/` の下にあります。レンダリングされたツリー
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予算は独自のファイルを持ちません。予算の働きはルートファイル dist/helm/gateway/model-routes.yaml に書き込まれます。これはゲートウェイがマウントし、ルーティング設定全体を読み込む ConfigMap です。各モデルは 1 つのファイルをレンダリングします。これはクラスタ内の名前を OpenAI の API ホストにマッピングする Service です。また、モデル接続上の各認証情報は、それぞれ独自の Secret をレンダリングします。その名前はゲートウェイと接続のエイリアスに由来します。
ゲートウェイが読み取る予算
その ConfigMap の apisix.yaml キーは次のとおりです。
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ここから読み取れることが 5 つあります。
予算は、両方のルートが参照するサービスに置かれます。 APISIX のトークンレート制限である ai-rate-limiting は、宣言されたオブジェクトの下でカウントを保持します。各ルートに記述すると、ルートごとに 1 つのカウントを保持します。すべてのルートが service_id で参照する model-budget に 1 回だけ記述すると、ゲートウェイが提供するすべてに対して 1 つのカウントを保持します。これはアタッチメントが要求した gateway スコープです。scope: model の場合、Recipe は代わりに接続ごとに 1 つのサービス model-assistant-budget と model-summarizer-budget を書き出すため、各モデルが独自の上限を持ちます。
期間は秒単位のウィンドウです。 1d は 86400 として書き出されます。ウィンドウは、前のウィンドウが閉じた後の最初のモデルリクエストで開き、その長さだけ続きます。深夜 0 時に始まるわけではありません。暦月には決まった秒数がないため、後述のとおり 1mo は拒否されます。
単位はカウントする対象です。 total_tokens は、各モデルの応答が報告する読み取りと書き込みを合わせたトークン数です。prompt_tokens と completion_tokens は片側のみをカウントします。ゲートウェイは応答が報告する値をカウントし、価格付けは一切行わないため、米ドル建ての予算は保持しません。
各モデルにはチャットルートがあり、コンプリーションルートはありません。 予算がなければ、各エイリアスには /<alias>/v1/completions も作られます。APISIX は、プロトコルを認識できるリクエストからのみ応答のトークンを読み取ります。本文に messages ではなく prompt を含むコンプリーションリクエストはそれに該当しないため、応答はされてもカウントはされません。そのため、予算がアタッチされている間はそのルートは書き出されず、コンプリーションリクエストには 404 Route Not Found が返されます。
キーは含まれていません。 各ルートは、接続のベアラートークンを保持する変数を APISIX の $env:// 参照で指定します。dist/helm/gateway-deployment-default-gateway.yaml にある、ゲートウェイのコンテナの env は次のとおりです。
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 は replicas: 1 で 1 つのレプリカを実行します。カウントはゲートウェイプロセスのメモリに保持されるため、2 つ目のレプリカは独自のカウントを保持することになります。予算がアタッチされている間、Recipe はチャートを 1 レプリカに固定します。
実行時にゲートウェイが行うこと
モデルへのリクエストごとに、ゲートウェイはカウントを limit と照合します。カウントがその値に達すると、ゲートウェイはウィンドウが閉じるまで 503 Service Temporarily Unavailable
を返し、リクエストはモデルに送られません。このレスポンスには、ゲートウェイ自身の X-AI-RateLimit-Limit-…、
X-AI-RateLimit-Remaining-…、X-AI-RateLimit-Reset-… ヘッダーが付きます。リクエストのトークンは応答が完了した時点で加算されるため、カウントを上限に到達させたリクエストは処理され、それと並行してすでに処理中のリクエストも同様に処理されます。
ここから 2 つの帰結が生じます。どちらも設定ではなくゲートウェイの動作によるものです。
- 再起動すると新しいウィンドウが始まります。 カウントはゲートウェイプロセスの メモリに保持されるため、ロールアウトまたは再起動された Pod はゼロからカウントを始めます。
- トークンを報告しない応答は何もカウントしません。 カウントは各モデルが 報告する値です。ゲートウェイはストリーミングのチャットリクエストに使用量の報告を求めますが、 何も報告しないモデルは何も加算しません。
ビルドを停止させるもの
以下はいずれもビルドが出力する文で、変更すべき箇所を示します。
-
米ドル建てのコスト。 アタッチメントで
unit: usdを設定すると、何もレンダリングされないうちにビルドが停止します:[… 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 -
呼び出し元ごとの予算(
scope: caller)で、Release が呼び出し元を宣言していない場合。ゲートウェイは各呼び出し元が提示するキーによって呼び出し元を区別し、infra.callersがなければすべてのルートが開放されます。次のセクションのように呼び出し元を宣言すると、各呼び出し元はすべてのルートにわたって独自のカウントを持ちます。 -
暦月(
period: 1mo)、およびトークン数が整数でない上限。 -
ゲートウェイ上の 2 つ目の
core/period-budgetアタッチメント。ゲートウェイは 1 つのルートで 1 つのトークンレート制限を実行します。 -
modelsソケットに何も接続されていない場合。カウントするモデルルートが残りません。2 つの接続だけを削除すると、ゲートウェイ自身の Component が先にビルドを停止し、etcd ストアと Admin API キーを要求します。モデルを持たないゲートウェイは、これらを通じてルートを保持するためです。 -
もう一方の実現。 Manifest で
core/gateway/apisixをhelm/apisixにマッピングすると、ビルドはmodelsの接続で停止し、helm/apisix-chartを名指しします。この実現は APISIX 3.17.0 を実行し、ルートを etcd に置くため、ルートを何もレンダリングしません。予算アタッチメントでも停止します。書き込む先のルートがなく、また 3.17.0 では各ゲートウェイプロセスが個別にカウントするためです。
セマンティックキャッシュには呼び出し元が必要です
APISIX 3.18.0 はセマンティックキャッシュを備えており、core/semantic-caching はこのゲートウェイにアタッチできます。aggregate.yaml のゲートウェイの features に 1 つ追加します。
answers: type: core/semantic-caching values: embedding_model: assistant similarity_threshold: 0.9 ttl_seconds: 3600Manifest はすでにこの Feature を APISIX の実現にルーティングしており、ビルドは停止します。
[… 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キャッシュは、後から十分に近い内容を尋ねた相手のために応答を保持します。そのため、誰が 1 つのキャッシュを共有するかによって、誰が他人のために生成された応答を受け取りうるかが決まります。このゲートウェイは、各呼び出し元が提示するキーによって呼び出し元を分離でき、そのキーを検証しますが、それより細かい分離はできません。scope: key を設定すると、ビルドは再び停止し、今度は与えられていない呼び出し元について停止します。
[… 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 slot3 つの追加でビルドが通ります。Release は呼び出し元とそのキーを指定します。
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 は、キャッシュが各プロンプトをベクトルに変換するためのモデルと、応答を保存する Redis ストアを接続し、アタッチメントで埋め込みモデルを embedding_model: embedder として、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: cacheembeddings コンポーネント(core/ai-model/openai-embedding、その values.model は text-embedding-3-small に設定)と cache コンポーネント(core/datastore/redis)をモデルの隣に宣言し、それぞれを Release に配置します。Manifest はその両方と、core/referenced-secret-set をその Kubernetes での実現である helm/k8s-secret-set にマッピングします。この実現はキーをレンダリングされた Secret に直接書き込むため、開発用のターゲットにのみ適しています。その後、ルートファイルは各呼び出し元を宣言してすべてのルートでそのキーを検査し、チャットルートがキャッシュを持ちます。
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]呼び出し元のキーはここには含まれません。各コンシューマーは、caller_keys アタッチメントがレンダリングする Secret から Deployment が呼び出し元自身の名前で設定する変数を指定し、それをヘッダー全体に組み立てます。
- 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]実行時、宣言されたキーを Authorization: Bearer <key> として提示しないリクエストは HTTP 401 で拒否され、ゲートウェイが転送するリクエストからはキーが取り除かれます。応答はルートと呼び出し元の下に保存されるため、ある呼び出し元が言い換えたプロンプトにはその呼び出し元のために保存された応答が返され、別の呼び出し元のために保存された応答が返されることはありません。キャッシュから返された応答は予算に一切カウントされず、上限を超えても返されます。embedder 接続には、models ソケット上のすべての接続と同様に、独自のルートが与えられます。
コンパイラが解釈しない箇所
コンパイラは、上限、ウィンドウ、単位を文字列としてルートファイルに渡し、各モデルのエンドポイントとモデル名はそのモデルが公開するものから渡します。OpenAI に接続することはなく、応答がトークン数を報告するかどうかも知らず、自らは何もカウントしません。上記の各停止はカタログ自身のエンティティによって、予算またはキャッシュの実現、あるいはゲートウェイのもう一方の Recipe におけるアサーションとして宣言されており、いずれもトラフィックについての理解に基づくものではありません。
応用する
- モデルごとの上限。
scope: modelを設定します。各エイリアスが専用のサービスと カウントを持ちます。 - 呼び出し元ごとの上限。 前述の「A semantic cache needs callers」のとおりに Release で呼び出し元とそのキーを宣言し、
scope: callerを設定します。各 呼び出し元が、すべてのルートにわたって専用のカウントを持ちます。 - 片側だけを数える。 モデルが読む量を数えるには
unit: prompt_tokensを設定し、 モデルが書く量を数えるにはcompletion_tokensを設定します。 - より短い、またはより長いウィンドウ。 Release で
periodを秒、分、 時間、または日の数で設定します。たとえば6hや30dのようにします。