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

エージェント、ルーター、2 つのアップストリームモデル

1 つのクラスター内ルーターを介して 2 つのアップストリームプロバイダーのモデルに到達するエージェントアプリケーションを、 Kubernetes マニフェストにコンパイルした例です。

エージェントは 1 つの名前でモデルを要求します。その名前の背後には別名のマップを保持するルーターがあり、 そのマップの背後には 2 つのプロバイダーがあります。エージェントは、どのプロバイダーが応答したかを知ることはなく、 プロバイダーの認証情報を保持することもなく、マップの向き先が変更されても変わりません。 これこそが、そこにルーターを置く理由です。

このワークスペースは独自のカタログエンティティを一切作成しません。ここで名前が挙がるすべての Component、 Feature、Recipe は標準ライブラリのカタログに含まれています。ここにある 3 つの エンティティファイル(Aggregate、Manifest、Release)が、 記述する必要のあるもののすべてです。

構築されるもの

agent ───────────────────┐ ┌────► openai/gpt-4o
│ │ │
▼ ├────► router ──────┤
checkpointer │ (the alias map) └────► anthropic/claude-sonnet-4
(run state) │
│
an Ingress at ───────────┘
assistant.example.internal

ルーターには、リクエストの入口が 2 つあり(エージェントは model エッジ経由で到達し、外部からは Ingress を通じて到達します)、出口はマップのエントリごとに 1 つあります。3 つ目のポートは、クラスター内のスクレイパーにメトリクスを提供します。

3 つのコンポーネントがあり、それぞれが異なる役割を担います。

インスタンスカタログの Componentここでの役割
routercore/gateway/litellmルーティングを担うコンポーネント。1 つのエンドポイント、エイリアスのマップ、2 つの上流プロバイダーを持ちます。自身のアドレスと、エージェントが要求するエイリアスを公開します
agentcore/ai-agent/langgraphアプリケーション。独自のグラフイメージを実行します
checkpointercore/datastore/valkeyエージェントが実行状態を保存する場所。データストアのカテゴリによって選択されます

uses エッジは 2 つあり、どちらもエージェントの Component が宣言するソケットにつながります。model (必須。モデルコンポーネント、またはモデル API を提供するゲートウェイを受け入れます。ルーターは後者です)と checkpointer_db(必須。データストアのカテゴリで選択します)です。4 種類の Feature にわたる 6 つの Feature アタッチメントがあり(5 つはルーターに、1 つはエージェントの model 接続に付きます)、それぞれがレンダリング出力に何かを加えます。各アタッチメントが何を生成するかは、後述のセクションで示します。

サンプルを生成する

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

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

Terminal window
aggrega scaffold --example ai-agent-and-model-router

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

Terminal window
cd ai-agent-and-model-router

ビルド

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

リリースはビルドの前にロックファイルを必要とします。ロックファイルは配布されるのではなく生成されるものなので、クローンした直後には存在しません。aggrega build はデフォルトで読み取り専用です。 ロックファイルがない場合は停止し、先に進むための 2 つの方法を示します。先にロックファイルを解決するか、ビルドに生成させてください。

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

このワークスペースは .aggrega-config.yaml が指定するデフォルトレジストリからエンティティを解決するため、--catalog フラグは不要です。

router の selection アタッチメントの実現では、コンパイラにもカタログにも同梱されていないプラグインを 1 つ実行します。ゲートウェイ設定ステップ pipeline-step/litellm-gateway-config で、解決時に default_registry が指すレジストリ hub.aggrega.ai から取得されます。

以下のいくつかのセクションでは、1 行を変更して再ビルドするよう求めます。 ロックファイルは、このディレクトリにある Aggregate と Manifest を含め、リリースが解決したすべてのエンティティのダイジェストを固定し、Release 自体はその内容のダイジェストで記録します。そのため、これら 3 つのファイルのいずれかを編集するとロックファイルは古くなり、次のビルドは古い固定値に対してレンダリングせずに停止します。メッセージは何が変更されたか(Release はそのファイルで、Aggregate や Manifest はその名前で)を示し、記録されたダイジェストと検出されたダイジェストを並べて表示します。pull を実行すると、他のすべての固定値を維持したまま変更が記録されます。

