コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

OpenAI の前段に置く Envoy Gateway と月間トークン予算

あるチームが OpenAI の gpt-4o-mini をクラスタ内のゲートウェイの背後に置き、 ゲートウェイがそのモデルに費やすトークンに暦月ごとの上限を設け、エージェントの接続先を OpenAI ではなくゲートウェイにしたいとします。このワークスペースはそれを Kubernetes マニフェストにコンパイルします。Envoy AI Gateway を通じてモデルを提供する Envoy Gateway に core/period-budget をアタッチし、Redis がカウントを保持し、CrewAI エージェントが モデルへのリクエストをゲートウェイ経由で送信します。

このページでは、このゲートウェイがカウントを拒否するものも示します。米ドル建ての予算は ビルドを停止させ、呼び出し元ごとの予算も同様にビルドを停止させます。

このワークスペースは独自のカタログエンティティを一切作成しません。 ここにある 3 つのエンティティファイル — Aggregate、Manifest、Release — が、 誰かが書くもののすべてです。

構築されるもの

インスタンスカタログの Componentここでの役割
edgecore/gateway/envoy-gatewayゲートウェイ。モデル chat から 1 つのエイリアス assistant を提供します
ai-controllercore/gateway/envoy-ai-gateway-operatorEnvoy AI Gateway のコントローラ。ゲートウェイが拡張サーバーとして呼び出すもので、6 つの AI Gateway リソース定義とともにインストールされます
chatcore/ai-model/openaiOpenAI の gpt-4o-mini。参照として到達されるもので、クラスタ内ではこのために何も実行されません
counterscore/datastore/redisゲートウェイのレート制限サービスが予算のカウントを保持するストア
assistantcore/ai-agent/crewaiモデルへのリクエストがゲートウェイに送られるエージェント
certscore/security/cert-managercert-manager。コントローラの Webhook が提供する証明書を発行します

ゲートウェイの uses エッジは、extension ソケットからコントローラへ、models からモデルへ(ゲートウェイが OpenAI に提示するキーを credential として運びます)、そして cache からストアへ(レート制限サービスがストアに提示するパスワードを運びます)と出ています。エージェントの model エッジは、モデルではなくゲートウェイを指します。ゲートウェイには Feature のアタッチメントが 1 つ、budget があります。Aggregate は何をカウントするか(total_tokens)と、1 つの制限がどのトラフィックを対象とするか(gateway、つまりゲートウェイが提供するすべて)を記述し、 Release はどれだけの量をどの期間にわたって許すか、すなわち暦月あたり 2,000 万トークンを記述します。

Manifest はすべての認証情報を k8s-existing-secret にバインドします。これはワークロードを、その名前空間にすでに存在する Secret に向けるもので、Secret を一切レンダリングしません。そのため、キーやパスワードは Aggregate にも Release にもレンダリング出力にも含まれません。Secret の名前は Release が満たす 2 つのパラメータであり、ストア自身の password スロットはゲートウェイの cache 接続と同じパラメータを読み取ります。そのため、ストアと、ストアにパスワードを提示するサービスは、同じ 1 つの Secret を指します。

Release は各ワークロードの実行場所を宣言します。cert-manager は cert-manager に、コントローラは envoy-ai-gateway-system に、エージェントは assistant に、ゲートウェイは envoy-gateway-system に配置され(コントローラはゲートウェイのコントロールプレーンをそこで探すため、ゲートウェイを他の場所に配置するとビルドは停止します)、ストアはゲートウェイと同じ場所に置かれます。モデルは何も実行しません。その唯一のファイルは、クラスタ内の名前を OpenAI のホストにマッピングする Service であり、名前空間を指定しません。また、ゲートウェイはその Service を経由するのではなく、モデルが公開するエンドポイントで OpenAI に到達します。

cert-manager は前提とせず宣言する

コントローラーの webhook は cert-manager が発行する証明書を提供します。その Recipe は cert-manager の Certificate と、それに署名する自己署名の Issuer をレンダリングしますが、これらを調整するのは稼働中の cert-manager だけです。コンパイラはクラスタを調べて cert-manager が稼働しているかどうかを確認できないため、ワークスペースは cert-manager を前提とせずに宣言します。certs は Aggregate 内でコントローラーの隣に置かれ、ビルドは他のすべてと一緒に cert-manager もレンダリングします。

