# セットアップガイド

LLM Gateway を利用するには、**管理者**と**開発者**がそれぞれ別の画面で準備を行います（SaaS版のみ）。

## 概要

| 担当  | 画面      | やること                             |
| --- | ------- | -------------------------------- |
| 管理者 | 管理コンソール | モデル定義（利用可能なモデルの登録）・IP 制限・利用ログの確認 |
| 開発者 | Console | LLM Gateway クライアントの作成（認証情報の取得）   |

> **前提条件**
>
> - 管理者は管理コンソールに、開発者は Console にログインできること（developer ロール以上）

## 管理者の準備（管理コンソール）

### モデルの定義

管理者は管理コンソールの「LLM Gateway 管理」メニューで、利用可能なモデルを登録します。登録した **公開モデル名** が、開発者がリクエストの `model` に指定する名前であり、`GET /llm/v1/models` の結果に反映されます。フォームは「基本設定 / 接続設定 / ルーティング/予算 / 管理者メモ」で構成されます。

#### 基本設定

| 項目      | 必須 | 説明                                                               |
| ------- | -- | ---------------------------------------------------------------- |
| 公開モデル名  | ✓  | 利用者が送る公開名（lookup キー）。開発者が `model` に指定し、`GET /v1/models` に反映されます。 |
| デプロイメント |    | 同一の公開モデル名で複数のデプロイを束ねる識別子。                                        |
| 有効化     |    | このモデル定義の有効 / 無効。                                                 |

#### ルーティング / 予算

| 項目   | 必須 | 説明                                                                  |
| ---- | -- | ------------------------------------------------------------------- |
| ティア  |    | ルーティング用のティア（高 / 中 / 低 / 未設定）。同一の公開モデル名に複数登録すると下記「自動ルーティング」の対象になります。 |
| 重み   |    | 同じ優先度の中で、大きい値ほど先に使われます（例: 5 は 1 より先。配分の比率ではありません）。既定 1。             |
| 優先度  |    | ルーティングの優先度（数値が小さいほど優先）。                                             |
| 日次予算 |    | 1 日あたりのコスト上限。「無制限」か「上限を設定」を選び、上限を設定するときは上限額（USD / 日）を入れます。          |

