Crea una fonte di conoscenza per Fabric Data Agent (anteprima)

Annotazioni

Azure AI Search è disponibile tramite il portale di Azure, le API REST e Azure SDK. È inoltre alla base di Foundry IQ, il livello di conoscenza gestito che trasforma il contenuto aziendale in knowledge base riutilizzabili e con riconoscimento delle autorizzazioni per gli agenti nel portale di Microsoft Foundry.

Importante

Queste funzionalità e funzionalità fanno parte dell'API REST 2026-05-01-preview. L'anteprima 2026-05-01-preview è concessa in licenza all'utente come parte della sottoscrizione Azure ed è soggetta ai termini applicabili alle "Anteprime" nei Microsoft Product Terms, nel Microsoft Products and Services Data Protection Addendum ("DPA") e nei Supplemental Terms of Use for Microsoft Azure Previews.

La versione 2026-05-01-preview supporta le connessioni ad altri servizi di servizi Microsoft e di terze parti. L'utilizzo di questi servizi è soggetto alle rispettive condizioni e potrebbe comportare l'elaborazione o l'archiviazione dei dati al di fuori del limite di conformità Azure, nonché il flusso dei dati nel limite di conformità Azure.

Quando ci si connette a Fabric IQ, è possibile che si verifichino costi e che i dati vengano inviati al di fuori del limite di conformità Azure e elaborati in base ai criteri di gestione dei dati e alle condizioni di servizio applicabili. È tua responsabilità gestire l'eventuale trasferimento dei tuoi dati al di fuori dei confini di conformità e geografici della tua organizzazione e le relative implicazioni, nonché garantire che siano predisposte le autorizzazioni, i limiti e le approvazioni appropriati.

L'utente è responsabile di esaminare e testare attentamente le applicazioni compilate nel contesto dei casi d'uso specifici e di prendere tutte le decisioni e le personalizzazioni appropriate. Ciò include l'implementazione di mitigazioni di intelligenza artificiale responsabili, ad esempio metaprompt, filtri di contenuto o altri sistemi di sicurezza, e garantire che le applicazioni soddisfino gli standard di qualità, affidabilità, sicurezza e attendibilità appropriati. Per altre informazioni, vedere la nota sulla trasparenza Azure AI Search.

Una fonte di conoscenza di Fabric Data Agent (anteprima) collega il tuo Microsoft Fabric Data Agent a una pipeline di recupero basata su agenti in Azure AI Search. Le origini delle informazioni vengono create in modo indipendente, a cui viene fatto riferimento in una Knowledge Base e usate come dati di base quando viene eseguita una query sulla Knowledge Base in fase di esecuzione.

L'agente dati funge da analista virtuale, generando ed eseguendo query sui dati Microsoft Fabric per restituire risposte, tabelle e grafici in linguaggio naturale. Questo rende utili le fonti di conoscenza di Fabric Data Agent per i dati ad alto tasso di variazione e per le query analitiche.

A differenza delle origini di conoscenza indicizzate, le origini di conoscenza di Fabric Data Agent interrogano direttamente i dati al momento del recupero. Non è necessaria alcuna pipeline di inserimento. Le query richiedono un token di accesso dell'utente finale, usato dal motore di recupero per eseguire query sull'agente dati Fabric per conto dell'utente finale.

Supporto per l'utilizzo

Portale di Azure	Portale di Microsoft Foundry	.NET SDK	PYTHON SDK	JAVA SDK	JavaScript SDK	API REST
❌	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisiti

Servizio di Ricerca con intelligenza artificiale di Azure disponibile in qualsiasi area che supporta il recupero tramite agenti autonomi.
Un'area di lavoro Microsoft Fabric con un agente data.
Il servizio di ricerca e l'area di lavoro devono trovarsi nello stesso tenant Microsoft Entra ID.
Autorizzazioni per la creazione di origini delle informazioni. Configurare l'autenticazione senza chiave con il ruolo Collaboratore servizio di ricerca assegnato all'account utente (scelta consigliata) o usare una chiave API.

Pacchetto di anteprima Azure.Search.Documents più recente: dotnet add package Azure.Search.Documents --prerelease

Pacchetto di anteprima azure-search-documents più recente: pip install --pre azure-search-documents

Versione 2026-05-01-preview delle API REST del servizio di ricerca.

Governance e conformità dei dati