Terminal window
aggrega pull --release release.yaml

これを実行してから再度ビルドするか、同じ pull を先に実行する --auto-pull を付けてビルドします。 いずれにしても、この停止は障害ではなく意図されたものです。ビルドは、古いとわかっている固定値に対して レンダリングを行いません。

ビルドは次のように出力します。<workspace> はこの例のフォルダを表します。

verify: plugin pipeline-step/litellm-gateway-config:1.0.0 host functions match the published .wasm
[… omitted: three warnings, one per credential attachment, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping]
Pull complete: release.lock (entities=24, source_artifacts=0, external_inputs=0)
[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]
Build completed: 12 files written to <workspace>/dist

エンティティは、ロックファイルの解決時に 1 回、リリースのビルド時に 1 回、カタログの慣例に照らしてチェックされます。 これらのチェックが出す各アドバイザリは lint: 行として出力されます。このリリースでは何も出ません。 同じチェックを単独で実行し、アドバイザリを、その発生元のエンティティファイルや一致させるための方法とともに詳しく読むには、次のようにします。

Terminal window
aggrega lint --release release.yaml

ここでは conventions checked: 19 entities, 0 advisory finding(s) と報告されます。

AI アシスタントを使う

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

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

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

dist/helm/
├── agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml
├── agent-deployment.yaml
├── checkpointer-default-service.yaml
├── checkpointer-deployment.yaml
├── router--api-zukey--router-secret-router-api-key.yaml
├── router--metrics--router-servicemonitor-router-scrape.yaml
├── router--provider-zukey--router-secret-router-provider-key.yaml
├── router--published--router-ingress-router-ingress.yaml
├── router-default-service.yaml
├── router-deployment.yaml
└── router/
├── litellm-gateway-config/
│ └── configmap.yaml
└── request-guard/
└── request-guard.yaml

router/ の下には、ルーターの Recipe 自身が出力するファイルがあります。どちらも Recipe が記述するのではなくインポートするバンドルに由来するため、それぞれインポート時のキーである litellm-gateway-config と request-guard の下に置かれます。

アタッチメントがもたらしたものはすべて、コンポーネント自身のマニフェストと同じディレクトリに置かれ、ファイル名に 2 つの座標を持ちます。アタッチ先のコンポーネントと、アタッチメントに付けられた名前です。router--metrics-- は router 上の metrics アタッチメントです。どれがどこから来たかは引き続きツリーから読み取ることができ、すべてのファイルは 1 つのディレクトリを読むツールが見つけられる場所にあります。これは、別途指定しない限り、このターゲットの利用者が行う動作です。

2 つの座標は、ファイル自身の名前と 1 つの文字列を共有するため、入力したとおりではなくエンコードされて書かれます。ファイル名が安全に扱えない文字は -z と 1 文字の英字になります。api_key は api-zukey に、router_model.credential(エージェントの router_model 接続上のアタッチメントが取る名前で、接続のエイリアス、ドット、スロットから成ります)は router-zumodel-zdcredential に、feature.aggrega.ai/monitoring(Feature 自身のアノテーションが生成するアタッチメント名)は feature-zdaggrega-zdai-zsmonitoring になります。ファイル自身の名前は含まれるドットをそのまま保持するため、.yaml 接尾辞は引き続き接尾辞として読めます。

ここのページでビルドが生成したものを示す場合、そのブロックは実際の実行からコピーしたものです。この慣例と、省略した行を示す記号については これらのページの出力の読み方 を参照してください。

ルーティングテーブル

ルーターの存在理由はそのマップであり、マップは記述されたファイルにとどまらず、レンダリングされた出力にまで届きます。以下は dist/helm/router/litellm-gateway-config/configmap.yaml の data ブロック全体です。

data:
config.yaml: |
model_list:
- model_name: assistant
litellm_params:
model: openai/gpt-4o
api_key: os.environ/LITELLM_PROVIDER_API_KEY
- model_name: assistant
litellm_params:
model: anthropic/claude-sonnet-4
api_key: os.environ/LITELLM_PROVIDER_API_KEY
litellm_settings:
callbacks:
- /etc/litellm-request-guard/request_field_filter.filter
- prometheus
router_settings:
routing_strategy: latency-based-routing

