Transformação em lote

A ferramenta Transformação em lote permite que os agentes processem arquivos CSV em massa usando fontes de dados just-in-time (JIT).Ela é projetada para cenários em que você deseja aplicar a mesma lógica de transformação em cada linha ou registro em um arquivo CSV sem configurar buckets de armazenamento ou índices antecipadamente.

A Transformação em lote pega um arquivo CSV de entrada fornecido no runtime e aplica uma tarefa de transformação definida pelo usuário ao arquivo. A ferramenta processa o arquivo, linha a linha, e produz um ou mais arquivos de saída que incluem os dados originais junto com quaisquer colunas ou linhas adicionais geradas pela lógica de transformação.

Os casos de uso típicos incluem:

• Enriquecer arquivos CSV com pontuações, rótulos ou classificações gerados por modelos
• Aplicar regras de negócios ou lógica de decisão a grandes conjuntos de dados.
• Produzir explicações ou justificativas junto com decisões automatizadas

Fontes de Dados

• A Transformação em lote é compatível apenas com fontes de dados JIT.
• Apenas arquivos CSV são compatíveis como entrada.
• Os arquivos são passados diretamente por meio de entradas do agente e resolvidos automaticamente no runtime.
• Nenhuma configuração de armazenamento externo ou criação de índice é necessária.

Para obter detalhes, consulte Melhores práticas para DeepRAG e Transformação em lote: JIT versus estratégias baseadas em índices.

Configuração da Transformação em lote

Adicione a ferramenta Transformação de lote

1. Abra seu agente no Modo de design.
2. Na lista de ferramentas integradas, adicione Transformação em lote ao agente.

Uma vez adicionada, a ferramenta Transformação em lote aparece como um nó de ferramenta dedicado que você pode configurar a partir do painel do lado direito.

Configurar entradas

Durante o design, você especifica como a ferramenta deve receber sua entrada:

• Arquivo de origem: a origem é uma entrada de arquivo (por exemplo, input-csv). No runtime, isso é resolvido automaticamente para o arquivo fornecido quando o agente é executado.

  Observação:

  Você deve configurar um argumento de tipo de arquivo no Gerenciador de dados.

• Tarefa de transformação em lote - a instrução específica da ferramenta que define como a transformação em lote deve ser realizada. Use esse campo para dizer à ferramenta exatamente como processar o arquivo de entrada, incluindo:

  • Quais novas colunas ou linhas gerar
  • Como cada linha deve ser processada
  • Quaisquer regras, critérios ou lógica de decisão a aplicar

  Por exemplo, você pode instruir a ferramenta a gerar duas colunas novas, como uma pontuação e um sinalizador de recomendação com base no conteúdo de cada linha. Isso não é uma solicitação de agente. O agente deve incluir apenas uma instrução de alto nível para quando invocar a transformação em lote e como deve ser a saída final.

  

• Colunas de saída — Defina o esquema para quaisquer colunas novas geradas pela transformação em lote. Para cada coluna, especifique:

  • O nome da coluna
  • Uma descrição do que a coluna representa e como seus valores devem ser interpretados

  Você pode adicionar novas colunas de saída, editar nomes de colunas ou descrições existentes ou remover colunas conforme necessário. A tarefa Transformação em lote deve descrever a lógica usada para preencher essas colunas configuradas.

Habilitar embasamento de pesquisa na Web (opcional)

A ferramenta Transformação em lote inclui uma configuração opcional de embasamento de pesquisa na Web que controla se o modelo pode usar resultados de pesquisa na Web ao gerar transformações.

• Quando habilitado, o modelo pode complementar os dados do arquivo de entrada com informações recuperadas da Web ao processar cada linha.
• Quando desabilitado, a transformação é realizada estritamente usando o conteúdo do arquivo de entrada, as instruções definidas na tarefa e qualquer contexto fornecido explicitamente ao agente.

Execução da Transformação em lote

Quando você executa ou depura o agente, a ferramenta Transformação em lote é executada como parte da execução do agente:

• O arquivo de entrada é passado para a ferramenta no runtime.
• A ferramenta processa o arquivo, linha por linha.
• É gerado um arquivo de saída transformado.
• O Arquivo de saída é retornado como parte da saída do agente.

