---
id: llm-gateway
title: LLM Gateway 連携
category: advanced
order: 150
keywords: [LLM Gateway, LiteLLM, プロキシ, モデル, Virtual Keys, 使用量, Usage, トークン]
---

## 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 され、サーバー再起動は不要です。設定画面全般は [設定](./17-settings.md) を参照してください。

このフォームには 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 タブは「実際に消費したトークン量の可視化」、課金パネルは「キーごとの予算管理」と捉えてください

このタブは管理者専用ではなく、ログインユーザーが自分の使用量を確認できます。