Problemas que resuelve cada herramienta
📍 In One Sentence
Las herramientas de salida estructurada resuelven tres problemas distintos — imponer un esquema en el momento de la generación, validar el resultado después y reparar salidas malformadas — y la mayoría de los sistemas solo necesita los dos primeros.
💬 In Plain Terms
No elijas por lista de funciones. Pregúntate qué fallo tienes de verdad: el modelo ignora tu formato, o lo respeta pero los valores están mal, o devuelve un JSON que ni siquiera se puede parsear. Cada caso pide una solución distinta.
El structured output requiere resolver tres problemas interdependientes: definición de esquema, cumplimiento en la API y validación. Las distintas herramientas atacan estos problemas de formas diferentes. Instructor gestiona los tres en Python con reintentos. Outlines elimina el paso de validación vía constrained decoding. Pydantic AI añade type safety para agentes. BAML traslada el esquema a un archivo compilado y repara salidas imperfectas. LangChain envuelve las APIs de proveedor. Marvin prioriza la velocidad del desarrollador. PromptQuorum valida la consistencia entre todos los modelos.
Problema | Instructor | Outlines | Pydantic AI | BAML | LangChain | Marvin |
|---|---|---|---|---|---|---|
| Definir esquema | Modelos Pydantic | JSON Schema / GBNF | Modelos Pydantic | Archivos de clase .baml | Definiciones de herramienta | Hints de tipo Python |
| Forzar en llamada API | Reintento + validación | Restricción a nivel token | Nativo / herramienta / prompt | Prompt generado + parser | Modo JSON del proveedor | Tipos de salida de Pydantic AI |
| Validar respuesta | Automático | Garantizado en la generación | Verificado por tipo | Schema-aligned parsing | Manual | Automático |
Instructor: extracción Pydantic
Instructor es la biblioteca de structured output más adoptada. Envuelve cualquier API LLM — OpenAI GPT-5.6, Claude Opus 5, Gemini 3.1 Pro, Ollama, vLLM — y devuelve modelos Pydantic validados en lugar de texto sin formato. Instructor gestiona reintentos automáticamente cuando falla la validación, haciéndolo apto para producción sin manejo de errores adicional.
- Funciona con todos los proveedores principales (OpenAI, Anthropic, Google, Groq, Mistral) y modelos locales vía Ollama o vLLM
- Esquemas Pydantic v2: hints de tipo, reglas de validación, descripciones de docstring integradas en el esquema
- Reintento automático con backoff en fallo de validación — no se necesita manejo de errores manual
- Seis implementaciones oficiales: Python, TypeScript, Ruby, Go, Elixir y Rust
- Open source con licencia MIT, mantenido activamente, actualmente en la línea 1.x
- Precios: Gratis (sin coste adicional más allá de las llamadas a la API LLM)
import instructor
from pydantic import BaseModel
from openai import OpenAI
class User(BaseModel):
name: str
age: int
client = instructor.from_openai(OpenAI())
user = client.chat.completions.create(
model="gpt-5.6",
response_model=User,
messages=[{"role": "user", "content": "Extract: John is 25 years old"}]
)
# user.name == "John", user.age == 25Outlines: constrained decoding
Outlines fuerza el cumplimiento del esquema al momento de la generación de tokens vía constrained decoding. En lugar de generar tokens y luego validar, Outlines limita los tokens válidos en cada paso para coincidir con tu esquema. Esto garantiza que la salida se parsea contra tu esquema sin riesgo de alucinación estructural, y es lo que lo convierte en la opción por defecto para modelos locales.
- Backends locales: transformers, llama.cpp, MLX y cualquier modelo de Hugging Face
- Backends de servidor: vLLM, Ollama y NVIDIA NIM
- También soporta APIs alojadas (OpenAI, Gemini), así que el mismo código se mueve entre local y nube
- Esquemas como modelos Pydantic, JSON Schema, patrones regex, opciones literales o gramáticas libres de contexto
- Cumplimiento estructural garantizado — no se necesita validación post-generación ni reintentos
- Open source Apache 2.0, actualmente en la línea 1.x, con un núcleo en Rust (outlines-core) para velocidad
Pydantic AI: agentes type-safe
Pydantic AI es el framework de agentes del equipo detrás de Pydantic. Combina modelos Pydantic con soporte de primera clase para conversaciones de agentes multi-turn, añadiendo type safety completo a los bucles de agentes mientras fuerza structured output en cada turno. Ya va por la línea 2.x y se usa en producción, no es un experimento.
- Sistema de tipos Pydantic v2 — soporte completo de IDE y verificación estática de lo que devuelve un agente
- Tres modos de salida: structured output nativo del proveedor, llamadas a herramientas y JSON por prompt como fallback
- Diseño async-first para aplicaciones de alto rendimiento
- Soporta OpenAI, Anthropic, Google, Bedrock, Azure AI Foundry, Groq, Mistral, xAI y Ollama
- Integraciones de ejecución duradera (Temporal, DBOS, Prefect) para que los agentes de larga duración sobrevivan a reinicios
- Llamadas a herramientas integradas — define herramientas como funciones Python con hints de tipo
- Licencia MIT y gratuito (sin coste adicional más allá de las llamadas a la API LLM)
BAML: archivos de prompt schema-first
BAML adopta el enfoque opuesto a las bibliotecas Python: el esquema y el prompt viven en un archivo .baml versionado, y un compilador genera un cliente tipado para tu lenguaje. Su parser alineado al esquema repara los errores que los modelos cometen de verdad — bloques markdown alrededor del JSON, comas finales, claves sin comillas, texto de razonamiento antes del objeto — en lugar de lanzar un error y quemar un reintento.
- Esquema y prompt conviven en archivos .baml, versionados y revisados como cualquier otro código fuente
- Genera clientes tipados nativamente para Python y TypeScript, más Go, Java, Ruby, PHP, Rust y C# vía clientes OpenAPI generados
- El schema-aligned parsing (SAP) recupera objetos válidos de salidas imperfectas en lugar de fallar
- Funciona con modelos que no tienen ningún tool-use ni modo JSON nativo
- Streaming con tipos — los objetos parciales llegan tipados, así puedes renderizar campos mientras se generan
- Open source Apache 2.0; el producto alojado de observabilidad Boundary Studio es una oferta de pago aparte
LangChain: APIs unificadas
LangChain expone with_structured_output() en todos los modelos de chat principales, unificando el structured output en OpenAI, Anthropic, Google y modelos locales detrás de un único método. Desde la reescritura 1.x lee la capacidad nativa de structured output de cada proveedor desde su perfil de modelo en lugar de codificarla, y los agentes creados con create_agent aceptan un response_format directamente.
- API unificada: un método .with_structured_output() funciona en todos los proveedores
- Convierte automáticamente las definiciones de herramientas de LangChain a formatos de esquema específicos del proveedor
- Los agentes creados con create_agent aceptan un response_format para su respuesta final
- El soporte nativo de structured output se lee por modelo desde los datos de perfil del proveedor en la línea 1.1+
- Soporta modelos Pydantic, TypedDict, dataclasses y JSON Schema en bruto
- Ideal para equipos ya invertidos en LangChain o LangGraph
Marvin: extracción basada en tareas
Marvin 3.x es el camino más corto de texto no estructurado a un objeto Python tipado. Está construido sobre Pydantic AI, así que obtienes la misma cobertura de proveedores y validación con mucho menos código. Ojo: la API basada en decoradores de Marvin 2 ya no existe — @marvin.fn se eliminó en la 3.0 en favor de helpers de nivel superior y un motor de agentes centrado en tareas.
- Helpers de una línea: marvin.extract, marvin.cast, marvin.classify y marvin.generate
- Construido sobre Pydantic AI, así que el soporte de proveedores y la validación se heredan, no se reimplementan
- Motor centrado en tareas para trabajo multi-paso: marvin.run, marvin.Task, marvin.Agent, marvin.Thread
- Los hints de tipo Python se convierten en el esquema — boilerplate mínimo para extracción y clasificación
- Nota de migración: el decorador @marvin.fn de Marvin 2 ya no existe; hay que reescribir esas llamadas
- Open source Apache 2.0, mantenido por Prefect, gratuito
PromptQuorum: testing multi-modelo
PromptQuorum no es una biblioteca de structured output en sí misma, sino una plataforma de testing para validar la consistencia del structured output entre modelos. Ejecuta el mismo prompt simultáneamente contra GPT-5.6, Claude Opus 5, Gemini 3.1 Pro y 20+ modelos más. Mide el cumplimiento del esquema, la latencia y el coste por modelo.
- Despacho multi-modelo en una sola llamada API — testea un prompt contra 25+ modelos
- Métricas de cumplimiento de structured output — tasa de paso, latencia, coste por modelo
- Identifica modelos que alucinan con tu esquema — evita desplegar en modelos poco fiables
- Modo consenso — encuentra acuerdos entre ejecuciones de modelos independientes
- Funciona con Instructor, Outlines, Pydantic AI, BAML, LangChain o APIs LLM en bruto
- Tier gratuito disponible, precios enterprise para testing de alto volumen
Comparativa lado a lado
Herramienta | Ideal para | Formato de esquema | Lenguaje | Modelos locales | Licencia | Curva de aprendizaje |
|---|---|---|---|---|---|---|
| Instructor | APIs Python + reintentos | Modelos Pydantic | Python, TS, Ruby, Go, Elixir, Rust | Sí (Ollama, vLLM) | MIT, gratis | Baja |
| Outlines | Despliegue de modelos locales | Pydantic, JSON Schema, regex, CFG | Python | Sí (nativo) | Apache 2.0, gratis | Media |
| Pydantic AI | Agentes type-safe | Modelos Pydantic | Python | Sí (Ollama) | MIT, gratis | Baja |
| BAML | Equipos políglotas, modelos poco fiables | Archivos de clase .baml | Python, TS + 6 vía OpenAPI | Sí (compatible con OpenAI) | Apache 2.0, observabilidad de pago | Media |
| LangChain | Chains + agentes | Definiciones de herramienta | Python, JS | Sí | MIT, gratis | Media |
| Marvin | Extract y classify rápidos | Hints de tipo | Python | Sí | Apache 2.0, gratis | Muy baja |
| PromptQuorum | Testing multi-modelo | API-agnóstico | API-first | Vía proxy OpenAI | Tier gratuito + enterprise | Baja |
Elegir la herramienta correcta
Empieza respondiendo tres preguntas: (1) ¿En qué lenguajes están escritos los servicios que llaman al modelo? (2) ¿Necesitas soporte de modelos locales? (3) ¿Cuánta complejidad de validación tienes?
- Usa Instructor si: construyes APIs Python y necesitas reintentos automáticos en fallo de validación. Mejor opción de uso general.
- Usa Outlines si: despliegas modelos locales (llama.cpp, vLLM, MLX) y quieres cumplimiento garantizado del esquema al momento de la generación.
- Usa Pydantic AI si: construyes flujos de agentes multi-turn con type safety en todos los pasos o necesitas ejecución duradera.
- Usa BAML si: servicios en Python, TypeScript y Go deben compartir un esquema, o tu modelo no tiene un modo JSON nativo fiable.
- Usa LangChain si: ya usas LangChain o LangGraph — with_structured_output() es la adición más sencilla.
- Usa Marvin si: quieres una sola llamada extract o classify y no necesitas lógica de validación propia.
- Usa PromptQuorum si: necesitas testear la consistencia del structured output en GPT, Claude y Gemini antes de producción.
Añadir structured output paso a paso
- 1Define tu esquema de salida — Crea un modelo Pydantic (Python), una clase .baml (BAML), una interfaz TypeScript o JSON Schema describiendo los campos, tipos y restricciones que quieres que devuelva el LLM.
- 2Elige una biblioteca — Instructor para APIs Python, Outlines para modelos locales, Pydantic AI para agentes, BAML para equipos políglotas, LangChain si ya está en uso, Marvin para extracción de una línea.
- 3Instala y envuelve tu llamada LLM — `pip install instructor` (Python), luego pasa tu esquema a la llamada API. Instructor gestiona validación y reintentos.
- 4Testea con PromptQuorum — Despliega en PromptQuorum y ejecuta tu prompt contra GPT, Claude y Gemini. Mide el cumplimiento del esquema por modelo.
- 5Refina el esquema según fallos — Si un modelo falla la validación, añade ejemplos a tu prompt o ajusta las restricciones del esquema. Itera hasta que todos los modelos pasen.
Errores comunes de structured output
❌ Tratar cualquier modo JSON como una garantía de esquema
Why it hurts: El modo JSON simple (response_format json_object, control JSON de Anthropic) solo garantiza que la respuesta es JSON válido, no que coincida con tus campos y tipos. Los modos de esquema estricto van más allá y garantizan la forma, pero ninguno garantiza que los valores sean correctos: un objeto bien formado puede contener igualmente un precio inventado o una fecha alucinada.
Fix: Añade validación encima en cualquier caso: Instructor, Outlines, Pydantic AI o BAML. Las reglas de negocio van en validadores Pydantic, no solo en el esquema. Testea con PromptQuorum para detectar fallos de cumplimiento por modelo.
❌ Diseñar esquemas demasiado estrictos
Why it hurts: Los esquemas demasiado restringidos (listas de enum pequeñas, patrones regex muy específicos) hacen que los LLMs fallen la validación frecuentemente. Los altos conteos de reintentos desperdician tokens y dinero.
Fix: Usa PromptQuorum para testear la rigurosidad del esquema entre modelos. Relaja las restricciones para lograr un 95%+ de cumplimiento. Usa campos opcionales en lugar de requeridos cuando sea posible.
❌ No testear diferencias entre modelos locales y de API
Why it hurts: Outlines en llama.cpp se comporta de forma diferente que Instructor en GPT-5.6. Las tasas de cumplimiento del esquema difieren por modelo. Construir solo para un modelo frontera de API y luego desplegar en uno local pequeño causa fallos en producción.
Fix: Testea todos los backends de modelos previstos pronto. Usa PromptQuorum para ejecutar el mismo prompt en modelos locales (vLLM, Ollama) y alojados (OpenAI, Anthropic, Google).
❌ Ignorar el impacto en latencia y coste de tokens
Why it hurts: El structured output con reintentos cuesta más tokens. Instructor reintenta en caso de fallo. El constrained decoding de Outlines añade sobrecarga por token frente a la generación libre. No medir el coste por modelo.
Fix: Usa el tracking de costes de PromptQuorum. Compara latencia entre modelos. Para flujos sensibles al presupuesto, prefiere Outlines o BAML (sin bucle de reintentos). Para precisión en esquemas flexibles, acepta el coste de reintentos de Instructor.
❌ Mezclar métodos de validación (sin consistencia)
Why it hurts: Algunas peticiones usan Instructor, otras parsing JSON en bruto. Algunos modelos validados, otros no. Esto lleva a errores inconsistentes en producción.
Fix: Estandariza en un enfoque de validación por base de código. Todas las peticiones usan Instructor, o todas usan Outlines. La consistencia reduce el tiempo de depuración por 10x.
❌ Copiar tutoriales escritos contra una API ya reemplazada
Why it hurts: Las bibliotecas de structured output se mueven rápido. Marvin eliminó el decorador @marvin.fn en la 3.0, LangChain reorganizó su documentación en la reescritura 1.x y Outlines cambió su superficie de imports en la 1.0. El código copiado de un tutorial antiguo falla ya en la instalación.
Fix: Fija la versión mayor contra la que desarrollas y consulta la documentación actual para la superficie de la API. Prefiere el README oficial del repositorio a los posts de blog, y revisa de nuevo al subir de versión mayor.
¿Qué es el structured output en LLMs?
El structured output restringe las respuestas de LLM a un esquema específico — formato JSON, campos definidos, restricciones de tipo. En lugar de respuestas en texto libre, el structured output devuelve datos que tu código puede parsear y validar directamente sin manejo de errores.
¿Qué herramienta es mejor para desarrolladores Python?
Instructor es la opción Python más popular. Usa modelos Pydantic para definir esquemas, gestiona automáticamente reintentos y validación, y soporta todas las APIs LLM principales además de modelos locales vía Ollama o vLLM. Pydantic AI encaja mejor si además quieres conversaciones multi-turn type-safe con agentes, y Marvin es la opción más rápida si solo necesitas una llamada extract o classify de una línea.
¿Puedo usar structured output con modelos locales como Llama?
Sí. Outlines se especializa en constrained decoding para modelos locales — funciona con transformers, llama.cpp, MLX, vLLM y Ollama, y garantiza en el momento de la generación que la salida se parsea contra tu esquema. Instructor y Pydantic AI también soportan Ollama y vLLM si los ejecutas como API, y BAML funciona contra cualquier endpoint compatible con OpenAI.
¿Cuál es la diferencia entre Instructor y Marvin?
Instructor envuelve tu propio cliente LLM y devuelve modelos Pydantic validados con reintentos automáticos, así que tú controlas la llamada. Marvin 3.x está construido sobre Pydantic AI y en su lugar te da helpers de una línea: marvin.extract, marvin.cast, marvin.classify. Instructor es más explícito y mejor para validación compleja; Marvin es más conciso para extracción sencilla. Ten en cuenta que el decorador @marvin.fn de Marvin 2 se eliminó en Marvin 3.
¿LangChain soporta structured output?
Sí. LangChain expone with_structured_output() en ChatOpenAI, ChatAnthropic, ChatGoogleGenerativeAI y las demás clases de modelos de chat, y los agentes construidos con create_agent aceptan un response_format. Desde la línea 1.x lee el soporte nativo de structured output de cada proveedor desde los datos de perfil del modelo en lugar de codificarlo. Úsalo si ya usas LangChain o LangGraph y quieres añadir cumplimiento del esquema sin cambiar de biblioteca.
¿Cómo testo si el structured output es fiable?
Usa PromptQuorum para ejecutar el mismo prompt en múltiples modelos y medir el cumplimiento del esquema. Diferentes modelos — GPT-5.6, Claude Opus 5, Gemini 3.1 Pro — tienen distintos niveles de fiabilidad, y los modelos locales pequeños difieren aún más. Testea antes de desplegar en producción y valida localmente con Instructor o Pydantic.
¿Qué significa "constrained decoding"?
El constrained decoding limita la generación de tokens a solo valores válidos según tu esquema. Outlines lo hace calculando el conjunto de tokens válidos siguientes en cada paso. Esto garantiza que la salida se parsea contra tu esquema sin validación post-generación ni reintentos, lo que lo hace más fiable que el modo JSON simple a nivel de API. Restringe la estructura, no la verdad: los campos serán correctos, los valores siguen necesitando comprobación.
¿Qué es BAML y cuándo debería usarlo en lugar de Instructor?
BAML es un lenguaje schema-first: escribes el esquema y el prompt en un archivo .baml y compilas un cliente tipado para tu lenguaje. Elígelo sobre Instructor cuando más de un lenguaje llame al mismo prompt — un worker en Python y un frontend en TypeScript compartiendo un contrato — o cuando tu modelo devuelva JSON casi válido, porque el parser alineado al esquema de BAML repara bloques markdown, comas finales y texto de razonamiento inicial en lugar de quemar un reintento. Quédate con Instructor si tu stack es solo Python y quieres mantener los esquemas como código Pydantic normal.
¿Puedo usar structured output sin ninguna biblioteca?
Técnicamente sí — puedes hacer que el modelo devuelva JSON y luego parsearlo tú mismo. Pero el parseo fallará con las salidas mal formadas que los modelos siguen produciendo, y nada fuerza tus nombres de campo ni tipos. Las siete herramientas resuelven esto validando con reintentos (Instructor, Marvin), forzando en el tiempo de decodificación (Outlines), reparando la salida al parsear (BAML) o envolviendo APIs de proveedor (LangChain, Pydantic AI).
¿Qué herramienta tiene la mejor documentación?
LangChain y Pydantic AI tienen la documentación más completa debido a su respaldo corporativo. La documentación de BAML es inusualmente buena para un proyecto joven porque el lenguaje necesita enseñarse. Instructor tiene excelentes tutoriales y ejemplos a pesar de ser mantenido por la comunidad. La documentación de Outlines es técnica pero exhaustiva. La de Marvin es concisa — consulta específicamente las páginas 3.x, ya que material antiguo de Marvin 2 sigue circulando.
¿Necesito las siete herramientas o solo una?
Empieza con una. Los desarrolladores Python deberían probar Instructor o Pydantic AI. Los equipos con modelos locales deberían probar Outlines. Los equipos políglotas deberían probar BAML. Los usuarios de LangChain deberían probar with_structured_output(). Usa PromptQuorum para validar la consistencia entre todos los modelos. La mayoría de equipos usa una herramienta más PromptQuorum para testing.
Fuentes
- Repositorio GitHub de Instructor — Repositorio oficial y docs para la biblioteca Instructor
- Repositorio GitHub de Outlines — Constrained decoding para cumplimiento garantizado del esquema
- Documentación de Pydantic AI — Framework de agentes type-safe con structured output
- Guía de structured output de LangChain — API unificada de structured output de LangChain
- Documentación de BAML — Lenguaje de prompts schema-first y schema-aligned parsing
- Repositorio GitHub de Marvin — Biblioteca de extracción centrada en tareas construida sobre Pydantic AI