Método parse() automático
En esta página
Actualizado el 3 de noviembre de 2026. Basado en la documentación de Structured Outputs de xAI y el SDK
openai3.42.1: al apuntar el SDK de OpenAI hacia xAI, el método esclient.chat.completions.parse, que devuelve una finalización donde el objeto tipado se lee desdechoices[0].message.parsed;client.chat.parseno existe (el SDK de xAI sí ofrecechat.parse(Schema)en una conversación, que devuelve un par de objeto-respuesta). Fuente: Structured Outputs.
La vía rápida: parse()
El método parse() es la forma más sencilla de utilizar salidas estructuradas con la API de Grok. Acepta un modelo de Pydantic como entrada y devuelve directamente un objeto tipado: sin JSON que analizar, sin validación manual.
Define el modelo de Pydantic
Creas una clase de Python que describe la estructura esperada.
Llama a client.chat.completions.parse()
Pasas el modelo de Pydantic como `response_format`.
Recibe la tupla (Response, ParsedModel)
El objeto tipado está listo para usar en tu código.
Ejemplo completo
Así es como extraer una reseña de película estructurada:
from openai import OpenAI
from pydantic import BaseModel
client = OpenAI(
api_key="your-xai-key",
base_url="https://api.x.ai/v1"
)
class MovieReview(BaseModel):
title: str
rating: float
summary: str
recommend: bool
completion = client.chat.completions.parse(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": "Escribe una reseña de la película Inception"
}],
response_format=MovieReview
)
parsed = completion.choices[0].message.parsed
# parsed es un objeto MovieReview tipado
print(parsed.title) # "Inception"
print(parsed.rating) # 9.2
print(parsed.recommend) # True
print(type(parsed)) # <class 'MovieReview'>
Qué devuelve parse()
El método parse() devuelve una tupla de dos elementos:
response: El objeto de respuesta completo de la API (con metadatos, tokens utilizados, etc.)parsed: Tu modelo de Pydantic instanciado con los datos extraídos
Puedes acceder a ambos según necesites:
completion = client.chat.completions.parse(...)
parsed = completion.choices[0].message.parsed
# Acceder a metadatos
print(completion.usage.total_tokens)
print(completion.model)
# Acceder a datos estructurados
print(parsed.title)
print(parsed.rating)
Modelos anidados
parse() gestiona estructuras complejas sin esfuerzo. Puedes anidar modelos de Pydantic:
class Actor(BaseModel):
name: str
role: str
class Review(BaseModel):
title: str
director: str
year: int
rating: float
main_actors: list[Actor]
genres: list[str]
strengths: list[str]
weaknesses: list[str]
completion = client.chat.completions.parse(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": "Análisis completo de la película Interstellar"
}],
response_format=Review
)
parsed = completion.choices[0].message.parsed
for actor in parsed.main_actors:
print(f"{actor.name} interpreta a {actor.role}")
Cuándo usar parse()
parse() es el camino más corto entre una respuesta del modelo y un objeto de Python utilizable: si trabajas con Pydantic, esta es la opción por defecto. El método encapsula todo: envía el esquema, valida la respuesta e instancia el objeto, entregándote directamente una instancia tipada, sin necesidad de json.loads ni comprobaciones manuales. Es el código más conciso posible y, para la gran mayoría de los casos, esta simplicidad no tiene coste: solo renuncias al control de análisis fino si realmente lo necesitas, algo poco frecuente. La siguiente lección cubre precisamente esos casos en los que el control manual está justificado.
Puntos clave
parse()devuelve una tupla(Response, ParsedModel): análisis automático- El objeto devuelto es una instancia de Pydantic tipada y validada
- Los modelos anidados y las listas de objetos funcionan de forma nativa
- Este es el método recomendado para la mayoría de los casos de uso en Python
- No es necesario usar
json.loads()ni realizar validaciones manuales