Creare una Knowledge Base per i flussi di lavoro agenti da usare in App per la logica di Azure (anteprima)

Si applica a: App per la logica di Azure (Standard)

L'organizzazione genera dati non strutturati da documenti, fogli di calcolo, API e sistemi interni. Utilizzando la funzionalità Knowledge Base-as-a-Service (KBaaS) in App per la logica di Azure, è possibile convertire questo contenuto in una knowledge base strutturata e più facilmente ricercabile che i loop degli agenti nei flussi di lavoro agentici possono usare per completare le attività. Una base di conoscenza è un container logico che organizza fonti di conoscenza correlate, come documenti o file relativi a un dominio specifico.

Ad esempio, è possibile creare una knowledge base contenente tutti i documenti correlati a criteri e procedure hr. Quando si crea una knowledge base, KBaaS configura automaticamente i database, i contenitori e i criteri di indicizzazione necessari Azure Cosmos DB. Per altre informazioni, vedere Azure Cosmos DB database, contenitori ed elementi.

Questa guida illustra come creare una knowledge base, caricare le origini delle informazioni e aggiungere la Knowledge Base come strumento che un ciclo di agenti può usare in un flusso di lavoro agente standard.

Limitations

Questa versione di anteprima presenta le limitazioni seguenti:

• Questa anteprima supporta le funzionalità seguenti:

  • File caricati come tipo di origine per gli artefatti della knowledge base.
  • File con i formati seguenti: DOC, DOCX, HTML, MD, PDF, PPT, PPTX, TXT, XLS, XLSX.
  • Analisi del contenuto basata su testo in documenti, non immagini.
  • Impostazioni predefinite per la suddivisione in blocchi, non la suddivisione in blocchi personalizzata.

• Dopo aver creato la connessione della knowledge base, è possibile modificare solo i nomi visualizzati della connessione e dei modelli di Azure OpenAI. Non è possibile modificare altri valori, ad esempio il tipo di autenticazione o le informazioni sull'endpoint.

• Per questa funzionalità è attualmente supportato solo il portale di Azure.

Funzionamento di una knowledge base

KBaaS semplifica la trasformazione dei dati e fornisce un livello di astrazione su Azure Cosmos DB e Azure OpenAI in modo che i flussi di lavoro possano usare, elaborare e recuperare informazioni strutturate più facilmente senza creare una pipeline di Retrieval-Augmented Generation (RAG) personalizzata.

KBaaS include le pipeline seguenti:

• Pipeline di acquisizione: Quando si carica un documento o una fonte di conoscenza nella propria knowledge base, il servizio analizza automaticamente il contenuto, lo suddivide in blocchi, lo riepiloga e lo vettorizza. Il servizio archivia quindi i risultati in Azure Cosmos DB.

• PipelineRetrieval: quando il ciclo dell'agente esegue una query sulla knowledge base, il servizio riscrive la query, se necessario, genera una rappresentazione vettoriale, esegue una ricerca semantica su Azure Cosmos DB e restituisce i blocchi più rilevanti al modello LLM (Large Language Model) per la generazione di risposte.

Prerequisiti

• Account e sottoscrizione di Azure. Ottenere un account Azure gratuito.

• Una risorsa Azure OpenAI. Per altre informazioni, vedere Creare e distribuire una risorsa Servizio Azure OpenAI.

  • La risorsa richiede i seguenti modelli distribuiti:

    • Modello di completamenti, ad esempio gpt-4o.
    • Modello di incorporamento, ad esempio text-embedding-3-small.

• Un account di Azure Cosmos DB per NoSQL.

  • Prima di creare la knowledge base, abilitare la ricerca vettoriale nell'account Cosmos DB. Questa operazione potrebbe richiedere fino a 15 minuti prima del completamento.

    Per ulteriori informazioni consulta:

    • Quickstart: Creare un Azure Cosmos DB per NoSQL account usando il portale di Azure
    • Ricerca vettoriale in Azure Cosmos DB per NoSQL

• Un'app per la logica standard e un flusso di lavoro agentico.

  Per ulteriori informazioni consulta:

  • Creare flussi di lavoro agenti autonomi senza interazioni umane in App per la logica di Azure
  • Crea flussi di lavoro conversazionali basati su agenti con interazioni tramite chat in App per la logica di Azure

Authentication

La funzionalità KBaaS supporta l'autenticazione usando Microsoft Entra ID con un'identità managed identity o una chiave API. Se possibile, configurare e usare un'identità gestita per una sicurezza ottimale e superiore. Non è necessario specificare e gestire manualmente credenziali, segreti o chiavi di accesso.

