Trabalhando com Embasamento de Contexto

Esta seção inclui informações sobre como usar a Embasamento de Contexto de forma eficaz.

Introdução

Para usar a Contextualização com agentes ou o Autopilot for Everyone, crie um índice seguindo as etapas descritas em Criação de índices.

Para usar a embasamento de contexto com atividades, crie uma conexão com o conector de atividades da UiPath GenAI e certifique-se de usar o Studio Web ou o Studio Desktop versão 2024.4 ou mais recente.

Gerenciamento do pipeline de ingestão

É possível gerenciar os pipelines de ingestão por meio de:

• Orchestrator ou Agentes, na página Índices . Consulte Gerenciamento de índices.
• A atividade Atualizar Índice de Contextualização , parte do pacote de atividades UiPath GenAI.

Consulta de dados com o Embasamento de Contexto

Após criar um índice no Orchestrator, os índices ficam acessíveis em toda a plataforma UiPath. Esses índices servem como armazenamento persistente para documentos ingeridos de suas origens de dados, oferecendo um recurso reutilizável para vários produtos da UiPath:

• No Autopilot for Everyone, a contextualização melhora as interações do usuário permitindo pesquisas em índices existentes para fornecer respostas precisas às consultas. Para obter detalhes, consulte Contextualização no Autopilot for Everyone.
• As atividades GenAI se beneficiam da Contextualização, permitindo a geração de conteúdo com base em informações armazenadas em bases de conhecimento com acesso controlado. Para obter detalhes, consulte as Atividades GenAI.
• Para agentes, os índices desempenham uma função crucial ao fornecer contexto durante as execuções. Para obter detalhes, consulte Contextos.

Contexto de monitoramento Embasamento

Entender como o embasamento de contexto influencia seus fluxos de trabalho é crucial para otimizar o desempenho e solucionar problemas. Veja como você pode rastrear e visualizar as saídas da Embasamento de Contexto em diferentes produtos da UiPath.

Em Agentes, acesse a visualização Trace da execução do agente para ver detalhes abrangentes. Essa visualização fornece todos os resultados de pesquisa e citações da consulta de Contextualização, oferecendo insights sobre o processo de tomada de decisão do agente.

Para reunir informações detalhadas sobre a embasamento de contexto nas atividades da GenAI:

1. Coloque uma atividade Log Message imediatamente após a atividade Content Generation em sua sequência de fluxo de trabalho.
2. Use as seguintes variáveis de saída para capturar informações específicas:
   • Texto gerado superior: visualize a resposta de geração de LLM após a execução do fluxo de trabalho.
   • Citações: examine os resultados da pesquisa semântica que influenciaram a saída da geração. Isso funciona apenas para tipos de dados PDF e JSON.

Embasamento por contexto nas atividades da GenAI

A embasamento de contexto interage com seus dados em três fases:

1. Estabeleça sua origem de dados para o Embasamento de contexto.
   • A embasamento de contexto segue as permissões de pasta compartilhada. Use uma pasta com o acesso apropriado para gerenciar e consultar os dados.
   • Crie uma conexão com as fontes de dados compatíveis com o Integration Service ou adicione dados a um local de bucket compartilhado do Orchestrator.
2. Ingerir dados de sua origem de dados para o Embasamento de Contexto.
   • Criação e sincronização de índices no Orchestrator.
   • Use a atividade Atualizar Índice de Contextualização para sincronizar um índice que você criou.
3. Consulte e confirme com seus dados.
   • Use a atividade Content Generation, agentes ou Autopilot for Everyone para consultar documentos e usar informações para aumentar ou fundamentar prompts.

Padrões de embasamento de contexto comum

Os componentes principais da Embasamento de contexto são projetados para fornecer um mecanismo que suporta a localização de informações pertinentes dentro e entre documentos, e revelando apenas as partes mais relevantes necessárias para uma geração de alta qualidade e baixa latência a partir de um LLM.

Pesquisando nos documentos

