Crie uma base de conhecimento para fluxos de trabalho agentivos para usar no Azure Logic Apps (pré-visualização)

Aplica-se a: Aplicativos Lógicos do Azure (Padrão)

A sua organização gera dados não estruturados a partir de documentos, folhas de cálculo, APIs e sistemas internos. Ao usar a funcionalidade Knowledge Base-as-a-Service (KBaaS) em Azure Logic Apps, pode converter este conteúdo numa knowledge base estruturada e mais pesquisável, que os ciclos de agentes nos fluxos de trabalho agenticos podem usar para completar tarefas. Uma base de conhecimento é um contentor lógico que organiza fontes de conhecimento relacionadas, como documentos ou ficheiros relacionados com um domínio específico.

Por exemplo, pode criar uma base de conhecimento que contenha todos os documentos relacionados com políticas e procedimentos de RH. Quando cria uma base de conhecimento, o KBaaS configura automaticamente as bases de dados, contentores e políticas de indexação necessárias do Azure Cosmos DB. Para mais informações, consulte Azure Cosmos DB bases de dados, contentores e itens.

Este guia mostra como criar uma base de conhecimento, carregar fontes de conhecimento e adicionar a base de conhecimento como uma ferramenta que um loop de agente pode usar num fluxo de trabalho agentical padrão.

Limitações

Esta versão de pré-visualização apresenta as seguintes limitações:

• Esta pré-visualização suporta as seguintes capacidades:

  • Ficheiros carregados como tipo de origem para artefactos de conhecimento.
  • Ficheiros com os seguintes formatos: DOC, DOCX, HTML, MD, PDF, PPT, PPT, TXT, XLS, XLSX.
  • Análise de conteúdos baseados em texto em documentos, não em imagens.
  • Definições padrão de segmentação, não personalizadas.

• Depois de criar a sua ligação à base de conhecimento, pode editar apenas os nomes de visualização para os modelos da ligação e do Azure OpenAI. Não podes editar outros valores, como o tipo de autenticação ou a informação do endpoint.

• Apenas o portal Azure é atualmente suportado para esta funcionalidade.

Como funciona uma base 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 os seus fluxos de trabalho possam consumir, processar e recuperar conhecimento estruturado mais facilmente sem construir um pipeline personalizado de geração de Retrieval-Augmented (RAG).

O KBaaS tem os seguintes pipelines:

• Pipeline de ingestão: Quando carrega um documento, ou fonte de conhecimento, para a sua base de conhecimento, o serviço analisa, fragmenta, resume e vetoriza automaticamente o conteúdo. O serviço armazena então os resultados no Azure Cosmos DB.

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

Pré-requisitos

• Uma conta Azure e uma assinatura. Crie uma conta Azure gratuita.

• Um recurso OpenAI do Azure. Para mais informações, consulte Criar e implementar um recurso Azure OpenAI Service.

  • O seu recurso necessita dos seguintes modelos implementados:

    • Um modelo de completamento, como gpt-4o.
    • Um modelo de embeddings, como text-embedding-3-small.

• Uma conta do Azure Cosmos DB para NoSQL.

  • Antes de criar a sua base de conhecimento, ative a pesquisa vetorial na sua conta Cosmos DB. Esta operação pode demorar até 15 minutos até ser concluída.

    Para obter mais informações, consulte:

    • Início rápido: Criar uma conta do Azure Cosmos DB para NoSQL com o portal do Azure
    • Pesquisa vetorial em Azure Cosmos DB para NoSQL

• Uma aplicação lógica Standard e um fluxo de trabalho agêntico.

  Para obter mais informações, consulte:

  • Criar fluxos de trabalho agentivos autónomos sem interações humanas em Azure Logic Apps
  • Crie fluxos de trabalho agentes conversacionais com interações de chat em Azure Logic Apps

Authentication