そして 2 つ目の ConfigMap である dist/helm/router/request-guard/request-guard.yaml の data ブロックです。格納しているファイルの本文は省略しています。

data:
request_field_filter.py: |
[… omitted: the text of the router's request guard, a Python module described below]
path-allowlist.conf: |
[… omitted: the configuration of the router's path allowlist, described below]

ここから読み取るべき点が 5 つあります。

両方のエントリが同じエイリアスを公開しています。 これにより、ルーターはリクエストごとに選択を行う必要が生じます。その選択方法は本文末尾の router_settings が示しています。latency-based-routing です。これは、後述のアタッチメントの節で示すとおり、ルーター自身の Recipe ではなく、ルーターの selection アタッチメントによって書き込まれたものです。エイリアスがすべて異なるマップは名前だけでルーティングされ、戦略は何も変えません。1 つのエイリアスを共有していることは、両方のエントリがルーターの models ソケットに接続されたモデルコンポーネントから提供されるのではなく、values.models に手で記述されている理由でもあります。接続されたモデルは自身の接続のエイリアスで提供され、そのエイリアスは他のどのエントリも公開できないため、接続された 2 つのモデルが 1 つのエイリアスを共有することはありません。2 つ目の理由は Anthropic に関するものです。ルーターは接続されたモデルのエントリを OpenAI API のみを通じて書き込みますが、Anthropic のモデルは独自の API で応答します。そのため core/ai-model/anthropic を接続するとビルドが停止し、そのアップストリームをマップに直接記述するよう指示されます。

ターゲットはコンパイラが解釈しない文字列です。 openai/gpt-4o は決定的なポインタであり、実行中のプロキシがリクエストを処理する時点で解決します。コンパイラはビルド時に provider に接続することがないため、ターゲットが存在するか、正しく綴られているか、アカウントからアクセスできるかを知らせることはできません。openai/gpt-4o を openai/not-a-real-model に変更してもビルドは成功します。失敗はリクエスト時に provider から返されます。

このファイルには認証情報の値が含まれていません。 各エントリは代わりに、プロキシ独自の間接参照を通じて環境変数を指定します。値はまったく別の経路でコンテナに届きます。これについては後述します。

すべてのリクエストは最初にガードを通ります。 最初の callbacks エントリは、モジュール request_field_filter をそのファイルのフルパスで登録します。2 つ目の ConfigMap はルーターのコンテナ内の /etc/litellm-request-guard にマウントされます。これは /etc/litellm の隣にある専用のディレクトリで、後者には 1 つ目の ConfigMap がマウントされ、プロキシはそこから設定を読み込みます。2 つ目の ConfigMap は LiteLLMGuard#/artifacts/RequestGuard から来ます。これはこのプロキシを実行するすべての Recipe がインポートするバンドルであるため、ガードと後述の許可リストは、プロキシがどこで動作しても同じ内容になります。ルーターはプロバイダーの認証情報を保持しているため、ルーターの Recipe はすべての Release でこのガードを提供します。ガードは、呼び出し元からのリクエストのうち、そのリクエストが通ったルートについてプロキシが宣言するリクエストフィールドと、Release がルーターの infra.admitted_request_fields で指定するフィールドだけを転送し、それ以外のフィールドにはそのフィールド名を示すエラーで応答し、何も転送しません。そのため、呼び出し元がリクエストボディのモデルリストを通じてルーターを自分のアドレスに向けたり、ルーターのキーの代わりに自分のプロバイダーキーを送ったりすることはできません。また、ルーター自身がすべてのリクエストに書き込む ID、つまり検証したキーのハッシュ、そのキーのチームと組織、およびエンドユーザーを、呼び出し元が設定することもできません。responses または messages のリクエストでは、ルーターは呼び出し元の metadata を自身のものと分けて保持し、呼び出し元がそこに書いたチーム、組織、エンドユーザーのフィールドを削除します。また、ガードはそこでキーを指定するリクエスト、metadata.user_api_key を拒否します。その他のすべてのルートでは、呼び出し元が送った値をルーターの値が置き換えます。この Release はそれ以上何も許可しません。2 つ目のエントリ prometheus はプロキシ自身のメトリクスコールバックで、ルーターの metrics_enabled の値によって有効になります。後述の metrics アタッチメントは、これが記録する内容をスクレイプします。

到達できるのはルーター自身のルートのみです。 ガードは自分にリクエストを渡すルートしか見ないため、2 つ目の ConfigMap のもう 1 つのファイルが Pod の 2 つ目のコンテナを設定します。このコンテナはその ConfigMap のみをマウントし、公式の nginx イメージをパス許可リストとして実行します。ルーター自体は Pod のループバックアドレスで待ち受けるため、Pod の外からは到達できません。許可リストはポート 4000 で待ち受けます。これは後述の Service がターゲットとするポートです。許可リストは、リクエストのメソッドとパスがルーターの提供するルートのいずれかである場合にのみ転送します。対象は、ガードが検査するモデルリクエストのルート(エイリアスにかかわらずルーターが提供する表記で、/v1/chat/completions や /v1/messages を含みます)、モデル一覧、ヘルスチェック、そして管理用ルートのうちキー管理です。それ以外のパスには 403 を返し、何も転送しません。そのため、プロキシのトークン数カウント用ルート、provider 独自の API へのパススルールート、その他の管理用ルート、および管理コンソールにはルーター経由で到達できません。Azure のクライアントが送るパスのように、パスにモデル名を含むモデルルートにも到達できません。その場合プロキシはパス内の単語(エイリアスを含む)を読んでリクエストの記録方法を決めるため、ルーターはそのルート上でこのマップ自身の assistant へのリクエストを拒否することになります。プロキシのメトリクスもこれらのルートには含まれません。ポート 4000 は /metrics に 403 を返します。Aggregate が設定しているようにルーターの metrics_enabled が true の場合、許可リストはポート 9090 でも待ち受け、そこでは /metrics への GET のみを、プロキシがループバックアドレス上でメトリクス用に保持しているリスナーへ転送し、それ以外のリクエストにはすべて 403 を返します。このポートは呼び出し元を検査しません。またメトリクスには、ルーターが利用額を帰属させるハッシュ化されたキー、キーのエイリアス、ユーザーのメールアドレスが含まれます。

ルーターが公開するもの

ルーターの Recipe は、すべてのモデルコンポーネントが公開する 2 つのキーを公開します。クライアントライブラリに渡されるベース URL である endpoint と、リクエストが要求する名前である model です。これにより、エージェントの model ソケットはモデルの代わりにルーターを受け入れられます。このソケットのセレクターは component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api です。これは、モデルまたはゲートウェイのカテゴリに属し、 model.aggrega.ai/api を持つコンポーネントを受け入れます。このラベルは、コンポーネントが公開するアドレスでどのモデル API が応答するかを示します。ルーターは model.aggrega.ai/api: openai を持ちます。モデル API を提供しないゲートウェイはこのラベルを持たず、エージェントからそのようなゲートウェイへのエッジはビルドを停止させ、ソケットと、ターゲットが満たさないセレクターを示します。

アドレスは、ルーター自身の Recipe が出力する Service です。以下は dist/helm/router-default-service.yaml の spec 全体です。

spec:
type: ClusterIP
selector:
app: router
ports:
- name: http
port: 4000
targetPort: http
- name: metrics
port: 9090
targetPort: metrics

Recipe は、公開するエンドポイント http://router-default:4000/v1 を、Service の名前とポートの元になっているのと同じ 2 つの事実、すなわちコンポーネント自身の名前とその infra.port から組み立てます。Service がターゲットとするポート http は、ルーターのパス許可リストが待ち受けるポートです。2 つ目の metrics は、ルーターのメトリクスが有効であるために存在し、メトリクスのみを運びます。3 つのファイルのどこにも router-default は明記されていません。router コンポーネントの名前を変更する(Aggregate と Release におけるそのキー、およびそれを指すエージェントのエッジを変更する)と、エージェントが受け取るアドレスもそれに従います。gateway に変更すると、エージェントの OPENAI_BASE_URL は http://gateway-default:4000/v1 になります。

名前は、ルーターがそのモデルとして公開するエイリアスです。このマップは両方のエントリから 1 つのエイリアス assistant を公開するため、ルーターはそれを公開し、その values.model は省略されています。2 つ目のエントリに独自のエイリアス(たとえば summarizer)を与えると、何もレンダリングされないうちにビルドが停止します。ルーターが公開できるのは 1 つだけだからです。この停止は E0033、つまりルーターの Component のアサーション失敗であり、そのメッセージはルール自身の文で終わります。 values.model is not set, but values.models publishes 2 aliases (assistant, summarizer), so the gateway cannot tell which one a component wired to it asks for; set values.model to one of them(values.model が設定されていませんが、values.models は 2 つのエイリアス(assistant、summarizer)を公開しているため、ゲートウェイはそれに接続されたコンポーネントがどれを要求しているか判断できません。values.model をそのいずれかに設定してください)。models の横に model: assistant を設定するとこれが解消され、エージェントには再び assistant が渡されます。summarizer を求める呼び出し元は、同じエンドポイントに名前でそれを要求します。

エージェントが受け取るもの

エージェントの Recipe は自身の 2 つのエッジとエージェント自身の値を読み取り、それらをコンテナの環境変数に変換します。以下は dist/helm/agent-deployment.yaml の env ブロック全体です。

env:
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: agent-router-model.credential
key: api-key
- name: LANGGRAPH_DEFAULT_RECURSION_LIMIT
value: "25"
- name: OPENAI_BASE_URL
value: http://router-default:4000/v1
- name: OPENAI_MODEL
value: assistant
- name: LANGGRAPH_CHECKPOINTER_HOST
value: checkpointer-default
- name: LANGGRAPH_CHECKPOINTER_PORT
value: "6379"
- name: LANGGRAPH_GRAPH_ENTRYPOINT
value: app.graph:graph

最初のエントリは model エッジが持つアタッチメントから来たもので、helm プロバイダは Secret から読み取るこのようなエントリを通常のエントリより前に書き出します。再帰の上限はエージェント自身の recursion_limit で、LangGraph が自ら読み取る変数として渡されます。次の 2 つは model エッジから、その後の 2 つは checkpointer_db エッジから来たもので、最後はエージェント自身の graph_entrypoint です。これはアプリケーションのコードが読み取るデフォルトの名前で渡され、コンポーネント自体の inject ブロックがあればその名前を置き換えます。Aggregate が記述する必要がなかったものに注目してください。どちらのエッジも inject ブロックを持っていません。消費側の Recipe が各接続をデフォルトの名前で配信し、エッジ上の inject ブロックはそれを置き換えるものだからです。開発者は、エージェントがモデルを使うことを宣言します。そのエンドポイントが届く変数はクライアントライブラリが読み取る変数であり、エッジが指定するとおりのままです。

LANGGRAPH_CHECKPOINTER_PORT: "6379" にも注目してください。Release は checkpointer: {} を宣言しているだけで何も設定していないため、このポートはキャッシュ Component 自身のスキーマのデフォルト値であり、それが具体化されてエッジを通じて渡されたものです。

エージェントは、プロバイダと直接通信する場合とまったく同じ方式、つまりベース URL、モデル名、キーでルーターと通信します。これにより、アプリケーションを変更することなく、ルーターを挿入、移動、または接続先の変更ができます。

6 つのアタッチメントと、それぞれがレンダリングするもの

出力に何も変化をもたらさないアタッチメントからは何も学べません。この 6 つはそれぞれ、出力に何かを加えます。

ルーターの api_key — 呼び出し元に要求するキー

core/referenced-secret で、ルーターの Component が宣言するスロットを埋めます。これが保持するキーは、LiteLLM がマスターキーと呼ぶものです。これは独自の Secret をレンダリングし、ルーターのコンテナがそれを参照します。 dist/helm/router--api-zukey--router-secret-router-api-key.yaml より:

stringData:
master-key: "dev-router-admin-key-change-me"

また、dist/helm/router-deployment.yaml のルーターのコンテナの env より:

- name: LITELLM_MASTER_KEY
valueFrom:
secretKeyRef:
name: router-api-key
key: master-key

コンテナが持つのは参照であり、値ではありません。Secret の名前はアタッチメントが公開し、利用側が読み取るため、どちらの側もそれを再導出しません。

ルーターの provider_key — アップストリームに提示するキー

同じ Feature を別のスロットで使うもので、この 2 つのスロットの違いこそがルーターの要点です。これは values.models に記述されたエントリ(ここではその両方)の唯一の認証情報です。ルーターの models ソケットに接続されたモデルは、代わりに自身の接続が持つキーを提示し、このキーを提示することはありません。 dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml より:

stringData:
provider-key: "upstream-provider-key-change-me"

また、同じコンテナの env より:

- name: LITELLM_PROVIDER_API_KEY
valueFrom:
secretKeyRef:
name: router-provider-key
key: provider-key

このアタッチメントはルーティングテーブルも変更します。 上のルーティングテーブルの data ブロックを見返すと、マップのすべてのエントリが api_key: os.environ/LITELLM_PROVIDER_API_KEY を持ち、この同じ変数を指定しています。 Aggregate から provider_key アタッチメントを削除して再ビルドすると、ビルドが報告するファイルは 12 ではなく 11 になり(Secret がなくなります)、ルーティングテーブルの ConfigMap はちょうどその 2 行の api_key だけが異なり、それ以外は変わりません。 ガードの ConfigMap は変更されません。マップの残りの部分は記述された順序と書式を保ち、ルーターは引き続きリクエストを受け付けてルーティングしますが、ルーティングされたリクエストは提示する認証情報がないため、プロバイダー側で失敗するようになります。

変数名はルーターの Recipe で一度だけ記述され、ルーティングテーブルとコンテナの環境の両方がそこから読み取るため、何も設定しない変数をテーブルが指定することにはなりません。

2 つの認証情報は分離されたままであり、この分離こそがルーターがもたらすものです。アップストリームのキーはルーターの内部にとどまり、呼び出し側のアプリケーションはルーターへのキー以外何も保持しません。

エージェントの model 接続の credential — ルーターに提示するキー

再び core/referenced-secret ですが、同じやり取りの反対側です。 エージェントの model ソケットは credential スロットを宣言しているため、キーはそれが提示される接続に、Aggregate 内のエッジの下でアタッチされます:

uses:
model:
router_model:
target: router
features:
credential:
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.router_admin_key }}"

