LLM構造化出力のスキーマ版管理｜項目追加・廃止・提供事業者切替で後続処理を守る

LLMがJSON Schemaどおりの出力を返しても、本番システムが安全に更新できるとは限りません。項目を一つ必須にしただけで古い利用側が落ちる。列挙値を追加すると未知値を拒否する。提供事業者を替えると、同じJSON Schemaの制約語が使えない。必要なのは指示文の調整ではなく、スキーマをAPI契約として版管理する運用です。

有効なJSON、スキーマ一致、業務上の正しさは別物

最初に三つの判定を分けます。有効なJSONは解析器が読めること。スキーマ一致は型、必須項目、列挙値などの制約に合うこと。業務上の正しさは、抽出した金額、日付、顧客ID、分類が原資料と一致することです。

MicrosoftはJSONモードについて、有効なJSONを保証しても指定スキーマへの一致は保証しないと説明します。トークン上限で終了した場合は不完全なJSONになり得ます[5]。構造化出力でスキーマ一致は強くできます。それでもGoogleは、値の意味をアプリケーション側で検証するよう求めています[3]。

したがって受入処理は、JSON解析、スキーマ検証、業務検証の三段にします。invoice_totalが数値型でも、明細合計と一致しなければ保留です。due_dateが日付形式でも、原文に日付がなければ推測値として採用しません。

提供事業者ごとに使えるスキーマは同じではない

OpenAIの厳格な構造化出力はJSON Schemaの一部に対応し、安全上拒否された場合は拒否内容が返ります[1]。Responses APIの応答には完了、失敗、未完了などの状態があります[2]。Geminiも一部対応で、大きく深いスキーマは拒否され得ます[3]。Azure OpenAIは、すべての項目を必須にし、objectでadditionalProperties: falseを指定し、項目総数100、階層5まで等の制約を公開しています[4]。

Amazon BedrockはDraft 2020-12の一部へ対応しますが、再帰スキーマ、外部$ref、一部の数値・文字列制約は非対応です[6]。共通範囲に見えるスキーマでも、事前検証なしに全提供事業者で動くとは仮定しません。共通の業務スキーマと、提供事業者へ渡す生成用スキーマを分けます。

業務スキーマは後続処理が必要とする契約です。生成用スキーマは、各提供事業者が扱える範囲へ変換したものです。返答は生成用スキーマで受けた後、業務スキーマへ正規化します。この境界に提供事業者名、モデル版、スキーマ版を記録すれば、障害時に「モデルの誤り」と「変換処理の誤り」を分けられます。

互換変更と破壊的変更を先に分類する

新しい任意項目の追加は、未知項目を無視できる利用側なら互換変更です。ただしadditionalProperties: falseで直接検証する古い利用側には破壊的です。列挙値の追加も、unknownへ退避できる実装なら互換ですが、分岐処理が全値列挙を前提にすれば落ちます。

必須項目の追加、項目名変更、型変更、意味の変更は破壊的変更です。amountを税込総額から税抜総額へ変えるような変更は、型が同じでも意味が壊れます。新しい名前を付け、旧項目と一定期間併存させます。

JSON Schemaプロジェクトは、スキーマがどの仕様体系で書かれたかを$schemaで明示することを推奨します[7]。過去にはDraft間で配列のitems等が変わり、同じスキーマが違う結果を返し得ました[8]。提供事業者APIの対応範囲と、JSON Schema自体の仕様体系を混同しないことが重要です。

スキーマ版は応答に残し、二重読取で移行する

応答の最上位へschema_versionを入れます。この値はモデルに推測させず、生成処理または正規化層が、実際に適用したスキーマの確定値として付与します。v1からv2へ移るときは、生成側だけを先に切り替えません。まず利用側をv1とv2の両方が読める状態にします。次に一部の通信だけv2を生成し、検証エラー、未知の列挙値、欠損項目、業務上の却下を版別に観測します。

移行中は、本番結果には使わず、同じ入力を旧版と新版へ流して差だけを見る「影実行」が役立ちます。ただし外部機能の実行や課金処理まで二重に動かしてはいけません。比較対象はJSON生成と検証までに止めます。差分は項目単位で数え、文章の見た目ではなく後続処理の判断が変わったかを確認します。

すべての利用側がv2を読み、v1出力が一定期間ゼロになった後で旧スキーマを廃止します。廃止日はコードだけでなく、監視画面、運用手順、データ保持規程にも反映します。保存済みの旧応答を再処理する可能性があるなら、旧検証器と移行関数を保持します。

再試行はスキーマ違反だけを直すために使わない

スキーマ検証が失敗するたびに同じモデルへ再試行すると、費用と遅延が増え、同じ入力で同じ失敗を繰り返します。APIの拒否、トークン不足、提供事業者の障害、スキーマ拒否、業務上の却下を分けます。トークン不足なら入力や出力上限を見直す。未対応の制約語なら生成用スキーマを直す。業務上の却下なら原資料不足として人へ戻します。

代替先へ送る場合も、先にその提供事業者用スキーマへ変換します。strictという名前が同じでも制約が同じとは限りません。代替後の出力には元の提供事業者と代替先、両方のスキーマ版を残します。

スキーマ一致は完成条件ではない

Structured Outputsは、JSON修復のための再試行や壊れやすい解析処理を減らせます。だが値の真偽、権限、業務制約を保証しません。日付抽出なら原文の該当箇所、分類なら根拠、外部操作なら現在の認可を別に確認します。

最初の実装は、一つの応答に生成処理が確定したschema_versionを追加し、JSON解析・スキーマ・業務検証の失敗件数を分けるところから始めます。版別の失敗が見えなければ、安全な移行日は決められません。

提供事業者の対応モデル、API、スキーマ制約は更新されます。公開前に各社の現行資料を再確認し、Azure固有の上限をOpenAI全体の仕様として扱わないでください。

根拠資料

資料確認日：2026年9月28日。本文中の手順例は編集部の提案で、導入効果の実測値ではありません。