LiteLLMのよくあるエラー：タイムアウト、予算アラート、プロバイダー障害

LiteLLMのよくあるエラー：タイムアウト、予算アラート、プロバイダー障害

多くのLiteLLMのよくあるエラーは、最初はプロバイダーの問題に見えます。リクエストがタイムアウトしたり、予算アラートが届かなかったり、正常だったモデルが突然404や503を返したりします。再試行を変更したりモデルを入れ替えたりする前に、障害が発生している制御レイヤーを特定することが、最も迅速な解決策です。

このガイドでは、クライアントの期限、LiteLLMゲートウェイのポリシー、モデル設定、プロバイダーの容量、支出の強制を切り分けます。タイムアウト、予算制御、プロバイダー障害に繰り返し利用できる小規模なインシデント対応ワークフローも含まれています。

簡単な回答：失敗したリクエストを1件保存し、エラーを分類し、最小限の呼び出しで再現して、一度に1つの制御だけを変更します。HTTPステータスだけでなく、LiteLLMの正規化された例外タイプ、リクエストメタデータ、呼び出しIDから確認を始めてください。

LiteLLMは多くのプロバイダー障害をOpenAI互換の例外タイプにマッピングし、HTTPステータス、メッセージ、発生元プロバイダーを例外上で公開します。そのため、元のエラーコンテキストを汎用的な500に置き換えずに保持すれば、LiteLLMのよくあるエラーをより簡単にトラブルシューティングできます。現在のマッピングについては、LiteLLMの例外マッピングリファレンスを参照してください。

LiteLLMのよくあるエラーのマトリクス

この表は、このLiteLLMのよくあるエラーガイドにおける主要な価値のある要素です。曖昧なゲートウェイ障害を、次に確認すべき具体的な観測事項へと変換します。

5分で行うLiteLLMのよくあるエラーのトリアージフロー

config.yamlを編集する前に、代表的な障害を1件保存してください。必要に応じてシークレットとプロンプト内容をマスキングしますが、運用上のフィールドは保持します。

1. リクエストの識別情報を取得する。タイムスタンプ、環境、ルート、要求されたmodel、HTTPステータス、LiteLLM例外タイプ、エラーメッセージ、プロバイダー名、クライアントの試行回数を記録します。
2. ゲートウェイの識別情報を取得する。存在する場合はx-litellm-call-idを保存します。LiteLLMはこのヘッダーを、ログシステムを通じてリクエストを追跡するための最適な手がかりとして文書化しています。また、レスポンスで公開されている場合は、x-litellm-model-id、x-litellm-model-api-base、バージョンヘッダーも記録します。現在のヘッダーについては、LiteLLMのロギングドキュメントに一覧があります。
3. 障害を分類する。無効なリクエスト、認証／権限の問題、予算／レート制限、タイムアウト、アップストリームサービス障害のどれでしょうか。すべての4xxエラーを1つの再試行バケットに入れないでください。
4. 本番環境以外で最小限の再現を1回行う。アプリケーションが使用するものと同じ仮想キーおよびパブリックmodel_nameを使用します。基本的なリクエストをテストする前に、アプリケーション固有の同時実行設定とツール呼び出しを削除します。
5. 変更するレイヤーは1つだけにする。同じデプロイメントでモデル名の修正、タイムアウト変更、フォールバック変更を行うと、最終結果を説明できなくなります。

以下は、OpenAI互換のLiteLLMプロキシ向けの汎用的な最小プローブです。

curl -i --request POST "$LITELLM_PROXY_URL/v1/chat/completions" \
  --header "Authorization: Bearer $LITELLM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "support-chat",
    "messages": [{"role": "user", "content": "Reply with OK."}],
    "max_tokens": 16
  }'

要点は、support-chat が汎用的なモデル名だということではありません。テストでは、ゲートウェイで設定されている公開名を使用し、その後、失敗したアプリケーションリクエストと比較できるようレスポンスヘッダーと本文を保持することが重要です。

タイムアウトエラー：実際に発生した期限を特定する

タイムアウトは、リクエストが複数のレイヤーで期限切れになる可能性があるため、最も誤解を招きやすいLiteLLMのよくあるエラーの一つです。

• 呼び出し元が先にキャンセルする可能性があります。
• LiteLLMのデプロイメントまたはルーターが、より短い期限を適用する可能性があります。
• プロキシのrequest_timeoutが、長時間実行されるアップストリーム呼び出しを停止することがあります。
• プロバイダー、ロードバランサー、またはネットワーク経路がリクエストを切断することがあります。
• ストリーミングレスポンスは正常に開始しても、チャンク間で停止することがあります。

