Criar uma base de dados de conhecimento para fluxos de trabalho agente a serem usados em Aplicativos Lógicos do Azure (versão prévia)

Aplica-se a: Aplicativos Lógicos do Azure (Standard)

Note

Este recurso de visualização está sujeito aos Termos de Uso Complementares para Visualizações do Microsoft Azure.

Sua organização gera dados não estruturados de documentos, planilhas, APIs e sistemas internos. Ao usar o recurso Knowledge Base-as-a-Service (KBaaS) no Aplicativos Lógicos do Azure, você pode converter esse conteúdo em uma base de conhecimento estruturada e mais fácil de pesquisar, que os loops de agente em fluxos de trabalho agênticos podem usar para concluir tarefas. Uma base de dados de conhecimento é um contêiner lógico que organiza fontes de conhecimento relacionadas, como documentos ou arquivos relacionados a um domínio específico.

Por exemplo, você pode criar uma base de dados de conhecimento que contenha todos os documentos relacionados a políticas e procedimentos de RH. Quando você cria uma base de dados de conhecimento, o KBaaS configura automaticamente os bancos de Azure Cosmos DB dados, contêineres e políticas de indexação necessários. Para obter mais informações, consulte Azure Cosmos DB bancos de dados, contêineres e itens.

Este guia mostra como criar uma base de dados de conhecimento, carregar fontes de conhecimento e adicionar a base de dados de conhecimento como uma ferramenta que um loop de agente pode usar em um fluxo de trabalho agente Standard.

Limitações

Esta versão prévia tem as seguintes limitações:

• Esta versão prévia dá suporte aos seguintes recursos:

  • Arquivos carregados como o tipo de origem para artefatos de conhecimento.
  • Arquivos com os seguintes formatos: DOC, DOCX, HTML, MD, PDF, PPT, PPTX, TXT, XLS, XLSX.
  • Análise de conteúdo baseada em texto em documentos, não em imagens.
  • Configurações de agrupamento padrão, não agrupamento personalizado.

• Depois de criar sua conexão da base de conhecimento, você pode editar apenas os nomes de exibição da conexão e dos modelos do Azure OpenAI. Não é possível editar outros valores, como o tipo de autenticação ou as informações do ponto de extremidade.

• No momento, somente o portal de Azure tem suporte para essa funcionalidade.

Como funciona uma base de dados de conhecimento

O KBaaS simplifica a transformação de dados e fornece uma camada de abstração sobre Azure Cosmos DB e Azure OpenAI para que seus fluxos de trabalho possam consumir, processar e recuperar conhecimento estruturado com mais facilidade sem criar um pipeline personalizado de geração de Retrieval-Augmented (RAG).

O KBaaS tem os seguintes pipelines:

• Pipeline de ingestão: quando você carrega um documento ou fonte de dados de conhecimento em sua base de dados de conhecimento, o serviço analisa automaticamente, agrupa, resume e vetoriza o conteúdo. Em seguida, o serviço armazena os resultados em Azure Cosmos DB.

• Pipeline de recuperação: quando o loop do agente consulta sua base de conhecimento, o serviço reescreve a consulta, se necessário, gera uma representação vetorial, realiza uma pesquisa semântica no Azure Cosmos DB e retorna os trechos mais relevantes ao modelo de linguagem de grande porte (LLM) para gerar a resposta.

Prerequisites

• Uma conta Azure e uma assinatura. Obtenha uma conta gratuita do Azure.

• Um recurso Azure OpenAI. Para obter mais informações, consulte Criar e implantar um recurso Serviço OpenAI do Azure.

  • Seu recurso precisa dos seguintes modelos implantados:

    • Um modelo de conclusões, como gpt-4o.
    • Um modelo de inserções, como text-embedding-3-small.

• Uma conta do Azure Cosmos DB para NoSQL.

  • Antes de criar sua base de dados de conhecimento, habilite a pesquisa de vetor em sua conta do Cosmos DB. Essa operação pode levar até 15 minutos antes da conclusão.

    Para obter mais informações, consulte:

    • Início rápido: criar uma conta do Azure Cosmos DB for NoSQL usando o portal do Azure
    • Busca vetorial no Azure Cosmos DB para NoSQL

• Um aplicativo lógico padrão e um fluxo de trabalho agêntico.

  Para obter mais informações, consulte:

  • Criar fluxos de trabalho agentes autônomos sem interações humanas no Aplicativos Lógicos do Azure
  • Criar fluxos de trabalho conversacionais com agentes com interações de chat no Aplicativos Lógicos do Azure

Autenticação

O recurso KBaaS dá suporte à autenticação usando Microsoft Entra ID com uma identidade manada ou uma chave de API. Se possível, configure e use uma identidade gerenciada para segurança ideal e superior. Você não precisa fornecer e gerenciar manualmente credenciais, segredos ou chaves de acesso.

