Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Output terstruktur untuk model Grok

Output terstruktur memungkinkan model menghasilkan output yang selalu mematuhi skema tertentu. Misalnya, model dapat dilengkapi dengan skema respons untuk memastikan bahwa respons menghasilkan JSON yang valid. Model Grok yang tersedia di Gemini Enterprise Agent Platform Model as a Service (MaaS) mendukung output terstruktur.

Untuk mengetahui informasi konseptual selengkapnya tentang kemampuan output terstruktur, lihat Pengantar output terstruktur.

Menggunakan output terstruktur dengan Responses API

Catatan: Setelan store ke true dan parameter previous_response_id untuk panggilan API stateful tidak didukung untuk model Grok saat ini, dan store secara default ditetapkan ke false. Dukungan direncanakan untuk rilis mendatang. Saat dukungan ditambahkan, perilaku default akan berubah menjadi store: true, dan previous_response_id akan diaktifkan. Jika Anda ingin mencegah respons Anda disimpan setelah perubahan ini, tetapkan store secara eksplisit ke false (atau False di Python) dalam permintaan Anda.

Template berikut menunjukkan cara menggunakan output terstruktur dengan Responses API:

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Agent Platform menggunakan library klien.

Untuk melakukan autentikasi ke Agent Platform, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

Sebelum menjalankan contoh ini, pastikan untuk menetapkan variabel lingkungan OPENAI_BASE_URL atau menyiapkan kredensial oauth. Untuk mengetahui informasi selengkapnya, lihat Autentikasi dan kredensial.

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: Nama model yang ingin Anda gunakan, misalnya xai/grok-4.20-reasoning.
INPUT: Prompt atau input untuk model.
SCHEMA_NAME: Nama untuk skema respons.
JSON_SCHEMA: Kamus yang menentukan skema JSON, misalnya:
{"type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "integer"}}, "required": ["name", "age"], "additionalProperties": False}

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

PROJECT_ID: Project ID Anda Google Cloud .
MODEL: Nama model yang ingin Anda gunakan, misalnya xai/grok-4.20-reasoning.
INPUT: Prompt atau input untuk model.
SCHEMA_NAME: Nama untuk skema respons.
JSON_SCHEMA: Objek skema JSON yang menentukan struktur output.

Metode HTTP dan URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses

Meminta isi JSON:

{
  "model": "MODEL",
  "input": "INPUT",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "SCHEMA_NAME",
      "strict": true,
      "schema": JSON_SCHEMA
    }
  },
  "stream": false
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$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

Contoh

Contoh berikut menunjukkan contoh lengkap penggunaan output terstruktur dengan Responses API:

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Agent Platform menggunakan library klien.

Untuk melakukan autentikasi ke Agent Platform, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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 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: Project ID Anda Google Cloud .

Contoh Respons

Berikut adalah contoh tampilan output model:

{
  "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
}

Menggunakan output terstruktur dengan Chat Completions API

Kasus penggunaan berikut menetapkan response schema yang memastikan bahwa output model adalah objek JSON dengan properti berikut: nama, tanggal, dan peserta. Kode Python menggunakan OpenAI SDK dan objek Pydantic untuk menghasilkan skema 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)

Output model akan mematuhi skema JSON berikut:

{ "name": STRING, "date": STRING, "participants": [STRING] }

Saat diberi prompt, "Alice and Bob are going to a science fair on Friday", model dapat menghasilkan respons berikut:

{
  "name": "science fair",
  "date": "Friday",
  "participants": [
    "Alice",
    "Bob"
  ]
}

Contoh mendetail

Kode berikut adalah contoh skema rekursif. Class UI berisi daftar children, yang juga dapat berupa class 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)

Output model akan mematuhi skema objek Pydantic yang ditentukan dalam cuplikan sebelumnya. Dalam contoh ini, model dapat menghasilkan formulir UI berikut:

Form
  Input
    Name
    Email
    Age

Respons dapat terlihat seperti berikut:

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')
    ]
)

Mendapatkan respons objek JSON

Anda dapat membatasi model untuk hanya menampilkan objek JSON yang valid secara sintaksis dengan menetapkan kolom response_format ke { "type": "json_object" }. Hal ini sering disebut mode JSON. Mode JSON berguna saat membuat JSON untuk digunakan dengan panggilan fungsi atau tugas hilir lainnya yang memerlukan input JSON.

Saat mode JSON diaktifkan, model dibatasi untuk hanya menghasilkan string yang diuraikan menjadi objek JSON yang valid. Meskipun mode ini memastikan output adalah JSON yang benar secara sintaksis, mode ini tidak menerapkan skema tertentu. Untuk memastikan model menghasilkan JSON yang mengikuti skema tertentu, Anda harus menyertakan petunjuk dalam prompt, seperti yang ditunjukkan dalam contoh berikut.

Contoh berikut menunjukkan cara mengaktifkan mode JSON dan menginstruksikan model untuk menampilkan objek JSON dengan struktur tertentu:

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Agent Platform menggunakan library klien.

Untuk melakukan autentikasi ke Agent Platform, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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)

Ganti MODEL dengan nama model yang ingin Anda gunakan, misalnya xai/grok-4.1-fast-reasoning.

Contoh output

{
  "rivers": [
    "Amazon River",
    "Paraná River",
    "Orinoco River",
    "São Francisco River",
    "Magdalena River"
  ]
}

REST

Sebelum menggunakan data permintaan apa pun, lakukan penggantian sebagai berikut:

PROJECT_ID: ID project Google Cloud Anda.
LOCATION: Region yang mendukung model Grok.
MODEL: Nama model yang ingin Anda gunakan, misalnya xai/grok-4.1-fast-reasoning.

Metode HTTP dan URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

Meminta isi 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."
    }
  ]
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$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

Anda akan melihat respons JSON yang mirip seperti berikut:

Respons

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "{\n  \"rivers\": [\n    \"Amazon River\",\n    \"Paraná River\",\n    \"Orinoco River\",\n    \"São Francisco River\",\n    \"Magdalena River\"\n  ]\n}",
        "role": "assistant"
      }
    }
  ],
  "created": 1721860000,
  "id": "123456789",
  "model": "xai/grok-4.1-fast-reasoning",
  "object": "chat.completion",
  "system_fingerprint": "12345",
  "usage": {
    "completion_tokens": 54,
    "prompt_tokens": 46,
    "total_tokens": 100
  }
}

Langkah berikutnya

Pelajari Panggilan fungsi.
Pelajari tentang Penalaran.

Output terstruktur untuk model Grok Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Menggunakan output terstruktur dengan Responses API

Python

REST

curl

PowerShell

Contoh

Python

REST

Contoh Respons

Menggunakan output terstruktur dengan Chat Completions API

Contoh mendetail

Mendapatkan respons objek JSON

Python

Contoh output

REST

curl

PowerShell

Respons

Langkah berikutnya

Output terstruktur untuk model Grok