> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# LiteLLM との連携

<Note>
  LiteLLM はサードパーティのプロキシサービスです。SambaNova は、LiteLLM のセキュリティや機能を保証・保守・監査していません。本ガイドは情報提供を目的としており、内容が古くなる可能性があります。ご利用はご自身の判断でお願いします。
</Note>

LiteLLM は、SambaStack の OpenAI 互換推論 API の前段に配置されるゲートウェイ層を提供し、エンタープライズレベルの制御機能を追加します。

| 機能 | 説明 |
| :- | :- |
| 認証の一元化 | API キーの管理とローテーションを一元的に実施 |
| 使用状況のトラッキング | チーム・プロジェクト・キー単位で使用状況を監視 |
| コスト制御 | 予算、クォータ、レート制限を設定 |
| 監査ログ | コンプライアンスやレビューのためにモデルとのやり取りを記録 |
| モデルルーティング | コード変更なしでデプロイメントやプロバイダーを切り替え |

<Info>
  **想定読者:** SambaStack の OpenAI 互換推論 API の上に制御レイヤー（レート制限、キー管理、ルーティング）を組み込むエンジニア。
</Info>

## アーキテクチャ

SambaStack は、専用の RDU ノード上でモデルデプロイメントを実行し、それらを OpenAI 互換の HTTPS API として公開します。LiteLLM は、これらのエンドポイントの前段にプロキシゲートウェイとして配置されます。

<Frame>
  <img src="https://mintcdn.com/sambanova-systems/emEy6D0rW6i9bD6c/images/docs/admin/litellm/litellm-arch.png?fit=max&auto=format&n=emEy6D0rW6i9bD6c&q=85&s=e32ab6c65619ab7b540f66f3c38da00a" style={{ maxWidth: "120%" }} alt="クライアントアプリケーションと SambaStack 推論 API の間に LiteLLM プロキシを配置した LiteLLM アーキテクチャ図" width="1024" height="189" data-path="images/docs/admin/litellm/litellm-arch.png" />
</Frame>

<Accordion title="責任分担マトリクス">
  | レイヤー | SambaStack | LiteLLM | アプリケーション |
  | :- | :- | :- | :- |
  | **ハードウェアとランタイム** | RDU ノード上でモデルを実行し、カーネル・バッチ処理・キューイングを管理 | – | – |
  | **推論 API** | OpenAI 互換エンドポイントを提供 | 単一のゲートウェイ URL の背後でエンドポイントをプロキシ | SambaStack を直接、または LiteLLM 経由で呼び出し |
  | **トラフィック制御** | プラットフォームレベルの制限 | キー・ユーザー・モデル・チーム単位のレート制限、クォータ、予算 | 任意の保護ロジック |
  | **API キー管理** | プラットフォーム API キーの発行と検証 | アプリ用キーのローテーション・スコープ設定・失効、アプリ用キーとプラットフォームキーのマッピング | アプリレベルのシークレットを保管 |
  | **モデルアクセス制御** | プラットフォーム API キーでデプロイメントへのアクセスを付与 | アプリキー単位でモデルエイリアスを許可/拒否 | ロールやポリシーごとに許可するエイリアスを選択 |
</Accordion>

## 前提条件

作業を始める前に、以下の環境を準備してください。

* Python 3.11 以上と pip
* PostgreSQL データベース（ローカル、セルフホスト、マネージドのいずれか）
* SambaStack の API キーとベース URL

また、以下の環境変数を設定する必要があります。

| 変数 | 説明 |
| :- | :- |
| `SAMBASTACK_BASE_URL` | SambaStack の OpenAI 互換 API のベース URL |
| `SAMBASTACK_API_KEY` | LiteLLM が SambaStack を呼び出す際に使用するプラットフォーム API キー |
| `DATABASE_URL` | PostgreSQL の接続文字列（形式: `postgresql://user:password@host:port/database`） |
| `LITELLM_MASTER_KEY` | LiteLLM プロキシおよび API の管理者キー |
| `LITELLM_SALT_KEY` | DB 内の認証情報を暗号化するためのソルト（一度設定すると変更不可） |
| `PORT` | LiteLLM HTTP サーバーのポート（デフォルト: `4000`） |
| `STORE_MODEL_IN_DB` | `True` に設定すると、モデル定義を DB に保存 |

## はじめに