Se você usar uma chave de API, proteja e proteja dados confidenciais e pessoais, como credenciais, segredos, chaves de acesso, cadeias de conexão, certificados, impressões digitais e informações semelhantes com o nível mais alto disponível ou com suporte de segurança. Armazene essas informações com segurança usando Microsoft Entra ID e Azure Key Vault. Não codifique essas informações, compartilhe com outros usuários ou salve em texto sem formatação em qualquer lugar que outras pessoas possam acessar. Defina um plano para alternar ou revogar segredos caso sejam comprometidos.

Para obter mais informações, consulte os seguintes recursos:

• Automatizar a rotação de segredos no Azure Key Vault
• Práticas recomendadas para proteger segredos
• Segredos no Azure Key Vault

1: Criar a conexão da base de conhecimento

Para criar a conexão da base de conhecimento, associe seu banco de dados Cosmos aos modelos de recurso do Azure OpenAI, seguindo estas etapas:

1a: Configurar a conexão de banco de dados do Cosmos

1. No portal do Azure, abra seu recurso de aplicativo lógico Padrão.

2. Na barra lateral do aplicativo lógico, em Agentes, selecione Base de dados de conhecimento.

3. Na página base de dados de conhecimento , selecione Configurar.

4. No painel Configurar , na guia Noções básicas , forneça as seguintes informações:

   Parâmetro	Obrigatório	Descrição
   Nome de exibição	Sim	Um nome legível para a sua conexão com a base de conhecimento. Use o mesmo nome que a base de dados de conhecimento que você planeja criar para que a ação de recuperação possa associar a conexão correta.
   Tipo de autenticação	Sim	Identidade de serviço gerenciada ou baseada em chave
   Subscription	Sim	Sua assinatura do Azure.
   Banco de dados	Sim	Seu banco de dados do Cosmos.
   endpoint de URL	Sim	Sua seleção de banco de dados preenche automaticamente esse valor.
   Chave	Sim	Disponível somente se você selecionar a autenticação baseada em chave . Sua seleção de banco de dados preenche automaticamente esse valor.

5. Ao terminar, selecione Avançar.

1b: Configurar a conexão de recurso Azure OpenAI

1. Na guia Modelo , forneça as seguintes informações:

   Parâmetro	Obrigatório	Descrição
   Tipo de autenticação	Sim	URL e autenticação baseada em chave ou Identidade de Serviço Gerenciado
   Subscription	Sim	Sua assinatura do Azure.
   Recurso do Azure OpenAI	Sim	Seu recurso Azure OpenAI.
   Ponto de extremidade da API	Sim	Sua seleção de recursos Azure OpenAI preenche automaticamente esse valor.
   Chave de API	Sim	Disponível somente se você selecionar URL e autenticação baseada em chave. Sua seleção de recursos Azure OpenAI preenche automaticamente esse valor.
   Modelo de conclusões	Sim	Insira o nome de exibição do modelo de conclusões implantado para o recurso Azure OpenAI.
   Modelo de inserções	Sim	Insira o nome de exibição do modelo de inserções implantado para o recurso Azure OpenAI.

2. Quando terminar, selecione Criar.

2: Adicionar artefatos de conhecimento

Depois de criar sua conexão de base de dados de conhecimento, adicione os arquivos de informações de origem a serem usados como artefatos de conhecimento em sua base de dados de conhecimento.

1. No portal do Azure, abra seu recurso de aplicativo lógico Padrão.

2. Na barra lateral do aplicativo lógico, em Agentes, selecione Base de dados de conhecimento.

3. Se você quiser criar um grupo antes de adicionar arquivos, na barra de ferramentas da página base de dados de conhecimento , selecione Nova>Criação de novo grupo e, em seguida, siga os prompts para criar o grupo.

4. Na página base de dados de conhecimento , selecione Adicionar arquivos. Ou, na barra de ferramentas da página, selecione Novo>Adicionar arquivos.

5. No painel Adicionar arquivos , conclua as seguintes tarefas:

   1. Na seção Grupo , insira as seguintes informações:

      Parâmetro	Obrigatório	Descrição
      Name	Sim	O nome do grupo que organiza arquivos em sua base de dados de conhecimento. Insira um novo nome ou selecione um grupo existente.
      Description	No	Uma descrição opcional para o grupo.

   2. Na seção Adicionar arquivos, selecione Procurar para carregar ou arraste e solte arquivos no seu grupo. Para cada arquivo, insira as seguintes informações:

      Parâmetro	Obrigatório	Valor	Descrição
      Name	Sim	< nome-fonte>	Um nome para o arquivo como uma fonte de conhecimento, por exemplo, HRPolicyDocument.
      Description	No	< descrição da fonte>	Uma descrição opcional para o arquivo como uma fonte de conhecimento.

