2026 OpenAI Structured Outputs：JSON Schemaを安定して出力するには？

OpenAIの公式説明では、複雑なJSON Schemaへの適合評価でStructured Outputsが100%に達した一方、従来のモデルでは40%未満だったと報告されています。公式評価の条件と結果は、単に「JSONで返して」と指示するより、SchemaをAPI側で厳格に指定する方が堅牢だと判断する材料になります。

症状： JSONとして解析できても、項目不足、型違い、拒否、途中で切れた出力が下流処理を止めている。 最短の解決策： Structured OutputsでJSON Schemaを厳格に指定し、API状態・拒否・切断を確認した後、アプリケーション側でも意味を検証します。

この手順は、JSON modeから移行した開発者、データ抽出パイプラインを構築するチーム、ツール呼び出しの引数と最終レスポンスを分けて管理したいエンジニア向けです。単にモデル名や出力形式を比較する記事ではなく、実装から保守までの時間軸で判断できるように構成しています。

最初に下流の消費方法から出力契約を決める

Structured Outputsの安定性は、APIパラメーターを追加する前のSchema設計で大きく決まります。最初に「何を保存するか」「どの処理が次に読むか」を洗い出し、説明文と業務データを同じ文字列へ詰め込まないでください。

例えば請求書抽出なら、vendor<em>name、invoice</em>number、total_amount、currencyをデータ項目として分離し、モデルの推測理由は別の監査ログへ保存します。下流が数値として計算する値を、単位付きの自然文にしてしまうと、Schemaに適合していても業務処理で失敗します。

OpenAIはJSON Schemaに合う出力をどのように保証するのでしょうか。 厳格モードでは、指定したSchemaに従う構造を生成する仕組みが使われます。ただし、これは「抽出内容が事実であること」や「金額の計算が正しいこと」を保証しません。Schema適合性と業務上の正しさは、別々の検査として扱う必要があります。

JSON Schemaが大きくなった場合は、1回の呼び出しで全項目を埋めようとせず、文書分類、項目抽出、業務ルール判定のように段階を分けます。各段階の出力を小さくすると、必須条件、列挙値、相互依存する項目を確認しやすくなります。

初回リクエストでは最終形式とツール引数を混同しない

Responses APIで最終レスポンスを構造化する場合と、Function Callingでツールの引数を構造化する場合は、Schemaを指定する場所が異なります。現在のパラメーター名を確認するには、Responses APIのクイックスタートとモデルAPIリファレンスを基準にしてください。

最小構成のPython例は次の形です。MODEL_NAMEには、利用時点で対象機能をサポートするモデルを環境変数から設定し、古い記事の固定値をそのままコピーしないでください。

import json
import os
from openai import OpenAI

client = OpenAI()
schema = {
    "type": "object",
    "properties": {
        "category": {"type": "string", "enum": ["invoice", "receipt", "other"]},
        "total_amount": {"type": ["number", "null"]},
        "currency": {"type": ["string", "null"]}
    },
    "required": ["category", "total_amount", "currency"],
    "additionalProperties": False
}

response = client.responses.create(
    model=os.environ["MODEL_NAME"],
    input="この文書を分類し、合計金額と通貨を抽出してください。",
    text={
        "format": {
            "type": "json_schema",
            "name": "document_result",
            "strict": True,
            "schema": schema
        }
    }
)

data = json.loads(response.output_text)

Function Callingでは同じSchemaを最終レスポンスの設定へ貼り付けるのではなく、関数定義のparametersへ置きます。ツール引数の検証に成功しても、ツール実行結果や最終回答まで正しいとは限らないため、実行前後に別の検査を設けます。Function Callingの位置付けと引数定義は、OpenAIのStructured Outputs公式説明で確認できます。

Structured OutputsとJSON modeの違いはどこにありますか。 JSON modeは、出力を有効なJSONに寄せるための機能ですが、キー名、型、必須項目、追加プロパティまで業務契約どおりになるとは限りません。Structured Outputsの厳格なSchema指定は構造面の保証範囲を広げますが、拒否や切断、意味上の誤りを処理するアプリケーションコードは別途必要です。

受信後はAPI状態と業務意味を二層で検証する

レスポンスを受け取ったら、いきなりデータベースへ保存しないでください。最初の層ではAPIエラー、拒否、出力の中断、空の結果を確認し、次の層で型、範囲、相互関係、業務ルールを確認します。