Fabric IQ elabora le richieste all'interno del perimetro di conformità di Microsoft Fabric per la regione dell'area di lavoro. Gli impegni seguenti si applicano quando si instradano le query dell'agente tramite Fabric IQ.

Residenza dei dati

Fabric IQ recupera ed elabora i dati all'interno dell'area in cui risiede l'area di lavoro Microsoft Fabric. I dati non superano i limiti a livello di area durante l'esecuzione delle query. L'area applicabile e il relativo ambito di conformità sono determinati dalla posizione dell'area di lavoro. Per l'elenco delle regioni supportate e dei framework di conformità a cui è conforme ogni regione, consulta Disponibilità delle aree di Microsoft Fabric.

Annotazioni

Se il servizio Azure AI Search si trova in un'area Azure diversa rispetto all'area di lavoro Fabric, i risultati delle query vengono restituiti tra aree. Esamina la disponibilità a livello di area geografica di Microsoft Fabric e i requisiti di residenza dei dati dell'organizzazione prima di connettere un'area di lavoro di Fabric in un'altra area geografica.

Certificazioni per la conformità

Fabric IQ eredita le certificazioni di conformità di Microsoft Fabric per l'area di lavoro. Per la documentazione sulla conformità, i report di audit e i framework applicabili a ogni area geografica, vedere Disponibilità a livello di area geografica di Microsoft Fabric.

Verificare la presenza di fonti di conoscenza esistenti

Un'origine delle conoscenze è un oggetto riutilizzabile di primo livello. Conoscere le origini conoscenze esistenti è utile per riutilizzare o denominare nuovi oggetti.

Eseguire il codice seguente per elencare le origini delle informazioni in base al nome e al tipo.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

Reference:SearchIndexClient

# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

for ks in index_client.list_knowledge_sources():
    print(f"  - {ks.name} ({ks.kind})")

Reference:SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
api-key: {{api-key}}

Reference:Knowledge Sources - List

Puoi anche restituire una singola fonte di conoscenza per nome per esaminarne la definizione JSON.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

Reference:SearchIndexClient

# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))

Reference:SearchIndexClient

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
api-key: {{api-key}}

Reference:Fonti di Conoscenza - Ottieni

Il seguente JSON è un esempio di risposta per un'origine di conoscenza di un agente dati di Fabric.

{
  "name": "my-fabric-data-agent-ks",
  "kind": "fabricDataAgent",
  "description": "A Fabric Data Agent knowledge source.",
  "encryptionKey": null,
  "fabricDataAgentParameters": {
    "workspaceId": "00000000-0000-0000-0000-000000000000",
    "dataAgentId": "00000000-0000-0000-0000-000000000001"
  }
}

Creare una fonte di conoscenza

Esegui il codice seguente per creare un'origine di conoscenza di Fabric Data Agent.

using Azure;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

Uri searchEndpoint = new Uri("<search-service-url>");
AzureKeyCredential credential = new AzureKeyCredential("<api-key>");
var indexClient = new SearchIndexClient(searchEndpoint, credential);

var fabricDataAgent = new FabricDataAgentKnowledgeSource(
    "<knowledge-source-name>",
    new FabricDataAgentKnowledgeSourceParameters("<fabric-workspace-id>", "<fabric-data-agent-id>"))
{
    Description = "A Fabric Data Agent knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(fabricDataAgent);

Reference:SearchIndexClient

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    FabricDataAgentKnowledgeSource,
    FabricDataAgentKnowledgeSourceParameters,
)

index_client = SearchIndexClient(
    endpoint="<search-service-url>",
    credential=AzureKeyCredential("<api-key>")
)

knowledge_source = FabricDataAgentKnowledgeSource(
    name="<knowledge-source-name>",
    description="A Fabric Data Agent knowledge source.",
    fabric_data_agent_parameters=FabricDataAgentKnowledgeSourceParameters(
        workspace_id="<fabric-workspace-id>",
        data_agent_id="<fabric-data-agent-id>"
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)

Reference:SearchIndexClient

### Create a Fabric Data Agent knowledge source
PUT {{search-url}}/knowledgesources/my-fabric-data-agent-ks?api-version=2026-05-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
  "name": "my-fabric-data-agent-ks",
  "kind": "fabricDataAgent",
  "description": "A Fabric Data Agent knowledge source.",
  "fabricDataAgentParameters": {
    "workspaceId": "{fabric-workspace-id}",
    "dataAgentId": "{fabric-data-agent-id}"
  }
}