dist/helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml より:

stringData:
api-key: "dev-router-admin-key-change-me"

これは上のルーターの master-key と同じ値であり、2 回記述されてはいません。両方のアタッチメントが、巻き上げられた 1 つのパラメータを読み取ります:

origin: "{{ .parameters.router_admin_key }}"

Aggregate がパラメータを宣言し、Release がそれを満たすため、キーの記述場所は 1 か所だけであり、2 つの Secret が別々に編集されることはありません。Release で一度変更すれば、レンダリングされる両方の Secret が一緒に変わります。

それでも各アタッチメントは独自の Secret をレンダリングし、その名前はそれを利用するコンポーネントと、エージェントの場合はアタッチされた接続から付けられます: agent-router-model.credential。共有パラメータが共有するのは値であり、リソースではありません。

ルーターの published — クラスター外部のアドレス

core/public-ingress はスロットを埋めません。これは独自のセレクター component.aggrega.ai/type=server によって受け入れられ、ルーターはこれを持っています。これは、ルーターの Recipe が何も知らないリソースをもたらします。 dist/helm/router--published--router-ingress-router-ingress.yaml の spec 全体:

spec:
rules:
- host: assistant.example.internal
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: router-default
port:
name: http

開発者は Aggregate で path を指定してこれをアタッチします。アプリケーションがどのリクエストを受け付けるかは、そのアプリケーションが何であるかの一部だからです。運用者は同じアタッチメントに対する Release のエントリに host とポート名を記述します。ホストはその環境におけるルーターの名前であるため、運用者は環境ごとに、各環境の Release でそれを命名します。バックエンドの Service はどちらからも指定されていません。service_name は未設定のままであり、アタッチメントの実現はルーター自身の Recipe が出力する Service にフォールバックします。出力に ingressClassName フィールドはありません。何もそれを設定しておらず、実現は与えられなかったものを省略するため、リソースはクラスターのデフォルトのクラスが引き受けることになります。

