Manual response_format
En esta página
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:
- La API devuelve el JSON como una cadena en
response.choices[0].message.content - 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()
| Aspecto | parse() | response_format |
|---|---|---|
| Retorno | (Response, ParsedModel) | Solo Response |
| Análisis | Automático | Manual |
| Acceso a datos | parsed.field | json.loads() o model_validate_json() |
| Flexibilidad | Estándar | Máxima |
| Gestión de errores | Integrada | Tu 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_formatdevuelve una cadena JSON enresponse.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