El problema
Los LLM son excelentes generando texto, pero las aplicaciones suelen necesitar datos estructurados — objetos JSON, arrays, valores tipados. Obtener una salida estructurada fiable requiere técnicas específicas.
Enfoque 1: Ingeniería de Prompts
Pide al modelo que responda en formato JSON:
- Especificar el esquema exacto en el prompt.
- Incluir un par de entrada/salida de ejemplo.
- Añadir "Responder solo con JSON válido. Sin explicación."
Enfoque 2: Llamada a función / Uso de herramientas
La mayoría de las APIs principales ahora admiten la llamada de funciones:
- Definir un esquema JSON para la salida esperada.
- El modelo está limitado a que la salida coincida con el esquema.
- Funciona con OpenAI, Anthropic, Google y la mayoría de los proveedores.
Enfoque 3: Decodificación con Restricciones
Librerías como Outlines y LMQL obligan al modelo a producir una salida válida:
- Definir un modelo Pydantic o un esquema JSON.
- El proceso de decodificación aplica el esquema token por token.
- Garantía del 100% de una estructura de salida válida.
Enfoque 4: La biblioteca Instructor
La biblioteca Instructor envuelve cualquier API LLM con validación Pydantic:
- Define tu modelo de datos con Pydantic.
- Instructor gestiona automáticamente los intentos y validaciones.
- Trabaja con OpenAI, Anthropic, Gemini y modelos locales.
Mejores prácticas
- Validar siempre la salida frente a un esquema.
- Utilizar tipos de enum para campos con opciones limitadas.
- Incluir lógica de reintento para respuestas mal formadas.
- Mantener los esquemas simples: las estructuras anidadas aumentan las tasas de error.
- Prueba con 50+ ejemplos para medir la fiabilidad.
Patrones prácticos
La forma más fiable de obtener salida estructurada es combinar una definición clara del esquema en el prompt del sistema con ejemplos few-shot. Muestra al modelo 2–3 pares de entrada/salida en el formato exacto que quieres. Para los modelos de OpenAI, usa el parámetro response_format con JSON schema. Para Claude, usa la API tool_use para forzar respuestas estructuradas.
Errores comunes
- Complejidad del esquema: mantén los esquemas planos y simples. Los objetos muy anidados aumentan las tasas de error. Si necesitas datos anidados, constrúyelos por etapas.
- Validación: valida siempre la salida frente a tu esquema antes de usarla. Los LLM a veces producen JSON inválido o pierden campos obligatorios.
- Manejo de enums: al usar enums, incluye todos los valores válidos en el prompt. A veces los modelos inventan valores que no están en tu esquema.
- Escapado: el JSON dentro de cadenas JSON es una fuente habitual de errores. Usa un escapado correcto o cambia a un formato como YAML para la capa externa.
Restringe el decodificador cuando puedas
Todos los proveedores ofrecen ya alguna forma de decodificación restringida por gramática o por esquema y, cuando está disponible, es estrictamente mejor que pedir JSON por favor. La diferencia no es la exactitud del formato; es la eliminación del bucle de reparación. Un modelo estructuralmente incapaz de emitir una llave sin cerrar te ahorra el reintento, el manejador de truncamiento y la rama de excepción del analizador que de otro modo tendrías que probar.
Donde la restricción no existe, pide el objeto más pequeño posible y valídalo antes de usarlo. El modo de fallo del JSON sin restricciones no es la sintaxis inválida, sino JSON válido con tipos equivocados, un campo extra inesperado o un nulo donde exigías una cadena.
Diseña esquemas para el modelo, no para tu base de datos
Un esquema con catorce campos obligatorios y una unión anidada producirá más errores que uno con cuatro campos planos, aunque la versión de base de datos sea la que realmente quieres almacenar. El camino intermedio práctico es hacer que el modelo emita una forma intermedia pequeña y dejar que tu código la mapee al esquema de almacenamiento. Ese mapeo son unas líneas de código normal, se puede probar sin un modelo, y le quita al modelo la capacidad de violar tus invariantes.
Los campos opcionales merecen cuidado especial. Un campo marcado opcional le enseña al modelo que omitirlo es aceptable, y lo omitirá precisamente cuando el valor sea difícil de determinar, que es el caso del que más necesitabas evidencia. Prefiere un valor centinela explícito a la ausencia cuando necesites distinguir desconocido de no aplicable.
Valida y repara una sola vez
Cuando la validación falla, reintenta con el error concreto añadido en lugar de solo la salida en bruto. Incluye la ruta exacta que falló. Un reintento dirigido resuelve la mayoría de los fallos; un reintento a ciegas suele reproducir el mismo error. Tras el segundo fallo, haz fallar la petición en lugar de iterar, y registra ambos intentos, porque el par es la evidencia más útil que obtendrás sobre tu prompt.