Transformación por lotes

La herramienta Transformación por lotes permite a los agentes procesar archivos CSV en masa utilizando fuentes de datos JIT. Está diseñada para escenarios en los que quieres aplicar la misma lógica de transformación en cada fila o registro de un archivo CSV sin configurar depósitos de almacenamiento o índices por adelantado.

La transformación por lotes toma un archivo CSV de entrada proporcionado en runtime y le aplica una tarea de transformación definida por el usuario. La herramienta procesa el archivo fila por fila y produce uno o varios archivos de salida que incluyen los datos originales junto con cualquier columna o fila adicional generada por la lógica de transformación.

Los casos de uso típicos incluyen:

• Enriquecer los archivos CSV con puntuaciones generadas por el modelo, etiquetas o clasificaciones
• Aplicar reglas empresariales o lógica de decisión a conjuntos de datos grandes
• Producir explicaciones o justificaciones junto con las decisiones automatizadas

Orígenes de datos

• La transformación por lotes solo admite fuentes de datos JIT.
• Solo se admiten archivos CSV como entrada.
• Los archivos se pasan directamente a través de las entradas del agente y se resuelven automáticamente en runtime.
• No se requiere configuración de almacenamiento externo ni creación de índice.

Para obtener más detalles, consulta Prácticas recomendadas para DeepRAG y transformación por lotes: JIT frente a estrategias basadas en índices.

Configurar la transformación por lotes

Añade la herramienta Transformación por lotes

1. Abre tu agente en modo de diseño.
2. Desde la lista de herramientas integradas, añade Transformación por lotes al agente.

Una vez añadida, la herramienta Transformación por lotes aparece como un nodo de herramienta dedicado que puedes configurar desde el panel derecho.

Configura entradas

En tiempo de diseño, especificas cómo debe recibir la herramienta su entrada:

• Archivo de origen: el origen es una entrada de archivo (por ejemplo, input-csv). En tiempo de ejecución, esto se resuelve automáticamente en el archivo proporcionado cuando se ejecuta el agente.

  Nota:

  Debes configurar un argumento de tipo de archivo en el Gestor de datos.

• Tarea de transformación por lotes: la instrucción específica de la herramienta que define cómo se debe realizar la transformación por lotes. Usa este campo para decirle a la herramienta exactamente cómo procesar el archivo de entrada, incluyendo:

  • Qué nuevas columnas o filas generar
  • Cómo se debe procesar cada fila
  • Cualquier regla, criterio o lógica de decisión para aplicar

  Por ejemplo, puedes indicar a la herramienta que genere dos columnas nuevas como una puntuación y un marcador de recomendación en función del contenido de cada fila. Esto no es una solicitud de agente. El agente solo debe incluir una instrucción de alto nivel para saber cuándo invocar la transformación por lote y cómo debe ser la salida final.

  

• Columnas de salida: define el esquema para cualquier nueva columna generada por la transformación por lotes. Para cada columna, especifica:

  • El nombre de columna
  • Una descripción de lo que representa la columna y cómo deben interpretarse sus valores

  Puedes añadir nuevas columnas de salida, editar los nombres o descripciones de las columnas existentes o eliminar las columnas según sea necesario. La tarea Transformación por lotes debe describir la lógica utilizada para rellenar estas columnas configuradas.

Habilitar fundamentación con búsqueda web (opcional)

La herramienta Transformación por lotes incluye una configuración opcional de fundamentación con búsqueda web que controla si el modelo puede utilizar los resultados de búsqueda web al generar transformaciones.

• Cuando está habilitado, el modelo puede complementar los datos del archivo de entrada con información recuperada de la web mientras procesa cada fila.
• Cuando está deshabilitado, la transformación se realiza estrictamente utilizando el contenido del archivo de entrada, las instrucciones definidas en la tarea y cualquier contexto proporcionado explícitamente al agente.

Ejecutar transformación por lotes

Al ejecutar o depurar el agente, la herramienta Transformación por lotes se ejecuta como parte de la ejecución del agente:

• El archivo de entrada se pasa a la herramienta en runtime.
• La herramienta procesa el archivo fila por fila.
• Se genera un archivo de salida transformado.
• El archivo de salida se devuelve como parte de la salida del agente.

