BroadRouter
始める

構造化出力(Structured Outputs)

更新日

構造化出力とは、モデルの回答を開発者が指定した形式(通常は JSON Schema)に制約し、コードで確実に解析できるようにする LLM API の機能です。有効な JSON であることだけを保証し、特定の形までは保証しない JSON モードより厳格です。

別名: 構造化出力、JSON スキーマ出力、JSON 出力、structured output、structured outputs、JSON schema output、response_format

コードには予測できる入力が必要です。構造化出力は、モデルの自由なテキストを、プログラムが信頼できるデータに変えます。

仕組み

制御のレベルは 3 段階あります。

方法 得られるもの
プロンプトで頼む たいていは JSON。ただし余分なテキストが付いたり、フィールドが欠けたりすることがある
JSON モード 有効な JSON。形は問わない
スキーマ付きの構造化出力 スキーマに一致する JSON

OpenAI の形式では、JSON モードは response_format: {"type": "json_object"} です。構造化出力ではスキーマを渡します。

"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "invoice",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "vendor": { "type": "string" },
        "total": { "type": "number" }
      },
      "required": ["vendor", "total"],
      "additionalProperties": false
    }
  }
}

OpenAI のリファレンスによると、json_schema 型は “ensures the model will match your supplied JSON schema”(訳:モデルが指定された JSON スキーマに一致することを保証する)とされています。多くのプロバイダーは、これを制約付きデコーディングで実現しています。各ステップでモデルが生成できるトークンを制限し、スキーマに反する出力をそもそも生成できないようにする方法です。

なぜ重要か

  • 解析エラーが減る。 情報抽出のパイプライン、分類器、エージェントが、フィールドを直接読めます。
  • プロンプトが簡単になる。 長い形式の指示をスキーマが置き換えます。
  • 完全な保証ではない。 OpenAI のガイドは、アプリ側で拒否、不完全なレスポンス、エラーを引き続き処理すべきだとしています。max_tokens で途中で切れた回答は、スキーマに関係なく壊れた JSON になります。

対応状況は OpenAI 互換 API によって異なります。json_schema だけを受け付けるもの、json_object だけを受け付けるもの、このフィールドを無視するものがあります。頼る前に確認してください。

BroadNet Inference の場合

BroadNet のドキュメントは、GLM 5.3 と Qwen3.8 27B について構造化出力を挙げています。リクエストのパラメーター名はドキュメントに書かれていないため、使うモデルで response_format をテストし、いずれにしてもエラー処理付きの JSON パーサーを用意してください。LLM JSON 出力バリデーターを使うと、回答のどこが壊れているかを示し、スキーマとの照合もできます。どちらのモデルも先に推論するので、max_tokens には推論と JSON の両方の余裕を持たせてください。

構造化出力はビジョンモデルと相性が良い機能です。アラビア語の請求書ガイドでは、画像を送り、各フィールドを JSON で返すよう求めています。回答ではなく操作をさせたい場合は、ツール呼び出しを使ってください。

よくある間違い

  • strict モードで additionalProperties: false を忘れたり、すべてのフィールドを required に並べていなかったりする。
  • 解析の前に finish_reason を確認しない。

よくある質問

JSON モードと構造化出力の違いは何ですか?

JSON モードが約束するのは、回答が JSON として解析できることだけです。スキーマを指定した構造化出力は、定義したフィールド、型、必須キーまで約束します。OpenAI のガイドによると、スキーマへの準拠を保証するのは Structured Outputs だけです。

それでも出力の検証は必要ですか?

必要です。回答が拒否だったり、max_tokens で途中で切れたりすることはあります。また、合計が明細の和と一致しなければならない、といったビジネスルールをすべてスキーマで表せるわけではありません。

構造化出力とツール呼び出しのどちらを使うべきですか?

最終的な回答を決まった形で受け取りたいなら、構造化出力を使ってください。モデルにコードの処理を依頼させ、その後も続けさせたいなら、ツール呼び出しを使ってください。

Markdown で読むChatGPT に聞くClaude に聞くPerplexity に聞く