ルーターの metrics — スクレイプ対象

core/prometheus-exporter で、同じセレクターによって受け入れられ、独自の別のリソースをもたらします。これが受け取る入力はすべて、アプリケーションの意図ではなく運用者によるサイジングです。プラットフォームがどのくらいの頻度でスクレイプし、どのポートとパスを読み取るかは、プラットフォームの特性だからです。そのため、運用者が Release で、ルーターのエントリに、infra と並べてその型を指定してアタッチします。Aggregate はこれに言及しません:

components:
router:
features:
metrics:
type: core/prometheus-exporter
infra:
interval: 30s
port: metrics
path: /metrics

dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml の spec 全体:

spec:
selector:
matchLabels:
app.kubernetes.io/name: router
endpoints:
- port: metrics
interval: 30s
path: /metrics

port は番号ではなく Service のポート名を指定します。metrics は、Aggregate がルーターの metrics_enabled 値を設定しているためにルーターの Recipe が出力するポートで、メトリクスを提供します。これは Feature のデフォルトのポート名でもあり、ここでは他の 2 つの設定項目と一緒に明示しています。上の Ingress がルーティングする http ポートは /metrics に 403 を返すため、そこに向けたスクレイプは何も収集しません。メトリクスをそもそも提供するかどうかは開発者の選択で、Aggregate で行います。プラットフォームがどのくらいの頻度で、どのポートとパスでスクレイプするかは運用者の選択で、ここで行います。

