litellm

LiteLLM AI ゲートウェイの運用

このスキルでは、組織の AI ゲートウェイとして LiteLLM を運用します。プロキシ（litellm --config config.yaml）を実行し、単一の OpenAI 互換 API を通じて 100 以上の LLM プロバイダーにリクエストをルーティングし、モデルリスト、ルーティングと信頼性、仮想キー、チーム、予算とレート制限、キャッシュ、ガードレール、可観測性、利用額を管理し、証拠に基づいて障害を診断します。LiteLLM には 2 つの提供形態があります。Python SDK（litellm.completion()、プロセス内で動作）とプロキシ（キー、予算、管理 UI を備えたポート 4000 の FastAPI サービス）です。これは、記載されているツールを対象としたツールスキルです。エンジンの選定とサービング方法については ml-engineering、単一エンジンの運用については vllm または llama-cpp を参照してください。

運用上の契約

1. 調整する前にデプロイメントを記録します。 固定されたイメージまたは pip のバージョン、config.yaml、モデルリスト、ルーティング、予算、環境変数の参照先、データストアをプロキシ設定記録に記録します。この記録がロールバックの単位となります。
2. 変更を加える前に、対象、範囲、ロールバック手順を確認します。 読み取り専用の調査（ヘルスプローブ、/v1/models、ログ、利用額のクエリ）は確認なしで実施できます。変更（設定変更、キーの発行・失効、再起動、イメージのアップグレード、DB マイグレーション）には、デプロイメントを指定した人間からの明示的な指示が必要です。
3. 応答するプロキシが、リクエストを処理できるプロキシとは限りません。 /health/liveliness が 200 を返すことが証明するのは、稼働状態のみです。配信境界で確認してください。代表的な /v1/chat/completions リクエストがトークンを返し、x-litellm-model-id に想定したデプロイメントが示されていることを確認します。
4. 証拠の共有範囲を制限します。 ログと設定は要約し、完全なログ、.env の内容、マスターキー、プロバイダーの認証情報をチャットに出力しないでください。利用額のログやデバッグ出力にはプロンプトの内容が含まれる場合があります。共有前に秘匿情報を除去してください。
5. バージョンを固定します。 LiteLLM は毎週リリースされ、デフォルト設定も変更されます。ここに記載したすべての情報は 1.97.0（2026-08-22）で確認しています。バージョンに左右される動作を前提にする前に、インストール済みのリリースで再確認してください。

litellm-health スクリプト

scripts/litellm-health は、実行中のプロキシを読み取り専用で検査するプローブです。GET リクエストのみを送信し、ファイルへの書き込みは行わず、出力も制限されています。

scripts/litellm-health --help                                   # no proxy needed
scripts/litellm-health --url http://127.0.0.1:4000 --json
scripts/litellm-health --check health --check readiness --json
scripts/litellm-health --check models --check model_info \
  --key "$LITELLM_MASTER_KEY" --json

終了コード：0 はすべてのチェックに合格、1 は問題の検出または致命的なエラー、2 は使用方法のエラー、124 はタイムアウトです。チェック項目：health（GET /health/liveliness、認証不要）、readiness（GET /health/readiness、認証不要。設定された DB に接続できない場合は 503）、models（GET /v1/models、キーが必要）、model_info（GET /model/info、キーが必要）。キーは Authorization: Bearer <key> として送信されます。このスクリプトは、指定されたプロキシ以外にはデータを一切送信しません。

運用の流れ

1. デプロイメントを特定します：固定されたバージョン／イメージダイジェスト、実行方法（ベアメタル、Docker、Compose、Helm）、設定ソース（ファイル、store_model_in_db、または両方）、データストア（Postgres？ Redis？）。
2. 証拠を収集します：litellm-health --json、キーを使った GET /v1/models と /model/info、レスポンスヘッダー（x-litellm-call-id、 x-litellm-model-id、x-litellm-model-api-base、x-litellm-version）、 アウトバウンドリクエストを確認するための --detailed_debug ログまたは LITELLM_LOG=DEBUG。
3. 症状に照らしてトリアージします：プロバイダーのエラーとゲートウェイのエラーを分類し（トラブルシューティングを参照）、クールダウン状態、予算、DB 接続を確認します。
4. 確認を得て対応します：人間からの指示を受けた後、範囲を限定した変更を行います。最初にロールバック手順を明示してください。
5. 検証します：プローブを再実行し、配信境界で代表的なチャットリクエストを実行します。

