Instructor es la biblioteca de Python más popular para arrancarle a un modelo de lenguaje datos estructurados y fiables, no un bloque de texto que luego toca interpretar a mano. Su idea es directa: declaras la respuesta que esperas como un modelo Pydantic, se lo pasas al cliente del modelo en response_model y Instructor se encarga de que la salida cumpla ese esquema, reintentando por su cuenta si el modelo se sale del formato. En esta guía verás qué problema resuelve, cómo se define el esquema, cómo funcionan la validación y los reintentos, su soporte multiproveedor y en qué se diferencia de la API nativa de salidas estructuradas. La misma explicación está disponible en inglés.

Puntos clave

  • Instructor es una biblioteca de código abierto que extrae salidas estructuradas y validadas de un LLM usando modelos Pydantic; supera las 11.000 estrellas en GitHub y acumula más de 3 millones de descargas al mes.
  • Va por la versión 1.15.4, publicada el 28 de junio de 2026, y requiere Python 3.9 o superior; se instala con un solo pip install instructor.
  • Su mecánica es un parche sobre el cliente del modelo: añade el parámetro response_model y devuelve una instancia ya tipada en lugar de texto suelto.
  • Cuando la validación falla, reintenta solo: vuelve a preguntar al modelo con el mensaje de error incluido, hasta max_retries veces, de modo que el propio modelo corrige su respuesta.
  • Es agnóstico del proveedor: la misma API funciona con más de 15 proveedores (OpenAI, Anthropic, Gemini, Mistral, Cohere, DeepSeek y modelos locales con Ollama).

¿Qué problema resuelve Instructor?

Un modelo de lenguaje devuelve texto, y el texto es un formato incómodo para un programa. Si necesitas que la respuesta sea un objeto con campos concretos (un nombre, una fecha, un importe), lo habitual es pedirle al modelo que «responda en JSON», recibir una cadena y cruzar los dedos al hacer json.loads. Ese enfoque se rompe a menudo: el modelo añade una coletilla antes del JSON, se inventa un campo, devuelve un número como texto o se olvida una llave. Cada uno de esos fallos revienta tu programa en producción.

Instructor, creado por Jason Liu (conocido como jxnl), ataca justo ese hueco. En lugar de parsear texto a mano, describes la forma que quieres con un modelo Pydantic y dejas que la biblioteca se encargue del resto: instruye al modelo para que produzca esa estructura, valida la respuesta contra tu esquema y, si algo no encaja, reintenta. El resultado es que tu código recibe siempre un objeto Python válido y con los tipos correctos, no una cadena que interpretar. La misma disciplina de tipos que aporta Pydantic AI al construir agentes, Instructor la lleva a cualquier llamada suelta a un modelo.

Modelos Pydantic como esquema de salida

El corazón de Instructor es que el esquema de salida es, sencillamente, una clase de Pydantic. Defines los campos que quieres con sus tipos, parcheas el cliente de tu proveedor y pasas esa clase en response_model. Lo que recibes ya no es texto: es una instancia de tu clase.

pip install instructor

import instructor
from pydantic import BaseModel

class Usuario(BaseModel):
    nombre: str
    edad: int

cliente = instructor.from_provider("openai/gpt-4o-mini")

usuario = cliente.chat.completions.create(
    response_model=Usuario,
    messages=[{"role": "user", "content": "Juan tiene 25 años"}],
)

print(usuario.nombre)  # Juan
print(usuario.edad)    # 25, ya validado como int

El objeto usuario es una instancia de Usuario con sus campos ya validados: usuario.edad es un int, no la cadena "25", y tu editor lo autocompleta y conoce su tipo. La factoría from_provider es el atajo recomendado desde las versiones recientes: con una sola cadena eliges proveedor y modelo, y por debajo aplica el parche adecuado.

Reintentos y validación automática

La verdadera potencia aparece cuando añades reglas de negocio, no solo tipos. Como el esquema es Pydantic, puedes usar validadores: si el modelo devuelve algo que incumple una regla, el validador lanza un error, Instructor lo captura y vuelve a preguntar al modelo con ese error como pista, hasta agotar max_retries. Es un bucle de autocorrección sin que tú escribas nada de lógica de reintento.

import instructor
from pydantic import BaseModel, field_validator

cliente = instructor.from_provider("openai/gpt-4o-mini")

class Ficha(BaseModel):
    nombre: str
    edad: int

    @field_validator("edad")
    @classmethod
    def edad_valida(cls, v: int) -> int:
        if v < 0 or v > 150:
            raise ValueError(f"La edad {v} no es válida")
        return v

ficha = cliente.chat.completions.create(
    response_model=Ficha,
    messages=[{"role": "user", "content": "Extrae la ficha del texto"}],
    max_retries=3,
)

