Analisar arquivos

A ferramenta Analisar arquivos permite que os agentes processem e raciocinem sobre o conteúdo do arquivo usando LLMs.

Adicione a ferramenta Analisar arquivos

Para adicionar a ferramenta Analisar arquivos ao seu agente, siga as seguintes etapas:

1. Defina entradas de arquivo. No painel Gerenciador de dados, adicione um argumento para cada entrada de arquivo em seu esquema de agente.

   Figura 1. Criação de argumentos de entrada de arquivo

   

   O argumento de entrada deve ser referenciado explicitamente na solicitação do usuário usando a sintaxe {{exampleInput}}. Os argumentos de entrada que não são referenciados são ignorados e podem afetar a pontuação do agente.

   • Para um arquivo único, defina o tipo de argumento como Arquivo e faça referência a ele na solicitação do usuário. Por exemplo: "Analise o seguinte relatório e resuma as principais descobertas: {{reportFile}}".
   • Para transmitir vários arquivos, defina o tipo de argumento como Array e o tipo de item como Arquivo e, em seguida, faça referência ao argumento por nome na solicitação do usuário.Você também pode adicionar argumentos de strings opcionais para instruções de runtime.Por exemplo:

   Analyze the following report files and summarize the key findings.
   
   ## Inputs
   - Report files: {{reportFiles}}
   - Additional instructions (optional): {{analysisInstructions}}
   

   Neste exemplo, reportFiles é um argumento Array de Arquivo e analysisInstructions é um argumento String opcional. Ambos devem ser definidos no painel Gerenciador de dados.

   

   

2. Adicione a ferramenta Analisar arquivos à definição do seu agente:

   1. Selecione Adicionar ferramenta no painel Ferramentas.
   2. Na categoria Ferramentas integradas, escolha Analisar arquivos.
   3. Atualize o nome e a descrição da ferramenta para ajudar o agente a entender melhor quando usá-la. O nome e a descrição orientam a fase de planejamento do agente — eles determinam quando o agente decide chamar a ferramenta, não o que a ferramenta faz com os arquivos no runtime.

   

3. Defina as entradas da ferramenta. A ferramenta vem pré-configurada com duas entradas principais:

   • attachments (array): uma entrada definida por solicitação que informa ao agente quais arquivos passar para a ferramenta. Nesse campo, descreva como o agente deve usar as entradas de arquivos mencionadas na solicitação do usuário (por exemplo, {{reportFiles}}). O agente mapeia automaticamente esses arquivos de referência para essa entrada no runtime. Exemplo: "Usar os arquivos fornecidos na solicitação do usuário (por exemplo, {{reportFiles}}) como entradas para análise."
   • analysisTask(string): uma instrução do runtime que informa ao LLM o que fazer com os arquivos depois que a ferramenta é invocada — por exemplo, "Analisar esses relatórios. Extrair o título do relatório, um resumo executivo, as principais descobertas ordenadas por importância, recomendações acionáveis e o sentimento geral." Isso é diferente do nome e da descrição da ferramenta, que controlam quando o agente chama a ferramenta. Se seu caso de uso envolver apenas um arquivo, você pode descrever os anexos adequadamente (por exemplo, "Usar o arquivo fornecido em {{reportFile}}…").

4. Execute o agente com arquivos de entrada.

   1. Abra a janela Configuração de depuração :
      1. Navegue até a guia Argumentos do projeto.
      2. Carregue seus arquivos de entrada vinculados ao seu argumento reportFiles.
   2. Selecione Salvar e execute a sessão de depuração.

   

5. Após executar o agente, inspecione o trace de execução por meio do painel inferior.

A ferramenta Analisar arquivos agora está adicionada ao seu agente e configurada para processar entradas de arquivos. O Trace de execução no painel Trilha de execução mostra como o sistema tratou cada anexo durante a execução.

Traces de anexos de arquivos

Ao usar a ferramenta Analisar arquivos, todas as entradas e saídas de arquivos são capturadas no painel Trilha de execução, na guia Histórico. O trace fornece visibilidade detalhada sobre como os anexos foram tratados durante a execução do agente.

Para cada arquivo, o trace mostra:

• ID: um identificador exclusivo para o anexo.