クイックスタート：1つの設定で複数のプロバイダーを利用

model_list:
  - model_name: gpt-4o                     # name clients request
    litellm_params:
      model: openai/gpt-4o                 # routed string (provider prefix required)
      api_key: os.environ/OPENAI_API_KEY   # resolved inside the proxy process
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY   # require auth on every call

litellm --config config.yaml --port 4000 で起動します。成功すると、ログに Proxy initialized with Config, Set models: と表示されます。クライアントは OpenAI のインターフェイスを呼び出します。 /v1/chat/completions、/chat/completions、/v1/embeddings、/v1/images/generations、 /v1/audio/transcriptions に加え、/responses、Anthropic 互換の /messages、 /model/info、/health/liveliness、/health/readiness を利用できます。OpenAI SDK は そのまま使用できます：openai.OpenAI(base_url="http://localhost:4000", api_key=<virtual key>)。 詳細と SDK のインターフェイスについては、クイックスタートのリファレンスを参照してください。

設定とルーティング

• 同じ model_name を共有するエントリーは、1つの負荷分散グループを構成します。各エントリーはデプロイメントであり、ヘルスチェックとクールダウンの追跡に使われる固有のハッシュ化された model_id を持ちます。
• router_settings.routing_strategy — simple-shuffle（デフォルト、推奨。litellm_params の rpm／tpm または weight に基づいて重み付け）、least-busy、 latency-based-routing、usage-based-routing（ドキュメントでは本番環境での使用を推奨していません）、 cost-based-routing。
• 信頼性：litellm_settings.num_retries（デプロイメント単位およびリクエスト単位のオーバーライドが可能です。num_retries はプロバイダー SDK の max_retries ではありません）、 fallbacks／context_window_fallbacks／content_policy_fallbacks、 クールダウン（allowed_fails、cooldown_time）、優先順位を指定するデプロイメントの order、 呼び出し前にコンテキストウィンドウとリージョンフィルターを適用する enable_pre_call_checks: true（オプトイン）。
• store_model_in_db: true の場合、UI／API による書き込みは Postgres の YAML 設定にディープマージされ、キーが競合すると UI／API の値が優先されます。該当する YAML キーを後から編集しても、DB の行が存在する間は反映されません。詳細は、設定とルーティングのリファレンスを参照してください。

キー、チーム、予算、利用額

• general_settings.master_key（sk- で始まる必要があります）は管理者の認証情報であり、UI のパスワードでもあります。仮想キー（POST /key/generate）では、ワークロードごとにモデル、予算、rpm／tpm を設定できます。キーはハッシュ化して保存され、プロバイダーの認証情報が含まれることはありません。
• 予算機能には Postgres が必要です。 DB に接続していない場合、予算チェックはフェイルオープンとなり（起動時の警告のみが通知されます）、キー関連のエンドポイントは No connected db. を返します。予算が重要なデプロイメントを DB なしで実行しないでください。
• チームキーで適用されるのは、チームおよびチームメンバーの予算のみです。オーナー個人の予算は適用されません。レート制限はプロキシ管理者には適用されません。利用額は /spend/logs と /global/spend に記録されます。store_prompts_in_spend_logs のデフォルト値は false です。 詳細は、キーと予算のリファレンスを参照してください。

キャッシュとガードレール

• レスポンスキャッシュ：本番環境で複数インスタンスを運用する場合は、litellm_settings.cache: true と cache_params.type: redis を設定します（インメモリキャッシュはプロセスごとです。ディスク／S3／GCS も利用できます）。リクエスト単位の制御：リクエスト本文に cache: {ttl, no-cache, namespace} を指定します。
• セマンティックキャッシュ（qdrant-semantic、redis-semantic、valkey-semantic）はメッセージ配列全体を埋め込み表現に変換するため、類似した複数ターンのやり取りで古い回答が再利用されることがあります。ドキュメントでは、エージェント型のトラフィックをセマンティックキャッシュから除外することを推奨しています。
• ガードレールは pre_call、post_call、during_call、logging_only のいずれかで実行されます（all モードはありません）。Presidio による PII マスキングは OSS です。違反があると HTTP 400 と判定結果が返されます。x-litellm-applied-guardrails には実行されたガードレールが示されます。 詳細は、キャッシュとガードレールのリファレンスを参照してください。

オブザーバビリティとログ記録