A capacidade KBaaS suporta a autenticação utilizando o Microsoft Entra ID com uma identidade gerida ou uma chave de API. Se possível, configure e utilize uma identidade gerida para garantir uma segurança ótima e superior. Não precisa de fornecer e gerir manualmente credenciais, segredos ou chaves de acesso.

Se usar uma chave API, proteja e proteja dados sensíveis e pessoais, como credenciais, segredos, chaves de acesso, cadeias de ligação, certificados, impressões digitais e informações semelhantes com o nível de segurança mais elevado disponível ou suportado. Armazene essa informação de forma segura usando Microsoft Entra ID e Azure Key Vault. Não codifice 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 credenciais secretas, caso sejam comprometidas.

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 ligação à base de conhecimento

Para criar a ligação à base de conhecimento, associe a sua base de dados Cosmos e os modelos de recursos do Azure OpenAI seguindo estes passos:

1a: Configurar a ligação à base de dados Cosmos

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

2. Na barra lateral da aplicação lógica, em Agentes, selecione Base de conhecimento.

3. Na página da Base de Conhecimento, selecione Configurar.

4. No painel de Configuração , no separador Básicos , forneça a seguinte informação:

   Parâmetro	Obrigatório	Description
   Nome de exibição	Sim	Um nome legível para humanos para a sua ligação à base de conhecimento. Use o mesmo nome da base de conhecimento que planeia criar para que a ação de recuperação possa associar a ligação correta.
   Tipo de autenticação	Sim	Baseada em chave ou Identidade de Serviço Gerida
   Subscription	Sim	A tua subscrição do Azure.
   Database	Sim	A tua base de dados Cosmos.
   URL do ponto final	Sim	A sua seleção da base de dados preenche automaticamente este valor.
   Chave	Sim	Disponível apenas se selecionar autenticação baseada em chaves . A sua seleção da base de dados preenche automaticamente este valor.

5. Quando terminar, selecione Avançar.

1b: Configurar a ligação de recursos Azure OpenAI

1. No separador Modelo , forneça a seguinte informação:

   Parâmetro	Obrigatório	Description
   Tipo de autenticação	Sim	Autenticação baseada em URL e chave ou Identidade de Serviço Gerido
   Subscription	Sim	A tua subscrição do Azure.
   recurso Azure OpenAI	Sim	O seu recurso Azure OpenAI.
   API Endpoint	Sim	A sua seleção de recursos Azure OpenAI preenche automaticamente este valor.
   Chave de API	Sim	Disponível apenas se selecionar autenticação baseada em URL e chaves. A sua seleção de recursos Azure OpenAI preenche automaticamente este valor.
   Modelo de completações	Sim	Introduza o nome de visualização do modelo de completações implementado para o seu recurso Azure OpenAI.
   Modelo de incorporações	Sim	Introduza o nome de visualização do modelo de embeddings implementado para o seu recurso Azure OpenAI.

2. Quando terminar, selecione Criar.

2: Adicionar artefactos de conhecimento

Depois de criar a sua ligação à base de conhecimento, adicione os ficheiros de informação de origem para usar como artefactos de conhecimento na sua base de conhecimento.

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

2. Na barra lateral da aplicação lógica, em Agentes, selecione Base de conhecimento.

3. Se quiser criar um grupo antes de adicionar ficheiros, na barra de ferramentas da página da Base de Conhecimento , selecione Novo>Criar novo grupo e depois siga os prompts para criar o grupo.

4. Na página da Base de Conhecimento, selecione Adicionar ficheiros. Ou, na barra de ferramentas da página, selecione Novos>Adicionar ficheiros.