• Nome: nome do arquivo original (por exemplo, 1.jpg).

• Tipo MIME: tipo de arquivo detectado (por exemplo, image/jpeg).

  Figura 2. A análise do arquivo na trilha de execução

  

Selecione a chamada de ferramenta no rastreamento de execução e navegue até a guia Arquivos para baixar o arquivo.

Figura 3. Como baixar um arquivo a partir de rastreamentos

Mascaramento de PII para conteúdo de arquivo

Quando o mascaramento de PII em voo é habilitado em sua política de AI Trust Layer, ele se aplica automaticamente ao conteúdo do arquivo processado por meio da ferramenta Analisar arquivos. As PII detectadas no conteúdo do arquivo extraído são pseudonimizadas antes que o conteúdo atinja o LLM e reimplantadas na resposta do LLM. Para obter detalhes de configuração, consulte Mascaramento de PII.

Os seguintes formatos de arquivo são compatíveis:

• PDF
• DOCX
• CSV
• TXT
• JSON
• Imagens

Melhores práticas e perguntas frequentes

Observação:

Consulte Trabalhando com arquivos para obter mais detalhes sobre o uso de arquivos de Processes do Maestro, fluxos de trabalho de RPA ou execuções de agentes independentes.

A ferramenta Analisar Arquivos permite que os agentes processem documentos e imagens usando LLMs.Embora sejam potentes, há algumas limitações e comportamentos importantes a serem considerados ao projetar agentes orientados por arquivos.

Limites de arquivos

Cada arquivo não deve exceder 30 MB. Não há limite imposto no número de arquivos por solicitação.

Suporte a tipos de arquivos por provedor

O suporte a arquivos depende do provedor de LLM e do modelo que você selecionar para o agente.Embora vários provedores sejam compatíveis com formatos como PDF, documentos do Word, planilhas, HTML, texto, Markdown e imagens, cada provedor pode processar esses arquivos de forma diferente antes de enviar o conteúdo ao modelo. Os resultados podem variar entre provedores e modelos, especialmente para arquivos que contêm gráficos, imagens incorporadas, layouts complexos, fórmulas ou tabelas grandes.

A tabela abaixo mostra os formatos compatíveis com os modelos mais recentes expostos pela UiPath:

Provedor / família de modelos	Formatos de Documento e texto compatíveis	Formatos de imagem compatíveis
Modelos da Anthropic por meio do AWS Bedrock	.pdf, .csv, .doc, .docx, .xls, *.xlsx, .html, .txt, .md	.gif, .jpe, .jpeg, .pdf, .png, .tiff, .webp
Modelos GPT da OpenAI	.pdf, .csv, .doc, .docx, .xls, *.xlsx, .html, .txt, .md	.gif, .jpe, .jpeg, .pdf, .png, .tiff, .webp
Modelos Gemini por meio da Vertex AI	.csv, .txt, .md, .html	.gif, .jpe, .jpeg, .pdf, .png, .tiff, .webp

Observação:

O suporte depende do modelo selecionado e dos recursos do provedor.Alguns modelos podem oferecer suporte a uma extensão de arquivo no nível de API, mas processam o arquivo internamente de forma diferente, o que pode afetar a qualidade da Resposta.

Suporte a arquivos para configurações de LLM personalizadas

Ao usar o recurso Bring Your Own LLM por meio da AI Trust Layer, os tipos de arquivos compatíveis com o recurso Analisar Arquivos dependem da configuração de LLM definida. Para obter detalhes, consulte Configuração de LLMs.

A combinação dos seguintes fatores determina a compatibilidade de arquivos:

• O provedor selecionado, como Azure OpenAI, Amazon Web Services ou Google Vertex
• A família e a versão do modelo selecionadas
• O tipo de API configurado, como o ponto de extremidade do provedor que chama o modelo
• Os recursos de processamento de arquivo que esse ponto de extremidade do provedor expõe

Um tipo de arquivo que funciona com um modelo ou provedor pode não funcionar com outro, mesmo quando ambos os modelos estão disponíveis por meio da AI Trust Layer. Por exemplo, a compatibilidade com documentos, planilhas, imagens e PDFs pode variar dependendo de a API do provedor aceitar esses arquivos diretamente, extrair texto deles, convertê-los em imagens ou aplicar uma etapa de pré-processamento específica do provedor.

