Structured Output

El componente Structured Output convierte la salida de un modelo de lenguaje (LLM) en un formato estructurado, como JSON, siguiendo un esquema que tú defines. Es ideal para extraer información específica de textos sin formato y garantizar que los datos tengan un formato uniforme para usarlos en otras partes de tu flujo de trabajo.

¿Cómo funciona?

1. Entrada de texto: Le das al LLM un mensaje de entrada y un system prompt que indica cómo debe formatear la respuesta (por ejemplo, “devuelve un objeto JSON con los campos X, Y y Z”).
2. Esquema de salida: Proporcionas un esquema JSON que describe los nombres de los campos y sus tipos (string, integer, date, etc.). El componente construye un modelo Pydantic a partir de ese esquema.
3. LLM con salida estructurada: Si el modelo de lenguaje que seleccionaste soporta la salida estructurada, el componente lo configura para que devuelva datos que coincidan con el modelo Pydantic.
4. Ejecución: Se envía la solicitud al LLM y se recibe la respuesta. Si el LLM devuelve un objeto que coincide con el esquema, se convierte en un objeto Data que se pasa a la siguiente etapa del flujo.
5. Múltiples resultados: Si activas la opción Generate Multiple, el componente espera que el LLM devuelva una lista de objetos y los devuelve como una lista de Data.

El proceso se realiza localmente dentro de Nappai; no se llama a ninguna API externa aparte de la del LLM que ya esté configurado en tu proyecto.

Entradas

Campo	Tipo	Descripción
Model	HandleInput	El modelo de lenguaje que se usará para generar la salida estructurada.
Input Message	MessageTextInput	El mensaje que se enviará al modelo.
Format Instructions	MultilineInput	Instrucciones que el modelo debe seguir para formatear la respuesta. Por defecto, se le pide que devuelva un objeto JSON con los campos definidos en el esquema.
Schema Name	StrInput	Nombre que le das al esquema de salida (útil cuando generas múltiples objetos).
Output Schema	MultilineInput	Definición JSON del esquema de salida (campos y tipos).
Generate Multiple	BoolInput	Si está activado, el componente espera una lista de objetos en lugar de un solo objeto.

Nota: Todos los campos son visibles en el panel de configuración del componente; no hay operaciones separadas.

Salidas

Campo	Tipo	Descripción
llm_structured_output	Any	Una lista de objetos Data que contienen los datos estructurados generados por el LLM. Cada objeto sigue el esquema que definiste.

Ejemplo de Uso

Supongamos que quieres extraer la información de facturas de un correo electrónico. Puedes configurar el componente de la siguiente manera:

1. Model: Selecciona tu modelo de lenguaje (por ejemplo, OpenAI GPT‑4).
2. Input Message: Pega el cuerpo del correo electrónico.
3. Format Instructions:

   You are an AI system designed to extract structured information from unstructured text.
   Given the input_text, return a JSON object with predefined keys based on the expected structure.
   Extract values accurately and format them according to the specified type (e.g., string, integer, float, date).
   If a value is missing or cannot be determined, return a default (e.g., null, 0, or 'N/A').
   If multiple instances of the expected structure exist within the input_text, stream each as a separate JSON object.

4. Schema Name: Invoice.
5. Output Schema:

   {
     "invoice_number": "string",
     "date": "date",
     "total_amount": "float",
     "vendor": "string"
   }

6. Generate Multiple: Desactivado (si solo esperas una factura por correo).

Al ejecutar el flujo, el componente devolverá un objeto Data con los campos invoice_number, date, total_amount y vendor. Puedes conectar esta salida a un componente de base de datos, a un spreadsheet o a cualquier otro proceso que necesite datos estructurados.

Componentes Relacionados

• Text Splitter – Divide textos largos en fragmentos antes de enviarlos al LLM.
• Data Validator – Verifica que los datos estructurados cumplan reglas adicionales (por ejemplo, rango de fechas).
• Database Writer – Guarda los objetos Data en una base de datos SQL o NoSQL.
• Spreadsheet Exporter – Exporta los datos estructurados a una hoja de cálculo.

Consejos y Mejores Prácticas

• Define un esquema claro: Cuanto más preciso sea el esquema, menos errores tendrá el LLM al generar la salida.
• Usa tipos de datos adecuados: Si esperas fechas, usa date; para cantidades monetarias, usa float.
• Maneja valores faltantes: En el esquema, puedes usar null o valores por defecto para campos que pueden no aparecer en el texto.
• Prueba con ejemplos reales: Antes de usarlo en producción, prueba el componente con varios textos para asegurarte de que el LLM sigue el esquema correctamente.
• Activa “Generate Multiple” solo cuando sea necesario: Si tu texto contiene varias instancias del mismo patrón, habilita esta opción para obtener una lista de objetos.

Consideraciones de Seguridad

• Privacidad de datos: Los textos que envías al LLM pueden contener información sensible. Asegúrate de que el modelo y la infraestructura cumplen con las políticas de tu organización.
• Control de acceso: Limita quién puede configurar y ejecutar este componente, especialmente si el LLM está conectado a servicios externos.
• Validación de salida: Aunque el LLM intenta seguir el esquema, siempre valida la salida antes de usarla en sistemas críticos (por ejemplo, bases de datos financieras).

---