• コールバック：litellm_settings.success_callback / failure_callback / callbacks （Langfuse、OTel、Prometheus、Datadog、Sentry など）。Prometheus の /metrics には 1.85.0 以降、認証が必要です。スクレイパーにベアラーキーを渡すか、 require_auth_for_metrics_endpoint: false を設定してください。
• フォレンジック用レスポンスヘッダー：x-litellm-call-id、x-litellm-model-id、 x-litellm-model-api-base、x-litellm-version、x-litellm-response-cost。
• プライバシー：turn_off_message_logging: true にすると、メタデータは保持されますが、コールバックからコンテンツが除外されます。redact_user_api_key_info: true にすると、キー／ユーザー／チームの識別子がマスキングされます。 --detailed_debug、LITELLM_LOG=DEBUG、またはリクエストごとの "litellm_request_debug": true でデバッグできます。 詳細：オブザーバビリティのリファレンス。

デプロイ

• キー、チーム、利用額、予算、UI の状態には Postgres が必須です。複数のインスタンスを使用する場合は Redis >=7 が必要です（共有のレート制限カウンター、クールダウン、キャッシュ）。
• イメージタグを固定してください（ghcr.io/berriai/litellm:vX.Y.Z — semver タグは 1.84.0 以降。-stable サフィックスは廃止され、main-latest は非推奨です）。イメージには cosign 署名が付与されています。
• Prisma のマイグレーションはデフォルトで起動時に実行されます。Kubernetes では、サービングポッドで DISABLE_SCHEMA_UPDATE=true を設定し、マイグレーションジョブのパターンを使用してください。ポッドごとの Uvicorn ワーカーは 1 つにします。DB プールのサイズは MAX_DB_CONNECTIONS / (instances x workers) にしてください。 詳細：デプロイのリファレンス。

セキュリティとパブリックホスティング

