Ir al contenido principal
Español— Elegir un idioma
Menú

Método parse() automático

Lección 4 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. La vía rápida: parse()
  2. Ejemplo completo
  3. Qué devuelve parse()
  4. Modelos anidados
  5. Cuándo usar parse()
  6. Puntos clave

Actualizado el 3 de noviembre de 2026. Basado en la documentación de Structured Outputs de xAI y el SDK openai 3.42.1: al apuntar el SDK de OpenAI hacia xAI, el método es client.chat.completions.parse, que devuelve una finalización donde el objeto tipado se lee desde choices[0].message.parsed; client.chat.parse no existe (el SDK de xAI sí ofrece chat.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.

1

Define el modelo de Pydantic

Creas una clase de Python que describe la estructura esperada.

2

Llama a client.chat.completions.parse()

Pasas el modelo de Pydantic como `response_format`.

3

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:

  1. response: El objeto de respuesta completo de la API (con metadatos, tokens utilizados, etc.)
  2. 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