1 つのクラスタで稼働する cert-manager は 1 つです。クラスタですでに cert-manager が稼働している場合は、ビルドの前に Aggregate と Release から certs を削除してください。そうすると、ビルドは cert-manager 自体のファイルを除いた同じファイルをレンダリングします。

サンプルを生成する

このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

Terminal window
aggrega scaffold --example envoy-ai-gateway-token-budget

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd envoy-ai-gateway-token-budget

ビルド

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

release はビルドの前に lockfile を必要とします。lockfile は同梱されるのではなく生成されるため、クローンした直後には存在しません。先に解決するか、ビルドに作成させてください:

Terminal window
aggrega pull --release release.yaml --pin-sources # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

解決では、Recipes がレンダリングする 3 つのチャート(Docker Hub から取得する Envoy Gateway と Envoy AI Gateway のチャート、quay.io から取得する cert-manager のチャート)を固定するため、ネットワークが必要です。このワークスペースは、.aggrega-config.yaml が指定するデフォルトレジストリからカタログのエンティティを解決します。

--auto-pull を付けてビルドすると、次のように出力されます(<workspace> はこの例のフォルダを表します):

Pull complete: release.lock (entities=26, source_artifacts=3, external_inputs=0)
[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and the total build time, which differs per run]
Build completed: 113 files written to <workspace>/dist

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `envoy-ai-gateway-token-budget` フォルダーがない場合は、`example` を `envoy-ai-gateway-token-budget` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、例が新しい `envoy-ai-gateway-token-budget` フォルダーに書き込まれます。次に、`workspace_root` を `envoy-ai-gateway-token-budget`、`release` を `release.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。ファイルは `envoy-ai-gateway-token-budget/dist/` の下にあります。

レンダリングされたツリー

dist/helm/
├── ai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yaml
[… omitted: the controller's two cluster roles and their bindings]
├── ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml
├── ai-controller-issuer-envoy-ai-gateway-system-self-signed-issuer-for-mutating-webhook.yaml
├── ai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yaml
├── ai-controller-service-envoy-ai-gateway-system-ai-controller.yaml
[… omitted: the controller's service account]
├── ai-controller/
│ ├── aigateway.envoyproxy.io_aigatewayroutes.yaml
[… omitted: the other five AI Gateway resource definitions]
├── assistant-deployment.yaml
[… omitted: the files cert-manager's chart renders, each named certs-…]
├── chat-service.yaml
├── counters-default-service.yaml
├── counters-deployment.yaml
[… omitted: Envoy Gateway's cluster roles and their bindings]
├── edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml
[… omitted: the resource definitions Envoy Gateway's chart installs]
├── edge-deployment-envoy-gateway-system-envoy-gateway.yaml
[… omitted: the rest of Envoy Gateway's chart — its certificate job, admission configurations, roles, bindings, Service and service accounts]
└── edge/
├── gateway.yaml
├── gatewayclass.yaml
└── models.yaml

予算は独自のファイルを持ちません。予算の働きは、ゲートウェイの 2 つのファイルに書き込まれます。AI ルートとモデルに到達するリソースを保持する dist/helm/edge/models.yaml と、コントロールプレーンの設定である dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml です。

ゲートウェイが読み取る予算

models.yaml から、AI ルートです。

apiVersion: aigateway.envoyproxy.io/v1beta1
kind: AIGatewayRoute
metadata:
[… omitted: the labels and annotations every rendered resource carries]
name: edge-models
namespace: "envoy-gateway-system"
spec:
parentRefs:
- name: edge
kind: Gateway
group: gateway.networking.k8s.io
llmRequestCosts:
- metadataKey: llm_total_token
type: TotalToken
rules:
- matches:
- headers:
- type: Exact
name: x-ai-eg-model
value: "assistant"
backendRefs:
- name: edge-assistant
modelNameOverride: "gpt-4o-mini"

そして同じファイルから、それを制限するトラフィックポリシーです。名前は対象とするルートと同じです。

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
[… omitted: the labels and annotations every rendered resource carries]
name: edge-models
namespace: "envoy-gateway-system"
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: edge-models
rateLimit:
global:
rules:
- limit:
requests: 20000000
unit: Month
shared: true
cost:
request:
from: Number
number: 0
response:
from: Metadata
metadata:
namespace: io.envoy.ai_gateway
key: llm_total_token

コントロールプレーンの設定の envoy-gateway.yaml キーは次のとおりです。

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyGateway
extensionApis:
enableBackend: true
enableEnvoyPatchPolicy: true
extensionManager:
hooks:
xdsTranslator:
post:
- Translation
- Cluster
- Route
translation:
cluster:
includeAll: true
listener:
includeAll: true
route:
includeAll: true
secret:
includeAll: true
service:
fqdn:
hostname: ai-controller.envoy-ai-gateway-system.svc.cluster.local
port: 1063
gateway:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
logging:
level:
default: info
provider:
kubernetes:
rateLimitDeployment:
container:
env:
- name: REDIS_AUTH
valueFrom:
secretKeyRef:
key: password
name: counter-store-password
- name: USE_CALENDAR_MONTH_RATE_LIMIT
value: "true"
image: docker.io/envoyproxy/ratelimit:8fe6ea42
patch:
type: StrategicMerge
value:
spec:
template:
spec:
containers:
- imagePullPolicy: IfNotPresent
name: envoy-ratelimit
shutdownManager:
image: docker.io/envoyproxy/gateway:v1.9.1
type: Kubernetes
rateLimit:
backend:
redis:
url: counters-default.envoy-gateway-system.svc.cluster.local:6379
type: Redis
failClosed: true

ここから読み取れることは次のとおりです。

コストは AI ルートに、制限はそれが変換されたルートに置かれます。 Envoy AI Gateway は、モデルの各応答が報告する total_tokens を読み取り、リクエストのメタデータの llm_total_token に書き込みます。これが llmRequestCosts の宣言する内容です。コントローラは AI ルートを同じ名前 edge-models の HTTP ルートに変換し、トラフィックポリシーはそのルートを対象とします。そのため、予算はモデルのトラフィックに適用され、ゲートウェイに接続された他のルートには適用されません。

応答は完了した時点で課金されます。 cost.request はリクエストの到着時には何も課金せず、cost.response は応答が完了した時点でその応答のトークンを課金します。それまでに課金されたカウントが limit を超えると、リクエストは拒否されます。

ゲートウェイ全体で 1 つのカウントです。 shared: true は、ルートのすべてのルールにわたって 1 つのカウントを保持します。これはアタッチメントが求めた gateway スコープです。 scope: model の場合、Recipe は models ソケット上の接続ごとに 1 つのルールを書き出し、各ルールはリクエストが x-ai-eg-model で指定するモデル名に一致するため、モデルごとに別々にカウントされます。

期間は時計上の単位です。 1mo は unit: Month として書き出され、設定は USE_CALENDAR_MONTH_RATE_LIMIT を通じて、Envoy Gateway のレート制限サービスに、Month を暦月の初日から末日までとしてカウントするよう指示します。この設定はサービスに属するため、この Envoy Gateway インストールが保持するすべての Month のレート制限に適用されます。予算のものにも、それ以外のものにも適用されます。どのウィンドウも、最初のリクエストからではなく UTC の時計上の固定点から始まります。日は 00:00 UTC、週は木曜日から始まります。

カウントは cache ソケット上のストアに保持されます。 rateLimit ブロックは Envoy Gateway 自身のレート制限サービスを有効にし、ゲートウェイの cache ソケットが到達する Redis をそのサービスに指定します。このサービスはコントロールプレーンが自身の名前空間に作成し、管理するすべてのゲートウェイで有効にします。ストアは名前空間なしでホストを公開するため、ゲートウェイは Release がストアを配置する名前空間でそれを修飾します。

応答のないチェックはリクエストを拒否します。 failClosed: true により、ストアまたはレート制限サービスに到達できない間、あるいはチェックが Envoy のレート制限タイムアウト(デフォルトは 20 ms)より長くかかった場合、Envoy はモデルへのリクエストを、カウントせずに処理するのではなく、HTTP 500 で拒否します。この設定はコントロールプレーンに属するため、この Envoy Gateway インストールが保持するすべてのレート制限に適用され、インストールに手動で適用したレート制限もフェイルクローズになります。設定にこれが含まれるのは、予算がアタッチされている間だけです。

パスワードは含まれません。 サービスは、cache 接続の認証情報が指定する Secret counter-store-password から、ストアのパスワードを REDIS_AUTH として読み取ります。この Secret は、サービス自身の名前空間、つまりゲートウェイの名前空間で解決されます。 ストア counters-deployment.yaml は、同じ Secret から読み取った --requirepass で起動します。

エージェントからモデルへの経路

assistant-deployment.yaml から、エージェントのコンテナの env です。

env:
- name: OPENAI_BASE_URL
value: http://envoy-envoy-gateway-system-edge-06431a46.envoy-gateway-system.svc.cluster.local:80/v1
- name: MODEL
value: assistant
- name: CREWAI_ALLOW_DELEGATION
value: "false"
- name: CREWAI_BACKSTORY
value: a help-desk agent answering customers
- name: CREWAI_GOAL
value: answer questions about the product
- name: CREWAI_LOG_LEVEL
value: DEBUG
- name: CREWAI_ROLE
value: support assistant

エージェントはゲートウェイが公開する 2 つのキーを読み取ります。これはモデルが公開する 2 つのキーと同じであるため、エージェントの Recipe はモデルのキーを読むのと同じようにそれらを読み取ります。CREWAI_ 変数は、CrewAI Component が既定で付ける名前のもとで、エージェント自身の値を運びます。アドレスは、Envoy Gateway がゲートウェイのデータプレーン用に作成する Service であり、ゲートウェイの名前空間、その名前、およびその 2 つのハッシュから命名され、envoy-gateway-system で修飾されるため、エージェントの名前空間から解決できます。モデル名はエイリアス assistant です。ルートは、この名前を指定したリクエストをモデルのバックエンドに送り、代わりに gpt-4o-mini を要求します。

バックエンドは、モデルが公開するエンドポイントで OpenAI に到達します。 models.yaml には、ポート 443 の api.openai.com に対する Envoy Gateway の Backend、その証明書をシステムのトラストアンカーに照らして検証する TLS ポリシー、/v1 配下の OpenAI API に対する AIServiceBackend、そしてキーを提示するセキュリティポリシー edge-assistant が含まれています。そのセキュリティポリシーの spec は次のとおりです。

spec:
targetRefs:
- group: aigateway.envoyproxy.io
kind: AIServiceBackend
name: edge-assistant
type: APIKey
apiKey:
secretRef:
name: "openai-api-key"

コントローラーは、ゲートウェイの名前空間にあるその Secret から、データキー apiKey の下にあるキーを読み取り、ベアラートークンとして OpenAI に送信します。そのため、レンダリングされたどのファイルにもキーは含まれず、エージェントがキーを保持することもありません。ゲートウェイは、コントローラーが公開するアドレスでコントローラーを呼び出します。このアドレスは、Release がコントローラーを配置する名前空間で修飾されます。これが上記の extensionManager ブロックです。モデルが接続されている間、ゲートウェイは Envoy AI Gateway のクライアントトラフィックポリシー(models.yaml 内の edge-client-buffer-limit)も受け取り、各受信接続に許可されるバッファを 50Mi に引き上げます。このポリシーはゲートウェイを対象とするため、ゲートウェイに接続されたすべてのルートに適用されます。

実行時にゲートウェイが行うこと

モデルへのリクエストごとに、ゲートウェイはレート制限サービスに、今月これまでに課金されたトークンが limit を超えているかどうかを問い合わせます。超えた時点から、月が終わるまでモデルへのリクエストには HTTP 429 で応答します。リクエストのトークンは応答が完了した時点で加算されるため、上限を超えるリクエストは処理され、それと並行して応答されたリクエストも同様に処理されます。ストアまたはレート制限サービスに到達できない間、あるいはチェックが Envoy のレート制限タイムアウトより長くかかった場合は、上記の failClosed 設定に従ってモデルへのリクエストを HTTP 500 で拒否します。そのため、カウントを確認できない間はモデルへのリクエストが受け付けられることはありません。

そこから生じる以下の点は、設定ではなく製品の挙動です。

  • 障害の直前に受け付けられたリクエストは引き続き処理され、カウントされません。 トークンは応答の後に課金されるため、ストアまたはサービスに到達できない間に完了した応答はカウントに何も加算しません。
  • カウントをメモリに保持するストアは、再起動するとすべてのウィンドウを最初からやり直します。 core/datastore/redis はデフォルトでエントリをメモリに保持するため、再起動したストアはそれまでのカウントを失い、その月の残りはゼロから数え直されます。
  • 使用量を報告しない応答は何も加算しません。 カウントは各応答が報告する値です。Envoy AI Gateway は、ストリーミング応答の最後にも使用量を報告するようモデルに求めます。

ビルドを停止させるもの

以下はいずれもビルドが出力する文で、変更すべき箇所を示します。

  • 米ドル建てのコスト。 アタッチメントで 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 assertions
    caused by: FeatureRecipe "period-budget-envoy-gateway" instance "edge" 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 "edge" asks for unit usd, but core/gateway/envoy-gateway, 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)。ゲートウェイは呼び出し元自身が書き込むヘッダーによってのみ 呼び出し元を区別し、この経路上には呼び出し元が誰かを検証するものがありません。そのため、新しい値を送る呼び出し元は新たな予算を開始し、 値を送らない呼び出し元はカウントされなくなります。

  • ゲートウェイにウィンドウがない期間。 ゲートウェイはレート制限の 1 単位全体を 保持します。1s、1m、1h、1d、7d、30d、365d、1mo、またはそれと同じ 長さを別の表記で書いたもの(24h など)です。2h、14d、2mo は停止します。

  • トークン数が整数でない上限、または 4294967295 を超える上限。

  • ゲートウェイ上の 2 つ目の core/period-budget アタッチメント。このアタッチメントは、モデルを提供するルートに 1 つの予算を書き込みます。

  • models ソケットに何も接続されていない場合はカウントするモデルルートがなくなり、cache ソケットに何も接続されていない場合はカウントを保持する場所がなくなります。モデルの接続だけを外すと、ゲートウェイ自身の Component が先に停止します。values.model が、どこからも提供されていないエイリアスを指すためです。

  • Redis プロトコルを話さない、cache ソケット上のストア — redis または valkey 以外のプロトコルを公開するストア。

  • envoy-gateway-system の外に配置されたゲートウェイ(コントローラーが その extension ソケットに接続されている場合)。

適用する前に

ツリーには Namespace も Secret も含まれないため、 dist/helm/ を受け取るクラスタには以下が必要です。

  • 名前空間 cert-manager、envoy-ai-gateway-system、 envoy-gateway-system、assistant。
  • envoy-gateway-system 内の Secret: OpenAI のキーをデータキー apiKey に保持する openai-api-key と、 ストアのパスワードを password に保持する counter-store-password。存在しない Secret を参照する workload は起動しません。
  • 2 つの AI Gateway 定義に対するサーバーサイド apply。 aigateway.envoyproxy.io_backendsecuritypolicies.yaml と aigateway.envoyproxy.io_mcproutes.yaml は、クライアントサイド apply が記録する適用済みオブジェクトのコピーよりも大きいため、クライアントサイド apply では拒否されます。
  • エージェントのイメージ。 Release は registry.example/crew-assistant:1.0.0 を指定しています。カタログはエージェントのランタイムをパッケージ化しており、それが実行する crew は独自のコードです。

コンパイラが解釈しない箇所

コンパイラは、上限、単位、トークンコストを文字列としてゲートウェイのリソースに渡し、モデルのエンドポイント、ストアのアドレス、コントローラのアドレスをそれぞれが公開するものから渡します。コンパイラは OpenAI に接続せず、応答がトークン数を報告するかどうかを知らず、自身では何も数えません。Secrets が存在することや cert-manager が稼働していることも確認しません。上記の各停止は、カタログ自身のエンティティによって、予算の実現内、またはゲートウェイの Component もしくは Recipe 内のアサーションとして宣言されたものであり、いずれもトラフィックについての理解には基づいていません。

応用する

  • モデルごとの上限。 models ソケットにさらにモデルを接続し、scope: model を設定します。各モデルがそれぞれ独自のルールとカウントを持ちます。
  • 片側だけをカウントする。 モデルが読み込む分をカウントするには unit: prompt_tokens を、モデルが書き出す分をカウントするには completion_tokens を設定します。
  • 失敗したリクエストを再送する。 core/retry-policy を max_attempts とともにゲートウェイにアタッチし、Manifest でそれを helm/retry-policy-envoy-gateway にマッピングします。Envoy Gateway は 1 つのルートに 1 つのトラフィックポリシーをアタッチするため、同じトラフィックポリシーである edge-models に、レート制限と並んで retry が追加されます。
  • より短い、または固定長のウィンドウ。 Release の period を上記の長さのいずれかに設定します。1d は 00:00 UTC から始まる 1 日であり、30d は暦月ではなく 1970 年 1 月 1 日から数えた 30 日です。1mo 以外の期間では、設定は暦月の設定を未設定のままにします。
  • MCP ルート。 コントローラは、ai-controller 上で infra.mcp_session_seed_secret が指定する Secret 内のシードから導出した鍵で MCP セッション識別子を暗号化します。ここでのように何も指定されていない場合、シードはそのチャートが公開しているデフォルト値になるため、このコントローラを通じて MCP ルートを提供する前に Secret を指定してください。