Durante a execução, a Transformação em lote aparece no Trace de execução como uma chamada de ferramenta dedicada. Você pode expandir essa etapa para inspecionar informações detalhadas do runtime.

Inspecionar detalhes de execução

Do trace de execução, você pode revisar detalhes exibidos na saída da chamada de ferramenta e, quando aplicável, a saída do agente:

• Entradas - O arquivo de entrada usado pela ferramenta, incluindo nome do arquivo, tipo e metadados (visíveis na saída da chamada de ferramenta).
• Saídas - O arquivo de saída gerado, incluindo ID do arquivo, nome do arquivo e tipo MIME (exibido na saída da chamada de ferramenta quando uma saída de arquivo é definida).
• Contexto da solicitação - as solicitações do sistema e do usuário usadas durante a execução do agente, que ajudam a explicar como a tarefa de transformação foi executada.

Você pode baixar os arquivos de entrada e saída diretamente do trace de execução para validação ou solução de problemas.

Quando uma saída de arquivo é definida, a saída final do agente normalmente inclui uma mensagem de confirmação indicando que o arquivo transformado foi gerado e fornecendo o nome do arquivo de saída.

Avaliação de transformações em lote

As avaliações permitem que você meça a qualidade e a exatidão das saídas processadas em lote. Além de avaliar resultados no nível do arquivo, os agentes são compatíveis com avaliações, linha por linha, o que é especialmente útil para saídas estruturadas como arquivos CSV.

Avaliação linha por linha

A avaliação linha por linha avalia cada linha em um arquivo de saída de forma independente em vez de avaliar o arquivo como uma única unidade. Isso fornece visibilidade granular sobre como registros individuais se comportam em relação aos seus critérios de avaliação. Esse modo é particularmente útil quando:

• Cada linha representa uma decisão ou classificação independente.
• Você precisa de métricas granulares de aprovação/falha em arquivos grandes.
• Para detalhar falhas individuais.

Configuração de avaliação linha por linha

Você pode configurar a avaliação linha por linha nas configurações do conjunto de avaliação

1. Habilite a avaliação linha por linha na configuração do conjunto de avaliações.
2. Selecione o arquivo de saída para avaliar. Isso é necessário quando um agente produz vários arquivos de saída.
3. Especifique o tipo de arquivo (por exemplo, CSV) em que o avaliador deve operar.

Uma vez configuradas, as avaliações serão realizadas em cada linha do arquivo de saída selecionado.

Avaliador de correspondência exata de colunas CSV

Para oferecer suporte à avaliação de arquivos estruturados, está disponível um avaliador determinista chamado Avaliador de correspondência exata de colunas CSV. Para obter detalhes, consulte Avaliações de agente.

Esse avaliador:

• Compara uma ou mais colunas especificadas entre saídas esperadas e saídas reais
• Executa uma correspondência exata de strings
• Retorna resultados de aprovação/falha por linha

O Avaliador de correspondência exata de colunas CSV é adequado para validar saídas categóricas, como rótulos, tipos de correspondência ou campos de status.

Execução e revisão de avaliações

Após configurar o conjunto de avaliações:

1. Crie uma execução de avaliação usando um arquivo de entrada e o arquivo de saída de transformação em lote correspondente.
2. Agende ou execute a avaliação.
3. Revise resultados em dois níveis:
   • Resumo de primeiro nível, mostrando quantas linhas foram aprovadas ou falharam no geral.
   • Detalhe no nível de linha, mostrando status, valores e metadados de aprovação/falha, para cada linha individual.

Por exemplo, uma avaliação pode mostrar que 141 de 199 linhas passaram em uma verificação de correspondência exata em uma coluna específica. A partir daí, você pode detalhar para inspecionar linhas individuais com falha, comparar valores esperados com valores reais e revisar detalhes de execução, como latência por linha.

A avaliação linha por linha fornece:

• Visibilidade clara sobre quais registros foram bem-sucedidos ou falharam.
• Depuração mais rápida da lógica de transformação.
• Métricas quantitativas para rastrear melhorias ao longo do tempo.