您可以確保模型生成的輸出內容一律符合特定結構定義，以便取得格式一致的回覆。舉例來說，您可能已建立用於其他工作的資料結構定義。如果模型遵循相同結構定義，您可以直接從模型輸出內容擷取資料，不必進行後續處理。
如要指定模型輸出的結構，請定義回覆結構定義，這就像模型回覆的藍圖。提交提示並加入回覆結構定義後，模型的回覆一律會遵循您定義的結構定義。
使用下列模型時，您可以控制生成的輸出內容：
Gemini 模型：
開放式模型：
如要使用開放模型，請參閱這份使用者指南。
應用實例
套用回覆結構定義的用途之一，是確保模型回覆會產生有效的 JSON，並符合您的結構定義。生成模型輸出的內容可能略有差異，因此加入回應結構定義可確保您一律收到有效的 JSON。因此，下游工作可以放心地從生成的結果中取得有效的 JSON 輸入內容。
另一個例子是限制模型的回覆方式。舉例來說，您可以讓模型使用使用者定義的標籤，而非模型產生的標籤，為文字加上註解。如果您預期會收到特定標籤組合 (例如 positive 或 negative)，且不希望收到模型可能產生的其他標籤 (例如 good、positive、negative 或 bad)，這項限制就非常實用。
注意事項
如果您打算使用回應結構定義，請參閱下列考量事項，瞭解可能遇到的限制：
- 您必須使用 API 定義及使用回覆結構定義。不支援遊戲主機。
- 回應結構定義的大小會計入輸入權杖限制。
- 僅支援特定輸出格式，例如
application/json或text/x.enum。詳情請參閱 Gemini API 參考資料中的responseMimeType參數。 - 結構化輸出內容支援 Vertex AI 結構定義參考資料的子集。詳情請參閱「支援的結構定義欄位」。
複雜的結構定義可能會導致
InvalidArgument: 400錯誤。複雜度可能來自於屬性名稱過長、陣列長度限制過長、列舉值過多、物件的可選屬性過多，或是這些因素的組合。如果使用有效結構定義時發生這項錯誤，請進行下列一或多項變更來解決問題：
- 縮短屬性名稱或列舉名稱。
- 整併巢狀陣列。
- 減少設有限制的屬性數量，例如設有上下限的數字。
- 減少具有複雜限制的屬性數量，例如具有複雜格式的屬性，如
date-time。 - 減少選用屬性的數量。
- 減少列舉的有效值數量。
支援的結構定義欄位
結構化輸出內容支援 Vertex AI 結構定義中的下列欄位。如果使用不支援的欄位，Vertex AI 仍可處理要求，但會忽略該欄位。
anyOfenumformatitemsmaximummaxItemsminimumminItemsnullablepropertiespropertyOrdering*required
* propertyOrdering 專為結構化輸出內容設計，不屬於 Vertex AI 架構。這個欄位會定義屬性的產生順序。列出的屬性不得重複，且必須是properties字典中的有效鍵。
Vertex AI 支援 format 欄位的下列值：date、date-time、duration 和 time。每個值的說明和格式請參閱 OpenAPI Initiative 登錄檔
事前準備
定義回覆結構定義，指定模型輸出的結構、欄位名稱，以及每個欄位的預期資料類型。請只使用「注意事項」一節中列出的支援欄位。系統會忽略其他欄位。
請只在 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 方法和網址：
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 輸出內容的結構定義範例
以下各節將示範各種範例提示和回應結構定義。每個程式碼範例後方也附有模型回應範例。
預測一週每天的天氣
以下範例會針對每週的每一天輸出 forecast 物件，其中包含預期溫度和當天濕度等屬性陣列。部分屬性設為可為空值，因此模型在沒有足夠的背景資訊可產生有意義的回應時，可以傳回空值。這項策略有助於減少幻覺。
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