> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 構造化 JSON の応答を修復する

> スキーマを広げたり不正な応答を手動で再試行したりせず、ほぼ有効な構造化 JSON 出力を復元します。

厳密な JSON が必要なアプリケーションで、モデルがほぼ正しいもののパーサーでエラーになる出力を返す場合は、このレシピを使います。

## 1. 構造化レスポンスの契約から始める

応答の修復が役立つのは、リクエストがすでに構造化出力を要求している場合だけです。

適した条件:

* `response_format.type = "json_object"`
* JSON Schema 形式の出力
* 複数の呼び出し元で共有する安定したオブジェクト形式

自由形式の文章を求めるリクエストでは修復を有効にしないでください。

## 2. 適切なレイヤーでプラグインを有効にする

`response-healing` は次の3か所で有効にできます。

1. ワークスペースの既定プラグインポリシー
2. プリセットのプラグイン設定
3. リクエストの `plugins`

優先順位:

1. ワークスペース
2. プリセット
3. リクエスト

ワークフローで常に構造化 JSON が必要な場合は、プリセットの既定値を使ってください。

## 3. モデル出力の範囲を絞る

要求する出力形式がすでに制限されているほど、修復の効果が高まります。

推奨事項:

* 無関係なブロックを複数作るのではなく、オブジェクトを1つにする
* 必須キーを明示する
* 可能であれば温度を決定的にする
* JSON ペイロードの外側に説明文を求めない

## 4. 応答の修復でできること、できないことを把握する

現在の修復処理は決定的で、ストリーミングなしの場合に限り動作します。ストリーミングリクエストでは応答修復が完全にスキップされます。

修復できる形式:

* JSON を囲む Markdown コードフェンス
* 末尾の余分なカンマ
* 安全に補完できる閉じ記号の不足
* それ以外は復元可能なオブジェクトにある引用符のないキー

より限定的なポリシーには `strict` モードを使います。このモードはコードフェンスや周囲のテキストから、すでに有効な JSON だけを取り出し、より広範な構文修復は行いません。

リクエストが JSON Schema 形式の出力を使う場合、修復後に書き直す前にペイロードを検証します。現在のバリデーターは次のような一般的な制約に対応しています。

* 必須キー
* 基本的なスカラー型とコンテナー型
* enum と const の値
* 配列の境界と `uniqueItems`
* 文字列の長さ、正規表現、`email`、`uri`、`uuid`、`date-time` などの一般的な形式
* 数値の境界と `multipleOf`
* オブジェクトのプロパティ数の上限と `additionalProperties: false`

次の処理はできません。

* 意味上必要な不足フィールドを作り出す
* 業務上の値を推測する
* 任意の文章を有効なデータに変換する

## 5. プラグインが実際に実行されたことを確認する

修復が実行されると、リクエストの詳細にプラグイン実行情報が表示されます。

次の点を確認してください。

* プラグイン ID
* 変換を試みたか
* ペイロードが変化したか
* 応答を復元できなかった場合の失敗理由
* 修復を期待していたリクエストがストリーミングなしだったか

プラグインが表示されない場合は、リクエスト、プリセット、またはワークスペースのポリシーで有効になっていることを確認してください。

## 6. パーサーの問題と内容の問題を区別する

修復で解決しない場合は、次のどの問題かを確認します。

1. 形式は壊れているが、構造は期待する形に近い JSON
2. スキーマ上は有効だが、フィールドが誤っている JSON
3. JSON ではなく文章が返っている
4. トークン上限が低すぎて出力が途中で切れている

応答修復が適しているのはケース1だけです。

## 7. 段階的に展開する

1. 構造化出力が安定している1つのプリセットで修復を有効にする
2. ログでプラグインの実行メタデータを確認する
3. 復元されたペイロードが想定スキーマに合うことを確認する
4. ログに問題がなければ、似たプリセットにも設定を広げる

## 8. 適切なモードを選ぶ

* 末尾のカンマ削除やキーへの引用符の追加など、範囲を限定した構文整理を行うには `safe` を使います。
* 外側のラッパーを取り除いた後、すでに有効な JSON だけを受け入れるには `strict` を使います。
* リクエストの詳細を確認して、実行されたモードを確かめてください。

## 関連ガイド

* [プリセットで応答キャッシュを使う](./response-caching-with-presets.mdx)
* [プリセットを展開してルーティングをデバッグする](./preset-rollout-and-routing-debug.mdx)
* [TypeScript Agent SDK](../sdk-reference/typescript/agent-sdk.mdx)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.