O serviço de Embasamento de Contexto ajuda a encontrar informações específicas em um único documento com mais eficiência. Em vez de apenas corresponder palavras-chave, ele entende o significado e o contexto da sua consulta de pesquisa. Por exemplo, se você estiver procurando informações sobre "receitas de pizza de laranja" em um livro de receitas, ele entenderia que seu interesse é por Sobremesas e Pastelaria, não por tecnologia ou produção de laranjas.

Pesquisando documentos

A ancoragem de contexto ajuda você a encontrar informações espalhadas por vários documentos. Pode entender as relações entre diferentes informações e fornecer resultados mais relevantes. Por exemplo, se você estiver pesquisando "efeitos das mudanças Climáticas na Agrupação" em vários artigos científicos, ele reunirá informações relevantes de várias fontes, entendendo que tópicos como padrões de pluviosidade, produtividade das colheitas e mudanças de temperatura estão todos relacionados à sua consulta.

Isso significa que você pode usar a Embasamento de Contexto para:

• Extração e comparação de dados: a contextualização pode identificar e extrair automaticamente tipos específicos de informações de documentos e, em seguida, compará-los de formas significativas. Imagine que você tenha uma pilha de currículos e queira comparar as experiências de trabalho dos candidatos. O serviço pode extrair cargos, durações e responsabilidades e, em seguida, apresentá-los de uma forma que facilita a comparação, mesmo que as informações estejam formatadas de forma diferente em cada currículo.
• Resumo: a Contextualização pode criar resumos de documentos longos ou vários documentos relacionados. Não escolhe frases aleatórias, mas entende os pontos-chave e a mensagem geral. Por exemplo, se você tiver um longo relatório sobre as tendências do mercado, o serviço poderá fornecer um resumo que destaca as principais descobertas, principais estatísticas e conclusões gerais.

Notificações

Você pode se inscrever para receber notificações da Contextualização. Acesse o painel Notificações para saber mais.

Os eventos servem como gatilhos para notificações. Os eventos de embasamento de contexto que geram notificações são:

• Trabalho de ingestão concluído
• Falha no trabalho de ingestão
• Trabalho de ingestão iniciado

Você também pode se inscrever em eventos com base em sua gravidade, como Success ou Error.

Trazer seu próprio banco de dados de vetores

Use seu banco de dados de vetores existente para fundamentar respostas de agentes em dados empresariais confiáveis, sem duplicar conteúdo ou alterar sua arquitetura atual.

Este guia mostra como conectar bancos de dados de vetores gerenciados externamente (como Databricks Vetores Search ou Azure AI Search) a agentes da UiPath usando fluxos de trabalho de API, habilitando a geração aumentada de recuperação (RAG) com suas próprias fontes de dados.

Ao final deste guia, você será capaz de:

• Consulte um banco de dados de vetores externo de um agente da UiPath.
• Retornar o conteúdo mais relevante como contexto estruturado.
• Baseie as respostas do agente nos dados da sua organização de forma segura e em tempo real.

Quando usar o padrão traga seu próprio banco de dados de vetores (BYOVD)

Use BYOVD quando:

• Seus dados já estão indexados em um armazenamento de vetores externo.
• Você quer que os agentes acessem o conhecimento empresarial atualizado.
• Você precisa evitar copiar ou reindexar dados na UiPath.
• Você precisa de controle total sobre armazenamento de dados, segurança e incorporações.

Como funciona

O BYOVD permite que os agentes fundamentam respostas de IA generativa em suas fontes de dados confiáveis. Em vez de depender de um índice de Contextualização integrado, você usa fluxos de trabalho de API que consultam com segurança seu banco de dados de vetores externo e retornam contexto relevante ao grande modelo de linguagem do agente.

Essa abordagem dá flexibilidade para integrar qualquer banco de dados de vetores com uma API pública, mantendo o controle sobre o acesso aos dados, autenticação e lógica de recuperação.

A UiPath habilita o BYOVD por meio de fluxos de trabalho de API que atuam como ferramentas para agentes. No runtime:

1. Consulta do usuário: o usuário envia uma solicitação para o agente.
2. Seleção de ferramenta: o LLM do agente determina que contexto adicional é necessário e seleciona a ferramenta de pesquisa de vetor personalizado.
3. Execução de fluxo de trabalho de API: o agente invoca o fluxo de trabalho de API publicado, passando a consulta do usuário como entrada.
4. Pesquisa de vetores: o fluxo de trabalho consulta o banco de dados de vetores para recuperar o conteúdo mais semanticamente relevante.
5. Retorno de contexto: o fluxo de trabalho retorna o conteúdo recuperado como JSON estruturado.
6. Formulação da resposta: o agente usa esse contexto para gerar uma resposta embasada e precisa.

Essa abordagem é compatível com a geração aumentada por Retrieval (RAG) sem exigir ingestão nativa no serviço de Contextualização.

Visão geral da arquitetura

A solução BYOVD consiste em três componentes principais:

• Banco de dados de vetores: seu sistema existente (por exemplo, Pesquisa de vetores do Databricks ou Pesquisa de IA do Azure).
• Fluxo de trabalho da API: um fluxo de trabalho do UiPath Integration Service que:
  • Aceita uma consulta.
  • Chama a API do banco de dados de vetores.
  • Retorna resultados relevantes.
• Ferramenta do agente: o fluxo de trabalho da API publicado, adicionado como uma ferramenta que o agente pode invocar.

Segurança e gerenciamento de credenciais

Antes de criar o fluxo de trabalho, armazene todas as chaves de API e segredos com segurança. Não embuta em código credenciais no seu fluxo de trabalho. Em vez disso, use o armazenamento de credenciais do Orchestrator:

• Armazenamento de credenciais no Orchestrator: adicione suas chaves de API e outros segredos como ativos de credenciais em seu tenant do Orchestrator. Isso proporciona um gerenciamento centralizado e seguro de informações confidenciais.
• Recuperar credenciais no runtime: em seu Fluxo de trabalho de API, use a atividade Get Credential para acessar credenciais armazenadas quando o fluxo de trabalho for executado. A atividade retorna o nome de usuário como uma string e a senha (por exemplo, uma chave de API) como um SecureString, impedindo que os segredos sejam expostos em logs ou definições de fluxo de trabalho.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Um banco de dados de vetores ativo (como a Pesquisa de vetores do Databricks ou a Pesquisa de IA do Azure) com dados indexados.
• Um ponto de extremidade de API válido e credenciais de autenticação armazenadas como ativos de credenciais no Orchestrator.
• Um ponto de extremidade e chave de incorporação de modelo, também armazenados com segurança (apenas para a vetorização do lado do cliente do Azure).

Configuração

É possível implementar o BYOVD usando uma das três abordagens: endpoints nativos do modelo, vetorização no lado do cliente (onde o fluxo de trabalho da API realiza a vetorização), ou vetorização integrada.

As seções a seguir fornecem instruções passo a passo para configurar cada abordagem. Os exemplos usam Databricks e Azure AI Search, mas o mesmo padrão se aplica a outros bancos de dados de vetores. Escolha a configuração que se alinha à forma como seu banco de dados de vetores lida com a vetorização de consultas.

Pesquisa de vetor do Databricks (extremidade do modelo nativo)

Use esta opção quando o Databricks lidar com a vetorização de consultas nativamente.

Por que usar essa opção

• Uma configuração simples
• Apenas uma chamada de API por consulta
• Não é necessário um modelo de incorporação separado

Etapas

1. Obtenha os detalhes do Databricks:
   1. Recupere o URL do ponto de extremidade.
   2. Armazene seu token de acesso pessoal do Databricks como um ativo de credencial no Orchestrator.
2. No Studio, crie um novo projeto de fluxo de trabalho da API e defina os seguintes argumentos:
   • in_QueryText (String)
   • in_TopK (Int32, com um valor padrão de 5)
   • out_Results (String)
3. Use a atividade Get Credential para recuperar o token de acesso pessoal do Databricks do Orchestrator no runtime.
4. Adicione uma atividade HTTP Request para chamar o endpoint do Databricks:
   • Ponto de extremidade: o ponto de extremidade de pesquisa de vetor do Databricks
   • Método: POST
   • Cabeçalhos: Authorization: Bearer <Personal Access Token>
   • Corpo: construa o corpo do JSON exigido pela API do Databricks, mapeando suas variáveis de entrada.
