1. 構造化レスポンスの契約から始める
応答の修復が役立つのは、リクエストがすでに構造化出力を要求している場合だけです。 適した条件:response_format.type = "json_object"- JSON Schema 形式の出力
- 複数の呼び出し元で共有する安定したオブジェクト形式
2. 適切なレイヤーでプラグインを有効にする
response-healing は次の3か所で有効にできます。
- ワークスペースの既定プラグインポリシー
- プリセットのプラグイン設定
- リクエストの
plugins
- ワークスペース
- プリセット
- リクエスト
3. モデル出力の範囲を絞る
要求する出力形式がすでに制限されているほど、修復の効果が高まります。 推奨事項:- 無関係なブロックを複数作るのではなく、オブジェクトを1つにする
- 必須キーを明示する
- 可能であれば温度を決定的にする
- JSON ペイロードの外側に説明文を求めない
4. 応答の修復でできること、できないことを把握する
現在の修復処理は決定的で、ストリーミングなしの場合に限り動作します。ストリーミングリクエストでは応答修復が完全にスキップされます。 修復できる形式:- JSON を囲む Markdown コードフェンス
- 末尾の余分なカンマ
- 安全に補完できる閉じ記号の不足
- それ以外は復元可能なオブジェクトにある引用符のないキー
strict モードを使います。このモードはコードフェンスや周囲のテキストから、すでに有効な JSON だけを取り出し、より広範な構文修復は行いません。
リクエストが JSON Schema 形式の出力を使う場合、修復後に書き直す前にペイロードを検証します。現在のバリデーターは次のような一般的な制約に対応しています。
- 必須キー
- 基本的なスカラー型とコンテナー型
- enum と const の値
- 配列の境界と
uniqueItems - 文字列の長さ、正規表現、
email、uri、uuid、date-timeなどの一般的な形式 - 数値の境界と
multipleOf - オブジェクトのプロパティ数の上限と
additionalProperties: false
- 意味上必要な不足フィールドを作り出す
- 業務上の値を推測する
- 任意の文章を有効なデータに変換する
5. プラグインが実際に実行されたことを確認する
修復が実行されると、リクエストの詳細にプラグイン実行情報が表示されます。 次の点を確認してください。- プラグイン ID
- 変換を試みたか
- ペイロードが変化したか
- 応答を復元できなかった場合の失敗理由
- 修復を期待していたリクエストがストリーミングなしだったか
6. パーサーの問題と内容の問題を区別する
修復で解決しない場合は、次のどの問題かを確認します。- 形式は壊れているが、構造は期待する形に近い JSON
- スキーマ上は有効だが、フィールドが誤っている JSON
- JSON ではなく文章が返っている
- トークン上限が低すぎて出力が途中で切れている
7. 段階的に展開する
- 構造化出力が安定している1つのプリセットで修復を有効にする
- ログでプラグインの実行メタデータを確認する
- 復元されたペイロードが想定スキーマに合うことを確認する
- ログに問題がなければ、似たプリセットにも設定を広げる
8. 適切なモードを選ぶ
- 末尾のカンマ削除やキーへの引用符の追加など、範囲を限定した構文整理を行うには
safeを使います。 - 外側のラッパーを取り除いた後、すでに有効な JSON だけを受け入れるには
strictを使います。 - リクエストの詳細を確認して、実行されたモードを確かめてください。