您可以保证模型生成的输出始终遵循特定架构，以便您收到格式一致的响应。例如，您可能已经建立了用于其他任务的数据架构。如果模型遵循相同的架构，您可以直接从模型的输出中提取数据，而无需进行任何后期处理。
如需指定模型的输出结构，请定义响应架构，该架构类似于模型响应的蓝图。如果您提交提示并添加响应架构，模型的响应始终遵循您定义的架构。
您可以控制使用以下模型时生成的输出：
应用场景示例
应用响应架构的一个用例是确保模型的响应生成有效的 JSON 并符合您的架构。生成模型输出可能会有一定程度的变化，添加响应架构可确保您始终收到有效的 JSON。因此，您的下游任务预计可以可靠地得到来自所生成响应的有效 JSON 输入。
另一个示例是限制模型的响应方式。例如，您可以让模型使用用户定义的标签而不是模型生成的标签来为文本添加注释。如果您期望获得一组特定标签（例如 positive 或 negative）而不希望同时收到模型可能会生成的各种其他标签（例如 good、positive、negative 或 bad），这种限制就非常有用。
注意事项
以下注意事项讨论了当您计划使用响应架构时可能会遇到的限制：
- 您必须使用 API 来定义和使用响应架构。目前不提供控制台支持。
- 回答架构的大小会计入输入 token 限制。
- 系统仅支持某些输出格式，例如
application/json或text/x.enum。如需了解详情，请参阅 Gemini API 参考文档中的responseMimeType参数。 - 受控生成支持 Vertex AI 架构参考文档中的一部分。如需了解详情，请参阅支持的架构字段。
复杂的架构可能会导致
InvalidArgument: 400错误。复杂性可能来自属性名称过长、数组长度限制过长、枚举值过多、对象具有许多可选属性，或者是这些因素的组合。如果您在使用有效架构时看到此错误，请进行以下一项或多项更改以解决此错误：
- 缩短属性名称或枚举名称。
- 展平嵌套数组。
- 减少存在限制的属性的数量，例如具有下限和上限的数量。
- 减少存在复杂限制的属性的数量，例如采用
date-time等复杂格式的属性。 - 减少可选属性的数量。
- 减少枚举的有效值数量。
支持的架构字段
受控生成支持 Vertex AI 架构中的以下字段。如果您使用的是不受支持的字段，Vertex AI 仍可以处理您的请求，但会忽略该字段。
anyOfenumformatitemsmaximummaxItemsminimumminItemsnullablepropertiespropertyOrdering*required
* propertyOrdering 专门用于受控生成，不属于 Vertex AI 架构。此字段定义了生成属性的顺序。列出的属性必须是唯一的，并且必须是 properties 字典中的有效键。
对于 format 字段，Vertex AI 支持以下值：date、date-time、duration 和 time。每个值的说明和格式如 OpenAPI 计划注册表中所述。
准备工作
通过定义响应架构指定模型输出的结构、字段名称以及每个字段的预期数据类型。仅使用注意事项部分中列出的受支持字段。系统会忽略所有其他字段。
仅在 responseSchema 字段中添加回答架构。请勿在输入提示中重复该架构。如果您这样做，生成的输出可能会降低质量。
如需查看示例架构，请参阅示例架构和模型回答部分。
模型行为和响应架构
模型生成响应时，会使用提示中的字段名称和上下文。因此，我们建议您使用清晰的结构和明确的字段名称，让您的意图清晰明了。
默认情况下，字段是可选的，这意味着模型可以填充或跳过字段。您可以将字段设置为必填字段，以强制模型提供值。如果关联的输入提示中上下文不足，模型会主要基于其训练所依据的数据生成回答。
如果您未看到预期结果，请在输入提示中添加更多上下文或修改响应架构。例如，查看非受控生成情况下模型的响应，以了解模型的响应方式。然后，您可以更新响应架构，使其更贴合模型的输出。
发送包含响应架构的提示
默认情况下，所有字段均为可选字段，这意味着模型可能会生成针对某个字段的响应。如需强制模型始终生成针对某个字段的响应，请将该字段设置为必填字段。
Gen AI SDK for Python
安装
pip install --upgrade google-genai
设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：
# 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=us-central1 export GOOGLE_GENAI_USE_VERTEXAI=True
Gen AI SDK for Go
了解如何安装或更新 Gen AI SDK for Go。
如需了解详情，请参阅 SDK 参考文档。设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：
# 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=us-central1 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.0-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 对象，其中包含一组属性（例如当天的预期温度和湿度水平）。某些属性会设置为可为 null，以便模型在没有足够的上下文来生成有意义的回答时返回 null 值。此策略有助于减少模型幻觉。
Gen AI SDK for Python
安装
pip install --upgrade google-genai
设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：
# 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=us-central1 export GOOGLE_GENAI_USE_VERTEXAI=True
Gen AI SDK for Go
了解如何安装或更新 Gen AI SDK for Go。
如需了解详情，请参阅 SDK 参考文档。设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：
# 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=us-central1 export GOOGLE_GENAI_USE_VERTEXAI=True
对产品进行分类
以下示例包含枚举，其中模型必须从给定值的列表中对对象的类型和条件进行分类。
Gen AI SDK for Python
安装
pip install --upgrade google-genai
设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：
# 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=us-central1 export GOOGLE_GENAI_USE_VERTEXAI=True
Gen AI SDK for Go
了解如何安装或更新 Gen AI SDK for Go。
如需了解详情，请参阅 SDK 参考文档。设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：
# 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=us-central1 export GOOGLE_GENAI_USE_VERTEXAI=True