OpenAI Responses API 入門 (3) - 構造化出力

「Responses API」の構造化出力についてまとめました。

前回

1. 構造化出力

「構造化出力」は、モデルが常に提供された「JSONスキーマ」に準拠した応答を生成することを保証する機能です。モデルが必要なキーを省略したり、無効な列挙値を幻覚化したりする心配がなくなります。

「構造化出力」の利点は次のとおりです。

サポートされているモデルは、次のとおりです。

2. OpenAI API の準備

「Google Colab」での「OpenAI API」の準備手順は次のとおりです。

(1) パッケージのインストール。
「Responses API」と「Agent SDK」のパッケージをインストールします。

# パッケージのインストール
!pip install -U openai openai-agents

(2) 環境変数の準備。
左端の鍵アイコンで「OPENAI_API_KEY」を設定してから、以下のセルを実行してください。

import os
from google.colab import userdata

# 環境変数の準備 (左端の鍵アイコンでOPENAI_API_KEYを設定)
os.environ["OPENAI_API_KEY"] = userdata.get("OPENAI_API_KEY")

(3) クライアントの準備。

from openai import OpenAI

# クライアントの準備
client = OpenAI()

3. 構造化出力の実行

(1) メッセージリストの準備。

# メッセージリストの準備
messages = [
    {"role": "developer", "content": "イベント情報を抽出します。"},
    {"role": "user", "content": "アリスとボブは金曜日に科学フェアに行く予定です。"}
]

(2) スキーマの準備。

# スキーマの準備
schema = {
    "format": {
        "type": "json_schema",
        "name": "calendar_event",
        "schema": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string"
                },
                "date": {
                    "type": "string"
                },
                "participants": {
                    "type": "array", 
                    "items": {
                        "type": "string"
                    }
                },
            },
            "required": ["name", "date", "participants"],
            "additionalProperties": False
        },
        "strict": True
    }
}

(3) 推論の実行。

# 推論の実行
response = client.responses.create(
    model="gpt-4o",
    input=messages,
    text=schema
)
print(response.output_text)

4. ヒント と ベストプラクティス

4-1. 入力から有効な応答を得られない場合の対応

入力から有効な応答を得られない場合の対応方法をプロンプトに含めてください。モデルは常に提供されたスキーマに固執しようとします。入力がスキーマと完全に無関係な場合、ハルシネーションが発生する可能性があります。入力から有効な応答を得られない場合、空のパラメータまたは特定の文を返すようにプロンプトで指示することが推奨されています。

4-2. 応答の間違いの対応

「構造化出力」の応答には間違いが含まれている可能性があります。間違いがある場合は、指示を調整したり、システムに出力例を提供したり、タスクをより単純なサブタスクに分割したりして調整する必要があります。

5. サポートするスキーマ

「構造化出力」は、「JSONスキーマ」のサブセットをサポートしています。

5-1. サポートするデータ型

以下のデータ型がサポートされています：

5-2. ルートオブジェクトは object

スキーマのルートオブジェクトは object である必要があり、anyOf を使用することはできません。

5-2. すべてのフィールドは required

すべてのフィールドは required として指定する必要があります。

5-3. オブジェクトのネストの深さとサイズの制限

オブジェクトのプロパティの総数は 最大100個 まで、ネストの深さは 最大5レベル までに制限されています。

5-4. 文字列の合計サイズの制限

すべてのプロパティ名、定義名、列挙（enum）値、定数（const）値の 合計文字数は15,000文字以内 にする必要があります。

5-5. enum のサイズ制限

enum 値の総数は最大500個 までです。単一の列挙プロパティ に 250個以上の列挙値 がある場合、そのすべての列挙値の合計文字数は 7,500文字以内 にする必要があります。

5-6. additionalProperties: false をオブジェクトに必ず設定

additionalProperties は、JSONスキーマで定義されていないキーや値をオブジェクトが含むことを許可するかどうかを制御します。

5-7. キーの順序

出力はスキーマ内のキーの順序と同じ順序で生成されます。

5-8. 一部の型固有のキーワードは未サポート

以下の主要なキーワードは現在サポートされていません。

strict: true を設定して構造化出力を有効にし、サポートされていないJSONスキーマをAPIに送信すると、エラーが発生します。

5-9. anyOf の制約

anyOf を使用する場合、ネストされた各スキーマは、構造化出力で許可されるJSONスキーマのサブセットに準拠している必要があります。

5-10. definitions はサポート

スキーマ内で参照されるサブスキーマを定義するために、definitions を使用できます。

5-11. 再帰的スキーマはサポート

再帰的スキーマはサポートされています。

詳しくは以下を参照してください。

次回