Se si utilizza una chiave API, mettere al sicuro e proteggere i dati sensibili e personali, ad esempio credenziali, segreti, chiavi di accesso, stringhe di connessione, certificati, impronte digitali e informazioni simili, con il livello di sicurezza più elevato disponibile o supportato. Archiviare in modo sicuro tali informazioni usando Microsoft Entra ID e Azure Key Vault. Non inserire queste informazioni come codice fisso, non condividerle con altri utenti, e non salvarle in testo non crittografato ovunque possano accedervi altri utenti. Definire un piano per sostituire o revocare i segreti nel caso in cui vengano compromessi.

Per ulteriori informazioni, vedi le seguenti risorse:

• Automatizzare il ciclo di rotazione dei segreti in Azure Key Vault
• Procedure consigliate per la protezione dei segreti
• Segreti in Azure Key Vault

1: Creare la connessione alla base di conoscenza

Per creare la connessione alla base di conoscenza, associa il tuo database Cosmos e i modelli della risorsa Azure OpenAI seguendo questi passaggi:

1a: Configurare la connessione al database Cosmos

1. Nel portale di Azure, aprire la risorsa dell’app per la logica Standard.

2. Nella barra laterale dell'app per la logica, in Agenti selezionare Knowledge Base.

3. Nella pagina Knowledge Base selezionare Configura.

4. Nel riquadro Configura specificare le informazioni seguenti nella scheda Informazioni di base :

   Parametro	Obbligatorio	Descrizione
   Nome visualizzato	Sì	Nome leggibile per la connessione alla Knowledge Base. Usare lo stesso nome della Knowledge Base che si prevede di creare in modo che l'azione di recupero possa associare la connessione corretta.
   Tipo di autenticazione	Sì	Identità del servizio gestita o basata su chiave
   Subscription	Sì	La sottoscrizione di Azure.
   Banca dati	Sì	Il database Cosmos personale.
   Endpoint URL	Sì	La selezione del database popola automaticamente questo valore.
   Chiave	Sì	Disponibile solo se si seleziona Autenticazione basata su chiave . La selezione del database popola automaticamente questo valore.

5. Al termine selezionare Avanti.

1b: Configurare la connessione alla risorsa OpenAI Azure

1. Nella scheda Modello specificare le informazioni seguenti:

   Parametro	Obbligatorio	Descrizione
   Tipo di autenticazione	Sì	Autenticazione basata su URL e chiave o identità del servizio gestita
   Subscription	Sì	La sottoscrizione di Azure.
   Risorsa OpenAI di Azure	Sì	La tua risorsa Azure OpenAI.
   Endpoint API	Sì	La selezione della risorsa di Azure OpenAI compila automaticamente questo valore.
   Chiave API	Sì	Disponibile solo se si seleziona l'URL e l'autenticazione basata su chiave. La selezione della risorsa OpenAI Azure popola automaticamente questo valore.
   Modello di completamenti	Sì	Immettere il nome visualizzato per il modello di completamento distribuito per la risorsa OpenAI Azure.
   Modello di incorporamento	Sì	Immetti il nome visualizzato per il modello di embedding distribuito per la tua risorsa Azure OpenAI.

2. Al termine, selezionare Crea.

2: Aggiungere artefatti di conoscenza

Dopo aver creato la connessione alla Knowledge Base, aggiungere i file di informazioni di origine da usare come artefatti della Knowledge Base.

1. Nel portale di Azure, aprire la risorsa dell’app per la logica Standard.

2. Nella barra laterale dell'app per la logica, in Agenti selezionare Knowledge Base.

3. Se si desidera creare un gruppo prima di aggiungere file, nella barra degli strumenti della pagina Knowledge Base selezionare Nuovo> nuovo e quindi seguire le istruzioni per creare il gruppo.

4. Nella pagina Knowledge Base selezionare Aggiungi file. In alternativa, sulla barra degli strumenti della pagina selezionare Nuovo>aggiungi file.

