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). Ele é projetado 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 com antecedência.

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 a ele. A ferramenta processa o arquivo linha por linha e produz um ou mais arquivos de saída que incluem os dados originais juntamente com quaisquer colunas ou linhas adicionais geradas pela lógica de transformação.

Os casos de uso típicos incluem:

• Enriquecimento de arquivos CSV com pontuações, rótulos ou classificações gerados pelo modelo
• Aplicação de regras de negócios ou lógica de decisão a grandes conjuntos de dados
• Produção de explicações ou justificativas junto com decisões automatizadas

Fontes de Dados

• A transformação em lote suporta apenas fontes de dados JIT.
• Apenas arquivos CSV são compatíveis como entrada.
• Os arquivos são passados diretamente por 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 as Práticas recomendadas para DeepRAG e Batch Transform: JIT vs. estratégias baseadas em índice.

Configurando a transformação em lote

Adicione a ferramenta Transformação em lote

1. Abra seu agente no modo de design.
2. Na lista de ferramentas integradas, adicione Batch Transform ao agente.

Após ter sido adicionada, a ferramenta Transformação em lote aparecerá como um nó de ferramenta dedicado que você pode configurar no painel do lado direito.

Configurar entradas

No tempo de 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 resolve automaticamente para o arquivo fornecido quando o agente é executado.

  Observação:

  Você deve configurar um argumento de tipo de arquivo no Data Manager.

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

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

  Por exemplo, você pode instruir a ferramenta para gerar duas novas colunas, como uma pontuação e um sinalizador de recomendação com base no conteúdo de cada linha. Esta não é uma solicitação do 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 novas colunas 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 ou descrições de colunas existentes ou remover colunas conforme necessário. A tarefa Batch Transform 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 complementa os dados do arquivo de entrada com informações recuperadas da web ao processar cada linha.
• Quando desabilitada, 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.

Executando transformação em lote

Quando você executa ou depura o agente, a ferramenta Batch Transform é 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.
• Um arquivo de saída transformado é gerado.
• O arquivo de saída é retornado como parte da saída do agente.

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

Inspeção de detalhes da execução

A partir do rastreamento da execução, você pode revisar os detalhes revelados na saída da chamada da ferramenta e, quando aplicável, na 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 (mostrado na saída da chamada da ferramenta quando uma saída do arquivo é definida).
• Contexto da solicitação – O prompt do sistema e do usuário usados 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.

Avaliando transformações em lote

As avaliações permitem que você meça a qualidade e a correção dos resultados processados em lote. Além de avaliar os resultados no nível do arquivo, os agentes são compatíveis com a avaliação linha por linha, 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 o desempenho dos registros individuais em relação aos seus critérios de avaliação. Este modo é especialmente útil quando:

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

Configurando a avaliação linha por linha

A avaliação linha por linha é configurada nas configurações do conjunto de avaliação:

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

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

Avaliador de correspondência exata da coluna CSV

Para permitir a avaliação de arquivos estruturados, está disponível um avaliador determinístico chamado Avaliador de correspondência exata de coluna de CSV . Para obter detalhes, consulte Avaliações de agentes.

Esse avaliador:

• Compara uma ou mais colunas especificadas entre as saídas esperadas e reais
• Executa uma correspondência exata de string
• Retorna resultados aprovado/reprovado por linha

O Avaliador de correspondência exata de coluna CSV é adequado para validar saídas categorizadas, 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ção:

1. Crie uma execução de avaliação usando um arquivo de entrada e o arquivo de saída da Transformação em lote correspondente.
2. Agende ou execute a avaliação.
3. Revisar resultados em dois níveis:
   • Resumo em nível de arquivo, mostrando quantas linhas aprovadas ou reprovadas no geral.
   • Detalhamento em nível de linha, mostrando status de aprovado/reprovado, valores e metadados 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 fazer um detalhamento para inspecionar linhas individuais com falha, comparar os valores esperados versus reais e revisar os detalhes de execução, como a latência por linha.

A avaliação linha por linha fornece:

• Visibilidade clara de 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.