重要なポイント
API-levelのJSON-modeは形式が正しくないJSON構文、スキーマ準拠の失敗は停止します。 有効なJSONは不足しているフィールド、間違ったタイプ、無効な列挙値を含めることができ、すべてが下流の検証に失敗します。
プロンプトにスキーマを埋め込むことは基盤です。 プロンプトに直接構造化されたJSONテンプレートを示すことで、モデルにフィールド名、ネストの深さ、およびプロズではなく構造でのタイプを示します。
有効な出力例は信頼性を5–10ポイント上げます。 モデルは成功した出力がどのように見えるかを見ると、より良く従います。
タイプ、形式、nullトレーニングのためのフィールドレベルの指示が重要です。 「列挙フィールド」は曖昧です; 「status (正確に: 'active'、'inactive'、'pending' — 省略形なし)」ではありません。
95%成功率は20ケースのテストセットで本番ゲートです。 95%以下では、本番環境の失敗は修正ループを必要とするほど頻繁に発生し、コストと遅延が倍になります。
プロンプト設計が構造化出力信頼性を決定する
JSON-mode API (OpenAI response_format、Anthropic tool_use、Google Gemini responseMimeType) は解析可能なJSONを強制しますが、スキーマ準拠 — 必須フィールド存在、正しいデータ型、有効な列挙値 — についてはいかなる処理もしません。これらのエラーはAPI-levelの強制にもかかわらず発生し、プロンプト設計コントロールが必要です。
🔍 JSON-modeは十分ではない
API-enforced JSON-modeは解析不可能な出力 (JSONのスペース、エスケープされていない引用符) を防ぎます。スキーマ準拠は防ぎません: JSON-modeを有効にしたモデルは、不足しているフィールド、間違ったタイプ、無効な値を含む有効なJSONを返すことができます。スキーマ準拠はプロンプト問題、API問題ではありません。
🔍 最初にプロンプトだけでスキーマをテストする
API-enforced JSON-modeなし (古いAPI、ローカルLLM) のモデルは、プロンプト内のスキーマだけで80–85%の構造化出力信頼性を達成します。これはベースラインを確立し、残りの15–20ポイントがどこに有用に追加されるかを示します。
スキーマをプロンプトに直接埋め込む
プロンプトにJSONテンプレートとしてスキーマを示すことは、最高価値のテクニックです。 スキーマをプロズだけで説明するプロンプト (「フィールドのリスト」) は曖昧です。モデルはフィールド名、ネストの深さ、またはタイプを明確に見ず、推測します。
🔍 ネストされたオブジェクトを複数行に分散
ネストされた構造を1行に詰め込むと、モデルは深さを見ることが難しくなります。複数行のテンプレートはインデント付きで、はるかに簡単に従うことができます。
🔍 nullと空の配列を明示的に表示
テンプレートを使用して、nullの見た目 (「nil」ではなく、「N/A」ではなく、 nullだけ) と空の配列の見た目 (nullではなく []) を示します。テンプレートにない場合、これらは誤ります。
❌ 曖昧です — 構造がありません
カスタマーデータのリストを返します。
✅ スキーマテンプレート、フィールドタイプを構造で表示
このJSONフォーマットで正確にカスタマーデータを返します: { "customer_id": "string", "name": "string", "email": "string", "purchases": ["item1", "item2"], "total_spent": 0.00, "is_premium": true } すべてのフィールドを含めます。nullに決してしません。
モデルに有効な出力例を見せる
出力例は信頼性を5–10ポイント上げ、トークンをほとんど消費しません。 モデルは成功した出力パターンを見ると、より良く従います。特に曖昧なタイプ (日付リストは配列またはカンマ区切り?) または列挙値 ('ACTIVE'または'active'?) のフィールド向けです。
🔍 ほとんどのケースで1つの例で十分
2つ以上の例は、入力条件によってデータが意味の異なる構造を持つ場合にのみ役立ちます。ほとんどのタスクでは、2番目の例は信頼性メリットなしでトークンコストが倍になります。
🔍 happy pathではなく境界ケースの例を選択
すべてのフィールドが満たされた例は、nullを示しているオプションフィールドを持つもの、または1つの要素を持つ配列ほど有用ではありません。これにより、モデルは境界ケースをどのように処理するかが見えます。
❌ 例なし — モデルが列挙で推測
JSON でカスタマーの詳細を返します。フィールド: customer_id、status。 Input: {{ data }}
✅ 例がフォーマット、タイプ、列挙値のスペルを示す
JSON でカスタマーの詳細を返します。フィールド: customer_id (string)、status (enum: 'active'、'inactive'、'pending')。 例: {"customer_id": "CUST-12345", "status": "active"} Input: {{ data }}
フィールドレベルの指示、スキーマだけではなく
タイプ、形式、許可された値、null処理のためのフィールドレベルの指示は、信頼性を90%から95%+に上げます。 これらの指示は曖昧さを排除する最終層です。
| フィールドタイプ | 一般的なエラー | それを防ぐフィールド指示 |
|---|---|---|
| 整数対浮動小数点 | モデルは整数が期待されるときに浮動小数点を返す | "score (整数 — 小数点なし、4.0ではなく4など)" |
| 列挙 (5+値) | モデルはリストにない値を発明 | すべての値がリストされている: 「リストからの値のみを使用します。略語はありません。」 |
| Nullableフィールド | モデルはnullではなく""を返す | "値が不明な場合はnullを返します。フィールドが既知の空の場合のみ""を返します。" |
| 日付の文字列 | モデルは異なるフォーマットを使用 | "date_created (ISO 8601: '2026-05-15')" |
| 配列 | モデルは空の配列にnullを返す | "常に配列を返します。空の場合でも。nullではなく[]。" |
🔍 指示は具体的で検証可能である必要があります
「良い品質」のようなフィールド指示は検証不可能です。「正確にISO 8601またはエラー」は検証可能です。検証可能な指示は、後で自動テストをサポートします。
🔍 フォーマットにregexまたは例を使用
日付、電話、またはフォーマットフィールドの場合、正規表現または2–3の例を指定します。プロズだけではなく: 「フォーマット: /^\d{3}-\d{3}-\d{4}$/ (例: 555-123-4567)」
タスクと強制に基づいてJSON、YAML、またはCSVを選択
ほとんどの構造化出力タスクはJSONが必要です。YAMLとCSVは人間にとっては書くのが速いですが、API強制なしではモデルはそれらでより信頼性が低いです。 JSON with API-modeは最高の信頼性フロアを持っています。
| フォーマット | APIなしの床 | APIを使用した床 | 最適な用途 |
|---|---|---|---|
| JSON | 80–85% | 95%+ | ネストされた構造、API、ログ |
| YAML | 70–75% | 85–90% | 人間が読める、ネスティングなし |
| CSV | 65–70% | 80–85% | フラットテーブル、バッチデータキャプチャ |
| XML | 75–80% | 90–95% | レガシーシステムが必要 |
🔍 JSONはデフォルトの選択です
ネストされた構造がある場合、またはAPI-level強制を使用できる場合はJSONを使用します。これは最高の信頼性フロアを提供します。
🔍 フラットなテーブル構造のCSVをテスト
CSVは単純なテーブルデータ (1行 = 1レコード) で高速で、トークンでより安価です。列が3–5個のみの場合は、スキーマでCSVをテストしてください; ネスティングが発生した場合はJSONに切り替えます。
モデル自身の不正な出力を修正させる
構造化出力プロンプトが失敗する場合、元の指示、形式が正しくない出力、および特定の検証エラーを含む修正プロンプトを送信します。モデルは、プロンプト書き直しなしで60–75%の場合、自身の形式が正しくない応答から有効な出力を回復します。
修正プロンプトには3つの必須の部分があります: (1) 出力がどのように見えるかの再ステートメント (スキーマまたはフォーマット)、(2) モデルが返した形式が正しくない出力、(3) 特定の検証エラー — 「必須フィールド'invoice_id'が不足している」、「量は文字列です、floatが期待されます」。この3部分構造は、異なる応答で異なる失敗を生成する代わりに、特定の問題を修正するようにモデルに十分なコンテキストを提供します。
🔍 修正が2回失敗する場合はベースプロンプトを修正
修正プロンプトが2回目の試行で有効な出力を生成しない場合、問題はベースプロンプトにあり、入力データにはありません。反復を停止し、失敗パターンを診断します: どのフィールドが失敗し、どの入力条件で。フィールド指示またはスキーマ変更を追加して、ソースで失敗を防ぎます。
⚠️ 修正プロンプトは遅延とコストを追加
各修正プロンプトは、そのコールのAPIコストと遅延が倍になります。修正プロンプトはエッジケースの失敗のみ (<出力の10%) に使用します。プロンプトが10%以上失敗する場合は、本番環境で修正ループを構築するのではなく、ベースプロンプトを修正してください。
❌ 曖昧な再試行 — エラーコンテキストなし
無効な出力を返しました。もう一度試して、有効なJSONを返します。 {{original_prompt}}
✅ スキーマ、出力、特定のエラーを使用した修正プロンプト
前回の応答は検証に失敗しました。以下にリストされたエラーのみを修正し、修正されたJSONを返します。 期待されるスキーマ: { "invoice_id": "string", "amount": 0.00, "status": "string" } 前回の応答: { "invoice_id": null, "amount": "150.00", "status": "PAID" } 検証エラー: - invoice_id はnullですが、必須の文字列フィールドである必要があります — 入力から抽出します - amount は文字列 ("150.00") ですが、floatである必要があります (150.00) - status は小文字である必要があります: 'PAID'ではなく'paid'を使用してください 修正されたJSONオブジェクトのみを返します。
配列、列挙型、ヌル値フィールドのプロンプトパターン
配列、列挙型、およびnullableフィールドは、スキーマだけが防止しない3つの一般的な構造化出力エラーソースです。それぞれは、プロンプト内の特定の指示パターンが必要です。
| データタイプ | 一般的なエラー | それを防ぐプロンプトパターン |
|---|---|---|
| 配列 (0要素) | モデルはnullではなく[]を返す | "要素がない場合は空の配列[]を返します。配列フィールドにnullを返すことはありません。" |
| 配列 (1+要素) | 1つの要素のみが見つかった場合、モデルは単一オブジェクトではなく配列を返す | "1つの要素のみがある場合でも、常に配列を返します。単一要素は{...}でラップされている必要があります" |
| 列挙 (2–5値) | モデルは省略形を作成するか、同様の値を発明 | "status: 正確に1: 'active'、'inactive'、'pending' — 省略形や変種なし" |
| 列挙 (6+値) | モデルはリストにない値を発明 | すべての値を番号付きリストで一覧表示し、以下の通り: 「上記のリストからのみ値を使用します。省略形や組み合わせはありません。」 |
| Nullableフィールド | モデルはnullではなく""を返すか、フィールドを完全に省略 | "値が不明な場合はnullを返します。フィールドが既知の空の場合のみ""を返します。常にフィールドを含める — 省略しないでください。" |
| 整数対浮動小数点 | モデルは整数が期待されるときに浮動小数点、または両方に文字列を返す | "score (整数 — 小数点なし、例: 4ではなく4.0)" または "price (浮動小数点 — 正確に2小数点、例: 13ではなく12.99)" |
| ネストされたオブジェクト | モデルはネストされたオブジェクトをフラットキーに折りたたむ (例: {"address": {"city": ...}} ではなく "address.city") | スキーマテンプレート内の完全なネストされた構造を適切なインデント付きで表示します。プロズだけでのネストの説明は、フラットキーに折りたたむことが多いです。 |
⚠️ nullと未定義と省略
JSONには未定義値がありませんが、モデルはそのように動作することがあります — 値が不明だと思うときはnullを返す代わりにフィールドを完全に省略する場合があります。下流コードがhasOwnProperty()チェックを使用する場合、省略されたフィールドはnullフィールドと異なります。追加: 「スキーマのすべてのフィールドを含めてください。値がnullであっても。」
🔍 ネストされた列挙はエクストラ明快さが必要
ネストされたオブジェクト内の列挙は、トップレベルの列挙よりもタイプミスまたは省略形の影響を受けやすくなります。ネストされたオブジェクト内に列挙がある場合、スキーマテンプレート内にフィールドが表示されている場所に近い指示を繰り返します。一般的なフィールドルールセクションだけでなく。
構造化出力信頼性を測定する
本番環境に構造化出力プロンプトをデプロイする前に、20ケースのテストセットで95%+パスレートを対象とします。95%未満では、失敗は十分に頻繁に発生して修正ループを必要とします — これは遅延を追加し、失敗したコールごとにAPIコストを倍にします。
フィールドレベルで信頼性を測定し、全体ではなく。95%の全体的なパスレートですが、1つの列挙フィールドで60%は既知の本番環境失敗モードを持つプロンプトです。フィールドレベルの測定は、正確にどの指示を追加または強化するかを示します。
- 1スキーマの各フィールドの合格/不合格基準を定義します。 各フィールド: タイプが正しい、必須フィールドが存在し、列挙値が許可されたリストにあり、日付形式が必要なパターンに一致します。これらをプログラム検査として記述します — ビジュアルインスペクションではなく。このステップはテストオラクルを生成します。
- 220ケースのテストセットを構築します。 10個のhappy-path (典型的、整形式)、5個のエッジケース (不足しているオプションフィールド、長いテキスト、異常な値、多言語コンテンツ)、5個の敵対的 (フィールド値に埋め込まれた指示、極端な日付、曖昧なタイプ)。実際のデータドメインからの現実的な入力を使用してください。
- 3温度0で実行し、フィールドごとの合格/不合格を記録します。 確定的で再現可能な結果のために、温度0で20ケースをすべて実行します。各テスト — 全体的な結果だけではなく — でどのフィールドが合格またはバックするかを記録します。フィールドレベルの失敗パターンは、どの指示が不足しているかを識別します。
- 4成功率が最も低いフィールドを修正し、再度テストします。 フィールド指示を追加または強化します: タイプ、形式、null処理、または列挙値。20ケースを再度実行します。単一のターゲット指示は通常、全体的なパスレートを5–15ポイント上げます。95%以上に達するまで繰り返します。
- 52番目のモデルで有効にします。 2番目のモデルに対して完全な20ケースセットを実行します。GPT-4oで95%+、Claude 4.6 Sonnetで70%のプロンプトはモデル依存です。両方で成功するように指示をより明確にするか、プロンプトが検証されたモデルを文書化し、再テストなしで変更しないでください。
🔍 温度0でテストを実行
構造化出力テストセットを温度0で実行して、確定的で再現可能な結果を取得します。温度0をパスするプロンプトは設計による信頼性 — ラッキーではありません。プロンプトが95%+デターミニスティックをパスした後にのみ温度を上げ、新しい温度で設定を再度テストして、信頼性が保持されることを確認します。
🔍 マルチモデル比較でPromptQuorumを使用
PromptQuorumは20ケースセットをGPT-4o、Claude 4.6 Sonnet、Gemini 2.5 Proで同時にテストし、フィールドごとのパスレートを並べて表示します。これにより、モデル依存の失敗が1回の実行で識別され、3回ではなく。
構造化出力プロンプトの5つの一般的な間違い
5つの最も一般的な構造化出力プロンプティングエラーはすべて同じ症状 — 間欠的または体系的な失敗を生成しますが — 異なる修正が必要です。指示を追加する前に、どのエラーを持っているかを診断することは時間を節約します。
❌ プロズでスキーマを説明し、埋め込まない
Why it hurts: プロズの説明は曖昧です — 「要素のリスト」は配列、カンマ区切り文字列、または番号付きリストの場合があります; 「合計」は文字列またはfloatの場合があります
Fix: スキーマを期待し、JSON-templateとしてプロンプトに直接埋め込みます。テンプレートは、プロズの説明ではなく、構造を通じてフィールド名、ネストの深さ、および値のタイプを示しています。
❌ 欠落している、または不明な値の処理方法を指定しないでください
Why it hurts: モデルは、nullを返す代わりに不明なフィールドの妥当な値を発明します — 日付は「不明」、金額は0、欠落したIDは「N/A」になります — なしがタイプ検証をパス
Fix: nullable各フィールドに対して明示的なnull処理を追加します: 「値が入力から確定できない場合はnullを返します。値を推測または発明しないでください。空の文字列を返さないでください。」
❌ プロンプトを開発したモデルに対してのみテストする
Why it hurts: 構造化出力信頼性はモデル間で大きく異なります — GPT-4oで95%のプロンプトはClaude 4.6 Sonnetで70%失敗することができ、スキーマ制約でのさまざまな指示フォローが原因で
Fix: ライブラリをモデル依存として処理する前に、最小2モデルに対して各構造化出力プロンプトを実行します。PromptQuorumまたは直接API呼び出しを使用して プロンプトをモデル全体でテスト 1つのステップで。
❌ 同じプロンプトで失敗した出力を再試行
Why it hurts: 失敗するプロンプトは温度0で再試行され、毎回同じ失敗を生成します。より高い温度では、異なるが依然として失敗した出力を生成します — 異なるエラー、同じ根本原因
Fix: 特定の検証エラーと形式が正しくない出力を使用する修正プロンプトを使用するか、失敗パターンを診断 (どのフィールド、どの入力型) し、ベースプロンプトにターゲット フィールド指示を追加します。
❌ 完全な構造化出力ソリューションとしてJSON-modeを扱う
Why it hurts: JSON-modeは解析不可能な出力を防ぎますが、スキーマ準拠の失敗を防ぎません — JSON-modeを使用するモデルは、不足しているフィールド、間違ったタイプ、無効な列挙値を含む有効なJSONを返すことができ、すべてが下流検証に失敗
Fix: API-enforced JSON-modeを使用する場合でも、常にスキーマ-in-prompｔと フィールド指示を含めてください。構造化出力とJSON-mode 参照 API構成— このガイドはプロンプトレベルの補完をカバーしています。
参考資料
- 構造化出力とJSON-mode: いつ、どのように使用するか — GPT-4o、Claude、Geminiのためのapi-levelJSON-mode構成と、モデル準拠テーブル
- 構造化出力用のベストツール (2026) — 構造化抽出ワークフロー用に比較されたInstructor、Outlines、Pydantic AI、LangChain
- 出力を制御する方法: フォーマット、温度、制約デコード — メカニクスデコード制約、構造化タスク、停止シーケンスの温度とtop-p
- プロンプト品質を評価する方法: メトリクス、テスト、チェックリスト — 20ケーステストセット構築、バイナリ合格/不合格スコアリング、LLM-as-judgeルーブリック
- モデル全体でプロンプトをテストする方法 — GPT-4o、Claude 4.6 Sonnet、Gemini 2.5 Pro全体で同じプロンプトを実行して、モデル依存の失敗を検出
- Zero-shotと少数shotプロンプティング — プロンプトに例を追加する場合とさまざまなタスクタイプで含める数
ソース
- OpenAI構造化出力ドキュメント — OpenAI APIのresponse_formatとJSON-modeの技術仕様
- Anthropictool-useドキュメント — Claude tool_useパラメータがAPI-levelでの構造化出力を強制する方法
- Google Gemini GenerationConfigドキュメント — GeminiのresponseMimeType構成ネイティブJSON出力
- BAMLベンチマーク: 構造化出力精度トレードオフ — モデル全体で制約と制約のない生成の間の信頼性の差についての証拠
- NIST AI Risk Management Framework — 本番システムにおけるAI出力検証のためのガバナンス原則