ルーターの selection — ターゲット間の選択方法

core/target-selection は、ルーターのように gateway.aggrega.ai/intelligence: semantic を持つゲートウェイにアタッチされます。ルーターがどの方法で選択するかはアプリケーションがルーターに求めることの一部であるため、開発者が Aggregate で、strategy を値として指定してアタッチします:

components:
router:
features:
selection:
type: core/target-selection
values:
strategy: latency

そして Manifest が、それをこのルーター用の実現にバインドします:

core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0

これは独自のファイルをレンダリングしません。その実現は、ルーターの Recipe がレンダリングするルーティングテーブルに設定を 1 つ書き込みます。上の data ブロックの最後の 2 行です:

router_settings:
routing_strategy: latency-based-routing

これにより、プロキシは assistant への各リクエストを、直近 10 回の応答の平均所要時間(応答がトークン数を報告する場合は出力トークンあたり)が最も短いエントリに送ります。まだ試されていないエントリは最速とみなされるため、平均で決まる前に各エントリが一度は試されます。Aggregate からアタッチメントを削除して再ビルドすると、ビルドは引き続き 12 ファイルを報告し、ルーティングテーブルの ConfigMap はちょうどその 2 行だけが異なります。ルーターの Recipe は独自の戦略を書き込まず、戦略がない場合、プロキシは 2 つのエントリからランダムに選びます。

