GuidesOneMux

JSON Schema抽出におけるOpenAI APIエラーの診断

構造化抽出パイプラインで発生するOpenAIの認証エラー、レート制限、タイムアウト、無効なJSONを切り分ける実践的な手順を紹介します。

AI

要約 · TL;DR

構造化抽出で問題が起きたら、通信やAPIのエラーと出力検証の失敗を切り分けます。まず認証情報とプロジェクトへのアクセスを確認し、一時的なエラーに限って再試行します。返されたJSONは、利用する前にスキーマに照らして検証してください。

要点

  • 401は出力スキーマの問題ではなく、認証情報、組織への所属、IP許可リストに原因があることを示します。
  • 429ではエラーコードを確認します。レート制限には間隔を空けた再試行が有効な場合がありますが、クレジット不足や支出上限の問題はアカウント側での変更が必要です。
  • APIリクエストが成功しても、抽出結果が利用できるとは限りません。返されたJSONを解析し、JSON Schemaに照らして検証してください。
  • 再試行回数を制限し、秘密情報や機密性の高い入力文を記録せずに、繰り返し発生する問題を診断できるだけのリクエスト情報を保持します。
目次 (7)

まずAPIの失敗と抽出の失敗を切り分ける

構造化抽出パイプラインには、モデルから利用可能な応答が返る前にリクエストが失敗する場合と、応答は返ってきたものの解析やスキーマ検証で失敗する場合という、2つの異なる障害ポイントがあります。両者は分けて扱いましょう。スキーマや応答を確認せずに不正な出力を再試行するとリクエストを無駄にする可能性があります。また、クレジットを使い切った状態で再試行を繰り返しても、アクセスは復旧しません。

OpenAIのエラーコードガイドでは、APIのステータスコードと、それに対応するPythonライブラリの例外型が説明されています。特に抽出ワークフローでは、認証やリクエストのエラーには設定の修正が必要で、一時的なスロットリングやサービスエラーには回数を制限した再試行が有効な場合があり、スキーマ検証は応答を受け取った後にアプリケーション側で行う、という区別が役立ちます。OpenAI APIのエラーコード

抽出コードを変更する前に認証を確認する

401が発生したら、アプリケーションが意図した有効なAPIキーと正しい組織コンテキストを使用しているか確認してください。エラーガイドでは、組織への所属やIP許可リストも原因として挙げられています。ある環境ではリクエストが成功し、別の環境では失敗する場合は、抽出プロンプトを編集する前に、それぞれの環境で使用している認証情報と送信元IPを比較しましょう。

403の場合は、リクエスト元がサポート対象の国、地域、または領土に該当するか確認してください。権限やアクセスの制限は、JSON Schemaのフィールドを変更しても解消されません。

認証情報をソース管理やログに含めないでください。デバッグ時には、秘密情報そのものではなく、環境名とマスキングしたキー識別子を記録します。

再試行する前に429の種類を見極める

429は、必ずしも「同じリクエストを後でもう一度送る」という意味ではありません。エラーコードとメッセージを確認しましょう。

  • リクエストレート制限: 同時実行数を減らすか、リクエスト間隔を調整します。Retry-Afterが示されている場合はそれに従い、以前のレートにすぐ戻すのではなく、トラフィックを段階的に増やしてください。
  • クレジット残高の不足: リクエストを再開する前にクレジットを追加します。
  • 組織またはプロジェクトの支出上限: 該当する支出上限を確認します。
  • 組織の利用上限: 承認済みの上限引き上げを申請するか、サポートに問い合わせます。

ガイドによると、こうした請求や利用上限に関するエラーは、再試行しても解消しません。大まかなエラー種別だけでなく、具体的なエラーコードに基づいてハンドラーを設計してください。請求に関するエラーの中には、ほかのエラーと同じ広義のクォータ関連タイプに分類されるものもあります。

抽出バッチでは、すべての文書を一度に処理するよりも、同時実行数を簡潔に制限するほうが安全です。一時的な問題の可能性があるリクエストだけを、最大試行回数とバックオフを設定して再試行してください。検証エラーをレート制限エラーのように再試行してはいけません。

タイムアウトや一時的なサービスエラーに安全に対処する

クライアント側のタイムアウトは、クライアントが時間内に応答を受け取れなかったことを示すもので、リクエストが処理されなかった証拠ではありません。抽出ジョブでは、ソース文書ごとに一意で安定したジョブIDを割り当て、結果の保存を冪等にしてください。再試行する場合も、後続のデータレコードが重複して作成されないようにします。

OpenAIのガイドでは、500サーバーエラーや503モデル過負荷の場合、少し待ってからの再試行が有効なことがあると説明されています。Retry-Afterがある場合はそれに従ってください。また、Pythonライブラリの例外としてAPITimeoutError、InternalServerError、RateLimitErrorが挙げられています。一方、接続エラーはネットワーク、プロキシ、証明書、ファイアウォールの設定が原因となることがあります。これらすべてに同じ再試行動作を適用するべきではありません。

