モデルの生成済み出力が常に特定のスキーマに準拠するように保証することで、一貫した形式のレスポンスを受信できます。たとえば、他のタスクで使用する確立したデータ スキーマがあるとします。モデルがこのスキーマに従っている場合、後処理なしでモデルの出力からデータを直接抽出できます。
モデルの出力の構造を指定するには、レスポンス スキーマを定義します。これは、モデルのレスポンスのブループリントのように機能します。プロンプトを送信してレスポンス スキーマを含めると、モデルのレスポンスは常に定義されたスキーマに従います。
生成された出力を制御するには、次のモデルを使用します。
Gemini モデル:
オープンモデル:
オープンモデルについては、こちらのユーザーガイドをご覧ください。
サンプル ユースケース
レスポンス スキーマを適用するユースケースの 1 つとして、モデルのレスポンスが有効な JSON を生成し、スキーマに準拠しているかを確認することが挙げられます。生成モデルの出力にはある程度のばらつきがあるため、レスポンス スキーマを含めることで、常に有効な JSON を受け取ることができます。したがって、下流のタスクは、生成されたレスポンスから有効な JSON 入力が得られることを確実に予測できます。
別の例として、モデルの応答方法を制限することが挙げられます。たとえば、モデルが生成したラベルではなく、ユーザー定義のラベルでテキストに注釈を付けることができます。この制約は、positive や negative などの特定のラベルセットを想定しており、good、positive、negative、bad など、モデルが生成する可能性のある他のラベルを混在させたくない場合に有用です。
考慮事項
レスポンス スキーマを使用する場合の制限事項について、次の考慮事項で説明します。
- レスポンス スキーマの定義や使用には、API を使用する必要があります。コンソール サポートはありません。
- レスポンス スキーマのサイズは、入力トークン制限にカウントされます。
- サポートされている出力形式は、
application/jsonやtext/x.enumなど、特定の形式のみです。詳細については、Gemini API リファレンスのresponseMimeTypeパラメータをご覧ください。 - 構造化出力は、Vertex AI スキーマ リファレンスのサブセットをサポートしています。詳細については、サポートされているスキーマ フィールドをご覧ください。
複雑なスキーマを使用すると、
InvalidArgument: 400エラーが発生する可能性があります。複雑になる要因としては、プロパティ名が長い、配列長の上限が大きい、列挙型の値が多い、オブジェクトのオプション プロパティが多い、またはこれらの要因の組み合わせが考えられます。有効なスキーマでこのエラーが発生する場合は、次の変更を 1 つ以上行ってエラーを解決します。
- プロパティ名または列挙型名を短くする。
- ネストされた配列をフラット化する。
- 最小値と最大値が設定された数値など、制約のあるプロパティの数を減らす。
- 複雑な制約を持つプロパティの数を減らす。たとえば、
date-timeのような複雑な形式のプロパティは減らす。 - オプションのプロパティの数を減らす。
- 列挙型の有効な値の数を減らす。
サポートされているスキーマ フィールド
構造化出力は、Vertex AI スキーマの次のフィールドをサポートしています。サポートされていないフィールドを使用した場合でも、Vertex AI はリクエストを処理できますが、そのフィールドは無視されます。
anyOfenum:string列挙型のみがサポートされています。formatitemsmaximummaxItemsminimumminItemsnullablepropertiespropertyOrdering*required
* propertyOrdering は構造化された出力専用であり、Vertex AI スキーマの一部ではありません。このフィールドは、プロパティが生成される順序を定義します。リストに含めるプロパティは一意である必要があり、properties ディクショナリの有効なキーである必要があります。
format フィールドでは、Vertex AI は date、date-time、duration、time の値をサポートしています。各値の説明と形式については、OpenAPI イニシアチブ レジストリに記載されています。
始める前に
レスポンス スキーマを定義して、モデルの出力の構造、フィールド名、各フィールドの想定されるデータ型を指定します。考慮事項セクションに記載されているサポートされているフィールドのみを使用します。他のフィールドをすべて無視されます。
レスポンス スキーマは responseSchema フィールドの一部としてのみ含めます。入力プロンプトでスキーマを重複させないでください。重複させると、生成された出力の品質が低下する可能性があります。
スキーマのサンプルについては、スキーマとモデル レスポンスの例のセクションをご覧ください。
モデルの動作とレスポンス スキーマ
モデルがレスポンスを生成するときは、プロンプトからフィールド名とコンテキストを使用します。そのため、意図が明確になるように、明確な構造と曖昧さのないフィールド名を使用することをおすすめします。
デフォルトでは、フィールドは省略可能です。つまり、モデルはフィールドにデータを入力することも、フィールドをスキップすることもできます。フィールドを必須として設定すると、モデルに値を提供させることができます。関連する入力プロンプトに十分なコンテキストがない場合、モデルは主にトレーニングに使用されたデータに基づいてレスポンスを生成します。
期待どおりの結果が表示されない場合は、入力プロンプトにコンテキストを追加するか、レスポンス スキーマを修正します。たとえば、構造化された出力なしでモデルのレスポンスを確認して、モデルがどのように応答するかを確認します。その後、モデルの出力により適したレスポンス スキーマを更新できます。
レスポンス スキーマを含むプロンプトを送信する
デフォルトでは、すべてのフィールドは省略可能です。つまり、モデルはフィールドに対するレスポンスを生成できます。モデルでフィールドに対するレスポンスを常に強制的に生成させるには、フィールドを必須として設定します。
Python
インストール
pip install --upgrade google-genai
詳しくは、SDK リファレンス ドキュメントをご覧ください。
Vertex AI で Gen AI SDK を使用するための環境変数を設定します。
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Go
Go をインストールまたは更新します。
詳しくは、SDK リファレンス ドキュメントをご覧ください。
Vertex AI で Gen AI SDK を使用するための環境変数を設定します。
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
REST
リクエストのデータを使用する前に、次のように置き換えます。
- GENERATE_RESPONSE_METHOD: モデルに生成させるレスポンスのタイプ。モデルのレスポンスを返す方法を生成するメソッドを選択します。
streamGenerateContent: レスポンスは生成時にストリーミングされます。ユーザーが遅延を感じることは少なくなります。generateContent: レスポンスは、完全に生成された後に返されます。
- LOCATION: リクエストを処理するリージョン。
- PROJECT_ID: 実際のプロジェクト ID。
- MODEL_ID: 使用するマルチモーダル モデルのモデル ID。
- ROLE: コンテンツに関連付けられた会話におけるロール。単一ターンのユースケースでも、ロールの指定が必要です。指定できる値は以下のとおりです。
USER: 送信するコンテンツを指定します。
- TEXT: プロンプトに含める指示のテキスト。
- RESPONSE_MIME_TYPE: 生成された候補テキストの形式タイプ。サポートされている値の一覧については、Gemini API の
responseMimeTypeパラメータをご覧ください。 - RESPONSE_SCHEMA: レスポンスの生成時に従うモデルのスキーマ。詳細については、スキーマのリファレンスをご覧ください。
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD
リクエストの本文（JSON）:
{
"contents": {
"role": "ROLE",
"parts": {
"text": "TEXT"
}
},
"generation_config": {
"responseMimeType": "RESPONSE_MIME_TYPE",
"responseSchema": RESPONSE_SCHEMA,
}
}
リクエストを送信するには、次のいずれかのオプションを選択します。
curl
リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"
PowerShell
リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
curl コマンドの例
LOCATION="us-central1"
MODEL_ID="gemini-2.5-flash"
PROJECT_ID="test-project"
GENERATE_RESPONSE_METHOD="generateContent"
cat << EOF > request.json
{
"contents": {
"role": "user",
"parts": {
"text": "List a few popular cookie recipes."
}
},
"generation_config": {
"maxOutputTokens": 2048,
"responseMimeType": "application/json",
"responseSchema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recipe_name": {
"type": "string",
},
},
"required": ["recipe_name"],
},
}
}
}
EOF
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:${GENERATE_RESPONSE_METHOD} \
-d '@request.json'
JSON 出力のスキーマの例
以降のセクションでは、さまざまなプロンプトとレスポンス スキーマの例を示します。各コードサンプルの後に、モデル レスポンスのサンプルも記載されています。
曜日ごとの天気を予測する
次の例では、1 週間の各曜日の forecast オブジェクトを出力します。このオブジェクトには、その日の予想気温や湿度などのプロパティの配列が含まれます。一部のプロパティは null 可能に設定されているため、意味のあるレスポンスを生成するのに十分なコンテキストがない場合、モデルが null 値を返すことができます。この戦略は、ハルシネーションを軽減するのに役立ちます。
Python
インストール
pip install --upgrade google-genai
詳しくは、SDK リファレンス ドキュメントをご覧ください。
Vertex AI で Gen AI SDK を使用するための環境変数を設定します。
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Go
Go をインストールまたは更新します。
詳しくは、SDK リファレンス ドキュメントをご覧ください。
Vertex AI で Gen AI SDK を使用するための環境変数を設定します。
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
商品を分類する
次の例では、モデルが特定の値のリストからオブジェクトのタイプと条件を分類する必要がある列挙型を使用しています。
Python
インストール
pip install --upgrade google-genai
詳しくは、SDK リファレンス ドキュメントをご覧ください。
Vertex AI で Gen AI SDK を使用するための環境変数を設定します。
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Go
Go をインストールまたは更新します。
詳しくは、SDK リファレンス ドキュメントをご覧ください。
Vertex AI で Gen AI SDK を使用するための環境変数を設定します。
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Node.js
インストール
npm install @google/genai
詳しくは、SDK リファレンス ドキュメントをご覧ください。
Vertex AI で Gen AI SDK を使用するための環境変数を設定します。
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Java
Java をインストールまたは更新します。
詳しくは、SDK リファレンス ドキュメントをご覧ください。
Vertex AI で Gen AI SDK を使用するための環境変数を設定します。
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True