• インターネットからアクセス可能なプロキシの最低バージョンは >=1.83.7 です（CVE-2026-42208 の認証前 SQLi、CVE-2026-42203 の SSTI、CVE-2026-42271 のコマンドインジェクション、および CVE-2026-48710 のホストヘッダーチェーンに対する Starlette >=1.0.1）。これらのうち 2 件は CISA KEV に掲載され、2026 年に実際に悪用されました。
• 管理用ルート（/key/*、/user/*、/team/*、/config/*、 /model/*、/spend/*、/ui、/prompts/test、/mcp-rest/*）は絶対に公開しないでください。allowed_routes によるルートの制限は Enterprise の機能です。OSS ではリバースプロキシで制限してください。
• LITELLM_SALT_KEY は DB に保存されたプロバイダーの認証情報を暗号化します。一度設定したら、モデルを追加した後に変更しないでください。マスターキーのローテーションは、ドキュメントに記載された手順でのみ行ってください。
• 2026 年 3 月のサプライチェーンインシデント：バックドアが仕込まれた litellm==1.82.7/.8 の PyPI ホイールが約 40 分間公開されました。固定されていない pip インストールより、cosign 検証済みの固定イメージを推奨します。 セキュリティ強化チェックリスト：セキュリティのリファレンス。

トラブルシューティング：基本の診断ルール

エラーに <Provider>Exception が含まれている場合、失敗したのはプロバイダーであり、ゲートウェイではありません。 AnthropicException、OpenAIException、BedrockException などは、上流への呼び出しが実行されたことを意味し、そのレスポンスが証拠になります。プロバイダー名が含まれていない場合は、ゲートウェイ自体が呼び出しを拒否しています（無効な LiteLLM キー、不明なモデル、クールダウン、予算）。

症状	最初に行うこと
Invalid model name passed in model=X	model_list に名前がないか、キーに許可されていません。同じキーで GET /v1/models を確認してください
No deployments available for selected model, Try again in N seconds	すべてのデプロイメントがクールダウン中（通常は上流の 429）か、litellm_params.model にプロバイダーのプレフィックスがありません
AnthropicException - Overloaded（HTTP 500、Anthropic の 529）	プロバイダー側の過負荷です。再試行またはフェイルオーバーしてください。ゲートウェイのバグではありません
Authentication Error ... ExceededTokenBudget	キー／チームの予算を使い切っています。GET /key/info を確認してください
起動時の ImportError: cannot import name 'get_flat_dependant'	fastapi が固定された litellm のバージョンに対して新しすぎます。1.97.0 では fastapi==0.136.3 に固定してください

エラーの全分類と対処方法：トラブルシューティングのリファレンス。

リファレンスの案内

読み込むタイミング	リファレンス
ソース、バージョンの確認、更新手順	references/00-source-index.md
プロキシのクイックスタート、config.yaml、Python SDK、OpenAI-SDK のドロップイン	references/01-quickstart-and-sdk.md
model_list、ルーティング戦略、リトライ／フォールバック／クールダウン	references/02-config-and-routing.md
仮想キー、チーム、予算、レート制限、使用額	references/03-keys-teams-budgets-spend.md
レスポンスキャッシュとガードレール	references/04-caching-and-guardrails.md
コールバック、Prometheus、ヘッダー、プライバシー設定	references/05-observability-and-logging.md
Docker／Compose／K8s／Helm、スケーリング、移行、アップグレード	references/06-deployment.md
公開環境向けの堅牢化、CVE の最低基準、サプライチェーン	references/07-security-and-public-hosting.md
エラー分類、障害モード、デバッグワークフロー	references/08-troubleshooting.md

同梱アーティファクト

• scripts/litellm-health：読み取り専用のプロキシプローブ（標準ライブラリのみ、--json、--check サブセット、認証が必要なルート用の --key、サーバーなしでの --help）。
• tests/test_litellm_health.py：読み取り専用の契約を含む、ローカルのスタブ HTTP サーバーに対する決定的なテスト。
• templates/proxy-config-record.md と templates/proxy-deployment.md：記入可能な記録です。config record はロールバック単位であり、deployment record はランタイム（イメージダイジェスト、ポート、環境変数、データストア、プローブ、ロールバック）を固定します。
• references/：上記のトピックを網羅する、日付とソースインデックス付きの9つのリファレンス。
• evals/evals.json：出力品質を評価する6つのケース。

検証の境界

主張	最低限必要な証拠
プロキシが稼働している	litellm-health --check health で /health/liveliness が 200 と報告される
プロキシが準備できている	--check readiness で /health/readiness が 200 と報告される（503 は DB が停止していることを意味します）
正しいモデルが登録されている	/v1/models（呼び出し元のキーを使用）に想定されるエイリアスが一覧表示される
デプロイが正しく設定されている	/model/info に、キーがマスキングされた状態で想定される litellm_params が表示される
推論が機能している	代表的な /v1/chat/completions リクエストがトークンを返し、x-litellm-model-id が意図したデプロイメントを示す
予算が適用されている	接続済みの DB が検証され（readiness）、/key/info にキーの使用額追跡が表示される
診断が妥当である	主張の前に証拠（エラー文字列、ヘッダー、ログ）が収集され、プローブと代表的なリクエストを再実行して修正を検証している

厳守すべき境界

• 明示的な人間の指示で対象とロールバック手順が指定されていない限り、本番プロキシ（設定、キー、チーム、予算、イメージ、DB）を変更してはいけません。読み取り専用の調査は自由に行えます。
• マスターキー、管理ルート、または /ui を信頼境界の外に公開してはいけません。認証はネットワークおよび TLS の制御の代わりにはなりません。
• プロバイダーキー、DATABASE_URL、LITELLM_MASTER_KEY、LITELLM_SALT_KEY をどこにもコミットしてはいけません。os.environ/ の参照とシークレットマネージャーを使用してください。
• Postgres なしで、予算が重要な公開デプロイメントを実行してはいけません。Postgres がないと予算はフェイルオープンになります。
• /health/liveliness からの 200 を、ゲートウェイがリクエストを処理できる証明とみなしてはいけません。デリバリー境界で検証してください。

使用しないケース

• エンジンの選定、サービング方式、量子化の判断、評価設計 — これは ml-engineering の対象です。
• 単一の推論エンジンの運用 — vLLM には vllm、 llama.cpp のスタックには llama-cpp を使用します。LiteLLM はエンジンへのルーティングを担いますが、 エンジン自体の運用に代わるものではありません。
• Kubernetes／Docker の基礎やリバースプロキシ／TLS の設定 — これは kubernetes、docker-compose、 traefik の対象です。このスキルでは LiteLLM 固有のレイヤーを扱います。
• LLM API 上にアプリケーションを構築すること（アプリのアーキテクチャ、エージェントフレームワーク） — これはバックエンド／フロントエンドエンジニアリングの対象です。このスキルではゲートウェイとその SDK を扱います。