Instructor: extracción tipada con Pydantic

La biblioteca instructor es un wrapper ligero del cliente de OpenAI que hace fiable la extracción estructurada. En lugar de confiar en que el modelo devuelva un JSON válido, instructor impone su esquema de Pydantic y vuelve a intentarlo automáticamente si la validación falla. Así elimina la necesidad de escribir su propia lógica personalizada de análisis y reintento.

Instale instructor con un único comando de pip. Requiere pydantic v2 y el SDK de openai. Una vez instalado, adapte el cliente de OpenAI con instructor.patch() para obtener el cliente mejorado, que admite el parámetro response_model en cada llamada.

Instructor funciona adaptando el cliente estándar de OpenAI. Al llamar a instructor.from_openai(client) se devuelve un cliente nuevo en el que cada llamada a chat.completions.create acepta un argumento de palabra clave response_model. La llamada a la API subyacente es idéntica; instructor simplemente añade la validación del esquema.

Defina la estructura de datos que desea recibir del modelo como un BaseModel de Pydantic. Los nombres de los campos, los tipos y las cadenas de documentación se convierten automáticamente en el esquema JSON que se envía al modelo. Use nombres de campo claros y descriptivos para que el modelo entienda qué debe rellenar. Añada validadores para las reglas de negocio.

Pase la clase de su modelo de Pydantic como response_model al cliente adaptado. Instructor construye una llamada a una herramienta en segundo plano, el modelo rellena los campos e instructor deserializa el resultado en un objeto de Python tipado. Obtendrá autocompletado completo en el IDE y seguridad de tipos para los datos devueltos.

Si el modelo devuelve datos que no superan la validación de Pydantic, instructor envía automáticamente el error de validación al modelo y le pide que corrija su respuesta. Puede configurar el número máximo de reintentos con el parámetro max_retries. Este ciclo de autocorrección elimina la mayoría de los fallos puntuales de extracción sin necesidad de código adicional.

Instructor gestiona sin problemas los modelos de Pydantic anidados. Puede definir esquemas profundamente anidados con listas, subobjetos opcionales y uniones discriminadas. El modelo recibe el esquema JSON completo y debe rellenar todos los campos obligatorios, por lo que resulta ideal para extraer objetos estructurados como facturas o currículos con varias secciones.

Para trabajos de extracción grandes, instructor admite el streaming parcial mediante instructor.Partial[YourModel]. A medida que el modelo genera tokens, recibe en tiempo real instancias del modelo parcialmente rellenadas. Esto resulta útil para mostrar el progreso en una interfaz de usuario o procesar los campos en cuanto llegan, en lugar de esperar a la respuesta completa.

Cuando necesite extraer varias entidades de un solo documento, envuelva su modelo en List[YourModel]. Instructor gestiona el esquema de la matriz JSON y deserializa cada elemento en un objeto de Python tipado. Este patrón funciona bien para extraer todas las personas mencionadas en un artículo, todas las transacciones de un extracto o todas las fechas de un contrato.

No todas las extracciones requieren GPT-4o. Para esquemas planos sencillos con menos de 10 campos, gpt-4o-mini produce resultados casi idénticos por una décima parte del coste. Use GPT-4o para esquemas anidados complejos, documentos largos o casos en los que sea importante la cobertura. Antes de elegir un modelo para producción, haga siempre una evaluación comparativa con una muestra de sus datos reales.

Instructor ofrece un sistema de hooks para la observabilidad. Registre una función de retorno de llamada on_completion para guardar la respuesta sin procesar de la API, el uso de tokens y el número de reintentos de cada extracción. Esto le ayuda a identificar qué tipos de documentos provocan más fallos y a ajustar sus esquemas o prompts en consecuencia.

En esta lección ha aprendido que instructor adapta el cliente de OpenAI para aceptar un parámetro response_model que impone esquemas de Pydantic; que el reintento automático tras un fallo de validación hace que la extracción sea sólida sin gestionar manualmente los errores; y que los modelos anidados y la extracción de listas permiten analizar documentos complejos con varias entidades y convertirlos en objetos de Python totalmente tipados. A continuación, gestionaremos los datos parciales y ausentes en los esquemas extraídos.