5. Nel riquadro Aggiungi file completare le attività seguenti:

   1. Nella sezione Gruppo immettere le informazioni seguenti:

      Parametro	Obbligatorio	Descrizione
      Nome	Sì	Nome del gruppo che organizza i file nella knowledge base. Immettere un nuovo nome o selezionare un gruppo esistente.
      Description	No	Descrizione facoltativa per il gruppo.

   2. Nella sezione Aggiungi file selezionare Sfoglia per caricare o trascinare i file nel gruppo. Per ogni file immettere le informazioni seguenti:

      Parametro	Obbligatorio	Value	Descrizione
      Nome	Sì	< source-name>	Un nome per il file come fonte di conoscenza, per esempio, HRPolicyDocument.
      Description	No	< source-description>	Descrizione facoltativa per il file come origine delle informazioni.

6. Al termine, selezionare Aggiungi.

   KBaaS crea i contenitori Cosmos DB seguenti:

   Contenitore	Purpose
   KnowledgeHubs	Archivia i metadati della Knowledge Base.
   KnowledgeArtifacts	Archivia i metadati di origine e i riferimenti al documento di origine.
   KnowledgeArtifactChunks	Archivia frammenti di documenti a testo completo.
   KnowledgeArtifactChunkSummaries	Archivia blocchi riepilogati con incorporamenti vettoriali per la ricerca semantica.

   KBaaS restituisce una risposta accettata 202 con un ID operazione per tenere traccia dello stato di avanzamento del caricamento.

   Durante il processo di caricamento, KBaaS esegue operazioni per analizzare, suddividere, riepilogare, incorporare e archiviare contenuto vettorializzato nel contenitore Cosmos DB. Al termine del processo, lo stato dell'origine diventa Completato o Non riuscito, in base al risultato.

7. Monitorare lo stato del caricamento nel portale di Azure o tramite l'ID dell'operazione.

8. Una volta completata la procedura di KBaaS, continua con la sezione successiva per aggiungere la base di conoscenza come strumento da usare nel loop dell’agente nel tuo flusso di lavoro Standard agentico.

3: Aggiungere la knowledge base come strumento

È ora possibile aggiungere la knowledge base al ciclo dell'agente da usare come strumento nei flussi di lavoro agentic Standard. I cicli di Agent eseguono automaticamente query sulla Knowledge Base per recuperare informazioni semanticamente rilevanti dai documenti caricati.

1. Nella stessa app per la logica di tipo Standard che include la base di conoscenza, nella finestra di progettazione apri il flusso di lavoro agentico e seleziona il ciclo dell'agente desiderato.

2. Nel riquadro informazioni agente selezionare Crea nella sezione Knowledge Base.

3. Nel riquadro Crea connessione selezionare la Knowledge Base dall'elenco Origini .

4. Per caricare altri file nella knowledge base, selezionare + Carica.

Gestire basi di conoscenza e fonti

Per elencare, visualizzare ed eliminare knowledge base o origini, usare il portale di Azure o l'API REST.

Elencare tutte le knowledge base

1. Nel portale di Azure, aprire la risorsa dell’app per la logica Standard.

2. Nella barra laterale dell'app per la logica, in Agenti selezionare Knowledge Base.

In alternativa, effettuare la chiamata api REST seguente:

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

Visualizzare una knowledge base specifica

Nel portale di Azure, dalla pagina Knowledge base, selezionare il nome della knowledge base.

In alternativa, effettuare la chiamata api REST seguente:

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

La risposta include le informazioni della Knowledge Base, un elenco con le origini associate e il relativo stato di caricamento.

Elenca le fonti in una base di conoscenza

Nel portale di Azure selezionare la Knowledge Base per visualizzarne le origini.

In alternativa, effettuare la chiamata api REST seguente:

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

Eliminare una fonte di conoscenza

Questa operazione rimuove i metadati di origine, i blocchi full-text e gli incorporamenti vettoriali da Cosmos DB. Il servizio restituisce una risposta 202 Accettata con un ID operazione per tenere traccia dello stato di avanzamento dell'eliminazione.

1. Nel portale di Azure selezionare la Knowledge Base per visualizzarne le origini.

2. Seleziona l'origine. Sulla barra degli strumenti, seleziona Elimina.

In alternativa, effettuare la chiamata api REST seguente:

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

Eliminare una base di conoscenza

Questa operazione rimuove la Knowledge Base e le origini, i blocchi e i riepiloghi associati da Cosmos DB.

1. Nel portale di Azure selezionare la Knowledge Base.

2. Sulla barra degli strumenti, seleziona Elimina.

In alternativa, effettuare la chiamata api REST seguente:

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

Contenuti correlati

• Cos'è App per la logica di Azure?
• Servizio OpenAI di Azure
• ricerca vettoriale Azure Cosmos DB
• Archivio vettoriale integrato - Azure Cosmos DB for NoSQL