Grok 模型的結構化輸出內容

結構化輸出內容可讓模型生成一律符合特定結構定義的輸出內容。舉例來說，模型可能會收到回應結構定義，確保回應產生有效的 JSON。Gemini Enterprise Agent Platform Model as a Service (MaaS) 支援結構化輸出內容，可使用 Grok 模型。

如要進一步瞭解結構化輸出功能的概念，請參閱「結構化輸出簡介」。

使用 Responses API 取得結構化輸出內容

如要使用無狀態功能，請在要求中明確將 store 設為 false (或 Python 中的 False)。store 的預設值為 true。

如要使用有狀態的功能，請務必設定 組織政策服務，允許使用這些功能。具體來說，請更新限制 constraints/vertexai.allowedPartnerModelFeatures，在允許的值中加入 publishers/xai/models/MODEL_NAME:stateful_responses_api (例如 publishers/xai/models/grok-4.20-reasoning:stateful_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：回應結構定義的名稱。
  • 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 設定說明操作。

如要向 Agent Platform 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證機制」。

執行這個範例前，請務必設定 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 物件：名稱、日期和參與者。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 和 Bob 星期五要去參加科學展」，模型可能會產生以下回覆：

{
  "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 物件結構定義。在本例中，模型可能會產生下列 UI 表單：

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.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 回應。

後續步驟