Output strutturato per i modelli Grok

Gli output strutturati consentono a un modello di generare un output che rispetta sempre uno schema specifico. Ad esempio, a un modello può essere fornito uno schema di risposta per garantire che la risposta produca un JSON valido. I modelli Grok disponibili su Gemini Enterprise Agent Platform Model as a Service (MaaS) supportano gli output strutturati.

Per ulteriori informazioni concettuali sulla funzionalità di output strutturato, consulta Introduzione all'output strutturato.

Utilizza gli output strutturati con l'API Responses

Il valore predefinito per store è false, quindi le richieste sono stateless, a meno che non imposti store su true (o True in Python). Per archiviare le risposte, consulta Effettua una chiamata stateful all'API Responses.

I seguenti modelli mostrano come utilizzare gli output strutturati con l'API Responses:

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Prima di eseguire questo esempio, assicurati di impostare la variabile di ambiente OPENAI_BASE_URL o di configurare le credenziali OAuth. Per saperne di più, consulta Autenticazione e credenziali.

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: il nome del modello che vuoi utilizzare, ad esempio xai/grok-4.20-reasoning.
  • INPUT: il prompt o l'input per il modello.
  • SCHEMA_NAME: un nome per lo schema di risposta.
  • JSON_SCHEMA: un dizionario che definisce lo schema JSON, ad esempio:
    {"type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "integer"}}, "required": ["name", "age"], "additionalProperties": False}

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • MODEL: il nome del modello che vuoi utilizzare, ad esempio xai/grok-4.20-reasoning.
  • INPUT: il prompt o l'input per il modello.
  • SCHEMA_NAME: un nome per lo schema di risposta.
  • JSON_SCHEMA: un oggetto schema JSON che definisce la struttura dell'output.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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
 

Esempio

I seguenti esempi mostrano un esempio completo di utilizzo degli output strutturati con l'API Responses:

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Prima di eseguire questo esempio, assicurati di impostare la variabile di ambiente OPENAI_BASE_URL o di configurare le credenziali OAuth. Per saperne di più, consulta Autenticazione e credenziali.

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: l'ID progetto Google Cloud .

Esempio di risposta

Di seguito è riportato un esempio di come potrebbe essere l'output del modello:

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

Utilizza output strutturati con l'API Chat Completions

Il seguente caso d'uso imposta uno schema di risposta che garantisce che l'output del modello sia un oggetto JSON con le seguenti proprietà: name, date e participants. Il codice Python utilizza l'SDK OpenAI e gli oggetti Pydantic per generare lo schema 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)

L'output del modello rispetterà il seguente schema JSON:

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

Se riceve il prompt "Alice e Bob andranno a una fiera della scienza venerdì", il modello potrebbe produrre la seguente risposta:

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

Esempio dettagliato

Il seguente codice è un esempio di schema ricorsivo. La classe UI contiene un elenco di children, che possono anche essere della classe 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)

L'output del modello rispetterà lo schema dell'oggetto Pydantic specificato nello snippet precedente. In questo esempio, il modello potrebbe generare il seguente modulo dell'interfaccia utente:

Form
  Input
    Name
    Email
    Age

Una risposta potrebbe essere simile alla seguente:

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

Ricevi risposte di oggetti JSON

Puoi limitare il modello in modo che restituisca solo oggetti JSON sintatticamente validi impostando il campo response_format su { "type": "json_object" }. Questa modalità è spesso chiamata modalità JSON. La modalità JSON è utile quando si genera un file JSON da utilizzare con la chiamata di funzione o altre attività downstream che richiedono un input JSON.

Quando la modalità JSON è attiva, il modello è vincolato a generare solo stringhe che vengono analizzate in oggetti JSON validi. Sebbene questa modalità garantisca che l'output sia un JSON sintatticamente corretto, non applica alcuno schema specifico. Per assicurarti che l'output del modello generi un output JSON che segue uno schema specifico, devi includere istruzioni nel prompt, come mostrato nell'esempio seguente.

Gli esempi seguenti mostrano come attivare la modalità JSON e indicare al modello di restituire un oggetto JSON con una struttura specifica:

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Prima di eseguire questo esempio, assicurati di impostare la variabile di ambiente OPENAI_BASE_URL o di configurare le credenziali OAuth. Per saperne di più, consulta Autenticazione e credenziali.

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)

Sostituisci MODEL con il nome del modello che vuoi utilizzare, ad esempio xai/grok-4.6.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud.
  • LOCATION: una regione che supporta Modelli di Grok.
  • MODEL: il nome del modello che vuoi utilizzare, ad esempio xai/grok-4.6.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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

Dovresti ricevere una risposta JSON simile alla seguente.

Passaggi successivi