Durante la ejecución, la Transformación por lotes aparece en el Seguimiento de ejecución como una llamada de herramienta dedicada. Puedes expandir este paso para inspeccionar información detallada de runtime.

Inspeccionar los detalles de ejecución

Desde el seguimiento de ejecución, puedes revisar los detalles que aparecen en la salida de la llamada de la herramienta y, cuando corresponda, la salida del agente:

• Entradas: el archivo de entrada utilizado por la herramienta, incluidos el nombre del archivo, el tipo y los metadatos (visibles en la salida de la llamada de herramienta).
• Salidas: el archivo de salida generado, incluido el ID de archivo, el nombre del archivo y el tipo MIME (que se muestra en la salida de la llamada de herramienta cuando se define una salida de archivo).
• Contexto de solicitud: las solicitudes del sistema y del usuario utilizadas durante la ejecución del agente, que ayudan a explicar cómo se ejecutó la tarea de transformación.

Puedes descargar tanto los archivos de entrada como los de salida directamente del seguimiento para su validación o solución de problemas.

Cuando se define una salida de archivo, la salida del agente final suele incluir un mensaje de confirmación que indica que se generó el archivo transformado y proporciona el nombre del archivo de salida.

Evaluar transformaciones por lotes

Las evaluaciones te permiten medir la calidad y la exactitud de las salidas procesadas por lotes. Además de evaluar los resultados en el nivel de archivo, los agentes admiten la evaluación línea por línea, lo que es especialmente útil para las salidas estructuradas como los archivos CSV.

Evaluación línea por línea

La evaluación línea por línea evalúa cada fila de un archivo de salida de forma independiente en lugar de evaluar el archivo como una sola unidad. Esto proporciona visibilidad granular de cómo se comportan los registros individuales en comparación con tus criterios de evaluación. Este modo es particularmente útil cuando:

• Cada fila representa una decisión o clasificación independiente.
• Necesitas métricas de aprobación/error granulares en los archivos grandes.
• Quieres profundizar en los fallos individuales.

Configurar la evaluación línea por línea

La evaluación línea por línea se configura en la configuración del conjunto de evaluación:

1. Habilita la evaluación línea por línea en la configuración del conjunto de evaluación.
2. Selecciona el archivo de salida para evaluar. Esto es necesario cuando un agente produce varios archivos de salida.
3. Especifica el tipo de archivo (por ejemplo, CSV) en el que debe operar el evaluador.

Una vez configuradas, se realizarán evaluaciones en cada fila del archivo de salida seleccionado.

Evaluador de coincidencia exacta de columna CSV

Para admitir la evaluación de archivos estructurados, hay disponible un evaluador determinista llamado Evaluador de coincidencia exacta de columna CSV. Para obtener más detalles, consulta Evaluaciones de agente.

Este evaluador:

• Compara una o más columnas especificadas entre las salidas esperadas y las salidas reales
• Realiza una coincidencia exacta de cadena.
• Devuelve resultados de aprobación/error por fila

El evaluador de coincidencia exacta de columna CSV es adecuado para validar salidas categóricas como etiquetas, tipos de coincidencia o campos de estado.

Ejecutar y revisar evaluaciones

Después de configurar el conjunto de evaluación:

1. Crea una ejecución de evaluación utilizando un archivo de entrada y el archivo de salida de transformación por lotes correspondiente.
2. Programa o ejecuta la evaluación.
3. Revisa los resultados en dos niveles:
   • Resumen en el nivel de archivo, que muestra cuántas filas aprobaron o fallaron en general.
   • Descripción detallada en el nivel de línea, que muestra el estado de aprobación/error, los valores y los metadatos para cada fila individual.

Por ejemplo, una evaluación puede mostrar que 141 de 199 Filas pasaron una comprobación de coincidencia exacta marcada en una columna específica. A partir de ahí, puedes profundizar para inspeccionar las filas fallidas individuales, comparar los valores esperados con los reales y revisar los detalles de ejecución como la latencia por fila.

La evaluación línea por línea proporciona:

• Visibilidad clara de qué registros aprobaron o fallaron.
• Depuración más rápida de la lógica de transformación.
• Métricas cuantitativas para realizar un seguimiento de las mejoras a lo largo del tiempo.