> **上限超過時の挙動**
>
> 日次予算を超えると `429`（`x-should-retry: false`）が返ります。詳細は[リファレンスのエラーレスポンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/llm-gateway/reference/api-reference.md#%E3%82%A8%E3%83%A9%E3%83%BC%E3%83%AC%E3%82%B9%E3%83%9D%E3%83%B3%E3%82%B9)を参照してください。

#### 接続設定

接続情報は [LiteLLM](https://docs.litellm.ai/docs/providers) 準拠のフォーマットで設定します。「簡易入力」または「JSON 入力」のどちらでも入力できます（タブで切替）。簡易入力の項目は次のとおりです。

| 項目            | 必須 | 説明                                                                                          |
| ------------- | -- | ------------------------------------------------------------------------------------------- |
| litellm model | ✓  | LiteLLM の `provider/model` 形式で指定します（例: `azure/gpt-5.5`）。                                    |
| API キー        |    | プロバイダの認証キー（プロキシ経由・ローカルモデル等では不要）。                                                            |
| API ベース URL   |    | プロバイダのエンドポイント URL（OpenAI 公式は不要。Azure / 自前ホストは指定）。                                           |
| API バージョン     |    | API バージョン（Azure OpenAI 等で必要）。                                                               |
| 追加 litellm 引数 |    | その他の LiteLLM パラメータを JSON で指定。上の専用欄の項目（model・api\_key・api\_base・api\_version）はここに入れても無視されます。 |

#### 管理者メモ（任意）

運用上の覚書を、任意の JSON で保存できます。ルーティングやモデルの能力判定には使われません。

> **モデル ID はハードコードしないでください**
>
> 利用可能なモデルはテナントごとに管理者が定義するため、環境によって異なります。アプリケーションでは `GET /llm/v1/models`（[リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/llm-gateway/reference/api-reference.md)）で動的に取得するか、管理者に確認してください。

### 自動ルーティング（任意）

同一のモデル名に複数のティア（高 / 中 / 低）が登録されている場合、管理者は管理コンソールの「LLM Gateway 管理」メニューで**自動ルーティング**をテナント単位で有効化できます。有効にすると、プロンプトの難易度に応じて適切なティアのモデルへ自動的に振り分けられます。開発者は従来どおりモデル名を指定するだけで、ティアの選択は自動で行われます。

### IP 制限（任意）

管理コンソールの「LLM Gateway 許可IP」で、LLM Gateway にアクセスできるネットワークを制限できます。

1. **許可 IP の登録** — IP アドレス（IPv4 / IPv6 / CIDR 形式に対応。例: `192.168.1.0/24`）と説明を登録します。
2. **IP 制限の有効化** — 有効にすると、登録された IP アドレスからのみ LLM Gateway へのアクセスが許可されます。許可 IP が1件も登録されていない場合は有効化できません。

有効時、許可外のネットワークからのリクエストは `403` で拒否されます。

### 利用ログ

モデル・プロバイダ・トークン数・コスト・レイテンシ等の利用状況は、管理コンソールおよび [システム連携 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/admin-api-reference.md) の `llm-gateway-logs` エンドポイントで確認できます。

## 開発者の準備（Console）

Console の「LLM Gateway」メニューでクライアントを新規登録し、詳細画面で認証情報の確認とライフサイクル管理（有効化 / 無効化 / 編集 / 削除）を行います。

### 1. 基本情報の入力

「LLM Gateway」メニューで「登録」をクリックし、以下を入力して作成します。

| 項目          | 必須 | 説明                   |
| ----------- | -- | -------------------- |
| LLM クライアント名 | ✓  | クライアントの表示名（最大255文字）。 |
| 説明          |    | 用途や目的の説明。            |

### 2. 認証情報の確認

作成後、詳細画面の「開発者情報」で認証情報を確認・管理できます。用途に応じて、**API キー**（SDK にそのまま設定）または **Client Credentials フロー**（Client ID / Client Secret でアクセストークンを取得。手順は[認証 API リファレンス（SaaS）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/auth-saas-ref.md#client-credentials-%E3%83%95%E3%83%AD%E3%83%BC)を参照）のいずれかを利用します。

| 項目           | 説明                                                                                                  |
| ------------ | --------------------------------------------------------------------------------------------------- |
| クライアントID     | クライアントの識別子。Client Credentials フローで使用します。                                                            |
| クライアントシークレット | Client Credentials フロー用のシークレット。マスク表示され、コピーおよび「シークレット再生成」ができます。                                      |
| API キー       | OpenAI / Anthropic SDK にそのまま設定できる固定キー（`agtstr_...`）。`Authorization: Bearer` または `x-api-key` で送信します。 |
| Token URL    | Client Credentials フローでアクセストークンを取得するエンドポイント。                                                        |

#### API キーの発行・管理

API キーは作成直後は未発行です。詳細画面で以下の操作を行います。

| 操作         | 説明                             |
| ---------- | ------------------------------ |
| API キーを発行  | 固定 API キー（`agtstr_...`）を発行します。 |
| API キーを再発行 | 新しいキーを発行します。以前のキーは無効になります。     |
| API キーを削除  | キーを削除します。以降、そのキーでは認証できません。     |

> **認証情報の取り扱い**
>
> API キー・クライアントシークレットはパスワードと同等の機密情報です。ソースコードにハードコードせず、環境変数や Secret Manager で管理してください。再発行・再生成を行うと、以前のキー / シークレットを使用しているすべての呼び出しが失敗するため、影響範囲を事前に確認してください。

### 3. 有効化 / 無効化

詳細画面のヘッダーから、クライアントを **有効化 / 無効化** できます。無効化したクライアントは LLM Gateway を呼び出せません。不要になったクライアントは **削除** できます。

> **有効化と契約枠**
>
> LLM Gateway を呼び出せるのは **有効化したクライアント**だけです。有効なクライアントは LLM 契約枠を使い、上限に達していると新規作成ができません（「LLM 契約枠の上限に達しているため、LLM アクセスを付与できません（有効なクライアントが枠を使います）」と表示されます）。不要なクライアントを **無効化** すると枠が 1 つ解放されます。

## 次のステップ

- [SDK から呼び出す](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/llm-gateway/quickstart/call-from-sdk.md) — SDK から呼び出す
- [API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/llm-gateway/reference/api-reference.md) — エンドポイント仕様
