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

Manual response_format

Lección 5 de 12 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Más control con response_format
  2. Flujo de trabajo
  3. Ejemplo completo
  4. Diferencias con parse()
  5. Análisis sin Pydantic
  6. Cuándo elegir response_format
  7. Gestión de errores
  8. Puntos clave

Más control con response_format

El método manual mediante response_format te ofrece un control total sobre el análisis (parsing). A diferencia de parse(), que devuelve un objeto tipado, este enfoque devuelve una cadena JSON que debes analizar tú mismo; el modelo de Pydantic solo proporciona el esquema (model_json_schema()) y valida posteriormente. Elige este método cuando necesites flexibilidad o cuando trabajes en un entorno sin Pydantic.

Flujo de trabajo

Con response_format, el proceso se desarrolla en dos pasos:

  1. La API devuelve el JSON como una cadena en response.choices[0].message.content
  2. Analizas esta cadena usando el método que prefieras

Ejemplo completo

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

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Review the movie Inception"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "movie_review",
            "schema": MovieReview.model_json_schema()
        }
    }
)

# El contenido es una cadena JSON
json_string = response.choices[0].message.content
print(type(json_string))  # <class 'str'>
print(json_string)
# {"title": "Inception", "rating": 9.2, "summary": "...", "recommend": true}

# Análisis manual con Pydantic
parsed = MovieReview.model_validate_json(json_string)
print(parsed.title)  # "Inception"

Diferencias con parse()

Aspectoparse()response_format
Retorno(Response, ParsedModel)Solo Response
AnálisisAutomáticoManual
Acceso a datosparsed.fieldjson.loads() o model_validate_json()
FlexibilidadEstándarMáxima
Gestión de erroresIntegradaTu responsabilidad

Análisis sin Pydantic

No es obligatorio usar Pydantic para analizar el resultado. El módulo estándar json también funciona:

import json

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Analyze this text and extract entities"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "entities",
            "schema": {
                "type": "object",
                "properties": {
                    "people": {
                        "type": "array",
                        "items": { "type": "string" }
                    },
                    "places": {
                        "type": "array",
                        "items": { "type": "string" }
                    }
                }
            }
        }
    }
)

data = json.loads(response.choices[0].message.content)
print(data["people"])  # ["Marie Curie", "Pierre Curie"]
print(data["places"])      # ["Paris", "Warsaw"]

Cuándo elegir response_format

response_format resulta ideal cuando necesitas ver o inspeccionar el JSON antes de que se convierta en un objeto. El caso más común es el registro (logging): en producción, conservar el JSON en bruto antes de la transformación suele ser un requisito de auditoría o depuración, y parse() no ofrece ese punto de intercepción. A continuación está la cuestión del esquema: si el contrato de tu interfaz es un esquema JSON en bruto —compartido con otros equipos, generado por una herramienta o versionado independientemente del código Python—, aplicarlo directamente es más fiel que reconstruirlo como un modelo de Pydantic. Por último, no todos los proyectos operan dentro del ecosistema de Pydantic: si tu validación pasa por otro framework o por un paso de procesamiento intermedio específico de tu canalización (pipeline), response_format te entrega el JSON tal cual y te deja el control de lo que viene después.

Gestión de errores

Con el método manual, debes gestionar tú mismo los errores de análisis:

import json

try:
    data = json.loads(response.choices[0].message.content)
except json.JSONDecodeError as e:
    print(f"Parsing error: {e}")

En la práctica, este error nunca debería ocurrir, ya que la API garantiza un JSON válido. No obstante, la gestión defensiva sigue siendo una buena práctica en producción.

Puntos clave

  • response_format devuelve una cadena JSON en response.choices[0].message.content
  • El análisis es tu responsabilidad: json.loads(), model_validate_json() u otro método
  • Puedes usar un esquema JSON en bruto en lugar de un modelo de Pydantic
  • Ofrece más flexibilidad que parse(), pero requiere escribir más código
  • El JSON devuelto está garantizado como válido; los errores de análisis no deberían ocurrir