Salida estructurada para los modelos de Grok

Los resultados estructurados permiten que un modelo genere resultados que siempre cumplan con un esquema específico. Por ejemplo, se puede proporcionar un esquema de respuesta a un modelo para garantizar que la respuesta genere un JSON válido. Los modelos de Grok disponibles en Model as a Service (MaaS) de Gemini Enterprise Agent Platform admiten resultados estructurados.

Para obtener más información conceptual sobre la capacidad de resultados estructurados, consulta Introducción a los resultados estructurados.

Usa resultados estructurados con la API de Responses

En las siguientes plantillas, se muestra cómo usar resultados estructurados con la API de Responses:

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración de Python que encontrarás en la guía de inicio rápido de Agent Platform sobre cómo usar las 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 muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

Antes de ejecutar esta muestra, asegúrate de configurar la variable de entorno OPENAI_BASE_URL o configurar 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 el prompt o la 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 Cloud de Confiance by S3NS proyecto de.
  • MODEL: Es el nombre del modelo que deseas usar, por ejemplo xai/grok-4.20-reasoning.
  • INPUT: Es el prompt o la 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 de Python que encontrarás en la guía de inicio rápido de Agent Platform sobre cómo usar las 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 muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

Antes de ejecutar esta muestra, asegúrate de configurar la variable de entorno OPENAI_BASE_URL o configurar 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.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: Es el ID del Cloud de Confiance by S3NS proyecto de.

Ejemplo de respuesta

A continuación, se muestra un ejemplo de cómo podría verse el resultado del modelo:

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

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: nombre, fecha y participantes. 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 cumplirá con el siguiente esquema JSON:

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

Cuando se proporciona el prompt "Alice and Bob are going to a science fair on Friday", 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 cumplirá con el 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

Una respuesta podría verse de la siguiente manera:

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 genere solo objetos JSON válidos desde el punto de vista sintáctico configurando el campo response_format en { "type": "json_object" }. A menudo, esto se denomina modo JSON. El modo JSON es útil cuando se genera JSON para usarlo con la llamada a funciones o con otras tareas posteriores que requieren entrada JSON.

Cuando se habilita el modo JSON, el modelo se limita a 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 modelo genere JSON que siga un esquema específico, debes incluir instrucciones en el prompt, como se muestra en el siguiente ejemplo.

En los siguientes ejemplos, se muestra cómo habilitar el modo JSON y se le indica al modelo que muestre un objeto JSON con una estructura específica:

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración de Python que encontrarás en la guía de inicio rápido de Agent Platform sobre cómo usar las 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 muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

Antes de ejecutar esta muestra, asegúrate de configurar la variable de entorno OPENAI_BASE_URL o configurar 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.1-fast-reasoning.

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.1-fast-reasoning.

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?