5.9 KiB
id, title, category, order, keywords
| id | title | category | order | keywords | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| llm-gateway | LLM Gateway 連携 | advanced | 150 |
|
LLM Gateway とは
LLM Gateway は、複数の物理 GPU / llama-server バックエンドへの呼び出しを 1 か所に集約する OpenAI 互換のプロキシです。MAESTRO は自身を Gateway として動かせるほか、外部の LiteLLM Proxy を Gateway として使うこともできます。
主な価値:
- ルーティングの一元化: 要求された性能ティア（ロール）を担うバックエンドの中から least-busy で振り分け、空いている GPU に送る
- 仮想キー管理: チームごとに発行する API キー (virtual key) で利用を分離・追跡
- 観測性: すべての LLM 呼び出しが 1 か所に集まる
直接接続 (各 worker が GPU を直に叩く) でも 1 インスタンス内のロードバランスはできますが、複数の MAESTRO が同じ GPU プールを共有すると互いの占有を知らずに衝突します。Gateway を間に挟むとこれを解消できます。個人利用や専有 GPU しか使わない場合は Gateway は不要です。
どこで設定するか
admin は 設定 → LLM → Gateway Server で同一プロセス Gateway を設定します (admin 専用)。設定変更は hot reload され、サーバー再起動は不要です。設定画面全般は 設定 を参照してください。
このフォームには 2 つのブロックがあります。
- Enable Gateway トグル + ステータスバッジ
- Backends — 物理バックエンドのリスト
- Virtual Keys — 仮想キーの発行・rotate・revoke
config.yaml では gateway セクションに対応します (キーは snake_case)。
Backends
バックエンドを 1 件以上追加します。各行のフィールド:
| フィールド | 意味 |
|---|---|
id |
バックエンド識別子 (例 gpu-rtx-a)。x-aao-backend-id / /v1/models に現れる |
endpoint |
llama-server の URL (例 http://gpu-host:8080/v1) |
model |
厳密一致ルーティングに使うモデル名 (例 qwen3:8b) |
roles |
このバックエンドが担う性能ティア (auto / fast / quality / reflection)。クライアントが要求したロールに合うバックエンドの中から振り分けます。未指定なら全ロールを担当 |
max_slots |
同時スロット数 (llama-server の -np と合わせる) |
api_key |
バックエンドが bearer を要求する場合のみ (任意) |
注意: フォームに入力した api_key は config.yaml に平文で保存されます。${VAR} 形式の環境変数参照を使いたい場合は、フォームではなく config.yaml を直接編集してください (フォーム保存では literal 文字列になります)。
Virtual Keys
Gateway を経由してアクセスするためのクライアント側 bearer キーです。Gateway Server フォーム内の Virtual Keys セクションで発行・管理します。
要点:
- 形式は
sk-aao-*。発行時に生キーが一度だけ表示され、以後は再表示できません (失くしたら rotate / revoke + 再発行) - DB には hash のみ保存される
- チーム単位で発行し、
allowed_modelsでモデルを絞れる - 月次 token 予算 (
tokens_budget) と RPM レート制限 (rate_limit_rpm) を設定可能。超過時はそれぞれ HTTP 402 / 429 で拒否される - rotate は新キー発行 + 旧キー失効をアトミックに行う
config.yaml の gateway.virtual_keys[] に書いたキーは起動時に DB へ idempotent に import されます (bootstrap / バックアップ用途)。通常の運用では UI / admin API での発行が推奨です。
外部 LiteLLM Proxy を使う場合
MAESTRO 内蔵 Gateway の代わりに、リファレンス実装の LiteLLM Proxy を Gateway として使うこともできます。クライアント側 (MAESTRO worker) は Gateway の URL と virtual key を worker の endpoint / api_key に設定するだけです。
LiteLLM の構築手順・モデル定義・料金体系・Enterprise 機能といった運用詳細はこのページには含めていません。docs/aao-gateway-overview.md (内蔵 Gateway の機能概要と運用パターン) および LiteLLM の公式ドキュメントを参照してください。
監視
Gateway / Worker いずれも Prometheus 互換の /metrics を公開できます (デフォルト有効)。team / backend / key prefix などのラベルで per-team の利用量・レイテンシ・バックエンド稼働を集計できます。/metrics は機密情報を含むため、内部ネットワークに限定して公開してください。
詳細な metric 一覧・Grafana クエリ例・scrape 設定は docs/aao-gateway-overview.md を参照してください。
使用量（Usage）タブ
上部の 使用量 タブでは、LLM のトークン使用量を日次で確認できます。Gateway 経由と Direct（各 worker が直接接続）の両方を合算し、お使いの環境のローカル日付で集計します。
- 内訳の切り替え: 経路・モデル・バックエンド・ユーザー・組織で分解して見られます
- 時間帯別プロファイル: 0〜23 時の時間帯ごとの使用傾向も確認でき、いつ負荷が集中するかが分かります
- 集計の対象: 入力 / 出力トークンとリクエスト数。ユーザー別の一覧も出ます
- Virtual Keys のキー別課金パネル（admin の Gateway 設定内）とは 別集計 です。Usage タブは「実際に消費したトークン量の可視化」、課金パネルは「キーごとの予算管理」と捉えてください
このタブは管理者専用ではなく、ログインユーザーが自分の使用量を確認できます。