OpenAI Structured Outputs：JSON出力を確実に得る方法

OpenAI Structured Outputsで型安全なJSON応答を得る：json_schemaモードの実装

Structured Outputsのresponse_format: json_schemaを使い、モデルの出力を事前定義したJSONスキーマに厳密に準拠させる方法を実装します。パースエラーのない型安全なAPI連携を実現できます。

from openai import OpenAI
import json

client = OpenAI()

# ---- 基本的なStructured Outputs ----
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "ユーザーが指定した技術トピックについて構造化された解説を返してください。"},
        {"role": "user", "content": "Transformerについて解説してください"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "tech_explanation",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "topic": {"type": "string", "description": "トピック名"},
                    "summary": {"type": "string", "description": "1〜2文の要約"},
                    "key_concepts": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "description": {"type": "string"}
                            },
                            "required": ["name", "description"],
                            "additionalProperties": False
                        },
                        "description": "主要概念のリスト（3〜5件）"
                    },
                    "difficulty_level": {
                        "type": "string",
                        "enum": ["beginner", "intermediate", "advanced"],
                        "description": "難易度レベル"
                    },
                    "use_cases": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "代表的なユースケース"
                    },
                    "related_topics": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "関連トピック"
                    }
                },
                "required": ["topic", "summary", "key_concepts", "difficulty_level", "use_cases", "related_topics"],
                "additionalProperties": False
            }
        }
    }
)

# 返り値は必ず指定スキーマ準拠のJSON
result = json.loads(response.choices[0].message.content)

print(f"トピック: {result['topic']}")
print(f"要約: {result['summary']}")
print(f"難易度: {result['difficulty_level']}")
print(f"\n主要概念:")
for concept in result["key_concepts"]:
    print(f"  - {concept['name']}: {concept['description']}")
print(f"\nユースケース: {', '.join(result['use_cases'])}")
print(f"関連トピック: {', '.join(result['related_topics'])}")

# ---- refusal対応（安全性フィルタ） ----
print(f"\nRefusal: {response.choices[0].message.refusal}")
# Noneなら正常、文字列ならモデルが回答を拒否した理由

Structured Outputsの最大の利点は、strict: trueを指定することでモデルの出力がJSONスキーマに100%準拠する保証が得られる点です。従来のjson_objectモードではスキーマ違反が起こり得ましたが、Structured Outputsではプロパティの欠落や型の不一致が発生しません。これにより、後続処理でのtry-catchやバリデーションコードを大幅に削減できます。注意点として、スキーマの全プロパティにrequiredを指定し、additionalProperties: falseを設定する必要があります。API連携・データ抽出・分類タスクなど、出力形式が厳密に決まっている場面では第一選択の手法です。