代わりに strategy: cost を求めると、ビルドは何も書き込まずに停止します。この停止は E0033 で、実現のアサーションの失敗であり、そのメッセージはルール自身の文で終わります: core/target-selection attachment “selection” on “router” asks for strategy cost, but core/gateway/litellm cannot choose between the entries of its model map by cost: the proxy looks each entry’s target up, exactly as written, in its own price table, which names OpenAI’s and Anthropic’s models without the provider prefix a target carries (gpt-4o, not openai/gpt-4o) and which the proxy may fetch afresh when it starts, and it prices an entry it does not find, and that carries no price of its own, at a fixed fallback, so the entries sharing an alias are priced alike and the choice falls to their order. Ask for strategy latency, or remove the attachment(core/gateway/litellm はコストによってモデルマップのエントリを選択できません。プロキシは各エントリのターゲットを記述どおりに独自の価格表で検索しますが、その価格表はターゲットが持つプロバイダー接頭辞なしで OpenAI と Anthropic のモデルを記載しており、起動時に改めて取得されることがあります。見つからず独自の価格も持たないエントリは固定のフォールバック価格で評価されるため、エイリアスを共有するエントリは同じ価格となり、選択はその順序で決まります。strategy latency を求めるか、アタッチメントを削除してください)。ここでは両方のターゲットがそのように記述されているため、Aggregate がコストを求めていても、プロキシはすべてのリクエストを最初のターゲットに送ることになります。

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