LiteLLMの例外マッピングでは、タイムアウト障害はopenai.APITimeoutErrorとして記載されています。ネイティブルートとパススルールートについては、現在のタイムアウトのドキュメントで、リクエスト、デプロイメント、ルーター、プロキシの設定にまたがる優先順位が説明されています。設定変更を適用する前に、デプロイメントに対応するバージョンのドキュメントを確認してください。

より大きな数値ではなく、期限予算から始める

ユーザーフローで許容できる合計レイテンシーを決め、それを逆算して配分します。たとえばインタラクティブな体験では、アップストリーム呼び出しにユーザーに見える期限全体を消費させるのではなく、キューイング、1回のリトライ、レスポンスのレンダリングのために時間を確保できます。

# 説明用の開始点 — ワークロードとLiteLLMのバージョンに合わせて調整してください。
litellm_settings:
  request_timeout: 60
  set_verbose: false
  json_logs: true

この例は意図的に保守的です。接続をハングさせるのではなく、プロキシに境界のある失敗モードを与えます。LiteLLMの本番環境向けガイダンスでは、リクエストタイムアウトの設定と構造化された本番ログの使用が推奨されています。

タイムアウトが発生した場合は、次の質問に順番に答えてください。

自動化されたタイムアウトリトライを無期限に続けないでください。リトライが妥当なのは、処理を安全に繰り返すことができ、代替の試行が呼び出し元の期限内に完了できる場合だけです。リクエストがツールをトリガーする、データを書き込む、またはユーザーに見えるストリームを開始する場合は、まず冪等性と再開のセマンティクスを定義してください。

長いレイテンシーとして現れる429起因のキューイングまたは容量問題については、このセクションをFlatkeyのRPM、TPM、リトライガイドと併せて確認してください。タイムアウトは、リクエスト時間設定の問題ではなく、過負荷の受け入れ制御の症状である可能性があります。

予算アラート：通知と強制を分ける

予算の動作は、チームがしばしば3つの異なる制御を「アラート」という言葉にまとめてしまうため、LiteLLMのよくあるエラーの不釣り合いに大きな割合を占めます。これらは互換的なものではありません。

最初の予算チェック：データベースはあるか？

LiteLLMの現在の予算に関するドキュメントでは、プロキシの予算はデータベースから読み取った支出に対して強制されることが明記されています。DBなしのデプロイメントでは、設定されたグローバルmax_budgetは信頼できる支出上限として機能しません。仮想キー、チーム、ユーザーの予算動作もデータベースに依存します。

これにより、よくある障害パターンが生じます。チームがmax_budgetを設定し、起動時の警告または設定値を確認して、本番トラフィックがしきい値で停止すると想定するのです。必要な支出追跡設定がなければ、これは信頼できる制御にはなりません。

# 説明用のポリシーのみ。本番展開前に非本番キーで検証してください。
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  fail_closed_budget_enforcement: true

litellm_settings:
  max_budget: 100
  budget_duration: 30d

fail_closed_budget_enforcementは、コピー＆ペーストで解決するものではなく、信頼性に関する判断として扱ってください。現在のLiteLLMドキュメントでは、より厳格な予算チェックにより、支出を検証できない場合にリクエストが拒否される可能性があると説明されています。広範に有効化する前に、デプロイ環境におけるデータベースおよびRedisの障害時の挙動をテストしてください。

ダッシュボードだけでなく、予算処理経路をテストする

非本番環境で使い捨てのキーまたはチームを使用し、次の手順を確認してください。

1. プロキシが支出ストアを読み書きできることを確認します。
2. キー、チーム、ユーザー、プロジェクト、エンドユーザーのいずれか、正しいスコープに意図的に小さなハード予算を作成します。
3. プロキシ経由で最小限のリクエストを送信します。
4. しきい値を必ず超える2回目のリクエストを送信します。
5. 返された例外、支出レコード、リセット期間、アラートチャネルをそれぞれ個別に確認します。
6. 一時的なプロバイダー過負荷であるかのように再試行せず、アプリケーションが予算ブロックを処理できることを確認します。

LiteLLMは、予算期間およびモデルごとの予算制御についても説明しています。リセットスケジュールを正確に設定してください。日次のガードレールと月次の上限は、異なるリスクを解決します。

Azure予算アラートとAWS予算アラートは代替手段ではなく、バックストップである

副次キーワードであるAzure budget alertsとAWS budget alertsが重要なのは、クラウドプロバイダーの請求アラートが異なる境界を対象とするためです。LiteLLMをバイパスするトラフィックを含め、プロバイダーアカウントまたはサブスクリプションの支出について警告できます。ただし、このリクエスト、このキー、このテナント、またはこのモデルを今受け入れるべきかどうかという、ゲートウェイレベルの判断に代わるものではありません。

適切な場合は、両方のレイヤーを使用してください。

• LiteLLMの予算ポリシーは、ゲートウェイが識別できるルートとテナントを保護します。
• Azure予算アラートまたはAWS予算アラートは、上流のクラウドアカウント支出を監視します。
• ゲートウェイの使用量台帳は両者を照合し、意図された経路をバイパスしたトラフィックを明らかにします。

OpenAIの支出については、LiteLLMの支出キャプチャ率チェックで、追跡された支出をOpenAI Organization Costs APIと比較できます。現在はプロバイダー固有の前提条件があるため、これを汎用的なマルチプロバイダー照合機能として扱う前に、バージョン対応のドキュメントを確認してください。

運用上のニーズが単一のLiteLLMデプロイメントを超える場合は、キー、予算、配分、アラート、照合について確認すべき質問をまとめた統合AI請求ダッシュボード評価ガイドを参照してください。

プロバイダー障害：公開モデル名と上流デプロイメントを個別に検証する

プロバイダー障害は最も目立つLiteLLM Common Errorsですが、多くの場合はゲートウェイ設定のエラーです。クライアントは通常、公開されているmodel_nameを呼び出します。LiteLLMはその名前を、プロバイダーモデル、デプロイメント、エンドポイント、認証情報、およびプロバイダー固有のパラメーターに解決します。

model_list:
  - model_name: support-chat       # クライアントがリクエストする名前
    litellm_params:
      model: azure/<deployment-name>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

model_nameとlitellm_params.modelは、意図的に異なる概念です。クライアントで無効なモデルエラーが発生した場合は、まず正確にリクエストされた名前とmodel_nameを比較してください。LiteLLMのモデル管理ドキュメントでは、公開モデル名とプロバイダーモデルを区別し、設定済みモデルの接続テストワークフローを提供しています。

プロバイダー障害の判断表

例外タイプに応じて、次に取るべきアクションを決める必要があります。LiteLLMの例外リファレンスでは、401、402、403、404、408、429、500、503の状態を正規化されたクラスにマッピングしています。また、詳細な調査のためにプロバイダー固有のフィールドも公開しています。

リトライ、フォールバック、クールダウン：インシデントを隠さずに復旧する

リトライとフォールバックは、表面化する障害を減らせますが、設定エラーをレイテンシー、コスト、または重複作業へと変えてしまう可能性もあります。適切なLiteLLMのよくあるエラーへの対処では、無効な設定と短時間のプロバイダー中断に対して異なるポリシーを使用します。

LiteLLMでは、次のような有用な区分が示されています。

• リトライは、現在のモデルグループ内での復旧を試みます。
• フォールバックは、設定されたリトライの後に別のモデルグループへ移行します。
• クールダウンは、正常な代替手段を利用可能な状態に保ちながら、障害が発生しているデプロイメントを分離します。

以下は、LiteLLMのプロバイダーフェイルオーバーガイドに基づく、小規模な例示用設定です。

model_list:
  - model_name: primary-chat
    litellm_params:
      model: openai/<primary-model>
      api_key: os.environ/PRIMARY_PROVIDER_KEY

  - model_name: backup-chat
    litellm_params:
      model: azure/<backup-deployment>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

litellm_settings:
  num_retries: 1
  request_timeout: 30
  fallbacks: [{"primary-chat": ["backup-chat"]}]
  allowed_fails: 3
  cooldown_time: 30

これは、意図的に発生させた本番環境以外のプロバイダーエラーでのみ検証してください。LiteLLMのドキュメントでは、古いモックフォールバックフラグはプロキシリクエストをテストしないと警告されています。実際に制御された障害を発生させることが、適切なプロキシ検証方法です。

明示的に別の対応を設計していない限り、404、認証、権限、スキーマ、およびコンテンツポリシーの状態を一般的なリトライループに含めないでください。LiteLLMのルーティングドキュメントは、NotFoundErrorに対するリトライ回数ゼロを含む、エラー固有のリトライポリシーをサポートしています。これにより、無効なモデル名が長引くインシデントになることを防げます。

クロスプロバイダーフォールバックを有効にする前に、プロダクト契約を検証してください。

• コンテキストウィンドウの動作とツールコールのセマンティクス
• 構造化出力およびレスポンス形式のサポート
• データレジデンシー、保持、および顧客ポリシーの要件
• 安全性の動作とコンテンツポリシーに関する期待
• レイテンシーとコストの境界
• ダウンストリーム副作用の冪等性

フォールバックは、リクエスト後に観測可能であるべきであり、サイレントに行われるべきではありません。LiteLLMでは、支出ログのメタデータに、試行されたフォールバックや元のモデルグループなどのフィールドが記録されます。フォールバック率、最終成功率、リトライ／フォールバックによって追加されたレイテンシー、および実際にリクエストを処理したルートのコストを監視してください。

より広範なルーティング設計については、Flatkeyのフォールバックルーティングのプレイブックを参照してください。同じルールが適用されます。代替手段が引き続きワークフローの契約を満たす場合にのみルーティングしてください。

LiteLLMの問題に対応するためのインシデント対応チェックリスト

インシデントをクローズする前、またはLiteLLMのよくあるエラーのいずれかを修正済みと判断する前に、このチェックリストを実行してください。

ルーティングの管理対象を簡素化すべき場合

モデル設定、使用量、信頼性ポリシーを一元化できるため、LiteLLMを求めるチームもあります。一方で、運用すべきゲートウェイインフラを減らしたいチームもあります。適切な答えは、ルーティングポリシー、プロバイダー認証情報、予算適用、およびインシデント対応ループを誰が所有するかによって決まります。

Flatkeyは、ルーティング、使用状況の確認、請求をより密接に連携させながら、サポート対象のモデルルート全体でOpenAI互換の統合インターフェースを必要とするアプリケーションに役立ちます。タイムアウト、予算ブロック、プロバイダーエラーを分類する必要性がなくなるわけではありませんが、アプリケーションで維持すべきプロバイダー固有のクライアント統合の数を減らせます。この運用モデルを評価したい場合は、複数のAIモデルに対応する1つのAPIキーまたはFlatkey APIクイックスタートから始めてください。

完全なセットアップ手順と設定例については、LiteLLMプロキシガイドをご覧ください。

よくある質問

LiteLLMのよくあるエラーはすべて安全に再試行できますか？

いいえ。認証、権限、無効なモデル、サポートされていないパラメータ、予算、および大半の請求エラーには、設定またはアカウントの修正が必要です。明確に一時的な状態のみを、小さな試行回数と時間の予算を設定して再試行してください。また、その操作を安全に繰り返せる場合に限ります。

LiteLLMプロキシでmax_budgetが支出を止めないのはなぜですか？

まず、プロキシに予算適用に必要なデータベースベースの支出追跡機能があることを確認してください。次に、トラフィックがプロバイダーを直接呼び出すのではなくLiteLLMに到達していること、および設定されたキー、チーム、ユーザー、またはプロジェクトが実際にリクエストを行っているスコープであることを確認します。LiteLLMの予算ドキュメントでは、データベース要件とスコープの動作について説明しています。

Azureの予算アラートまたはAWSの予算アラートだけで、アプリケーションの超過を防ぐのに十分ですか？

これらはプロバイダーアカウント側の有用なセーフティネットですが、特定のゲートウェイリクエストを受け入れるべきかどうかを判断するものではありません。プロバイダーの請求アラートを維持したうえで、リクエストコンテキストが分かる場所に、テスト済みのゲートウェイ予算とアプリケーションレベルのプロダクト制限を追加してください。

失敗したLiteLLM呼び出しから何を保存すべきですか？

サニタイズ済みのエラー本文、正規化された例外クラス、HTTPステータス、プロバイダー名、要求したモデル、タイムスタンプ、環境、クライアントの試行回数、および利用可能な場合はx-litellm-call-idを保存してください。APIキーや機密性の高いプロンプト／レスポンスの内容はログに記録しないでください。

フォールバックによって不適切な設定が隠れることはありますか？

はい。フォールバックにより、プライマリルートが失敗し続けていても、顧客リクエストを成功させることができます。そのため、フォールバック率、ルート固有のエラー、最終モデルグループ、レイテンシ、コストについて、アラートまたはダッシュボードを用意する必要があります。フォールバック率の上昇は、修正完了ではなく運用上のシグナルとして扱ってください。

まとめ

LiteLLMのよくあるエラーに対する持続的な解決策は、万能の再試行回数やより長いタイムアウトではありません。実際の障害を取得し、ポリシーレイヤーを特定し、最小限で安全な変更を検証し、制御されたテストで復旧経路を実証する、再現可能な運用ループです。これにより、タイムアウトを適切に制限し、予算アラートを有意義なものにし、プロバイダー障害を修正できるだけ十分に可視化できます。

参考資料

• LiteLLMの例外マッピング
• LiteLLMの予算とレート制限
• LiteLLMのプロバイダーフェイルオーバーとフォールバック
• LiteLLMのルーティング、再試行、クールダウン、同時実行性
• LiteLLMの本番環境におけるベストプラクティス
• LiteLLMのロギング
• LiteLLMの支出キャプチャ率チェック