6. Quando terminar, selecione Adicionar.

   O KBaaS cria os seguintes contêineres do Cosmos DB:

   Contêiner	Purpose
   KnowledgeHubs	Armazena metadados da base de dados de conhecimento.
   KnowledgeArtifacts	Armazena os metadados de origem e as referências de documento de origem.
   KnowledgeArtifactChunks	Armazena partes de documento de texto completo.
   KnowledgeArtifactChunkSummaries	Armazena partes resumidas com inserções de vetor para pesquisa semântica.

   O KBaaS retorna uma resposta aceita 202 com uma ID de operação para acompanhar o progresso do upload.

   Durante o processo de upload, o KBaaS executa operações para analisar, agrupar, resumir, inserir e armazenar conteúdo vetorizado no contêiner do Cosmos DB. Quando o processo for concluído, o status da origem muda para Concluído ou Falha, dependendo do resultado.

7. Monitore o status de upload no portal do Azure ou usando a ID da operação.

8. Quando o KBaaS for concluído, continue para a próxima seção para adicionar a base de conhecimento como uma ferramenta a ser usada pelo loop do agente no seu workflow Standard agêntico.

3: Adicionar a base de dados de conhecimento como uma ferramenta

Agora você pode adicionar a base de dados de conhecimento ao loop do agente para usar como uma ferramenta em seus fluxos de trabalho padrão agente. Os loops do agente consultam automaticamente a base de dados de conhecimento para recuperar informações semanticamente relevantes de seus documentos carregados.

1. No mesmo aplicativo lógico Standard que inclui sua base de conhecimento, no designer, abra seu fluxo de trabalho agêntico e selecione o loop de agente desejado.

2. No painel de informações do agente, na seção Base de dados de conhecimento , selecione Criar.

3. No painel Criar Conexão , na lista Fontes , selecione a base de dados de conhecimento.

4. Para carregar mais arquivos em sua base de dados de conhecimento, selecione + Carregar.

Gerenciar bases de dados de conhecimento e fontes

Para listar, exibir e excluir bases de dados de conhecimento ou fontes, use o portal Azure ou a API REST.

Listar todas as bases de dados de conhecimento

1. No portal do Azure, abra seu recurso de aplicativo lógico Padrão.

2. Na barra lateral do aplicativo lógico, em Agentes, selecione Base de dados de conhecimento.

Ou faça a seguinte chamada à API REST:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{logicAppName}/hostruntime/runtime/webhooks/workflow/api/management/knowledgehubs

Exibir uma base de dados de conhecimento específica

No portal Azure, na página Knowledge base, selecione o nome da base de dados de conhecimento.

Ou faça a seguinte chamada à API REST:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{logicAppName}/hostruntime/runtime/webhooks/workflow/api/management/knowledgehubs/{knowledgeBaseName}

A resposta inclui as informações da base de dados de conhecimento, uma lista com as fontes associadas e seu status de upload.

Listar fontes em uma base de dados de conhecimento

No portal Azure, selecione a base de dados de conhecimento para exibir suas fontes.

Ou faça a seguinte chamada à API REST:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{logicAppName}/hostruntime/runtime/webhooks/workflow/api/management/knowledgehubs/{knowledgeBaseName}/knowledgeArtifacts

Excluir uma fonte de conhecimento

Essa operação remove os metadados de origem, as partes de texto completo e as inserções de vetor do Cosmos DB. O serviço retorna uma resposta aceita 202 com uma ID de operação para acompanhar o progresso da exclusão.

1. No portal Azure, selecione a base de dados de conhecimento para exibir suas fontes.

2. Selecione a fonte. Na barra de ferramentas, selecione Excluir.

Ou faça a seguinte chamada à API REST:

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{logicAppName}/hostruntime/runtime/webhooks/workflow/api/management/knowledgehubs/{knowledgeBaseName}/knowledgeArtifacts/{artifactName}

Excluir uma base de dados de conhecimento

Esta operação remove a base de conhecimento e as fontes, os fragmentos e os resumos associados no Cosmos DB.

1. No portal Azure, selecione a base de dados de conhecimento.

2. Na barra de ferramentas, selecione Excluir.

Ou faça a seguinte chamada à API REST:

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{logicAppName}/hostruntime/runtime/webhooks/workflow/api/management/knowledgehubs/{knowledgeBaseName}

Conteúdo relacionado

• O que é Aplicativos Lógicos do Azure?
• Serviço OpenAI do Azure
• Azure Cosmos DB Vector Search
• Repositório de vetores integrado – Azure Cosmos DB para NoSQL