结构化输出使模型能够生成始终遵循特定架构的输出。例如，可以为模型提供响应 schema，以确保响应生成有效的 JSON。Gemini Enterprise Agent Platform 模型即服务 (MaaS) 上提供的 Grok 模型支持结构化输出。
如需详细了解结构化输出功能的概念性信息，请参阅结构化输出简介。
将结构化输出与 Responses API 搭配使用
store 的默认值为 false，因此除非您将 store 设置为 true（或 Python 中的 True），否则请求是无状态的。如需存储回答，请参阅对 Responses API 进行有状态调用。
以下模板展示了如何将结构化输出与 Responses API 搭配使用：
Python
在尝试此示例之前，请按照《Agent Platform 快速入门：使用客户端库》中的 Python 设置说明执行操作。
如需向 Agent Platform 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。
在运行此示例之前，请务必设置 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：响应 schema 的名称。
- 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：响应 schema 的名称。
- 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 设置说明执行操作。
如需向 Agent Platform 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。
在运行此示例之前，请务必设置 OPENAI_BASE_URL 环境变量或设置 OAuth 凭据。
如需了解详情，请参阅身份验证和凭证。
from openai import OpenAI client = OpenAI()response = client.responses.create( model="xai/grok-4.7", 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.7", "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": 1793837914,
"created_at": 1793837914,
"error": null,
"frequency_penalty": 0,
"id": "d18533b9-ecdc-447d-9bbd-f061359c89e9",
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"max_tool_calls": null,
"metadata": {
"system_fingerprint": "fp_grok47_0"
},
"model": "xai/grok-4.7",
"object": "response",
"output": [
{
"content": [
{
"annotations": [],
"logprobs": [],
"text": "{\"age\":30,\"name\":\"John Doe\"}",
"type": "output_text"
}
],
"id": "msg_d18533b9-ecdc-447d-9bbd-f061359c89e9",
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"parallel_tool_calls": true,
"presence_penalty": 0,
"previous_response_id": null,
"prompt_cache_key": null,
"reasoning": {
"effort": "high",
"summary": "detailed"
},
"safety_identifier": null,
"service_tier": "default",
"status": "completed",
"store": false,
"temperature": 0.7,
"text": {
"format": {
"schema": {
"additionalProperties": false,
"properties": {
"age": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"age"
],
"type": "object"
},
"type": "json_schema"
}
},
"tool_choice": "auto",
"tools": [],
"top_logprobs": 0,
"top_p": 0.95,
"truncation": "disabled",
"usage": {
"context_details": {
"input_tokens": 276,
"output_tokens": 70
},
"extra_properties": {
"google": {
"traffic_type": "ON_DEMAND"
}
},
"input_tokens": 276,
"input_tokens_details": {
"cached_tokens": 0
},
"num_server_side_tools_used": 0,
"num_sources_used": 0,
"output_tokens": 70,
"output_tokens_details": {
"reasoning_tokens": 59
},
"total_tokens": 346
},
"user": null
}
将结构化输出与 Chat Completions API 搭配使用
以下用例设置了一个响应 schema，以确保模型输出是具有以下属性的 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 设置说明执行操作。
如需向 Agent Platform 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。
在运行此示例之前，请务必设置 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.6。
REST
在使用任何请求数据之前，请先进行以下替换：
- PROJECT_ID：您的 Google Cloud 项目 ID。
- LOCATION：支持 Grok 模型的区域。
- MODEL：您要使用的模型名称，例如
xai/grok-4.6。
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 响应。