エージェントのアドレスとモデル名はルーターが公開するものから読み取られるため、3 つのファイル内で名前の組を手作業で揃えておく必要はありません。ビルドが実際に検査するのは、ルーターが公開するエイリアスがそのマップの公開するエイリアスの 1 つであるという、ルーター自身のルールです。これはその Component が宣言し、エンティティが持つ他のアサーションと同様にビルドが評価するルールです。

残りは、ある場所から別の場所へ受け渡される文字列です。コンパイラはアドレスとエイリアスを読まずにルーティングします。一方がホスト名で他方がモデル名であることは知らず、router-default:4000 で何かが応答することを確認するために稼働中のクラスタへアクセスする手段も持ちません。ルーターを受け入れた model.aggrega.ai/api ラベルも同じ種類の文字列です。ソケットのセレクタがこれに一致するだけで、そこで実際にどの API が応答するかは何も検査しません。また、マップ内のすべての target は、稼働中のプロキシが解決するポインタです。openai/gpt-4o を openai/not-a-real-model に変更してもビルドは成功し、失敗はリクエスト時に発生します。

これは、この例の残りの部分を機能させているのと同じ性質です。コンパイラは受け渡すものを解釈しないため、ルーターを別のプロバイダーへ向け直すことも、エージェントを別のルーターに接続することも、認証情報の実現をストアに基づくものに差し替えることもできます。いずれも、コンパイラがその内容を理解する必要はなく、エージェントが変わることもありません。

応用する

  • プロバイダーの向き先を変える。 ルーターのマップ内の target を編集します。それ以外は何も 変わりません。モデルも、エージェントも、レンダリングされた Secret も変わりません。

  • 3 つ目のプロバイダーを追加する。 マップのエントリーを追加します。既存のエイリアスを公開する場合、 ストラテジーは 3 つの中から選択するようになります。新しいエイリアスを公開する場合、マップは 2 つのエイリアスを公開し、ルーターの values.model がエージェントに渡されるエイリアスを指定します。 もう一方を使いたい呼び出し元は、名前で指定して要求します。カタログがモデル化している、API が OpenAI API であるモデルは、代わりにルーターの models ソケットに接続することもできます。その場合、 そのモデルは独自のエイリアスの下で、その接続が持つキーを提示します。このとき values.model は、エージェントに渡されるエイリアスを指定します。

  • 代わりにストアから認証情報を取得する。 core/referenced-secret を helm/k8s-external-secret に バインドしている Manifest の 1 行を変更し、再ビルドします。 レンダリングされた各 Secret は、クラスターのシークレットストア内のエントリーを指す ExternalSecret になり、 ストアのオペレーターがそれを調整します。そして各コンシューマーのレンダリングされた参照は バイト単位で同一 のまま保たれます。 ロケーターは両者の間で取り決めるのではなく、生成側が公開するためです。ビルドを成功させるために、 3 つのファイルの他の部分を変更する必要はありません。

    ただし、この切り替えを意味のあるものにするには、1 点書き直しが必要です。 origin の意味は 2 つの実現方式の間で異なります。このワークスペースの 実現方式はそれを保存する値として読み取り、もう一方は取得するキーとして読み取ります。 origin の値を見直さずに行を切り替えると、 レンダリングされる remoteRef.key は、値の代わりに置かれていたプレースホルダー、 ここでは dev-router-admin-key-change-me になります。その場合、出力ツリー内でその文字列を 機密情報として保持しているものはありませんが、存在しないエントリーを指すストアキーとして 依然として残ります。

  • ルーターをなくす。 代わりにエージェントの model エッジを、プロバイダーごとのモデル コンポーネントに向けます。するとエージェント自身がプロバイダーの認証情報を保持することになり、 これはまさにルーターが取り除くために存在するトレードオフです。

  • カタログがモデル化していないルーターに到達する。 エージェントの model エッジを core/ai-model/openai-compatible コンポーネントに向け、Release 内のその infra.endpoint に そのルーターのアドレスを書き込みます。そのコンポーネントの背後ではクラスター内で何も動作しないため、 アドレスを書き込み、それが指すサービスと一致させ続けるのはオペレーターの役割です。

複数のコンシューマーの接続間で 1 つの認証情報を共有する方法については、 model-api-key-sharing を参照してください。どのカタログ エンティティも宣言していないソケットについては、adhoc-uses-socket を参照してください。