JSON Mode

Activación y uso de JSON mode legacy

El JSON mode legacy representa la primera aproximación de OpenAI para garantizar respuestas estructuradas en formato JSON válido. Aunque actualmente se considera una funcionalidad heredada en favor de las Structured Outputs más modernas, sigue siendo útil para casos simples donde necesitas asegurar que la respuesta del modelo sea JSON válido sin definir esquemas complejos.

Configuración básica del JSON mode

Para activar el JSON mode legacy, debes especificar el parámetro text con el formato json_object en tu solicitud. Esta configuración instruye al modelo para que genere exclusivamente respuestas en formato JSON válido:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4.1-mini",
    input=[
        {"role": "system", "content": "Eres un asistente que responde únicamente en formato JSON."},
        {"role": "user", "content": "Dame información sobre Python como lenguaje de programación"}
    ],
    text={"format": {"type": "json_object"}}
)

print(response.output_text)

El parámetro clave es text={"format": {"type": "json_object"}}, que activa el modo JSON y garantiza que la salida sea JSON sintácticamente correcto.

Estructura de prompts para JSON mode

Cuando utilizas JSON mode legacy, es fundamental incluir en tu prompt del sistema una instrucción explícita sobre el formato JSON esperado. El modelo necesita esta guía para estructurar adecuadamente su respuesta:

response = client.responses.create(
    model="gpt-4.1-mini",
    input=[
        {
            "role": "system", 
            "content": "Responde siempre en formato JSON con las claves: 'nombre', 'descripcion', 'ventajas' y 'casos_uso'."
        },
        {
            "role": "user", 
            "content": "Explícame qué es FastAPI"
        }
    ],
    text={"format": {"type": "json_object"}}
)

print(response.output_text)

Esta configuración producirá una respuesta estructurada similar a:

{
    "nombre": "FastAPI",
    "descripcion": "Framework web moderno y rápido para construir APIs con Python",
    "ventajas": ["Alto rendimiento", "Documentación automática", "Validación de tipos"],
    "casos_uso": ["APIs REST", "Microservicios", "Aplicaciones web backend"]
}

Limitaciones y consideraciones importantes

El JSON mode legacy presenta varias limitaciones significativas que debes considerar:

Disponibilidad limitada: Esta funcionalidad solo está disponible en modelos anteriores a la serie gpt-4o, lo que limita su uso con las versiones más recientes y eficientes de los modelos de OpenAI.

Falta de validación de esquema: Aunque garantiza JSON sintácticamente válido, no valida que la estructura coincida con un esquema específico. El modelo puede generar claves diferentes a las esperadas o estructuras inconsistentes.

# El modelo podría generar esto cuando esperabas otra estructura:
response_example = {
    "informacion": "FastAPI es un framework...",  # Clave diferente a 'descripcion'
    "caracteristicas": [...],  # En lugar de 'ventajas'
}

Control limitado sobre tipos de datos: No puedes especificar tipos de datos precisos para cada campo, lo que puede resultar en inconsistencias entre diferentes respuestas.

Casos de uso apropiados

El JSON mode legacy resulta más adecuado para escenarios específicos:

• Prototipado rápido donde necesitas JSON válido sin esquemas complejos
• Migración gradual desde respuestas de texto libre hacia estructuras más definidas
• Compatibilidad con sistemas que requieren modelos anteriores a gpt-4o
• Casos simples donde la flexibilidad en la estructura es aceptable

Transición hacia alternativas modernas

Aunque el JSON mode legacy cumple su función básica, las Structured Outputs modernas ofrecen ventajas significativas como validación de esquemas, consistencia garantizada y soporte para modelos más recientes. Para proyectos nuevos, considera evaluar estas alternativas más robustas que se abordarán en las siguientes lecciones del módulo.

El JSON mode legacy mantiene su utilidad como punto de entrada hacia las salidas estructuradas, especialmente cuando trabajas con restricciones de compatibilidad o necesitas una solución rápida sin la complejidad de definir esquemas detallados.