LiteLLM Proxy をセルフホスト：仮想キー・予算管理と、New API・Magpie との比較

AI アプリケーションの開発やチームでの LLM 利用で、上流プロバイダーのメイン API キーを各クライアントやリポジトリにそのまま入れてしまうと、サービスごとの利用上限を設けられず、キーのローテーションのたびにすべてを書き換えることになります。LiteLLM は Python・AI エンジニアリング分野で広く使われているオープンソースの LLM プロキシです。100 以上のモデルプロバイダーを1つの OpenAI 互換 API にまとめ、/ui 管理画面、仮想キー（Virtual Keys）、予算上限（Budgets）、リクエストごとの費用ログを備えています。

この記事では、Zenavo の LiteLLM テンプレートを使って LiteLLM と PostgreSQL を自分の Linux サーバーにデプロイする手順と、New API・Magpie との選び方の違いを説明します。サーバー、Zenavo、上流のモデル API の料金はそれぞれ別に発生します。

1. LiteLLM と PostgreSQL をデプロイする

Zenavo に Linux サーバーを接続し（1 GB 以上のメモリを推奨）、LiteLLM テンプレートを開いてサーバーを選び、デプロイします。

デプロイすると、プロジェクトのプライベートネットワークでつながった2つのサービスが起動します。

サービス / 変数	値または用途
litellm	イメージ ghcr.io/berriai/litellm:v1.109.1、HTTP ポート 4000
postgresql	イメージ postgres:16、データベース litellm、永続ボリューム /var/lib/postgresql/data
LITELLM_MASTER_KEY	自動生成される sk-... 形式のマスターキー。/ui へのログインと管理 API に使用
LITELLM_SALT_KEY	自動生成される暗号化ソルト。PostgreSQL に保存する上流プロバイダーの API キーを暗号化します
STORE_MODEL_IN_DB	True。/ui 管理画面から追加したモデルを PostgreSQL に永続化します

LITELLM_SALT_KEY は絶対に変更しないでください：管理画面からプロバイダーの認証情報を登録したあとに LITELLM_SALT_KEY を変更すると、データベース内の API キーを復号できなくなります。デプロイしたらすぐに、LITELLM_MASTER_KEY と LITELLM_SALT_KEY の両方をパスワードマネージャー（セルフホストした Vaultwarden など）に控えておいてください。

2. ドメインを設定して /ui 管理画面にログインする

1. litellm サービスの Networking タブで、ポート 4000 に llm.example.com などのカスタムドメインを割り当て、サーバーを指す DNS の A レコードを追加します。詳しくはドメインと HTTPS をご覧ください。
2. litellm サービスの Variable タブで LITELLM_MASTER_KEY をコピーします。
3. ブラウザで https://llm.example.com/ui を開き、ユーザー名 admin と LITELLM_MASTER_KEY でログインします。

postgresql はプライベートネットワーク経由で litellm から参照されるだけなので、外部公開は不要です。

3. モデルの追加と仮想キーの発行

上流モデルを追加する

テンプレートで STORE_MODEL_IN_DB="True" が設定されているため、YAML ファイルを書き換える必要はありません。

1. /ui で Models → Add Model を開きます。
2. プロバイダー（OpenAI、Anthropic、DeepSeek、Gemini、Azure、Bedrock など）を選び、クライアントから呼び出すモデル名（claude-sonnet や gpt-4o など）と上流の API キーを入力します。
3. 保存したら、Test Key / Playground からテストリクエストを送って応答を確認します。

予算上限付きの仮想キー（Virtual Keys）を発行する

アプリケーションのコードや普段のツールでは LITELLM_MASTER_KEY を直接使わず、Virtual Keys → Create New Key から仮想キーを発行します。

• アプリ、メンバー、ツールごとに個別のキーを作成します（例：nextjs-prod、open-webui、claude-code-alex）。
• そのキーで呼び出せるモデルを制限します。
• Max Budget（例：$20）とリセット周期（日次・月次）、およびレート制限（TPM / RPM）を設定します。

4. アプリ・コーディングエージェント・チャット UI を接続する

OpenAI の Base URL を変更できる SDK やツールであれば、そのまま LiteLLM に接続できます。

