借助结构化输出，模型可以生成始终遵循特定架构的输出。例如，可以为模型提供响应架构，以确保响应生成有效的 JSON。Gemini Enterprise Agent Platform 模型即服务 (MaaS) 上提供的 Grok 模型支持结构化输出。
如需详细了解结构化输出功能的概念性信息，请参阅结构化输出简介。
将结构化输出与 Responses API 搭配使用
如需使用无状态功能，请在请求中将store 明确设置为 false（或在 Python 中设置为 False）。store 的默认值为 true。如需使用有状态功能，您必须配置 Organization Policy Service 以允许使用这些功能。具体而言，请通过将
publishers/xai/models/MODEL_NAME:stateful_responses_api 添加到允许的值（例如 publishers/xai/models/grok-4.20-reasoning:stateful_responses_api）来更新限制 constraints/vertexai.allowedPartnerModelFeatures。如需了解详情，请参阅控制模型访问权限。
以下模板展示了如何将结构化输出与 Responses API 搭配使用：
Python
试用此示例之前，请按照《Agent Platform 快速入门：使用客户端库》中的 Python 设置说明进行操作。
如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
在运行此示例之前，请务必设置 OPENAI_BASE_URL 环境变量或设置 OAuth 凭据。如需了解详情，请参阅身份验证和凭证。
from openai import OpenAI client = OpenAI()response = client.responses.create( model="MODEL", input="INPUT", text={ "format": { "type": "json_schema", "name": "SCHEMA_NAME", "strict": True, "schema": JSON_SCHEMA } }, stream=False, ) print(response)
- MODEL：您要使用的模型名称，例如
xai/grok-4.20-reasoning。 - INPUT：模型的提示或输入。
- SCHEMA_NAME：响应架构的名称。
- JSON_SCHEMA：用于定义 JSON 架构的字典，例如：
{"type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "integer"}}, "required": ["name", "age"], "additionalProperties": False}
REST
在使用任何请求数据之前，请先进行以下替换：
- PROJECT_ID：您的 Google Cloud 项目 ID。
- MODEL：您要使用的模型名称，例如
xai/grok-4.20-reasoning。 - INPUT：模型的提示或输入。
- SCHEMA_NAME：响应架构的名称。
- JSON_SCHEMA：用于定义输出结构的 JSON 架构对象。
HTTP 方法和网址：
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses
请求 JSON 正文：
{
"model": "MODEL",
"input": "INPUT",
"text": {
"format": {
"type": "json_schema",
"name": "SCHEMA_NAME",
"strict": true,
"schema": JSON_SCHEMA
}
},
"stream": false
}
如需发送请求，请选择以下方式之一：
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://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses"
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://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses" | Select-Object -Expand Content
示例
以下示例展示了如何将结构化输出与 Responses API 搭配使用：
Python
试用此示例之前，请按照《Agent Platform 快速入门：使用客户端库》中的 Python 设置说明进行操作。
如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
在运行此示例之前，请务必设置 OPENAI_BASE_URL 环境变量或设置 OAuth 凭据。如需了解详情，请参阅身份验证和凭证。
from openai import OpenAI client = OpenAI()response = client.responses.create( model="xai/grok-4.20-reasoning", input="Extract: John Doe is 30.", text={ "format": { "type": "json_schema", "name": "person_info", "strict": True, "schema": { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer"} }, "required": ["name", "age"], "additionalProperties": False } } }, stream=False, ) print(response)
REST
curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses -d \ '{ "model": "xai/grok-4.20-reasoning", "input": "Extract: John Doe is 30.", "text": { "format": { "type": "json_schema", "name": "person_info", "strict": true, "schema": { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "required": [ "name", "age" ], "additionalProperties": false } } }, "stream": false }'
- PROJECT_ID：您的 Google Cloud 项目 ID。
示例响应
以下是模型输出的示例：
{
"background": false,
"completed_at": 1779159186,
"created_at": 1779159184,
"error": null,
"frequency_penalty": 0,
"id": "kNALat3NENmDifEP14TQ8Qk",
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"max_tool_calls": null,
"metadata": {
"system_fingerprint": "fp_39c5j0a3e9"
},
"model": "xai/grok-4.20-reasoning",
"object": "response",
"output": [
{
"content": [
{
"annotations": [],
"logprobs": [],
"text": "**Extracted Information:**\n\n- **Name:** John Doe\n- **Age:** 30\n\n**Structured output:**\n```json\n{\n \"name\": \"John Doe\",\n \"age\": 30\n}\n```",
"type": "output_text"
}
],
"id": "msg_kNALat3NENmDifEP14TQ8Qk",
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"parallel_tool_calls": true,
"presence_penalty": 0,
"previous_response_id": null,
"prompt_cache_key": null,
"reasoning": {
"effort": "medium",
"summary": "detailed"
},
"safety_identifier": null,
"service_tier": "default",
"status": "completed",
"store": true,
"temperature": 0.7,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_logprobs": 0,
"top_p": 0.95,
"truncation": "disabled",
"usage": {
"extra_properties": {
"google": {
"traffic_type": "ON_DEMAND"
}
},
"input_tokens": 343,
"input_tokens_details": {
"cached_tokens": 0
},
"num_server_side_tools_used": 0,
"num_sources_used": 0,
"output_tokens": 369,
"output_tokens_details": {
"reasoning_tokens": 325
},
"total_tokens": 712
},
"user": null
}
将结构化输出与 Chat Completions API 搭配使用
以下用例设置了一个回答架构，该架构可确保模型输出是一个具有以下属性的 JSON 对象：name、date 和 participants。Python 代码使用 OpenAI SDK 和 Pydantic 对象生成 JSON 架构。
from pydantic import BaseModel
from openai import OpenAI
client = OpenAI()
class CalendarEvent(BaseModel):
name: str
date: str
participants: list[str]
completion = client.beta.chat.completions.parse(
model="MODEL_NAME",
messages=[
{"role": "system", "content": "Extract the event information."},
{"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
],
response_format=CalendarEvent,
)
print(completion.choices[0].message.parsed)
模型输出将遵循以下 JSON 架构：
{ "name": STRING, "date": STRING, "participants": [STRING] }
如果向模型提供提示“Alice and Bob are going to a science fair on Friday”，模型可能会生成以下回答：
{
"name": "science fair",
"date": "Friday",
"participants": [
"Alice",
"Bob"
]
}
详细示例
以下代码是一个递归架构的示例。UI 类包含 children 的列表，该列表也可以是 UI 类。
from pydantic import BaseModel
from openai import OpenAI
from enum import Enum
from typing import List
client = OpenAI()
class UIType(str, Enum):
div = "div"
button = "button"
header = "header"
section = "section"
field = "field"
form = "form"
class Attribute(BaseModel):
name: str
value: str
class UI(BaseModel):
type: UIType
label: str
children: List["UI"]
attributes: List[Attribute]
UI.model_rebuild() # This is required to enable recursive types
class Response(BaseModel):
ui: UI
completion = client.beta.chat.completions.parse(
model="MODEL_NAME",
messages=[
{"role": "system", "content": "You are a UI generator AI. Convert the user input into a UI."},
{"role": "user", "content": "Make a User Profile Form"}
],
response_format=Response,
)
print(completion.choices[0].message.parsed)
模型输出将遵循上一个代码段中指定的 Pydantic 对象的架构。在此示例中，模型可能会生成以下界面表单：
Form
Input
Name
Email
Age
响应可能如下所示：
ui = UI(
type=UIType.div,
label='Form',
children=[
UI(
type=UIType.div,
label='Input',
children=[],
attributes=[
Attribute(name='label', value='Name')
]
),
UI(
type=UIType.div,
label='Input',
children=[],
attributes=[
Attribute(name='label', value='Email')
]
),
UI(
type=UIType.div,
label='Input',
children=[],
attributes=[
Attribute(name='label', value='Age')
]
)
],
attributes=[
Attribute(name='name', value='John Doe'),
Attribute(name='email', value='john.doe@example.com'),
Attribute(name='age', value='30')
]
)
获取 JSON 对象响应
您可以将 response_format 字段设置为 { "type": "json_object" }，以限制模型仅输出语法有效的 JSON 对象。这通常称为 JSON 模式。当生成 JSON 以用于函数调用或其他需要 JSON 输入的下游任务时，JSON 模式非常有用。
启用 JSON 模式后，模型只能生成可解析为有效 JSON 对象的字符串。虽然此模式可确保输出是语法正确的 JSON，但不会强制执行任何特定架构。为确保模型输出符合特定架构的 JSON，您必须在提示中添加说明，如以下示例所示。
以下示例展示了如何启用 JSON 模式并指示模型返回具有特定结构的 JSON 对象：
Python
试用此示例之前，请按照《Agent Platform 快速入门：使用客户端库》中的 Python 设置说明进行操作。
如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
在运行此示例之前，请务必设置 OPENAI_BASE_URL 环境变量或设置 OAuth 凭据。如需了解详情，请参阅身份验证和凭证。
from openai import OpenAI client = OpenAI()response = client.chat.completions.create( model="MODEL", response_format={ "type": "json_object" }, messages=[ {"role": "user", "content": "List 5 rivers in South America. Your response must be a JSON object with a single key "rivers", which has a list of strings as its value."}, ] ) print(response.choices[0].message.content)
将 MODEL 替换为您要使用的模型名称，例如 xai/grok-4.1-fast-reasoning。
REST
在使用任何请求数据之前，请先进行以下替换：
- PROJECT_ID：您的 Google Cloud 项目 ID。
- LOCATION：支持 Grok 模型的区域。
- MODEL：您要使用的模型名称，例如
xai/grok-4.1-fast-reasoning。
HTTP 方法和网址：
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions
请求 JSON 正文：
{
"model": "MODEL",
"response_format": {
"type": "json_object"
},
"messages": [
{
"role": "user",
"content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."
}
]
}
如需发送请求，请选择以下方式之一：
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/endpoints/openapi/chat/completions"
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/endpoints/openapi/chat/completions" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应。