LiteLLM Proxy セットアップ — 3モデル LLM ルーター

概要

本プロジェクトは、LiteLLM Proxy を用いたマルチモデル LLM ルーターの自動化セットアップ・デプロイメントです。

3つのAIモデル（ai2/ai4/ai5）を1つのProxy経由で統一API（OpenAI互換）として提供し、 ai4が停止した場合はai2/ai5へ自動フォールバックする耐障害性設計を採用しています。

アーキテクチャ

                    ┌─────────────────────────────┐
  クライアント ───▶ │  LiteLLM Proxy (:4000)       │
                    │                              │
                    │  ルーティング:               │
                    │    ai4 → 軽量高速 (ctx16k)   │
                    │    ai2 → 大規模 (ctx96k)     │
                    │    ai5 → 大規模 (ctx96k)     │
                    │                              │
                    │  Fallback: ai4→ai2/ai5       │
                    └────┬───────────┬──────────┬──┘
                         │           │          │
                   ai2(:48082)  ai4(:48080)  ai5(:48085)
                   Qwen3.6-35B  Qwen3.5-2B   Qwen3.6-35B
                   ctx96k       ctx16k       ctx96k

設計思想

"どう落ちても止まらないか" で決める

設定	値	意図
num_retries	0	リトライせずに即フォールバック（待たない）
timeout	60 秒	60秒でタイムアウト（無限待ちはしない）
fallback	ai4→ai2/ai5	軽量モデルが失敗 → 大規模モデルに退避
Restart=always	systemd	サービス停止時は自動再起動

---

システム要件

項目	要件
OS	Ubuntu 22.04+ / Debian 12+
Python	3.10+
メモリ	4GB+ 推奨
ディスク	10GB+ 推奨
ネットワーク	AIエンドポイントへのローカルアクセス

---

セットアップ手順

1. スクリプトの準備

# リポジトリをクローン
git clone <repository-url>
cd litellm

2. APIキーの準備（任意）

環境変数でAPIキーを設定します。設定しない場合は空のままになります。

export AI2_API_KEY="your-ai2-key"
export AI4_API_KEY="your-ai4-key"
export AI5_API_KEY="your-ai5-key"

3. ドライラン実行（推奨）

まず設定ファイルのみを生成して内容を確認します。

sudo ./setup-litellm.sh --dry-run

生成されるファイル:

• litellm-config.yaml — モデル構成・ルーティング設定
• litellm.env — 環境変数（APIキー・ポート設定）

4. 本番実行

sudo ./setup-litellm.sh

スクリプトが以下のことを自動で行います:

1. 既存環境チェック — 重複インストールを防ぐ
2. 前提パッケージ確認 — Python 3.10+ の検証
3. ディレクトリ作成 — /opt/litellm/ 配下に構成を整理
4. Python venv + litellm インストール — 隔離された環境で実行
5. 設定ファイル生成 — リアルタイムでエンドポイント情報を埋め込み
6. systemd サービス登録 — 常駐化・自動起動
7. 動作確認テスト — モデル一覧 + チャットAPI

5. AIエンドポイントの接続確認

セットアップ完了後、各AIエンドポイントが応答するか確認してください。

# ai2 (port 48082)
curl http://127.0.0.1:48082/v1/models

# ai4 (port 48080)
curl http://127.0.0.1:48080/v1/models

# ai5 (port 48085)
curl http://127.0.0.1:48085/v1/models

---

モデル構成

モデル一覧

名称	ポート	コンテキスト	モデル	用途
ai2	48082	96k	Qwen3.6-35B-A3B-Q5_K_S	メイン大規模モデル（reasoning）
ai5	48085	96k	Qwen3.6-35B-A3B-Q4_K_M	メイン大規模モデル（reasoning）
ai4	48080	16k	Qwen3.5-2B-Q8_0	軽量高速モデル（通常用途）

モデルの選択

OpenAI互換APIとしてアクセスします。

export OPENAI_API_BASE=http://<サーバーIP>:4000
export OPENAI_API_KEY=<master-key>

# ai4 でチャット（軽量・高速）
python3 -c "
from openai import OpenAI
client = OpenAI(base_url=\$OPENAI_API_BASE, api_key=\$OPENAI_API_KEY)
resp = client.chat.completions.create(
    model='ai4',
    messages=[{'role': 'user', 'content': 'こんにちは'}]
)
print(resp.choices[0].message.content)
"

# ai2 でチャット（大規模・推論性能）
python3 -c "
from openai import OpenAI
client = OpenAI(base_url=\$OPENAI_API_BASE, api_key=\$OPENAI_API_KEY)
resp = client.chat.completions.create(
    model='ai2',
    messages=[{'role': 'user', 'content': 'この問題を解いて'}],
    max_tokens=4096  # reasoning modelはトークン消費が多いため大きめに
)
print(resp.choices[0].message.content)
"

Reasoning Model の注意点

ai2/ai5 は reasoning model です。以下に注意してください:

1. トークン消費が多い: reasoning_content に推論プロセスのトークンを消費
2. content が空になりがち: max_tokens を十分大きく設定（4096以上推奨）
3. 応答時間が長い: 推論プロセスのため ai4 より遅い

---

運用コマンド

サービス管理

# 起動・停止・再起動
sudo systemctl start litellm
sudo systemctl stop litellm
sudo systemctl restart litellm

