Gli output strutturati consentono a un modello di generare output che aderiscono sempre a uno schema specifico. Ad esempio, a un modello può essere fornito uno schema di risposta per garantire che la risposta produca 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.
Utilizzare gli output strutturati con l'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 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' Google Cloud ID progetto.
- 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,
e 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 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.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: l' Google Cloud ID progetto.
Esempio di risposta
Di seguito è riportato un esempio di come potrebbe apparire l'output del modello:
{
"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
}
Utilizzare gli 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à: nome, data e partecipanti. 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] }
Quando viene fornito 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 UI:
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')
]
)
Ottenere risposte di oggetti JSON
Puoi vincolare il modello a restituire solo oggetti JSON sintatticamente validi impostando il campo response_format su { "type": "json_object" }. Questa modalità viene spesso chiamata modalità JSON. La modalità JSON è utile quando si genera JSON da utilizzare con la chiamata di funzione o altre attività downstream che richiedono input JSON.
Quando la modalità JSON è attivata, il modello è vincolato a generare solo stringhe che vengono analizzate in oggetti JSON validi. Sebbene questa modalità garantisca che l'output sia JSON sintatticamente corretto, non applica uno schema specifico. Per assicurarti che il modello restituisca JSON che segue uno schema specifico, devi includere le istruzioni nel prompt, come mostrato nell'esempio seguente.
I seguenti esempi 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 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.1-fast-reasoning.
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 i modelli Grok.
- MODEL: il nome del modello che vuoi utilizzare,
ad esempio
xai/grok-4.1-fast-reasoning.
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,
e 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
- Scopri di più sulla chiamata di funzione.
- Scopri di più sul ragionamento.