このページは機械翻訳されています。元の英語の記事を表示。

API エラーとレイテンシのトラブルシューティング

この記事では、OpenAI API の利用時に発生する一般的なエラーやレイテンシの問題を、Service Health ダッシュボードと Usage ダッシュボードを使ってトラブルシューティングする方法を説明します。

更新日: 21 hours ago

重要なリンク

お使いのアカウントでサービス稼働状況を確認できない場合は、サポートへのお問い合わせ時に、アプリケーションのリクエスト ID、機密情報を除去したエラーレスポンス、処理時間の記録をお知らせください。データレジデンシーを利用しているだけでは、Enterprise 専用ダッシュボードへのアクセス権は付与されません。

適切なデフォルトから開始

Service Health ダッシュボードを開くと、デフォルトは次のとおりです。

  • すべてのプロジェクト

  • 過去 30 日間

  • 1 時間単位の解像度

このビューは状況把握のみに役立ちます。意味のあるトラブルシューティングには、常にフィルタリングが必要です。

調査前のフィルタリング

正しくフィルタリングすることが最も重要な手順です。誤解の多くは、モデル、ティア、プロジェクトを混在させることで発生します。

モデルでフィルタリング(一度に 1 つ)

常に単一のモデルにフィルタリングします。

理由:

  • トラフィックの少ないモデルの問題が、より大量のトラフィックに隠れることがある

  • トラフィック量の多いモデルにより、局所的な問題が全体的な問題のように見えることがある

  • モデルごとにパフォーマンス目標が異なる

注: 複数のモデルを選択すると集計されます。モデル間で切り替わるわけではありません。

サービスティアによる絞り込み

複数のティア(標準、Fast モード(旧 Priority processing)、スケールティア)を使用している場合は、調査対象のティアで必ず絞り込んでください。

理由:

  • ティアごとにパフォーマンス特性が異なる

  • Fast モードとスケールティアには所定の SLA がある

  • ティアが混在すると有料ティアのパフォーマンスが見えにくくなる

これはレイテンシ分析で特に重要です。

既存のモデルでは、Fast モードのトラフィックは引き続き Usage ダッシュボードに priority と表示されます。

プロジェクトでフィルタリング

デフォルトでは、Service Health はすべてのプロジェクトを表示します。

トラブルシューティングでは、問題が観測されたプロジェクトにフィルタリングします。

理由:

  • トラフィック量の多い 1 つのプロジェクトがメトリクスを支配することがある

  • 影響を受けている小規模なプロジェクトが、無関係のトラフィックによって見えにくくなることがある

問題が本当に組織全体に及んでいると考える場合のみ、「すべてのプロジェクト」を選択したままにします。

エラーのトラブルシューティング

HTTP リクエストビューの使用

エラーを調査するには:

  1. モデルとサービスティアでフィルタリングします。

  2. 稼働時間タブではなく、HTTP リクエストタブを開きます。

このビューには、HTTP ステータスコード別の総リクエスト数とエラー数が表示されます。分単位の解像度までズームして、細かな急増や変化を特定します。

件数ではなくエラー率の解釈

どの本番システムでも、一定のエラーは想定されます。生の合計件数ではなく、エラーの割合に注目します。

総量が大きいほど、エラー率が非常に低くても、発生し得るエラー数は多くなります。

Service Health にエラーが表示されない場合

クライアント側のエラーが表示される一方で、Service Health に対応するデータがない場合:

  • リクエストが OpenAI に到達していない可能性があります。

  • 問題は通常、アップストリーム(タイムアウト、プロキシ、ネットワーク)にあります。

これは、クライアント側のタイムアウト設定が厳しい場合によく見られます。

レイテンシのトラブルシューティング

レイテンシ分析は、SLA が定められている Fast モードとスケールティアで最も有効です。標準ティアではレイテンシの変動幅が大きくなる可能性があり、レイテンシは保証されません。

主要メトリクス

各メトリクスを表示するには、該当するタブをクリックします。

  • トークン速度: 1 秒あたりに生成されるトークン数。プロンプトサイズには依存しません。

  • リクエスト時間: リクエストの合計所要時間。出力サイズと推論の影響を大きく受けます。

  • 最初のトークンまでの時間(TTFT): 最初のトークンが生成されるまでの時間。キャッシュされていない入力プロンプトサイズと推論の影響を大きく受けます。

常に P50 / P75 / P95 パーセンタイルを確認してください。平均値は実際のユーザーへの影響を隠すことがあります。

レイテンシとトークン使用量の相関

Service Health では、動作がいつ変化したかを確認できます。使用状況データは、その理由を把握するのに役立ちます。

Service Health ダッシュボードの表示内容に対応するデータを確認するため、使用状況ダッシュボードで次の操作を行ってください。

  • 同じプロジェクトとモデルでフィルターを設定します。

  • 該当する場合は、サービスティアでグループ化します。

  • レイテンシへの影響が最も大きい出力トークンに注目します。

