項目追加で止めない、AI出力の「二重読み移行」

AIが返すJSONへ項目を足しただけなのに、後続の請求登録が止まることがあります。AI基盤の開発責任者向けに、旧形式を動かしたまま新形式へ切り替える「二重読み移行」と、コピーできる出力契約を作ります。

生成成功と業務接続の成功を分ける

構造化出力は、モデルの回答を決めたJSON Schemaへ合わせる仕組みです。OpenAIはStructured Outputsについて、指定したSchemaへの準拠を目的とする機能だと説明しています。一方で、拒否や出力上限による中断など、Schema通りの応答にならない場合も明記しています。[1] したがって、生成結果の検証と、後続システムが受け取れる版かの判定は別に置きます。

JSON Schemaでは、propertiesだけでは項目は必須にならず、requiredで必須項目を指定します。また、未定義の項目は既定で許可され、additionalProperties: falseで拒否できます。[2] この違いを曖昧にすると、「任意項目を追加したつもりが利用側では必須」「未知項目を厳格に拒否して停止」といった食い違いが起きます。

コピーして使える出力契約

モデル名やプロンプト版ではなく、利用側が依存するデータ形式に版を付けます。本文と制御情報を分け、どのSchemaで検証済みかを毎件残します。

output_contract:
  contract: invoice_extract
  schema_version: 2
  producer: invoice-reader
  payload:
    invoice_id: "INV-1042"
    total_amount: 120000
    currency: "JPY"
    payment_due: "2026-11-30"
  validation:
    schema_id: "invoice_extract/v2"
    status: passed
  compatibility:
    readable_as: [1, 2]
    adapter_used: "v2_to_v1"
  trace:
    source_id: "pdf-8831"
    run_id: "run-20261017-042"

schema_versionは整数で比較し、readable_asは実際に変換テストを通った版だけを入れます。金額の数値化、日付形式の変更、列挙値の削除は破壊的変更として新しい版にします。任意項目の追加でも、未知項目を拒否する利用側があるなら破壊的変更として扱います。

4段階で旧版から切り替える

1. 依存先を一覧にする

生成APIだけでなく、キュー、保存DB、CSV出力、通知、分析処理を利用側として登録します。各利用側について、受理できる版、未知項目の扱い、失敗時の再処理方法、担当者を一行で記録します。

2. 先に読める範囲を広げる

利用側へv1とv2の両方を読めるアダプターを配ります。v2のpayment_dueがなくても旧処理を続けられるようにし、v1へ戻す変換も用意します。ここではモデルの出力形式をまだ変えません。

3. 同じ入力で差分を測る

保存済み入力をv1とv2へ流し、JSONの形だけでなく業務値を比較します。検査項目は、必須欠落、型不一致、変換不能、金額・通貨・請求番号の差、下流登録結果です。完了条件は、対象サンプルが両版で処理でき、説明できない業務値差がゼロ、切り戻し手順が実行済みであることです。

4. 書き出しを切り替えて旧版を閉じる

最初はv2生成の一部だけを本番利用側へ送り、失敗率とアダプター利用数を記録します。異常時は生成側をv1へ戻し、保存済みv2はv2_to_v1で再処理します。全利用側がv2を受理し、観測期間中にv1変換が使われなくなってから、v1の読み取りを終了します。

仮想例：支払期日を請求書抽出へ加える

【仮想例】経理チームが、請求書JSONへpayment_dueを追加するとします。先に会計登録、確認画面、CSV出力を調べると、CSV処理だけが未知項目を拒否していました。そのため、いきなり項目を追加せず、CSV処理へv2アダプターを配ります。

次に保存済み請求書で二重生成し、請求番号、金額、通貨が一致するか、期日を読めない場合にnullとなるかを確認します。差分の理由を記録できた入力だけを合格にし、v2を段階配信します。最終出力は「v2で登録済み」「v1変換を使用」「人の確認へ送付」のいずれかになり、無分類の失敗を残しません。

出力が人向け文章だけで、機械処理や保存を行わないという場合には向きません。二重対応の実装費が価値を上回るためです。反対に、金額、在庫、顧客、権限などを更新する処理では、移行期間が長くなっても互換性と切り戻しを優先します。

明日から使える移行チェックリスト

[ ] 出力形式にschema_versionを付ける
[ ] 利用側ごとの受理版と未知項目の扱いを書く
[ ] 生成側より先に二重読みを配る
[ ] v2からv1へ戻すアダプターを用意する
[ ] 保存済み入力で業務値の差を比較する
[ ] 拒否・中断・nullを通常データと分ける
[ ] 切り戻し後に再処理できるよう入力を保持する
[ ] v1変換の利用がなくなるまで旧版を消さない

明日は一つの構造化出力を選び、利用側一覧を作ってください。新項目を追加したデータ、欠落したデータ、型が違うデータを各利用側へ通し、停止箇所と復旧方法が一枚で分かれば、移行準備は完了です。

参考資料

本記事はAIを活用して作成し、公開前に自動レビューを実施しています。情報の確認日：2026-10-17。