strict: trueなのに解析に失敗するのはなぜでしょうか。 厳格モードは、拒否されたレスポンスや途中で切断されたレスポンスを、完成済みの業務データへ変換する機能ではありません。また、SDKが返すイベントやストリーミングの断片を完成JSONと誤認している可能性もあります。Responses APIの拒否イベントについては、公式のrefusal deltaリファレンスを確認し、完了状態を見てから解析してください。

検証コードでは、最低限次を分けます。

• API呼び出し自体の例外とタイムアウト
• 拒否の有無と拒否理由
• 完了状態、出力の欠落、JSON解析エラー
• Schemaバリデーターによる型と必須項目
• 金額が0以上か、通貨と金額が同時に存在するか、といった業務条件

失敗の種類ごとに復旧経路を固定する

障害時にすべてを同じ再試行へ送ると、同じ不備を繰り返したり、危険な入力を何度も処理したりします。エラーの分類ごとに、Schemaを直すのか、リクエストを変えるのか、人手確認へ送るのかを決めておきます。

Schemaが複雑すぎるときは、必須項目を減らすだけでなく、責務そのものを分離します。例えば住所の正規化と請求金額の抽出を別呼び出しにし、1つ目の結果を2つ目の入力へ渡します。ただし、分割すると呼び出し回数、失敗箇所、再実行の管理が増えるため、各段階に相関IDを付けて追跡してください。

OpenAIの構造化出力が拒否された場合、再試行すればよいのでしょうか。 安全上の拒否なら、温度やプロンプトだけを変えて反復する設計は適切ではありません。拒否を成功データと同じ形式へ無理に変換せず、監査ログを残したうえで利用者への説明、入力の修正、または人手キューへ分岐させます。

リリース前の回帰テストで「たまたま動いた」を排除する

本番投入前には、通常データだけでなく、境界値、空欄、極端に長い入力、読めない文書、安全上の拒否が想定される入力を用意します。合格条件は「JSONを解析できた」だけにせず、下流の登録処理やツール呼び出しまで確認します。

テスト記録には、少なくともモデル識別子、Responses APIまたはツール呼び出しの種別、Schemaのバージョン、バリデーターのバージョン、入力ケースの識別子、失敗分類を残します。API仕様の変更を追う際は、エンドポイント別のデータ管理説明も確認対象に含めてください。

Schemaは単なるプロンプト部品ではなく、データベースやツールとのAPI契約です。変更時はメジャー、マイナーなどの版を付け、旧Schemaを読む下流が残っている間は互換形式を維持します。新Schemaを一部のトラフィックだけへ流し、キャッシュ、初回準備の遅延、失敗キュー、下流の登録結果を確認してから全体へ広げてください。

実装を複数のMac環境で検証する場合は、開発端末だけに結果を残さず、再現手順と環境情報をチームで共有できる状態にします。kvmbootのヘルプセンターで利用条件を確認し、短期の回帰試験に必要な環境だけを確保する方法も選択肢になります。

現在の実行環境とMac環境をどう使い分けるか

通常のバックエンドAPI運用であれば、既存のLinuxやクラウド環境を置き換える必要はありません。一方、iOS向けの統合テスト、Mac固有のSDK、複数環境での自動回帰を同時に行う場合、手元のMacだけに依存すると、端末の占有、環境差、担当者不在時の停止、テスト用設定の再現性が問題になります。

その場合は、常時稼働する本番基盤をレンタルMacへ移すのではなく、検証期間だけMac環境を追加する方が現実的です。kvmbootのサービス背景は運営情報で確認でき、対象地域の利用を検討するなら日本向けMac環境の案内を参照できます。

ただし、物理ポートへの常時アクセスが必要な開発、長期間にわたる高負荷処理、固定端末を社内設備として保有することが必須の組織では、購入や既存設備の方が適します。反対に、短期間のStructured Outputs回帰試験やMac固有の結合確認では、購入費用、端末の空き待ち、環境構築のやり直しを抱えずに済むため、レンタルMacの方が試験計画を組みやすいケースがあります。

まずは業務データを含まないSchema、正常・境界・拒否のサンプル、検証項目だけをまとめた受入れ用の枠組みを作ってください。そのうえで大量の回帰試験やMac固有の統合テストを一時的に実行する必要があるなら、常設設備を増やす前に、kvmbootのMac環境を候補として比較すると判断しやすくなります。