5. No painel Adicionar ficheiros , complete as seguintes tarefas:

   1. Na secção de Grupo , introduza a seguinte informação:

      Parâmetro	Obrigatório	Description
      Nome	Sim	O nome do grupo que organiza ficheiros na tua base de conhecimento. Insira um novo nome ou selecione um grupo existente.
      Description	No	Uma descrição opcional para o grupo.

   2. Na secção Adicionar ficheiros , selecione navegar para carregar ou arrastar e largar ficheiros para o seu grupo. Para cada ficheiro, introduza a seguinte informação:

      Parâmetro	Obrigatório	valor	Description
      Nome	Sim	< Nome de origem>	Um nome para o ficheiro como fonte de conhecimento, por exemplo, HRPolicyDocument.
      Description	No	< fonte-descrição>	Uma descrição opcional do ficheiro como fonte de conhecimento.

6. Quando terminar, selecione Adicionar.

   O KBaaS cria os seguintes contentores Cosmos DB:

   Contentor	Purpose
   KnowledgeHubs	Armazena metadados da base de conhecimento.
   Artefactos de Conhecimento	Armazena metadados de origem e referências de documentos de origem.
   FragmentosDeArtefactoDeConhecimento	Armazena blocos de documentos em texto integral.
   ResumosFragmentosArtefactos do Conhecimento	Armazena blocos resumidos com incorporações vetoriais para pesquisa semântica.

   O KBaaS devolve uma resposta 202 Aceite com um ID de operação para acompanhar o progresso do carregamento.

   Durante o processo de upload, o KBaaS realiza operações para analisar, fragmentar, resumir, incorporar e armazenar conteúdo vetorizado no contentor da base de dados Cosmos. Quando o processo termina, o estado da fonte muda para Concluído ou Falhado, consoante o resultado.

7. Monitorize o estado do carregamento no portal do Azure ou usando o ID da operação.

8. Depois de o KBaaS estar concluído, avance para a secção seguinte para poder adicionar a base de conhecimento como ferramenta para o seu ciclo do agente utilizar no seu fluxo de trabalho Standard agêntico.

3: Adicionar a base de conhecimento como ferramenta

Agora pode adicionar a base de conhecimento ao ciclo do agente para a utilizar como ferramenta nos seus fluxos de trabalho Standard baseados em agentes. Os loops de agentes consultam automaticamente a base de conhecimento para recuperar informação semanticamente relevante dos seus documentos carregados.

1. Na mesma aplicação de lógica Standard que inclui a tua base de conhecimento, no designer, abre o teu fluxo de trabalho agentical e seleciona o loop de agente que queres.

2. No painel de informação do agente, na secção da Base de Conhecimento , selecione Criar.

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

4. Para carregar mais ficheiros na sua base de conhecimento, selecione + Carregar.

Gerir bases de conhecimento e fontes

Para listar, visualizar e eliminar bases de conhecimento ou fontes, utilize o portal Azure ou a API REST.

Listar todas as bases de conhecimento

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

2. Na barra lateral da aplicação lógica, em Agentes, selecione Base 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

Consulte uma base de conhecimento específica

No portal Azure, a partir da página Knowledge base, selecione o nome da base 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 a informação da base de conhecimento, uma lista com as fontes associadas e o seu estado de upload.

Liste as fontes numa base de conhecimento

No portal Azure, selecione a base de conhecimento para visualizar as 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

Eliminar uma fonte de conhecimento

Esta operação remove os metadados de origem, blocos de texto completo e embeddings vetoriais do Cosmos DB. O serviço devolve uma resposta 202 Aceite com um ID de operação para acompanhar o progresso da eliminação.

1. No portal Azure, selecione a base de conhecimento para visualizar as suas fontes.

2. Selecione a origem. Na barra de ferramentas, selecione Eliminar.

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}

Apagar uma base de conhecimento

Esta operação remove a base de conhecimento e as fontes, blocos e resumos associados do Cosmos DB.

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

2. Na barra de ferramentas, selecione Eliminar.

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 é Azure Logic Apps?
• Azure OpenAI Service
• Azure Cosmos DB Pesquisa Vetorial
• Armazenamento vetorial integrado - Azure Cosmos DB para NoSQL