Los resultados estructurados permiten que un modelo genere resultados que siempre cumplan con un esquema específico. Por ejemplo, se puede proporcionar un modelo con un esquema de respuesta para garantizar que la respuesta genere un JSON válido. Los modelos de Grok disponibles en el modelo como servicio (MaaS) de Gemini Enterprise Agent Platform admiten resultados estructurados.
Para obtener más información conceptual sobre la capacidad de salida estructurada, consulta Introducción a la salida estructurada.
Usa salidas estructuradas con la API de Responses
El valor predeterminado de store es false, por lo que las solicitudes no tienen estado, a menos que configures store como true (o True en Python). Para almacenar respuestas, consulta
Realiza una llamada con estado a
la API de Responses.
En las siguientes plantillas, se muestra cómo usar salidas estructuradas con la API de Responses:
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de Agent Platform sobre cómo usar bibliotecas cliente.
Para autenticarte en Agent Platform, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Antes de ejecutar esta muestra, asegúrate de configurar la variable de entorno OPENAI_BASE_URL o las credenciales de OAuth.
Para obtener más información, consulta Autenticación y credenciales.
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: Es el nombre del modelo que deseas usar, por ejemplo,
xai/grok-4.20-reasoning. - INPUT: Es la instrucción o entrada para el modelo.
- SCHEMA_NAME: Es un nombre para el esquema de respuesta.
- JSON_SCHEMA: Es un diccionario que define el esquema JSON, por ejemplo:
{"type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "integer"}}, "required": ["name", "age"], "additionalProperties": False}
REST
Antes de usar cualquiera de los datos de solicitud a continuación, haz los siguientes reemplazos:
- PROJECT_ID: Es el ID del proyecto de Google Cloud .
- MODEL: Es el nombre del modelo que deseas usar, por ejemplo,
xai/grok-4.20-reasoning. - INPUT: Es la instrucción o entrada para el modelo.
- SCHEMA_NAME: Es un nombre para el esquema de respuesta.
- JSON_SCHEMA: Es un objeto de esquema JSON que define la estructura del resultado.
Método HTTP y URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses
Cuerpo JSON de la solicitud:
{
"model": "MODEL",
"input": "INPUT",
"text": {
"format": {
"type": "json_schema",
"name": "SCHEMA_NAME",
"strict": true,
"schema": JSON_SCHEMA
}
},
"stream": false
}
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:
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
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$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
Ejemplo
En los siguientes ejemplos, se muestra un ejemplo completo del uso de resultados estructurados con la API de Responses:
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de Agent Platform sobre cómo usar bibliotecas cliente.
Para autenticarte en Agent Platform, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Antes de ejecutar esta muestra, asegúrate de configurar la variable de entorno OPENAI_BASE_URL o las credenciales de OAuth.
Para obtener más información, consulta Autenticación y credenciales.
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: Es el ID del proyecto de Google Cloud .
Ejemplo de respuesta
A continuación, se muestra un ejemplo de cómo podría verse el resultado del modelo:
{
"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
}
Usa resultados estructurados con la API de Chat Completions
En el siguiente caso de uso, se establece un esquema de respuesta que garantiza que el resultado del modelo sea un objeto JSON con las siguientes propiedades: name, date y participants. El código de Python usa el SDK de OpenAI y los objetos de Pydantic para generar el esquema 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)
El resultado del modelo se ajustará al siguiente esquema JSON:
{ "name": STRING, "date": STRING, "participants": [STRING] }
Cuando se proporciona la instrucción "Alice y Bob irán a una feria de ciencias el viernes", el modelo podría producir la siguiente respuesta:
{
"name": "science fair",
"date": "Friday",
"participants": [
"Alice",
"Bob"
]
}
Ejemplo detallado
El siguiente código es un ejemplo de un esquema recursivo. La clase UI contiene
una lista de children, que también puede ser de la clase 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)
El resultado del modelo se adherirá al esquema del objeto de Pydantic especificado en el fragmento anterior. En este ejemplo, el modelo podría generar el siguiente formulario de IU:
Form
Input
Name
Email
Age
La respuesta podría ser similar a la siguiente:
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')
]
)
Obtén respuestas de objetos JSON
Puedes restringir el modelo para que solo genere objetos JSON sintácticamente válidos
configurando el campo response_format como { "type": "json_object" }. Esto suele
denominarse modo JSON. El modo JSON es útil cuando se genera JSON para usarlo
con llamadas a funciones o con otras tareas downstream que requieren una entrada JSON.
Cuando el modo JSON está habilitado, el modelo se restringe para generar solo cadenas que se analizan en objetos JSON válidos. Si bien este modo garantiza que el resultado sea un JSON sintácticamente correcto, no aplica ningún esquema específico. Para garantizar que el resultado del modelo genere un JSON que siga un esquema específico, debes incluir instrucciones en la instrucción, como se muestra en el siguiente ejemplo.
En los siguientes ejemplos, se muestra cómo habilitar el modo JSON y cómo indicarle al modelo que devuelva un objeto JSON con una estructura específica:
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de Agent Platform sobre cómo usar bibliotecas cliente.
Para autenticarte en Agent Platform, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Antes de ejecutar esta muestra, asegúrate de configurar la variable de entorno OPENAI_BASE_URL o las credenciales de OAuth.
Para obtener más información, consulta Autenticación y credenciales.
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)
Reemplaza MODEL por el nombre del modelo que deseas usar,
por ejemplo, xai/grok-4.6.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID es el ID del proyecto de Google Cloud.
- LOCATION: Es una región que admite modelos de Grok.
- MODEL: Es el nombre del modelo que deseas usar,
por ejemplo,
xai/grok-4.6.
Método HTTP y URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions
Cuerpo JSON de la solicitud:
{
"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."
}
]
}
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:
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
Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:
$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
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
¿Qué sigue?
- Obtén más información sobre la llamada a función.
- Obtén más información sobre el razonamiento.