Outputs Estructurados y JSON Mode

El mayor problema al integrar IA en aplicaciones es la imprevisibilidad del formato de respuesta. Si le pides al modelo "responde con JSON", a veces incluye texto antes del JSON, o usa nombres de campos diferentes, o agrega comentarios que rompen el JSON.parse(). Esto hace que el código sea frágil.

OpenAI resolvió esto con JSON Mode (garantiza JSON válido sintácticamente) y Structured Outputs (garantiza que el JSON siga exactamente el schema que defines).

Structured Outputs funciona con Zod (TypeScript) o JSON Schema: defines el shape exacto de lo que quieres con tipos, campos obligatorios y opcionales, y enums; el modelo usa esa definición como guía estricta y es matemáticamente imposible que devuelva algo que no cumpla el schema.

Esto transforma la IA de una caja negra impredecible a un servicio confiable que puedes usar en producción. El caso de uso clásico es extracción de datos: convertir texto no estructurado (un email, un contrato) en objetos JavaScript tipados.

// JSON Mode - garantiza JSON válido
const resp = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    {
      role: "system",
      content: "Extrae datos del texto. Responde SOLO con JSON.
      Formato: {nombre, email, telefono, empresa}"
    },
    { role: "user", content: textoDelUsuario }
  ],
  response_format: { type: "json_object" }, // Garantiza JSON válido
});

const datos = JSON.parse(resp.choices[0].message.content);

// Structured Outputs con Zod (TypeScript)
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

// Definir schema con Zod
const EventoSchema = z.object({
  nombre: z.string(),
  fecha: z.string(),
  lugar: z.string(),
  asistentes: z.array(z.string()),
  virtual: z.boolean(),
});

const respEstructurada = await openai.beta.chat.completions.parse({
  model: "gpt-4o-mini",
  messages: [{
    role: "user",
    content: "Extrae los datos: React Summit el 15/06 en Amsterdam, online y presencial"
  }],
  response_format: zodResponseFormat(EventoSchema, "evento"),
});

const evento = respEstructurada.choices[0].message.parsed;
console.log(evento.nombre);     // React Summit
console.log(evento.fecha);      // 15/06
console.log(evento.virtual);    // true

// Extracción de múltiples items
const ListaTareasSchema = z.object({
  tareas: z.array(z.object({
    titulo: z.string(),
    prioridad: z.enum(["alta", "media", "baja"]),
    asignado: z.string().optional(),
  }))
});