Si el modelo devolviera una edad de 200, el validador la rechazaría y Instructor reenviaría la petición con el mensaje «La edad 200 no es válida» adjunto, para que el modelo lo corrija en el siguiente intento. Además de un entero simple, max_retries acepta un objeto Retrying de Tenacity, la biblioteca de reintentos de referencia en Python, con lo que puedes configurar esperas exponenciales o condiciones de parada más finas. Si prefieres garantizar el formato durante la propia generación en vez de reintentar después, esa es la vía de la generación restringida de Outlines.

Soporte multiproveedor y modelos locales

Uno de los grandes atractivos de Instructor es que la misma API vale para más de 15 proveedores. Cambiar de OpenAI a Anthropic, a Gemini o a un modelo que corras en tu propia máquina es cuestión de editar la cadena de from_provider; el resto del código, con su response_model y sus validadores, no se toca.

# El mismo esquema y la misma llamada, con otro proveedor
cliente = instructor.from_provider("anthropic/claude-sonnet-4-5")

# O un modelo local servido por Ollama
cliente = instructor.from_provider("ollama/llama3.1")

Para los modelos que ejecutes de forma local con Ollama o llama-cpp, esta combinación es especialmente valiosa: los modelos abiertos pequeños fallan más al respetar un formato, y la pareja «validación de Pydantic más reintentos» convierte una salida poco fiable en un objeto correcto sin que tú tengas que parchear cadenas a mano. Si vienes de la llamada a funciones con Ollama, Instructor te ofrece la misma capacidad con una ergonomía mucho más cómoda. La biblioteca no se limita a Python: la misma idea existe hoy en TypeScript, Go, Ruby, Elixir y Rust.

Instructor frente a la API de structured outputs

Desde 2024, OpenAI ofrece salidas estructuradas nativas: con response_format y un esquema JSON en modo estricto, la API garantiza que la respuesta es un JSON sintácticamente válido conforme a ese esquema. Es una función excelente, y conviene entender en qué se diferencia de Instructor, porque no compiten en el mismo plano.

La API nativa garantiza la forma del JSON, pero se queda ahí y solo existe en algunos proveedores. Instructor trabaja una capa por encima y añade tres cosas que la API nativa no cubre: validadores de negocio en Python (reglas como «la edad está entre 0 y 150», más allá de la comprobación de tipos), reintentos con realimentación cuando una de esas reglas falla, y una API idéntica para más de 15 proveedores, incluidos los modelos locales. De hecho, Instructor puede apoyarse por debajo en la propia función nativa cuando el proveedor la ofrece. En la práctica: si solo usas OpenAI y te basta con que el JSON tenga la forma correcta, la API nativa sobra; si quieres validación de reglas propias, reintentos automáticos y no atarte a un proveedor, Instructor es la opción más completa.

Preguntas frecuentes

¿En qué se diferencia Instructor de Pydantic AI?

Resuelven problemas cercanos pero distintos. Instructor es una capa ligera que parcheas sobre el cliente de tu proveedor para que una llamada devuelva un objeto validado; no impone una arquitectura. Pydantic AI es un framework de agentes completo, con herramientas, dependencias y grafos de estado, que también valida la salida con tipos. Si solo quieres extracción estructurada fiable, Instructor basta; si vas a construir un agente entero, Pydantic AI aporta más piezas.

¿Funciona con modelos que ejecuto en mi propia máquina?

Sí. Instructor admite modelos locales a través de Ollama y de llama-cpp-python, con la misma API de from_provider que usarías con un proveedor en la nube. Como los modelos abiertos pequeños respetan peor el formato, la combinación de validación de Pydantic y reintentos automáticos es justo lo que los hace utilizables para tareas de extracción sin sorpresas.

¿Cuánto código hace falta para empezar?

Muy poco. Instalas con pip install instructor, defines una clase Pydantic con los campos que quieres, parcheas el cliente con instructor.from_provider(...) y añades response_model a tu llamada habitual. Con esas cuatro líneas ya recibes un objeto tipado en lugar de texto, y a partir de ahí puedes ir sumando validadores y max_retries según lo exija tu caso.

Conclusión

Instructor convierte la parte más frágil de trabajar con un LLM, sacar datos estructurados de una respuesta de texto, en algo predecible: defines la forma con Pydantic, la biblioteca valida la salida y reintenta sola cuando el modelo se equivoca, y todo ello con la misma API para más de 15 proveedores. Con más de 11.000 estrellas, tres millones de descargas al mes y una superficie mínima que se aprende en una tarde, es la vía más corta hacia salidas fiables. El siguiente paso es instalarlo con pip install instructor, escribir tu primer modelo Pydantic con un validador y compararlo con la generación restringida de Outlines para decidir cuál encaja mejor en tu proyecto.

Fuentes: [1] Documentación oficial de Instructor[1], [2] Instructor en GitHub (567-labs)[2], [3] Paquete instructor en PyPI[3], [4] Blog de Jason Liu, creador de Instructor[4].

Visitas: 1

Fuentes

  1. Documentación oficial de Instructor
  2. Instructor en GitHub (567-labs)
  3. Paquete instructor en PyPI
  4. Blog de Jason Liu, creador de Instructor

Ruta: Modelos agénticos self-hosted y tool calling