5. Publique o fluxo de trabalho em seu tenant do Orchestrator.
6. Adicione o fluxo de trabalho como uma ferramenta ao seu agente, fornecendo um nome e descrição claros para o LLM a ser usado.

Azure AI Search (vetorização do lado do cliente)

Use essa opção quando seu índice da Azure AI Search esperar entradas de vetor.

Por que usar essa opção

• Controle total sobre a incorporação de modelos
• Compatibilidade com índices de vetores existentes

Etapas

1. Obtenha os detalhes da API:
   • Para Azure AI Search: recupere o URL do endpoint, nome do índice e armazene sua chave de API como um ativo de credencial no Orchestrator.
   • Para o modelo de incorporação: recupere o URL do endpoint e armazene a chave de API para seu serviço de incorporação como um ativo de credencial no Orchestrator.
2. No Studio, crie um novo projeto de fluxo de trabalho da API e defina os seguintes argumentos:
   • in_QueryText (String)
   • in_TopK (Int32, com um valor padrão de 5)
   • out_Results (String)
3. Primeiro, vetorize a consulta:
   1. Adicione uma atividade Get Credential para recuperar a chave de API do seu modelo de incorporação.
   2. Adicione uma atividade HTTP Request para chamar seu modelo de incorporação com o in_QueryText.
   3. Deserialize a resposta JSON e armazene o vetor de incorporação resultante em uma variável (por exemplo, queryVector).
4. Consultar Pesquisa de IA do Azure:
   1. Adicione uma atividade Get Credential para recuperar sua chave de API do Azure AI Search.
   2. Adicione uma atividade HTTP Request e configure-a da seguinte forma:
      • Ponto de extremidade: seu ponto de extremidade do Azure AI Search.
      • Método: POST.
      • Cabeçalhos: adicione um cabeçalho api-key com sua variável de chave da API do Azure AI Search, da seguinte forma: api-key: <API key>.
      • Corpo: construa o corpo JSON para a consulta de pesquisa de vetores da Pesquisa de IA do Azure, incorporando sua variável queryVector .
5. Publique o fluxo de trabalho em seu tenant do Orchestrator.
6. Adicione o fluxo de trabalho publicado como uma ferramenta ao seu agente, fornecendo uma descrição clara para o LLM a ser usado.

Azure AI Search (vetorização integrada)

Use essa opção quando seu índice do Azure AI Search for compatível com vetorização integrada.

Por que usar essa opção

• Configuração mais simples do Azure
• Nenhuma chamada incorporada no fluxo de trabalho
• Solicitação de API única por consulta

Etapas

1. Obtenha os detalhes da API:
   • Recupere seu URL do endpoint do Azure AI Search, nome do índice e armazene sua chave de API como um ativo de credencial no Orchestrator.
2. No Studio, crie um novo projeto de fluxo de trabalho da API e defina os seguintes argumentos:
   • in_QueryText (String)
   • in_TopK (Int32, com um valor padrão de 5)
   • out_Results (String)
3. Adicione uma atividade Get Credential para recuperar sua chave de API do Azure AI Search do Orchestrator.
4. Adicione uma atividade HTTP Request e configure-a da seguinte forma:
   • Ponto de extremidade:

     https://<service>.search.windows.net/indexes/<index-name>/docs/search?api-version=2023-11-01
     

   • Método: POST
   • Cabeçalhos: adicione um cabeçalho api-key com sua variável de chave da API do Azure AI Search, da seguinte maneira: api-key: <API key>
   • Corpo: construa o corpo JSON para realizar uma pesquisa de vetor usando o texto da consulta. O Azure AI Search lida com a vetorização automaticamente.

     {
       "vectorQueries": [
         {
           "kind": "text",
           "text": "<%= in_QueryText %>",
           "fields": "contentVector",
           "k": "<%= in_TopK %>"
         }
       ],
       "select": "chunk, source_document"
     }
     

5. Publique o fluxo de trabalho em seu tenant do Orchestrator.
6. Adicione o fluxo de trabalho publicado como uma ferramenta ao seu agente, fornecendo uma descrição clara para o LLM.