Structured Outputsの活用法。AIの出力をコードで検証する設計

「AIがJSONを出力してくれない」「スキーマで指定した制約が無視される」。AIエージェントを運用する開発者は、この事態に直面する。

モデルの推論能力だけに頼ったデータ構築には限界がある。Structured Outputsの制約は「ヒント」であり、実効的な保証はコード側でのバリデーションが担う。

本記事では、モデルの出力を「不確実な自然言語」から「検証可能なデータ」へ昇華させるための、多層的な防御設計を解説する。Claude CodeでSaaSを開発する僕が、運用で直面した落とし穴と回避策を数字と事実で紐解く。

SNS運用を自動化しませんか？

ThreadPostなら、投稿作成・画像生成・スケジュール管理までAIがサポート。

AI出力の「制約」と「保証」の境界線

AIエージェント開発では、モデルの出力を特定のJSON構造に固定するStructured Outputsの活用が標準化している。しかし、スキーマで指定した制約が正しく適用されない事象が頻発する。

Azure OpenAIなどのプラットフォームにおいて、JSON Schemaに記述した`minimum`や`maximum`といった数値制約、あるいは`minItems`などの配列制約が無視されるケースがある。公式ドキュメントでは、これらは「サポートされないキーワード」として明記されており、strictモードであっても強制力が働かない。

一方で、Google Cloud BigQueryのAI関数（`AI.GENERATE_BOOL`や`AI.GENERATE_INT`など）は、型付き関数を用いることで、パース処理を介さずに型安全な結果を取得する。これにより、アプリケーション側で発生していた文字列変換エラーやパース失敗のリスクを、クエリ実行レイヤーで低減する。

しんたろー：
スキーマを書けば全部解決すると思っていた時期がある。モデルが吐き出すのは確率的な文字列であり、型システムではない。APIのバージョンやプロバイダごとに「効く制約」と「ただの指示」が混在している状況が気になる。

同じモデル名であっても、利用するAPI中継によって可用性やレスポンスの安定性は異なる。P95レイテンシや成功率を継続的に計測し、インフラとしての信頼性を担保する。

エンジニアが採用しているアプローチは、以下の3層構造による多重防御だ。

静的制約（スキーマ）: モデルに対する「ヒント」として構造を定義する。
動的バリデーション（コード）: アプリケーション側で出力結果を型検証する。
自己修正ループ（プロンプト）: 検証失敗時にエラー内容をモデルにフィードバックし、再生成させる。

モデルの推論能力に過度な期待を寄せず、検証可能なデータパイプラインを設計する。この「制約の配置」が、AIエージェントの安定稼働を左右する。

構造化出力の「幻想」と「現実」の設計思想

AIモデルの出力をJSON Schemaで制御する「構造化出力」は、一見すると魔法のように見える。しかし、本番環境で運用するとその脆さに直面する。

多くのエンジニアは、スキーマ定義を「契約」だと信じ込む。`minimum`や`pattern`といった制約をJSON Schemaに書き込めば、モデルが厳格に守ると期待する。

現実にはプロバイダやモデルのバージョンによって、これらの制約が「無視される」。これは仕様の一部だ。ある環境では`strict`モードで定義した制約が素通りし、別の環境ではエラーを吐く。この不確実性をハンドリングする。

しんたろー：

Claude Codeでバックエンドを組んでいるが、AIの出力は「常に壊れる」前提で書いている。スキーマは「こう書いてほしい」というお願いであり、守られるかどうかは運次第だ。最後のバリデーションをコード側で書かないと、JSONパースエラーでアラートが鳴る。

この設計思想では、制約を「どこに配置するか」が重要だ。

まず、スキーマ層はモデルへの「ヒント」として機能させる。ここで`description`を丁寧に書き込むことで、モデルの推論精度を底上げする。次に、コード層で型安全なバリデーションを行い、不正なデータがDBに混入するのを防ぐ。最後に、エラー発生時にはモデルに自己修正ループを回させる。

このプロセスは、AIの出力を「不確実な自然言語」から「検証可能なデータ」へと変換するコストを、どこで支払うかというトレードオフだ。

BigQueryのAI関数のように、型付きの生成関数を直接提供するサービスも増えている。これはパース処理をSQL層で完結させることで、変換コストをインフラ側に寄せるアプローチだ。アプリケーション側で泥臭いJSONパースを書く手間が省ける一方、ベンダーロックインのリスクや、複雑なロジックをSQL内に埋め込むメンテナンス性を考慮する。