Riferimento:Fonti di conoscenza - Crea o Aggiorna

Assegnare a una knowledge base

Se sei soddisfatto della fonte di conoscenza, aggiungila a una base di conoscenza.

Importante

Le fonti di conoscenza di Fabric Data Agent non supportano il processo di ragionamento per il recupero minimal. In sostituzione utilizzare low o medium.

Eseguire una query su una base di conoscenza

Dopo aver configurato la knowledge base, richiamare l'azione di recupero o l'endpoint MCP per interrogare il contenuto di Fabric Data Agent. Questa fonte di conoscenza presenta caratteristiche specifiche nell'applicazione delle autorizzazioni al momento della query e nella risposta.

Applicare le autorizzazioni al tempo di interrogazione

Le fonti di conoscenza di Fabric Data Agent utilizzano un flusso di token "on-behalf-of" (OBO). Si passa il token di accesso dell'utente finale nell'intestazione x-ms-query-source-authorization della richiesta di recupero. Il token deve essere associato al pubblico di Azure AI Search (https://search.azure.com/.default). Il motore di recupero scambia questo token per un token con ambito Microsoft Fabric e lo usa per eseguire una query sull'agente dati Fabric per conto dell'utente finale.

Per la richiesta di recupero è necessaria anche l'autenticazione standard Azure AI Search. Il x-ms-query-source-authorization token viene passato separatamente e non sostituisce l'autenticazione del servizio.

Per istruzioni sul passaggio del token, vedere Applicare le autorizzazioni in fase di query (anteprima).

Campi di risposta specifici di Fabric Data Agent

Le fonti di conoscenza di Fabric Data Agent restituiscono i risultati nell'oggetto sourceData di ciascuna voce references e le informazioni diagnostiche relative alla query nell'array activity. sourceData Contiene:

fabricAnswer: risposta in linguaggio naturale dell'agente dati.
fabricEmbeddedResources: qualsiasi risorsa incorporata, ad esempio tabelle e grafici, quando la query produce output strutturato.

L'esempio seguente mostra una risposta di recupero contenente un riferimento a una fonte di conoscenza di Fabric Data Agent e il record attività corrispondente. Per indicazioni più ampie sull'interpretazione delle risposte recuperate, vedere Esaminare la risposta.

Tip

Per ottenere sourceData per i riferimenti, imposta includeReferenceSourceData su true nella voce dell'origine della conoscenza all'interno di knowledgeSourceParams nella richiesta di recupero.

{
  "response": [
      // ... Response omitted for brevity
  ],
  "activity": [
    {
      "type": "fabricDataAgent",
      "id": 1,
      "knowledgeSourceName": "my-fabric-data-agent-ks",
      "queryTime": "2026-05-11T19:37:11.600Z",
      "count": 1,
      "fabricDataAgentArguments": {
        "search": "my query"
      }
    },
    {
      // ... Additional activity records omitted for brevity 
    }
  ],
  "references": [
    {
      "type": "fabricDataAgent",
      "id": "0",
      "activitySource": 1,
      "rerankerScore": 2.57,
      "workspaceId": "00000000-0000-0000-0000-000000000000",
      "dataAgentId": "00000000-0000-0000-0000-000000000001",
      "sourceData": {
        "fabricAnswer": "There were 47 airline delays in Q1 2026. The majority occurred on transcontinental routes.",
        "fabricEmbeddedResources": [
          {
            "title": "Q1 2026 Airline Operations Report",
            "mimeType": "text/csv",
            "content": "Route | Delays | Avg. Delay (min)\n--- | --- | ---\nJFK–LAX | 18 | 42\nORD–MIA | 12 | 31"
          }
        ]
      }
    },
    {
      // ... Additional references omitted for brevity 
    }
  ]
}

Eliminare una fonte di conoscenza

Prima di poter eliminare una fonte di conoscenza, è necessario eliminare qualsiasi base di conoscenza che vi faccia riferimento o aggiornare la definizione della base di conoscenza per rimuovere il riferimento. Per le fonti di conoscenza che generano un indice e una pipeline di indicizzazione, vengono eliminati anche tutti gli oggetti generati. Tuttavia, se è stato usato un indice esistente per creare un'origine conoscenze, l'indice non viene eliminato.

Se si tenta di eliminare una fonte di conoscenza attualmente in uso, l'azione fallisce e restituisce un elenco delle basi di conoscenza interessate.

Per eliminare una fonte di conoscenza:

Ottenere un elenco di tutte le knowledge base nel servizio di ricerca.

using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeBases = indexClient.GetKnowledgeBasesAsync();

Console.WriteLine("Knowledge Bases:");

await foreach (var kb in knowledgeBases)
{
    Console.WriteLine($"  - {kb.Name}");
}

Reference:SearchIndexClient

Una risposta di esempio potrebbe essere simile alla seguente:

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

Ottenere una singola definizione della Knowledge Base per verificare la presenza di riferimenti all'origine della knowledge base.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge base name to retrieve
string kbNameToGet = "earth-knowledge-base";

// Get a specific knowledge base definition
var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
var kb = knowledgeBaseResponse.Value;

// Serialize to JSON for display
string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

Reference:SearchIndexClient

Una risposta di esempio potrebbe essere simile alla seguente:

 {
   "Name": "earth-knowledge-base",
   "KnowledgeSources": [
     {
       "Name": "earth-knowledge-source"
     }
   ],
   "Models": [
     {}
   ],
   "RetrievalReasoningEffort": {},
   "OutputMode": {},
   "ETag": "\u00220x8DE278629D782B3\u0022",
   "EncryptionKey": null,
   "Description": null,
   "RetrievalInstructions": null,
   "AnswerInstructions": null
 }

Eliminare la Knowledge Base o, se si dispone di più origini informazioni, aggiornare la Knowledge Base per rimuovere l'origine. Questo esempio mostra l'eliminazione.

using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");

Reference:SearchIndexClient

Eliminare l'origine delle informazioni.

await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");

Reference:SearchIndexClient

Ottenere un elenco di tutte le knowledge base nel servizio di ricerca.

# Get knowledge bases
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

print("Knowledge Bases:")
for kb in index_client.list_knowledge_bases():
    print(f"  - {kb.name}")

Reference:SearchIndexClient

Una risposta di esempio potrebbe essere simile alla seguente:

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

Ottenere una singola definizione della Knowledge Base per verificare la presenza di riferimenti all'origine della knowledge base.

# Get a knowledge base definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
kb = index_client.get_knowledge_base("knowledge_base_name")
print(kb)

Reference:SearchIndexClient

Una risposta di esempio potrebbe essere simile alla seguente:

 {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks",
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

Eliminare la Knowledge Base o, se si dispone di più origini informazioni, aggiornare la Knowledge Base per rimuovere l'origine. Questo esempio mostra l'eliminazione.

# Delete a knowledge base
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_base("knowledge_base_name")
print(f"Knowledge base deleted successfully.")

Reference:SearchIndexClient

Eliminare l'origine delle informazioni.

# Delete a knowledge source
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_source("knowledge_source_name")
print(f"Knowledge source deleted successfully.")

Reference:SearchIndexClient

Ottenere un elenco di tutte le knowledge base nel servizio di ricerca.

### Get knowledge bases
GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
api-key: {{api-key}}

Reference:Knowledge Bases - List

Una risposta di esempio potrebbe essere simile alla seguente:

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

Ottenere una singola definizione della Knowledge Base per verificare la presenza di riferimenti all'origine della knowledge base.

### Get a knowledge base definition
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
api-key: {{api-key}}

Riferimento:Basi di conoscenza - Get

Una risposta di esempio potrebbe essere simile alla seguente:

 {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks",
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

Eliminare la Knowledge Base o, se si dispone di più origini informazioni, aggiornare la Knowledge Base per rimuovere l'origine. Questo esempio mostra l'eliminazione.
```
### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
api-key: {{api-key}}
```
Reference:Basi di conoscenza - Elimina

Eliminare l'origine delle informazioni.

### Delete a knowledge source
DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
api-key: {{api-key}}

Riferimento:Fonti di Conoscenza - Elimina

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-06-29

Crea una fonte di conoscenza per Fabric Data Agent (anteprima)

Supporto per l'utilizzo

Prerequisiti

Governance e conformità dei dati

Residenza dei dati

Certificazioni per la conformità

Verificare la presenza di fonti di conoscenza esistenti

Creare una fonte di conoscenza

Assegnare a una knowledge base

Eseguire una query su una base di conoscenza

Applicare le autorizzazioni al tempo di interrogazione

Campi di risposta specifici di Fabric Data Agent

Eliminare una fonte di conoscenza

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive