信頼性の高い AI API ルーティングと診断

明示的なフォールバック順序、グループの RPM 制限、リクエスト単位のタイミング記録を使って、障害の原因を診断できる信頼性の高い AI API ルーティングを設計します。

信頼性の高い AI API ルーティングと診断

信頼性の高い AI API ルーティングとは、単なる再試行のループではありません。各 API キーにプライマリグループ、フォールバックグループ、モデルの機能、リクエストの上限を明確に割り当て、リクエストが遅くなったり失敗したりしたときに、ユーザーが確認できる十分な根拠を残すことです。

優れたルーティング設計では結果を説明でき、グループの切り替えによって、リクエストしたモデルや課金の方針が知らないうちに変わることを防げます。

まずキーのポリシーを明確にする

Modelflare では、2 種類のルーティング方式を利用できます。

  • 通常の API キーは、明示的に指定した 1 つのプライマリグループと、順序付きのフォールバックグループのリストを使用します。
  • スマート API キーは、アカウントで現在利用できるグループを評価し、その方式に従って条件を満たす候補を順に試します。

フォールバックの順序はトラフィックの分散ではなく、優先順位です。プライマリグループが利用できない場合、リクエストは後続のグループへ順番に引き継がれます。

アプリケーションや環境ごとに別々のキーを作成してください。1 つのキーをあらゆる場所で共有するよりも、グループへのアクセス、クォータ、有効期限、利用記録を把握しやすくなります。

フォールバックでもリクエストの仕様を維持する

グループをフォールバックのリストに追加する前に、そのグループが次の条件を満たしているか確認します。

  1. リクエストするモデルを提供している
  2. 同じエンドポイントとストリーミングの動作に対応している
  3. 必要なサービスティアやプロバイダー固有のフィールドを許可している
  4. 使用量の倍率とリクエストレートの上限が許容範囲内である
  5. アカウントで実際に解放されている

フォールバックグループは、任意のモデルに置き換えてよいという許可ではありません。通信上の仕様は、引き続きリクエストしたモデルとプロトコルによって決まります。

グループのリクエスト上限を理解する

リクエストレートの上限は、アカウントと、そのリクエストを処理するグループに応じて適用されます。API キーを分けると使用量を分析しやすくなりますが、アカウントやグループの上限を自動的に回避できるわけではありません。

現在のグループが上限に達した場合、フォールバックグループを設定した API キーは、次に利用可能なグループへ処理を引き継げます。利用できるフォールバックがない場合、そのリクエストには 429 が返されます。クライアントで再試行するときは、すぐに大量の新しいリクエストを送るのではなく、回数に上限を設けたバックオフを使用してください。

リクエスト単位のパフォーマンス指標を活用する

利用ログでは、リクエストを把握するために必要なプロダクトレベルの指標を確認できます。

指標 わかること
合計応答時間 リクエストを送信してから完了するまでの時間
初回応答 最初の有効なテキスト、推論、ツールイベントが届くまでの時間
最初の可視テキスト テキストを生成するはずのリクエストで、テキストが表示され始めるまでの時間
可視出力速度 可視出力が始まった後の生成速度
出力トークン リクエストで生成された出力の量

初回応答が遅い場合は、通常、生成が始まるまでの待ち時間が長かったことを意味します。初回応答は正常でも出力速度が遅い場合は、生成段階に原因がある可能性が高くなります。これらの指標をステータス、モデル、グループ、期間と組み合わせて、一時的な遅延か継続的な問題かを見分けてください。

ツール呼び出しのみのレスポンスには可視テキストが含まれないことがあるため、Responses のトラフィックでは「初回応答」のほうが、最初の有効な出力を測る指標として確実です。

保持しても安全な根拠を使う

Modelflare のタイミングメタデータには、プロンプト、レスポンスのテキスト、生のリクエストボディ、API キー、メールアドレス、平文の IP アドレスは含まれません。これにより、レイテンシの診断記録が第二のコンテンツ保管場所になることを避けながら、運用記録としての有用性を保てます。

インシデントが発生したときは、次の情報を記録します。

  • リクエスト ID とタイムスタンプ
  • リクエストしたモデルと選択されたグループ
  • エンドポイントとストリーミングモード
  • ダウンストリーム側のステータス
  • ステータス、合計応答時間、初回応答までの時間
  • リクエストの完了前にクライアントがキャンセルしたかどうか

これらの根拠があれば、通常のログで内部のサービス構成を公開することなく、サポートがグループの切り替え、モデルの生成の遅さ、クライアントによるキャンセルを確認できます。

本番環境の信頼性チェックリスト

  • アプリケーションごとに専用の API キーを用意する
  • プライマリとフォールバックの順序を意図して決める
  • すべての候補グループで、モデルとプロトコルへの対応を確認する
  • 実際のワークロードに十分な長さのクライアントタイムアウトを設定する
  • 再試行可能なエラーには、ジッター付きで回数に上限のある再試行を使う
  • 認証、クォータ、モデルアクセスのエラーを、一時的な障害のように再試行しない
  • 非ストリーミングとストリーミングの両方のリクエストをテストする
  • 429、初回応答、出力スループット、キャンセルを監視する
  • フォールバックを同等とみなす前に、グループの料金を確認する

信頼性は、リクエストの仕様を維持しながら、失敗時に十分な根拠を残すことで得られます。順序付きのフォールバックグループは単一のグループへの依存を減らし、パフォーマンスと使用量の記録は、それでも残る失敗の原因を説明できるようにします。

認証、アクセス、レート制限、キャンセル、5xx の失敗を読み解くには、AI API エラーガイドを参照してください。フォールバックで使えるアクセス範囲を広げる前に、AI API キーのセキュリティで紹介している管理策を適用してください。