# ステータス確認
sudo systemctl status litellm --no-pager

# 自動起動有効化/無効化
sudo systemctl enable litellm
sudo systemctl disable litellm

ログ確認

# 最新のログ（journald）
journalctl -u litellm --no-pager -n 50

# リアルタイムフォロー
journalctl -u litellm -f

# 特定の時間以降のログ
journalctl -u litellm --since "1 hour ago"

# エラーのみ抽出
journalctl -u litellm -p err --no-pager

# 直近5分間のエラーカウント
journalctl -u litellm --since "5 min ago" | grep -ci error

ヘルスチェック

#!/bin/bash
# litellm-healthcheck.sh — LiteLLM Proxy ヘルスチェック

PROXY_URL="http://localhost:4000"

# 1. サービス死活チェック
if systemctl is-active --quiet litellm; then
    echo "[OK] Service: litellm is active"
else
    echo "[CRIT] Service: litellm is NOT active"
    exit 2
fi

# 2. モデル一覧取得テスト
if curl -sf --max-time 5 "${PROXY_URL}/v1/models" | grep -q "ai4"; then
    echo "[OK] Models: /v1/models responded"
else
    echo "[WARN] Models: /v1/models failed or slow"
fi

# 3. チャットAPIテスト（ai4）
RESPONSE=$(curl -sf --max-time 10 "${PROXY_URL}/v1/chat/completions" \
    -H 'Content-Type: application/json' \
    -d '{"model":"ai4","messages":[{"role":"user","content":"test"}]}')

if echo "$RESPONSE" | grep -q "content"; then
    echo "[OK] Chat: ai4 responded with content"
else
    echo "[WARN] Chat: ai4 did not return expected content"
fi

echo ""
echo "Health check completed."

---

trouble shooting

Proxy が起動しない

# 1. サービスステータス確認
sudo systemctl status litellm --no-pager

# 2. ログを確認
journalctl -u litellm --no-pager -n 100

# 3. よくある原因
#    - AIエンドポイントが応答していない
#    - APIキーが設定されていない（空でも動作する）
#    - port 4000 が既に使用中
lsof -i :4000

モデルが認識されない

# /v1/models で確認
curl -s http://localhost:4000/v1/models | python3 -m json.tool

# AIエンドポイントが応答するか直接確認
curl -s http://127.0.0.1:48082/v1/models   # ai2
curl -s http://127.0.0.1:48080/v1/models   # ai4
curl -s http://127.0.0.1:48085/v1/models   # ai5

# 設定ファイルを確認
cat /opt/litellm/etc/litellm-config.yaml

fallback が動作しない

• num_retries: 0 と timeout: 60 が router_settings に設定されているか確認
• fallbacks キーが litellm-config.yaml のトップレベルにあるか確認
• ai4のエンドポイントが実際に停止しているか確認（curlで直接アクセス）

# ai4 を意図的に無効化してテスト
sudo sed -i 's/^AI4_API_KEY=.*/AI4_API_KEY=/' /opt/litellm/etc/litellm.env
sudo systemctl restart litellm
sleep 5
curl -s http://localhost:4000/v1/chat/completions \
    -H 'Content-Type: application/json' \
    -d '{"model":"ai4","messages":[{"role":"user","content":"test"}]}' | python3 -m json.tool

# 元に戻す
sudo sed -i 's/^AI4_API_KEY=.*/AI4_API_KEY=<actual-key>/' /opt/litellm/etc/litellm.env
sudo systemctl restart litellm

APIキーエラー (401)

• litellm.env に各モデルのAPIキーが設定されているか確認
• キーに空白や改行が含まれていないか確認
• 環境変数から読み取る場合は os.environ/AI2_API_KEY 形式になっているか確認

cat /opt/litellm/etc/litellm.env

ディスク容量の問題（journald）

# journald のディスク使用量を確認
journalctl --disk-usage

# 古いログを削除（直近3日間のみ保持）
sudo journalctl --vacuum-time=3d

# またはサイズで制限（100MBまで）
sudo journalctl --vacuum-size=100M

---

ファイル構成

/opt/litellm/
├── app/                        # インストールディレクトリ
│   ├── .venv/                  # Python venv
│   └── litellm                 # LiteLLM バイナリ
├── etc/                        # 設定ファイル
│   ├── litellm-config.yaml     # Proxy 設定
│   └── litellm.env             # 環境変数（APIキー等）
└── logs/                       # ログ出力先

設定ファイルの説明

litellm-config.yaml — LiteLLM Proxy の主要設定

• model_list: モデル定義（エンドポイント・APIキー）
• fallbacks: フォールバック先モデル
• router_settings: ルーター動作設定（retries, timeout）

litellm.env — 環境変数ファイル

• AI2_API_KEY, AI4_API_KEY, AI5_API_KEY: Provider APIキー
• HOST, PORT: Proxy リッスン設定

---

アンインストール

sudo ./setup-litellm.sh --uninstall

以下の操作を自動で行います:

1. サービス停止・無効化
2. systemd ユニットファイル削除
3. /opt/litellm/ 全体の削除
4. クリーンアップ確認

---

ライセンス

本プロジェクトは内部運用目的のスクリプト集です。

---

リリース情報

バージョン	日付	内容
v1.0	2026-05-08	初回安定版 — セットアップ自動化、3モデルルーター、運用ドキュメント完了

詳細は CHANGELOG.md を参照してください。