Bring your own vector database

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.
• Ground agent responses in your organization's data securely and in real time.

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

BYOVD allows agents to ground generative AI responses in your trusted data sources. Instead of relying on a built-in Context Grounding index, you use API workflows that securely query your external vector database and return relevant context to the agent's large language model.

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. Tool selection: The agent's LLM determines that additional context is required and selects the custom vector search tool.
3. API Workflow execution: The agent invokes the published API Workflow, passing the user's query as input.
4. Pesquisa de vetores: o fluxo de trabalho consulta o banco de dados de vetores para recuperar o conteúdo mais semanticamente relevante.
5. Context return: The workflow returns the retrieved content as structured JSON.
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 esta 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 esta 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.
      • Method: POST.
      • Headers: Add an api-key header with your Azure AI Search API key variable, as follows: api-key: <API key>.
      • Body: Construct the JSON body for the Azure AI Search vector search query, embedding your queryVector variable.
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 esta 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.