Structured Output

プログラムで解析、検証しやすい構造化データをモデルに返させます。

Structured Outputは、モデルに期待するデータ構造で結果を返させ、プログラムでのフィールド抽出、データベースへの保存、後続ワークフローへの受け渡しを容易にします。代表的な用途には、問い合わせの分類、フォーム抽出、コンテンツ審査結果、固定構造の分析レポートがあります。

Structured OutputとTool Callingは異なる問題を解決します

構造化された回答を返させる場合はStructured Outputを使用します。モデルに関数を選択させ、アプリケーションへ実行を要求させる場合はTool Callingを使用します。ツール引数もSchemaで制約できますが、ツール呼び出しループの一部です。

適切な出力方式を選択する

方式	解決できる問題	クライアント側で必要な処理
PromptでJSONを要求	専用フィールドに対応しないモデルへ基本的な制約を加える	JSONを抽出、解析、検証し、失敗時に再試行する
JSON Object	有効なJSONオブジェクトをモデルに出力させる	フィールド、型、業務ルールを検証する
JSON Schema	リクエストに目標構造を指定する	モデルの対応範囲、拒否、切り詰め、検証失敗を処理する

JSON Object、JSON Schema、厳密な準拠に対応するかどうかは、現在のモデルとプロトコルによって異なります。リクエストが200を返しただけで、指定したSchemaが有効になったと判断しないでください。

小さく明確なSchemaを定義する

次の構造は、顧客の問い合わせをサポートチケットに分類する例です。

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account"]
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "summary": {
      "type": "string"
    }
  },
  "required": ["category", "priority", "summary"],
  "additionalProperties": false
}

フィールド名は安定して理解しやすいものにし、列挙値は業務コードと一致させてください。最初から深すぎる入れ子、多数の任意分岐、説明しにくい正規表現制約を使用しないでください。

Chat Completionsで構造化結果を返す

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "API Keyが使用できません。この問い合わせを分類してください。"
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "category": {
              "type": "string",
              "enum": ["billing", "technical", "account"]
            },
            "priority": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3
            },
            "summary": {"type": "string"}
          },
          "required": ["category", "priority", "summary"],
          "additionalProperties": false
        }
      }
    }
  }'

strictは目標形式の一部ですが、利用できるかどうかはモデルによって決まります。完全なフィールドはChat Completions Referenceを参照してください。

プロトコルごとのフィールド位置

Chatはresponse_formatでjson_objectまたはjson_schemaを選択します。JSON Schemaを使用する場合、Schemaはresponse_format.json_schema.schemaに配置します。

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "schema": {"type": "object"}
    }
  }
}

これらの構造を別のプロトコルへそのままコピーすることはできません。使用前にResponses ReferenceとGemini Generate Content Referenceを確認してください。

解析後も検証する

type SupportTicket = {
  category: 'billing' | 'technical' | 'account';
  priority: number;
  summary: string;
};

function parseTicket(raw: string): SupportTicket {
  const value: unknown = JSON.parse(raw);

  if (
    typeof value !== 'object' ||
    value === null ||
    !('category' in value) ||
    !('priority' in value) ||
    !('summary' in value)
  ) {
    throw new Error('構造化結果に必須フィールドがありません');
  }

  return value as SupportTicket;
}

この例は最小限の確認のみを示します。本番プロジェクトでは、業務データモデルと一致するSchemaバリデーターを使用し、列挙値、長さ、数値範囲、フィールド間ルールを検証してください。

不完全または無効な結果を処理する

状況	処理方法
通常のテキストが返る	モデルが目標形式に対応するか、フィールド位置とSDKによるリクエストの書き換えを確認する
JSONを解析できない	機密情報を除いたレスポンスと停止理由を保存し、業務方針に従って限定的に再試行する
必須フィールドがない	検証失敗として扱い、デフォルト値で重要なデータ不足を隠さない
出力が切り詰められた	出力予算を調整するかSchemaを簡素化し、不足するJSONを推測して連結しない
モデルが回答を拒否した	拒否を個別に処理し、拒否テキストを業務オブジェクトとして扱わない
Schemaは解析できるが業務上無効	業務検証で明確なエラーを返すか、人手による処理へ移行する

公開前の確認

Schemaとアプリケーションの型定義を同じ情報源から生成するか、同期を維持する。
モデル切り替え前に、プロトコル、対応するSchemaのサブセット、厳密モードへの対応を再確認する。
解析失敗、拒否、切り詰め、空出力に独立した処理分岐がある。
構造化結果をデータベースへ保存する、または業務操作を開始する前に再検証する。
ログにはトラブルシューティングに必要な、機密情報を除いた情報だけを保存する。

まずモデルマーケットプレイスでモデルを確認し、その後、対応するAPI Referenceで完全なフィールドを確認してください。リクエストに失敗した場合はエラーとトラブルシューティングを参照してください。