您可以保证模型生成的输出始终遵循特定架构，以便您收到格式一致的响应。例如，您可能已经建立了用于其他任务的数据架构。如果模型遵循相同的架构，您可以直接从模型的输出中提取数据，而无需进行任何后期处理。
如需指定模型的输出结构，请定义响应架构，该架构类似于模型响应的蓝图。如果您提交提示并添加响应架构，模型的响应始终遵循您定义的架构。
您可以控制使用以下模型时生成的输出：
- Gemini 1.5 Pro
- Gemini 1.5 Flash
如需了解使用受控生成的函数调用（也称为强制函数调用），请参阅函数调用简介。
应用场景示例
应用响应架构的一个用例是确保模型的响应生成有效的 JSON 并符合您的架构。生成模型输出可能会有一定程度的变化，添加响应架构可确保您始终收到有效的 JSON。因此，您的下游任务预计可以可靠地得到来自所生成响应的有效 JSON 输入。
另一个示例是限制模型的响应方式。例如，您可以让模型使用用户定义的标签而不是模型生成的标签来为文本添加注释。如果您期望获得一组特定标签（例如 positive 或 negative）而不希望同时收到模型可能会生成的各种其他标签（例如 good、positive、negative 或 bad），这种限制就非常有用。
注意事项
以下注意事项讨论了当您计划使用响应架构时可能会遇到的限制：
- 您必须使用 API 来定义和使用响应架构。目前不提供控制台支持。
- 响应架构的大小会占用输入词元限额。
- 仅支持某些输出格式，例如
application/json或text/x.enum。如需了解详情，请参阅 Gemini API 参考文档中的responseMimeType参数。 受控生成支持以下架构字段，这些字段是 Vertex AI 支持的字段的子集：
enumitemsmaxItemsnullablepropertiesrequired
如果您使用不受支持的字段，Vertex AI 仍然可以处理您的请求，但会忽略该字段。如需查看每个字段的详细信息，请参阅 Vertex AI 架构参考文档。
准备工作
通过定义响应架构指定模型输出的结构、字段名称以及每个字段的预期数据类型。仅使用注意事项部分中列出的受支持的字段。系统会忽略所有其他字段。
如需查看示例架构，请参阅示例架构和模型响应部分。
模型行为和响应架构
模型生成响应时，会使用提示中的字段名称和上下文。因此，我们建议您使用清晰的结构和明确的字段名称，让您的意图清晰明了。
默认情况下，字段是可选的，这意味着模型可以填充或跳过字段。您可以将字段设置为必填字段，以强制模型提供值。如果关联的输入提示中上下文不足，模型会主要基于其训练所依据的数据生成回答。
如果您未看到预期结果，请在输入提示中添加更多上下文或修改响应架构。例如，查看非受控生成情况下模型的响应，以了解模型的响应方式。然后，您可以更新响应架构，使其更贴合模型的输出。
发送包含响应架构的提示
默认情况下，所有字段均为可选字段，这意味着模型可能会生成针对某个字段的响应。如需强制模型始终生成针对某个字段的响应，请将该字段设置为必填字段。
Python
在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。
如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
REST
在使用任何请求数据之前，请先进行以下替换：
- GENERATE_RESPONSE_METHOD：您希望模型生成的回答类型。选择一种方法来生成您希望返回模型回答的方式：
streamGenerateContent：在生成回答时进行流式传输，以降低真人受众群体对于延迟的感知度。generateContent：回答在完全生成后返回。
- LOCATION：处理请求的区域。
- PROJECT_ID：您的项目 ID。
- MODEL_ID：您要使用的多模态模型 ID。选项包括：
gemini-1.5-pro
- 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-1.0-pro"
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 \
-d `@request.json`
示例架构和模型响应
以下部分演示了各种示例提示和响应架构。每个代码示例后还包含模型响应示例。
汇总评价评分
以下示例输出一个对象数组，其中每个对象都有两个属性：评分和冰淇淋口味的名称。
Python
在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。
如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
模型响应示例
candidates { content { role: "model" parts { text: "[\n [\n {\n \"rating\": 4\n },\n {\n \"flavor\": \"Strawberry Cheesecake\"\n },\n {\n \"rating\": 1\n },\n {\n \"flavor\": \"Mango Tango\"\n }\n ]\n] " } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.1139734759926796 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.10070161521434784 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.13695430755615234 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.12241825461387634 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.11676400154829025 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.05310790613293648 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.10521054267883301 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.08299414813518524 } } usage_metadata { prompt_token_count: 61 candidates_token_count: 66 total_token_count: 127 }
预测一周内每一天的天气
以下示例针对一周内的每一天输出一个 forecast 对象，其中包含一组属性（例如当天的预期温度和湿度）。某些属性设置为可为 null，因此模型在没有足够的上下文来生成有意义的响应时可以返回 null 值。此策略有助于减少幻觉。
Python
在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。
如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
模型响应示例
candidates { content { role: "model" parts { text: "{\"forecast\": [{\"Day\": \"Sunday\", \"Forecast\": \"sunny\", \"Humidity\": \"50%\", \"Temperature\": 77, \"Wind Speed\": 10}, {\"Day\": \"Monday\", \"Forecast\": \"partly cloudy\", \"Humidity\": null, \"Temperature\": 72, \"Wind Speed\": 15}, {\"Day\": \"Tuesday\", \"Forecast\": \"rain showers\", \"Humidity\": \"70%\", \"Temperature\": 64, \"Wind Speed\": null}, {\"Day\": \"Wednesday\", \"Forecast\": \"thunderstorms\", \"Humidity\": null, \"Temperature\": 68, \"Wind Speed\": null}, {\"Day\": \"Thursday\", \"Forecast\": \"cloudy\", \"Humidity\": \"60%\", \"Temperature\": 66, \"Wind Speed\": null}, {\"Day\": \"Friday\", \"Forecast\": \"partly cloudy\", \"Humidity\": null, \"Temperature\": 73, \"Wind Speed\": 12}, {\"Day\": \"Saturday\", \"Forecast\": \"sunny\", \"Humidity\": \"40%\", \"Temperature\": 80, \"Wind Speed\": 8}]}" } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.1037486344575882 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.09670579433441162 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.18126320838928223 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.10052486509084702 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.15960998833179474 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.09518112242221832 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.1388116478919983 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.10539454221725464 } } usage_metadata { prompt_token_count: 280 candidates_token_count: 249 total_token_count: 529 }
对商品进行分类
以下示例包含枚举，其中模型必须从给定值的列表中对对象的类型和条件进行分类。
Python
在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。
如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
模型响应示例
candidates { content { role: "model" parts { text: " [{\n \"item_category\": \"winter apparel\",\n \"subcategory\": \"coat\",\n \"to_discard\": 1\n }] " } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.08945459872484207 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.13753245770931244 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.19208428263664246 severity: HARM_SEVERITY_LOW severity_score: 0.23810701072216034 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.07585817575454712 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.04336579889059067 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.12667709589004517 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.07396338135004044 } } usage_metadata { prompt_token_count: 38 candidates_token_count: 33 total_token_count: 71 }
识别图片中的对象
以下示例会识别存储在 Cloud Storage 中的两张图片的对象。
Python
在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。
如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
模型响应示例
candidates { content { role: "model" parts { text: "[\n [\n {\n \"object\": \"globe model\"\n },\n {\n \"object\": \"tablet computer\"\n },\n {\n \"object\": \"shopping cart\"\n },\n {\n \"object\": \"Eiffel Tower model\"\n },\n {\n \"object\": \"airplane model\"\n },\n {\n \"object\": \"coffee cup\"\n },\n {\n \"object\": \"computer keyboard\"\n },\n {\n \"object\": \"computer mouse\"\n },\n {\n \"object\": \"passport\"\n },\n {\n \"object\": \"sunglasses\"\n },\n {\n \"object\": \"US Dollar bills\"\n },\n {\n \"object\": \"notepad\"\n },\n {\n \"object\": \"pen\"\n }\n ],\n [\n {\n \"object\": \"watering can\"\n },\n {\n \"object\": \"oregano\"\n },\n {\n \"object\": \"flower pot\"\n },\n {\n \"object\": \"flower pot\"\n },\n {\n \"object\": \"gardening gloves\"\n },\n {\n \"object\": \"hand rake\"\n },\n {\n \"object\": \"hand trowel\"\n },\n {\n \"object\": \"grass\"\n }\n ]\n] " } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.1872812658548355 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.16357900202274323 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: LOW probability_score: 0.37920594215393066 severity: HARM_SEVERITY_LOW severity_score: 0.29320207238197327 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.14175598323345184 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.12074951827526093 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.12241825461387634 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.0955180674791336 } } usage_metadata { prompt_token_count: 525 candidates_token_count: 333 total_token_count: 858 }
使用单个纯文本枚举值进行响应
以下示例根据电影的说明来确定其类型。输出是模型从在响应架构中定义的列表值中选择的一个纯文本枚举值。
Python
在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。
如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
模型响应示例
candidates { content { role: "model" parts { text: "documentary" } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.051025390625 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.08056640625 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.1416015625 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.068359375 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.11572265625 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.0439453125 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.099609375 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.146484375 } avg_logprobs: -8.783838711678982e-05 } usage_metadata { prompt_token_count: 33 candidates_token_count: 2 total_token_count: 35 }