• アプリケーションのバックエンド（OpenAI SDK / LangChain / Vercel AI SDK）：Base URL に https://llm.example.com/v1、API キーに仮想キーを指定します。アプリも同じ Zenavo プロジェクト内で動いている場合（Next.js + PostgreSQL アプリなど）は、プライベートネットワークの http://litellm.zenavo.internal:4000/v1 を使えばインターネットを経由せず低遅延で通信できます。
• Claude Code と Codex CLI：LiteLLM は /v1/messages と /v1/responses にも対応しているため、New API ガイドの環境変数設定と同じ手順で接続できます。また、Claude Code から MCP で Zenavo のサービスを運用したい場合は、Claude Code から Zenavo プロジェクトをデプロイ・デバッグするをご覧ください。
• チャット UI とパーソナルエージェント：セルフホストした Open WebUI、LobeHub、OpenClaw の OpenAI プロキシ URL に https://llm.example.com/v1（同一プロジェクト内なら http://litellm.zenavo.internal:4000/v1）を設定します。

5. LiteLLM・New API・Magpie：3つのゲートウェイの選び方

Zenavo のテンプレートカタログには、特徴の異なる3種類のオープンソース LLM ゲートウェイが用意されています。

テンプレート	主な特徴	データベース / 保存先	向いている用途
LiteLLM	エンジニアリング・SDK 向けの OpenAI プロキシ。仮想キー、予算上限、ガードレール、Langfuse / OpenTelemetry 連携に対応	PostgreSQL 16	自社 AI アプリのバックエンドや、サービス単位で予算・呼び出しログを管理したい開発チーム
New API	マルチテナント型のキー配布・利用量管理ハブ。ユーザー登録、トークン管理、チャネル重み付けを搭載	デフォルトは SQLite（/data）	チームメンバーごとにアカウントやトークンを配り、Open WebUI・LobeHub・Claude Code・Codex で共有する用途
Magpie	単一コンテナの軽量マルチプロトコルゲートウェイ。Anthropic Messages・OpenAI Responses/Chat・Gemini 間の変換とフェイルオーバーに対応	/config ボリューム	個人開発者や小規模チームが Claude Code・Codex CLI で複数モデルを切り替え、/me ページで利用枠を確認する用途

6. バックアップとアップグレード

LiteLLM のモデル設定、仮想キー、利用ログはすべて postgresql サービスに保存されます。

1. postgresql サービスの Backup & Restore タブからデータベースのバックアップを作成・ダウンロードするか、定期自動バックアップを有効にします。詳しくはバックアップと復元をご覧ください。
2. データベースのバックアップと一緒に、litellm サービスの LITELLM_SALT_KEY も必ず保管してください。元の LITELLM_SALT_KEY がないと、復元したデータベース内のプロバイダーキーを復号できません。
3. アップグレードする際は、先に PostgreSQL をバックアップしてから、litellm サービスの Settings → Source でイメージタグ（デフォルトは v1.109.1）を更新します。

よくある質問

デプロイ直後に /ui を開くと 502 になります。 LiteLLM は起動時に PostgreSQL へ接続して Prisma のデータベースマイグレーションを実行するため、テンプレートでは 40 秒のヘルスチェック猶予時間（start_period: 40）を設けています。サービスの状態が Running になってから再度開いてください。エラーが続く場合は、コンソール右端の Zenavo Agent で起動ログを診断できます。

/ui でモデルを追加しようとするとデータベースに保存できないと表示されます。 litellm サービスの環境変数で STORE_MODEL_IN_DB="True" が設定されていること、および postgresql サービスが Running であることを確認してください。

クライアントで BudgetExceededError が発生します。 その仮想キーの累計利用額が設定した Max Budget に達しています。/ui の Virtual Keys ページで上限を引き上げるか、利用額をリセットするか、月次の自動リセットを設定してください。

LiteLLM と New API を組み合わせて使えますか？ はい。New API で上流チャネルを束ね、アプリケーションの手前に LiteLLM を置いてマイクロサービスごとの予算管理や Langfuse トレースを行う構成もよく使われます。同じ Zenavo プロジェクト内なら .zenavo.internal で接続できます。

LiteLLM テンプレートをデプロイして、数分で PostgreSQL 付き・予算管理対応のモデルプロキシを自分のサーバーで動かしましょう。