A UiPath valida se o ponto de extremidade do LLM configurado é acessível e compatível com a configuração do produto selecionada. Ao usar uma configuração de LLM personalizada, você é responsável por garantir que o modelo, o provedor e o tipo de API configurados sejam compatíveis com os tipos de arquivos que seu caso de uso Analisar arquivos exige.

Observação:

A compatibilidade do arquivo pode mudar ao alternar de um modelo gerenciado pela UiPath para uma configuração de LLM personalizada ou ao alterar o provedor, a versão do modelo ou o tipo de API. Se Analisar arquivos não processar um arquivo após alterar a configuração de LLM, revise o provedor, o modelo e o tipo de API configurados na AI Trust Layer.

Como funciona o processamento de arquivos

Quando você passa um arquivo para um LLM, o modelo não recebe o arquivo original como está.A maioria dos provedores aplica uma etapa de pré-processamento antes de adicionar o conteúdo ao contexto do modelo. O comportamento do pré-processamento depende do tipo de arquivo.

Para entradas de arquivos OpenAI:

• Você pode processar arquivos PDF tanto como texto extraído quanto como imagens de páginas em modelos com capacidade de visão.
• Você só pode processar arquivos de documento e de texto que não são PDF como texto extraído.
• Os arquivos de planilhas usam um fluxo de aumento específico da planilha. A OpenAI analisa até as primeiras 1.000 linhas por planilha e adiciona metadados de resumo e cabeçalho para que o modelo funcione a partir de uma representação estruturada dos dados.

Outros provedores, como AWS Bedrock e Vertex AI, podem usar abordagens de pré-processamento semelhantes, mas os detalhes exatos da implementação são específicos do provedor e talvez não seja possível documentá-los totalmente.

Arquivos grandes podem exceder os limites de token

Agents processam arquivos incorporando seu conteúdo a solicitações de LLM, que são restringidas pelo limite de tokens do modelo. PDFs grandes ou documentos de imagem digitalizados podem falhar silenciosamente ou retornar erros vagos como "Ocorreu um erro", especialmente quando eles excedem o orçamento de token do modelo.

Para mitigar:

• Use modelos com capacidade de token mais alta.
• Use recursos orientados à recuperação, como Pesquisar arquivo ou contextualização, especialmente para arquivos grandes ou com várias páginas.
• Pré-indexe documentos e sincronize-os antes ou durante a execução do agente por meio de ferramentas personalizadas.

Tratamento de PDFs grandes

PDFs grandes podem exceder o orçamento de Token do LLM ao realizar a leitura completa. Divida o PDF em partes menores ou páginas individuais antes de passá-las para o agente.

LLMs redimensionam imagens

Quando os arquivos de imagem (por exemplo, .jpg, .png) são enviados como parte da solicitação do LLM, a maioria dos modelos os redimensiona automaticamente. Isso pode distorcer as relações de aspecto ou perder dados precisos em pixels.

Evite solicitações que dependam de coordenadas exatas, caixas de delimitação ou comparações alinhadas por pixels (por exemplo, diferenças de imagem que exigem posicionamento x/y específico). Para obter mais informações, consulte o guia de visão de imagem do OpenAI para comportamento de redimensionamento específico do modelo.

Dicas para melhores resultados

• Os nomes dos arquivos devem estar limpos: os modelos antrópicos, em particular, rejeitam nomes de arquivos com caracteres especiais ou espaços em branco repetidos.
• Mantenha a contagem de imagens baixa: alguns modelos, como o GPT-4o, são compatíveis com um máximo de 10 a 50 imagens por solicitação.
• Use o formato PDF quando o layout, gráficos ou diagramas forem importantes. Imagens e gráficos incorporados em formatos não PDF, como .docx talvez não sejam extraídos no contexto do modelo.
• Use formatos baseados em texto, como .txt, .md, ou .html para tarefas diretas do Document Understanding.
• Para análises de planilhas complexas que envolvam agregações, junções, fórmulas ou gráficos, use uma etapa de processamento determinista ou um fluxo de trabalho de processamento de dados dedicado antes de passar o resultado para o agente.