モデルの推論能力に依存した開発を卒業する。

モデルが賢いからといって、バリデーションをサボればシステムは破綻する。特に、APIプロバイダの中継サーバーを経由する場合、同じモデル名でもレスポンスの安定性や制約の効き具合が異なる。

P95レイテンシやエラー率を計測し、インフラとしての信頼性を監視する。モデルの出力結果を「信じる」のではなく、「疑って検証する」仕組み。この防衛的な設計思想が、一過性のプロトタイプと、長く生き残るSaaSの分かれ道だ。

AI開発の難易度は「AIをどう動かすか」ではなく、「AIが壊れたときに、どうやってシステムを安全に復旧させるか」という、堅牢なシステム設計の原則に回帰している。

ここまで読んだあなたに

今なら無料で全機能をお試しいただけます。設定後はAIが投稿案を毎日生成。確認して選ぶだけ。

無料で始める

実務への影響：AIエージェントを「止まらないシステム」にするために

明日からの開発で意識すべきは、「AIの出力は常に壊れるもの」という前提での多層防御だ。

まず、スキーマ定義を過信しない。 JSON Schemaで`minimum`や`pattern`を指定しても、それが強制されない環境は多い。スキーマは「モデルへの丁寧な依頼」と捉え、実行時のバリデーションをアプリケーションコード側の型定義とセットで実装する。

次に、エラーハンドリングの設計を変える。 バリデーションに失敗した際、単に例外を投げて処理を停止させるのは避ける。エラー内容をプロンプトに戻し、「この制約に従って修正せよ」というフィードバックループを回す設計に書き換える。

また、APIプロバイダの中継先を監視する仕組みも必要になる。同じモデル名でも、リセラーやリージョンによってレスポンスの揺れや制約の効きが異なることはある。P95レイテンシや成功率を定期的に計測する小さなプローブを仕込み、特定のプロバイダが不安定になったら切り替えられる準備をしておく。

しんたろー：
Claude Codeでコードを書かせていても、最後は自分でテストを通さないと夜も眠れない。AIの出力を「信じる」のではなく「テストする」という、当たり前の泥臭い作業が一番の近道だ。

最後に、SQLやパイプラインへのAI組み込みを検討しているなら、型付き関数の活用を推奨する。`AI.GENERATE_BOOL`や`AI.GENERATE_INT`のような関数を使えば、文字列パースというバグを生みやすい工程をスキップできる。

これからのAI開発は、モデルの賢さを競うフェーズから、いかにAIの不確実性をシステム側で吸収するかというフェーズに移っている。AIを気まぐれな外部APIとして扱い、堅牢なガードレールを敷く。この設計思想に切り替えることが、本番環境で生き残るための解だ。

👉 ThreadPostでSNS運用を自動化する

よくある質問

JSON Schemaの制約が効かない場合、どう対処すべきですか？

JSON Schemaの制約は、あくまでモデルへの「ヒント」として記述し、実効的な保証は必ずアプリケーションコード側のバリデーターで行ってください。検証に失敗した場合は、エラー内容をモデルにフィードバックし、「この制約に従って修正せよ」とプロンプトで指示する自己修正ループを実装するのがベストプラクティスです。モデルの出力を「一度の呼び出しで完成させる」のではなく、「対話を通じて正解に収束させる」設計にすることで、制約の不完全さを補完できます。

BigQueryのAI関数を使うメリットは何ですか？

最大のメリットは、モデルの出力を文字列として受け取った後の「パース処理」を省略できる点です。AI.GENERATE_BOOLやAI.GENERATE_INTなどの型付き関数を使えば、モデルの推論結果をSQLのWHERE句やORDER BY句に直接組み込めるため、データパイプラインが簡潔になります。特に、後続の集計処理でパースエラーによりパイプラインが停止するリスクを低減できるため、安定性が求められるデータ基盤でのAI活用において強力な武器となります。

モデルの信頼性を担保するために開発者が監視すべき指標は？

レスポンスの成功率だけでなく、P95（95パーセンタイル）の応答速度を注視してください。同じモデル名でも、APIの中継先やプロバイダによって、ピークタイムの性能やエラー率は異なります。本番運用では、20回程度の短いプロンプトを定期的に投げ、可用性と応答時間の推移を計測するスクリプトを自前で走らせることを推奨します。ステータスコードが200であっても、中身がエラーになっているケースは多いため、必ずボディのJSON構造まで含めた自動テストを継続的に実行してください。