Pythonの参考パターン:解析、検証してから利用する

以下の例は、構造化応答を扱う際の確認手順を示すものです。設定がテスト済みであることを示すものではありません。使用するモデル、SDKのバージョン、エンドポイント、構造化出力のパラメーターが、このリクエスト形式に対応していることを確認してください。OpenAIのエラーコードガイドでは、JSON Schemaパラメーターの互換性について説明されていません。

import json
from jsonschema import validate, ValidationError
from openai import OpenAI, APIConnectionError, APITimeoutError
from openai import APIStatusError, RateLimitError

client = OpenAI()

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "total": {"type": "number"},
        "currency": {"type": "string"}
    },
    "required": ["invoice_number", "total", "currency"],
    "additionalProperties": False
}

try:
    response = client.responses.create(
        model="YOUR_SUPPORTED_MODEL",
        input="Extract the invoice number, total, and currency from: ...",
        text={
            "format": {
                "type": "json_schema",
                "name": "invoice",
                "strict": True,
                "schema": schema
            }
        }
    )
    data = json.loads(response.output_text)
    validate(instance=data, schema=schema)
except (RateLimitError, APITimeoutError, APIConnectionError) as exc:
    # Apply a bounded, error-aware retry policy in the job runner.
    print(f"Transient or connection failure: {exc}")
except APIStatusError as exc:
    # Inspect status and the API error code before deciding what to do.
    print(f"API failure: status={exc.status_code}, message={exc}")
except (json.JSONDecodeError, ValidationError) as exc:
    # Quarantine the result; do not pass invalid data downstream.
    print(f"Response failed JSON parsing or schema validation: {exc}")

選択したエンドポイントやモデルがこのスキーマ形式のパラメーターに対応していない場合、リクエストは形式不正または未対応として失敗することがあります。検証を黙って外すのではなく、エンドポイントの最新のドキュメントを確認してください。出力形式を制約できる場合でも、データベースや業務プロセスに渡す前にアプリケーション側で解析・検証することは、有効な安全策になります。

簡潔な診断チェックリスト

  1. 応答がない、またはクライアント例外が発生する? 接続、タイムアウト設定、プロキシ、TLS設定を確認します。
  2. 401または403? APIキー、組織へのアクセス、IP許可リスト、地域の利用可否を確認します。
  3. 429? 正確なエラーコードを確認します。一時的なレート制限には間隔を空けて再試行し、アカウント制限にはクレジットの追加や上限の見直しで対処します。
  4. 500または503? Retry-Afterが示されている場合はそれに従い、回数を制限して再試行します。
  5. 応答は届いたが利用できない? 応答を安全に記録し、JSONの解析とスキーマ検証のどちらが失敗したか特定します。不正なレコードは後続処理に渡さないでください。
  6. 問題が続く? モデル名、エラーコードとメッセージ、日時とタイムゾーン、関連するリクエスト情報とヘッダーを保持します。診断情報を共有する前に、APIキーと機密性の高い入力文をマスキングしてください。

まとめ

信頼性の高いJSON抽出を実現するには、まずHTTPまたはSDKのエラーを診断し、成功した応答は個別に検証します。復旧する可能性があるエラーだけを再試行し、具体的なエラーコードを使って、スロットリングとクレジット不足、支出上限、その他のアクセス制限を区別してください。

よくある質問

OpenAIの429はすべて再試行すべきですか?

いいえ。リクエストレート制限による失敗は、上限を超えない範囲で間隔を空けて再試行し、`Retry-After`がある場合はそれに従います。クレジット不足、支出上限、利用上限のエラーは、該当するアカウントや上限を変更する必要があります。再試行だけではアクセスは復旧しません。

抽出処理でOpenAIの401が発生した場合、何を確認すべきですか?

APIキーが正しく有効であること、意図した組織を指定していること、アカウントがその組織に所属していることを確認してください。IP許可リストが設定されている場合は、リクエスト元のIPが許可されているかも確認します。

APIリクエストが成功すれば、スキーマに適合したJSONが返ると保証されますか?

いいえ。返されたテキストを解析し、利用前に生成されたオブジェクトをアプリケーションのJSON Schemaに照らして検証してください。また、使用するエンドポイント、モデル、SDKが、リクエスト内の構造化出力パラメーターに対応していることも確認します。

エラーが続く場合、どの情報を保持すべきですか?

モデル、エラーコードとメッセージ、日時とタイムゾーン、関連するリクエスト情報とヘッダーを記録してください。ログに記録したり診断情報を共有したりする前に、認証情報と機密性の高い入力内容をマスキングします。

関連記事