より詳しく分析するには、アクティビティデータをエクスポートして、リクエストあたりのトークン数の推移を調べます。

サポートへのお問い合わせ時に共有する情報(必要な場合)

サポートにお問い合わせの際は、以下の情報をお知らせください。

  • 影響を受けている組織 ID (重要)

  • 影響を受けているエンドポイント(Chat Completions や Responses など)(重要)

  • 影響を受けているモデル(重要)

  • 影響を受けているリクエストで使用したサービスティア(Standard、Fast モード、スケールティアなど)(重要)

  • 遅延やエラーが発生した時間帯とタイムゾーン(重要)

  • 関連する x-request-id または X-Client-Request-Id(確認できる場合)

  • 共有するリクエストのタイムスタンプとタイムゾーン(少なくとも日付)

確認できる場合は、以下もお知らせください。

  • リクエストに関連するプロジェクト ID

  • データレジデンシーを指定したリクエストへの影響の有無と、影響を受けたリクエストをお知らせください。指定したレジデンシーのリージョンと、使用したリージョン別 API ホスト名も記載してください。プロジェクトの地理的な場所が固定されているか、リクエストごとにレジデンシーを指定する Global プロジェクトかも記載してください。

  • 確認されている傾向の説明

リージョンごとのモデルとエンドポイントの最新の対応状況については、API データレジデンシーガイドをご覧ください。

機密情報を除去したうえで、設定とエラーの詳細を共有してください。例やスクリーンショットからは、API キー、認証情報、プロンプト、その他の機密性の高い顧客コンテンツを削除してください。

問題の種類に応じて、以下の情報をお知らせください。

  • エラー:失敗またはエラーとなったリクエストの割合の概算、レスポンスコード、エラーメッセージ、エラーレスポンスの受信までにかかった時間

  • 遅延:影響を受けているパーセンタイル(P50 / P90 / P95 / P99)、お客様の通常時の値と比べた上昇幅、遅いリクエストの例とその送受信タイムスタンプ

  • 両方:エラーまたは遅延のデータを示すスクリーンショットや表、およびエラー率や遅延が想定を上回っていると判断した方法

一般的なトラブルシューティングシナリオ

タイムアウトが発生するが Service Health は正常に見える場合

考えられる原因: リクエストが OpenAI に到達する前にタイムアウトしています。

確認:

  • クライアントまたはプロキシのタイムアウト設定

  • ローカルネットワークまたはロードバランサーの変更

  • Service Health ダッシュボードに 499 エラーがあるか(これらは自社システムでは 5xx エラーとして表示される場合があります)。

デプロイなしでのレイテンシ増加

考えられる原因: 出力トークンサイズまたは推論の使用量が増加した、またはトラフィックがサービスティア間で移動しました。

確認:

  • 使用状況ダッシュボードでのリクエストあたりの平均出力トークン数(データをダウンロードし、出力トークン数を総リクエスト数で割る必要があります)。

  • Service Health ダッシュボードでのリクエスト時間と TTFT パーセンタイル

Fast モードまたはスケールティアが遅く見える場合

考えられる原因:ティア間でメトリクスが混在し、標準ティアのトラフィックによって有料ティアのパフォーマンスが見えにくくなっています。

確認事項:

  • フィルターが単一のティアとモデルに限定されていること

  • ティア間のトークン生成速度の比較

5XX エラーの急増

考えられる原因: トラフィックの一部に影響する一時的な障害です。

確認:

  • エラー率の割合

  • 同時にトラフィック量が変化したかどうか

1 つのプロジェクトのみに影響する問題

考えられる原因:プロジェクト固有の設定や利用パターンです。

確認事項:

  • プロジェクト単位でのフィルタリング

  • 影響を受けていないプロジェクトとの比較

リージョンが固定されたプロジェクト、またはリクエストごとにレジデンシーを指定する Global プロジェクトの場合は、リクエストのホスト名、モデル、エンドポイント、ティアを API データレジデンシーガイドと照合してください。設定項目が見つからない場合は、API プラットフォームでのプロジェクト管理をご覧ください。トラブルシューティング中も、リクエストは必ず要件で指定されたリージョンのルートに送信してください。

最終的な要点

  • メトリクスを解釈する前に、必要に応じてモデル、ティア、プロジェクトでフィルタリングします。

  • レイテンシ分析には平均値ではなく、パーセンタイルを使用します。

  • 小さなエラー率は想定内です。

  • データが欠落している場合、通常はアップストリームの問題を示します。

  • 使用状況データはレイテンシが変化した理由を説明するのに役立ちます。Service Health は挙動が変化した時期を示します。

この記事は役に立ちましたか?