Transformación por lotes

La herramienta Transformación por lotes permite a los agentes procesar archivos CSV de forma masiva utilizando orígenes de datos justo a tiempo (JIT). Está diseñado para escenarios en los que deseas aplicar la misma lógica de transformación en cada fila o registro en un archivo CSV sin configurar depósitos de almacenamiento o índices con antelación.

La Transformación por lotes toma un archivo CSV de entrada proporcionado en tiempo de ejecución y le aplica una tarea de transformación definida por el usuario. La herramienta procesa el archivo fila por fila y produce uno o más 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 archivos CSV con puntuaciones, etiquetas o clasificaciones generadas por modelos
• Aplicar reglas empresariales o lógica de decisión a grandes conjuntos de datos
• Producir explicaciones o justificaciones junto con decisiones automatizadas

Orígenes de datos

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

For details, refer to Best practices for DeepRAG and Batch Transform: JIT vs. index-based strategies.

Configurar la transformación por lotes

Añadir 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 de la derecha.

Configurar entradas

En el momento del diseño, se especifica 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 Data Manager.

• 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. Utiliza este campo para indicar a la herramienta exactamente cómo procesar el archivo de entrada, incluyendo:

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

  Por ejemplo, puedes indicar a la herramienta que genere dos nuevas columnas, 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 sobre cuándo invocar la transformación por lotes y cómo debe ser la salida final.

  

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

  • El nombre de la 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 nombres o descripciones de columnas existentes o eliminar columnas según sea necesario. La tarea Transformación por lotes debe describir la lógica utilizada para rellenar estas columnas configuradas.

Habilitar búsqueda en la web (opcional)

La herramienta Transformación por lotes incluye una configuración de búsqueda web opcional que controla si el modelo puede utilizar 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 tiempo de ejecución.
• 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 ampliar este paso para inspeccionar información detallada de runtime.

Inspeccionar detalles de ejecución

Desde el seguimiento de la 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, incluido el nombre de archivo, el tipo y los metadatos (visibles en la salida de la llamada de la herramienta).
• Salidas: el archivo de salida generado, incluido el ID de archivo, el nombre de 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 desde el seguimiento de ejecución para la validación o la resolución de problemas.

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

Evaluar transformaciones por lotes

Las evaluaciones te permiten medir la calidad y la corrección 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, que es especialmente útil para salidas estructuradas como 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 una visibilidad granular sobre el rendimiento de 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 granulares de aprobación/fallo en archivos grandes.
• Desea profundizar en 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. Seleccione 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 configurado, las evaluaciones se realizarán 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 CSV Column Exact Match Evaluator . Para obtener más información, consulta Evaluaciones de agentes.

Este evaluador:

• Compara una o más columnas especificadas entre las salidas esperadas y las reales
• Realiza una coincidencia de cadena exacta
• Devuelve resultados de aprobado/desaprobado por fila

El Evaluador de coincidencia exacta de columna CSV es muy 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 a nivel de archivo, que muestra cuántas filas se aprobaron o fallaron en general.
   • Desglose a nivel de línea, que muestra el estado de aprobado/reprobado, los valores y los metadatos de cada fila individual.

Por ejemplo, una evaluación puede mostrar que 141 de 199 filas pasaron una comprobación de coincidencia exacta en una columna específica. A partir de ahí, puedes profundizar para inspeccionar 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 los registros correctos o fallidos.
• 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.