その他のインストール方法については、[LiteLLM の公式ドキュメント](https://docs.litellm.ai/) をご参照ください。

### ステップ 1: 仮想環境のセットアップ

```bash theme={}
python3 -m venv litellm-env
source litellm-env/bin/activate
pip install "litellm[proxy]" prisma
```

### ステップ 2: 環境変数の設定

```bash theme={}
export SAMBASTACK_BASE_URL="https://your-sambastack-instance.example.com/v1"
export SAMBASTACK_API_KEY="your-sambastack-api-key"
export DATABASE_URL="postgresql://litellm_admin:YOUR_PASSWORD@localhost:5432/sambastack_litellm"
export LITELLM_MASTER_KEY="sk-admin-your-master-key"
export LITELLM_SALT_KEY="sk-salt-your-salt-key"
export PORT=4000
export STORE_MODEL_IN_DB=True
```

### ステップ 3: データベースのセットアップ

スーパーユーザーとして PostgreSQL に接続します。

```bash theme={}
psql -U <SUPERUSER> -d postgres
```

データベースとユーザーを作成します。

```sql theme={}
CREATE USER litellm_admin WITH PASSWORD 'YOUR_PASSWORD';
CREATE DATABASE sambastack_litellm OWNER litellm_admin;
GRANT ALL PRIVILEGES ON DATABASE sambastack_litellm TO litellm_admin;
\c sambastack_litellm
ALTER SCHEMA public OWNER TO litellm_admin;
```

### ステップ 4: データベーススキーマの初期化

```bash theme={}
# Find the schema path dynamically
SCHEMA_PATH=$(python -c "import litellm_proxy_extras; print(litellm_proxy_extras.__path__[0])")/schema.prisma

# Generate client and create tables
prisma generate --schema "$SCHEMA_PATH"
prisma db push --schema "$SCHEMA_PATH"
```

### ステップ 5: 設定ファイルの作成

`litellm_config.yaml` を作成します。

```yaml theme={}
model_list:
  - model_name: "<MODEL_NAME_1>"
    litellm_params:
      model: "sambanova/<MODEL_NAME_1>"
      api_base: "os.environ/SAMBASTACK_BASE_URL"
      api_key: "os.environ/SAMBASTACK_API_KEY"
      rpm: 5
  - model_name: "<MODEL_NAME_2>"
    litellm_params:
      model: "sambanova/<MODEL_NAME_2>"
      api_base: "os.environ/SAMBASTACK_BASE_URL"
      api_key: "os.environ/SAMBASTACK_API_KEY"
      rpm: 5

general_settings:
  database_url: "os.environ/DATABASE_URL"
  database_connection_pool_limit: 100
  database_connection_timeout: 60
```

<Warning>
  `<MODEL_NAME_1>` と `<MODEL_NAME_2>` は、SambaStack 上の実際のモデル名に置き換えてください。
</Warning>

### ステップ 6: LiteLLM プロキシの起動

```bash theme={}
litellm --config ./litellm_config.yaml --detailed_debug
```

### ステップ 7: インストールの確認

<Steps>
  <Step title="LiteLLM UI にログイン">
    `http://localhost:4000/` にアクセスします。ユーザー名に `admin`、パスワードにマスターキーを入力します。
  </Step>

  <Step title="モデル接続の確認">
    **Model Management → Health Status** に移動します。モデルが SambaStack に接続済みとして表示されるはずです。
  </Step>

  <Step title="ヘルスチェックの実行">
    Health Check をクリックして、接続を確認します。

    <img src="https://mintcdn.com/sambanova-systems/emEy6D0rW6i9bD6c/images/docs/admin/litellm/litellm-health-check.png?fit=max&auto=format&n=emEy6D0rW6i9bD6c&q=85&s=65fa8522f1d2d8212c1102042243bba7" alt="LiteLLM のヘルスチェック画面" width="3516" height="1966" data-path="images/docs/admin/litellm/litellm-health-check.png" />
  </Step>
</Steps>

## チーム・キー・レート制限

全機能の詳細については、[LiteLLM の公式ドキュメント](https://docs.litellm.ai/) をご参照ください。

### チームの作成

<Steps>
  <Step title="Teams に移動">
    **Teams → Create New Team** に移動します
  </Step>

  <Step title="チーム設定の入力">
    * **Team name:** 例: `Test-team`
    * **Models:** SambaStack のモデルを選択
    * **Max Budget (USD):** 例: `10`
    * **Reset Budget:** 例: `monthly`
    * **RPM limit:** 例: `3`

          <img src="https://mintcdn.com/sambanova-systems/emEy6D0rW6i9bD6c/images/docs/admin/litellm/litellm-team-creation.png?fit=max&auto=format&n=emEy6D0rW6i9bD6c&q=85&s=ae7ddd0471dbb86c51682dfd6b8fb92f" alt="LiteLLM のチーム作成画面" width="3510" height="1954" data-path="images/docs/admin/litellm/litellm-team-creation.png" />
  </Step>

  <Step title="保存">
    **Save** をクリックしてチームを作成します。
  </Step>
</Steps>

### ユーザーの招待

<Steps>
  <Step title="Internal Users に移動">
    **Internal Users → Invite User** に移動します
  </Step>

  <Step title="ユーザーの設定">
    メールアドレスを入力し、ロールを選択して、チームに割り当てます。

    <img src="https://mintcdn.com/sambanova-systems/emEy6D0rW6i9bD6c/images/docs/admin/litellm/litellm-invite-user.png?fit=max&auto=format&n=emEy6D0rW6i9bD6c&q=85&s=1198674ec446e157e9eda1a85adab9a5" alt="LiteLLM のユーザー招待画面" width="3520" height="1956" data-path="images/docs/admin/litellm/litellm-invite-user.png" />
  </Step>

  <Step title="招待の送信">
    招待リンクをコピーして、ユーザーに共有します。
  </Step>
</Steps>

### 仮想 API キーの作成

<Steps>
  <Step title="Virtual Keys に移動">
    **Virtual Keys → Create New Key** に移動します
  </Step>

  <Step title="キーの設定">
    * **Team:** チームを選択
    * **Key Name:** 例: `limited-key`
    * **Models:** All Team Models または特定のモデルを選択

          <img src="https://mintcdn.com/sambanova-systems/emEy6D0rW6i9bD6c/images/docs/admin/litellm/litellm-key-creation.png?fit=max&auto=format&n=emEy6D0rW6i9bD6c&q=85&s=bbd2bb77e78cd471fa019e78aefd9651" alt="LiteLLM のキー作成画面" width="3526" height="1868" data-path="images/docs/admin/litellm/litellm-key-creation.png" />
  </Step>

  <Step title="キーの作成とコピー">
    **Create Key** をクリックし、キーをすぐにコピーします。キーは一度しか表示されません。
  </Step>
</Steps>

### 仮想 API キーのテスト

```bash theme={}
curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_VIRTUAL_KEY>" \
  -d '{
    "model": "<MODEL_NAME>",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

### 使用状況とログの監視

* **使用状況:** **Usage** タブで、期間・チーム別の支出、リクエスト数、トークン数を確認できます
* **ログ:** **Logs** タブで、レート制限による失敗を含むリクエストの結果を確認できます

<Note>
  デフォルトでは、リクエスト/レスポンスのボディは保存されません。コンプライアンス上必要な場合は、プロキシ設定でボディの保存を有効にしてください。
</Note>

## クラスター内へのインストール

本番環境では、最適なパフォーマンスを得るために、SambaStack と同じ Kubernetes クラスター内に LiteLLM をインストールしてください。詳細は [LiteLLM Kubernetes デプロイガイド](https://docs.litellm.ai/docs/proxy/deploy) をご参照ください。

## トラブルシューティング

### ヘルスチェックの失敗

**症状:** モデルのヘルスチェックが接続エラーを返す。

**対処方法:**

* `SAMBASTACK_BASE_URL` が正しく、アクセス可能であることを確認する
* `SAMBASTACK_API_KEY` が有効であることを確認する
* LiteLLM と SambaStack 間のネットワーク接続を確認する

### データベース接続エラー

**症状:** LiteLLM がデータベースエラーで起動に失敗する。

**対処方法:**

* `DATABASE_URL` の形式が正しいことを確認する
* PostgreSQL が稼働しており、アクセス可能であることを確認する
* データベースとユーザーが存在し、正しい権限が付与されていることを確認する

### Prisma スキーマが見つからない

**症状:** `prisma generate` が「schema not found」エラーで失敗する。

**対処方法:** 仮想環境が有効化されており、`litellm[proxy]` がインストールされていることを確認してください。ステップ 4 で示した動的なパス検出を使用してください。

## 参考情報

* [LiteLLM ドキュメント](https://docs.litellm.ai/)（英語）
* [LiteLLM Kubernetes デプロイ](https://docs.litellm.ai/docs/proxy/deploy)（英語）
* [LiteLLM API リファレンス](https://docs.litellm.ai/docs/proxy/api_reference)（英語）