Erstellen einer Fabric Ontologie-Wissensquelle (Vorschau)

Note

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

Important

Fabric Ontology Knowledge Source befindet sich in der öffentlichen Vorschau und unterliegt den ergänzenden Nutzungsbedingungen für Microsoft Azure Previews.

Die für dieses Feature geltenden Vorschaubedingungen finden Sie unter Previewfunktionalität.

Bedingungen, die gelten, wenn Sie eine Verbindung mit externen Datenquellen herstellen, finden Sie unter Externe Datenquellen.

Wenn Sie eine Verbindung mit Fabric IQ herstellen, entstehen möglicherweise Kosten, und Daten werden möglicherweise außerhalb der Azure Compliancegrenze gesendet und gemäß den geltenden Servicebedingungen und Datenverarbeitungsrichtlinien verarbeitet.

Eine Fabric Ontology Knowledge Source (Vorschau) verbindet Ihre Microsoft Fabric Ontologie mit einer agentischen Abrufpipeline in Foundry IQ (Azure KI-Suche). Wissensquellen werden unabhängig erstellt, in einer Wissensbasis referenziert und als Erdungsdaten verwendet, wenn die Wissensbasis zur Laufzeit abgefragt wird.

Ontologien erfassen, wie Ihr Unternehmen seine Daten, Entitäten und Beziehungen definiert, sodass Agenten in Geschäftsbedingungen antworten können, anstatt über unformatierte Tabellen und Spalten zu denken.

Im Gegensatz zu indizierten Wissensquellen fragen Fabric Ontology-Wissensquellen Live-Daten direkt zum Zeitpunkt des Abrufs ab. Es ist keine Aufnahmepipeline erforderlich. Abfragen erfordern ein Endbenutzerzugriffstoken, das vom Abrufmodul zum Authentifizieren mit Microsoft Fabric im Namen des Aufrufers verwendet wird.

Nutzungssupport

Azure Portal Microsoft Foundry-Portal .NET SDK Python SDK Java SDK JavaScript SDK REST-API
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Voraussetzungen

  • Das neueste Azure.Search.Documents Vorschaupaket: dotnet add package Azure.Search.Documents --prerelease

  • Für die schlüssellose Authentifizierung das Paket Azure.Identity: dotnet add package Azure.Identity

  • Das neueste azure-search-documents Vorschaupaket: pip install --pre azure-search-documents

  • Für die schlüssellose Authentifizierung das Paket azure-identity: pip install azure-identity

Datenverwaltung und Compliance

Fabric IQ verarbeitet Anforderungen innerhalb der Microsoft Fabric Compliancegrenze für die Region Ihres Arbeitsbereichs. Die folgenden Verpflichtungen gelten, wenn Sie Agent-Abfragen über Fabric IQ weiterleiten.

Datenresidenz

Fabric IQ ruft Daten innerhalb der Region ab, in der sich Ihr Microsoft Fabric Arbeitsbereich befindet. Daten überschreiten während der Abfrageausführung keine regionalen Grenzen. Die entsprechende Region und deren Compliancebereich werden von Ihrem Arbeitsbereichsort bestimmt. Eine Liste der unterstützten Regionen und die Complianceframeworks, die die einzelnen Regionen erfüllen, finden Sie unter Microsoft Fabric Regionsverfügbarkeit.

Note

Wenn sich Ihr Foundry IQ-Dienst in einer anderen Azure-Region befindet als Ihr Fabric-Arbeitsbereich, werden Abfrageergebnisse regionsübergreifend zurückgegeben. Überprüfen Sie die Verfügbarkeit der Microsoft Fabric-Regionen und die Anforderungen Ihrer Organisation hinsichtlich der Datenresidenz, bevor Sie einen Fabric-Arbeitsbereich in einer anderen Region verbinden.

Compliance-Zertifizierungen

Fabric IQ übernimmt die Compliancezertifizierungen von Microsoft Fabric für die Region des Arbeitsbereichs. Compliancedokumentation, Überwachungsberichte und die für jede Region geltenden Frameworks finden Sie unter Microsoft Fabric Regionsverfügbarkeit.

Überprüfen auf vorhandene Wissensquellen

Eine Wissensquelle ist ein wiederverwendbares Objekt auf oberster Ebene. Das Wissen über vorhandene Wissensquellen ist hilfreich, um neue Objekte wiederzuverwenden oder zu benennen.

Führen Sie den folgenden Code aus, um Wissensquellen nach Namen und Typ auflisten.

// 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
Authorization: Bearer {{token}}

Referenz:Wissensquellen - Liste

Sie können auch eine einzelne Wissensquelle anhand des Namens zurückgeben, um die JSON-Definition zu überprüfen.

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}}
Authorization: Bearer {{token}}

Referenz:Wissensquellen - Abrufen

Der folgende JSON-Code ist eine Beispielantwort für eine Fabric Ontology-Wissensquelle.

{
  "name": "my-fabric-ontology-ks",
  "kind": "fabricOntology",
  "description": "A Fabric Ontology knowledge source.",
  "encryptionKey": null,
  "fabricOntologyParameters": {
    "workspaceId": "00000000-0000-0000-0000-000000000000",
    "ontologyId": "00000000-0000-0000-0000-000000000001"
  }
}

Erstellen einer Wissensquelle

Führen Sie den folgenden Code aus, um eine Fabric Ontology-Wissensquelle zu erstellen.

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

Uri searchEndpoint = new Uri("<search-endpoint>");
DefaultAzureCredential credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(searchEndpoint, credential);

var fabricOntology = new FabricOntologyKnowledgeSource(
    "<knowledge-source-name>",
    new FabricOntologyKnowledgeSourceParameters("<fabric-workspace-id>", "<fabric-ontology-id>"))
{
    Description = "A Fabric Ontology knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(fabricOntology);

Reference:SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    FabricOntologyKnowledgeSource,
    FabricOntologyKnowledgeSourceParameters,
)

index_client = SearchIndexClient(
    endpoint="<search-endpoint>",
    credential=DefaultAzureCredential()
)

knowledge_source = FabricOntologyKnowledgeSource(
    name="<knowledge-source-name>",
    description="A Fabric Ontology knowledge source.",
    fabric_ontology_parameters=FabricOntologyKnowledgeSourceParameters(
        workspace_id="<fabric-workspace-id>",
        ontology_id="<fabric-ontology-id>"
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)

Reference:SearchIndexClient

### Create a Fabric Ontology knowledge source
PUT {{search-endpoint}}/knowledgesources/my-fabric-ontology-ks?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "my-fabric-ontology-ks",
  "kind": "fabricOntology",
  "description": "A Fabric Ontology knowledge source.",
  "fabricOntologyParameters": {
    "workspaceId": "{fabric-workspace-id}",
    "ontologyId": "{fabric-ontology-id}"
  }
}

Referenz:Wissensquellen – Erstellen oder Aktualisieren

Zuweisen zu einer Wissensbasis

Wenn Sie mit der Wissensquelle zufrieden sind, fügen Sie sie einer Wissensbasis hinzu.

Note

Fabric Ontology-Wissensquellen unterstützen den minimalAbrufbegründungsaufwand nicht. Verwenden Sie stattdessen low oder medium.

Abfragen einer Wissensbasis

Nachdem die Wissensdatenbank konfiguriert wurde, rufen Sie die Abrufaktion oder den MCP-Endpunkt auf, um Inhalte der Fabric-Ontologie abzufragen. Diese Wissensquelle verfügt über eindeutige Erzwingungs- und Antwortmerkmale für Abfragezeitberechtigungen.

Erzwingen von Berechtigungen während der Abfrage

Fabric Ontologie-Wissensquellen verwenden einen OBO-Tokenfluss (On-Behalf-Of). Sie übergeben das Endbenutzer-Zugriffstoken im x-ms-query-source-authorization-Header der Abrufanfrage. Das Token muss auf die Foundry IQ-Zielgruppe (https://search.azure.com/.default) festgelegt sein. Das Abrufmodul tauscht dieses Token gegen ein auf Microsoft Fabric beschränktes Token aus und verwendet es, um das Ontologieelement im Auftrag des Endbenutzers abzufragen.

Standard Foundry IQ-Authentifizierung ist auch für die Abrufanforderung erforderlich. Das x-ms-query-source-authorization Token wird separat übergeben und ersetzt die Dienstauthentifizierung nicht.

Anweisungen zum Übergeben des Tokens finden Sie in Berechtigungen bei der Abfrage erzwingen (Vorschau).

Fabric Ontology-spezifische Antwortfelder

Fabric Ontology-Wissensquellen geben Ergebnisse im Objekt sourceData jedes references-Eintrags und Abfragediagnosen im Array activity zurück. sourceData enthält:

  • fabricAnswer: Die Antwort der Ontologie in natürlicher Sprache.
  • fabricRawData: Die strukturierten Daten, die der Antwort zugrunde liegen, werden im CSV-Format zurückgegeben.

Das folgende Beispiel zeigt eine Abrufantwort, die einen Verweis auf die Fabric Ontologie-Wissensquelle und den zugehörigen Aktivitätsdatensatz enthält. Weiterführende Hinweise zum Interpretieren von Retrieve-Antworten finden Sie unter Antwort überprüfen.

Tip

Um sourceData für Verweise zu erhalten, legen Sie includeReferenceSourceData beim Wissensquelleneintrag in true der Abrufanforderung auf knowledgeSourceParams fest.

{
  "response": [
      // ... Response omitted for brevity
  ],
  "activity": [
    {
      "type": "fabricOntology",
      "id": 1,
      "knowledgeSourceName": "my-fabric-ontology-ks",
      "queryTime": "2026-05-11T20:29:24Z",
      "count": 1,
      "fabricOntologyArguments": {
        "search": "Which airlines operate domestic routes?"
      }
    },
    {
      // ... Additional activity records omitted for brevity
    }
  ],
  "references": [
    {
      "type": "fabricOntology",
      "id": "0",
      "activitySource": 1,
      "sourceData": {
        "fabricAnswer": "There are 3 airlines with domestic routes: Delta, United, and American.",
        "fabricRawData": "Airline,Routes\nDelta,47\nUnited,38\nAmerican,29"
      },
      "rerankerScore": 0,
      "workspaceId": "00000000-0000-0000-0000-000000000000",
      "ontologyId": "00000000-0000-0000-0000-000000000001"
    },
    {
      // ... Additional references omitted for brevity
    }
  ]
}

Löschen einer Wissensquelle

Bevor Sie eine Wissensquelle löschen können, müssen Sie alle Knowledge Basen löschen, die darauf verweisen, oder die Knowledge Base-Definition aktualisieren, um den Verweis zu entfernen. Für Wissensquellen, die eine Index- und Indexerpipeline generieren, werden auch alle generierten Objekte gelöscht. Wenn Sie jedoch einen vorhandenen Index zum Erstellen einer Wissensquelle verwendet haben, wird Ihr Index nicht gelöscht.

Wenn Sie versuchen, eine verwendete Wissensquelle zu löschen, schlägt die Aktion fehl und gibt eine Liste der betroffenen Wissensdatenbanken zurück.

So löschen Sie eine Wissensquelle:

  1. Erhalten Sie eine Liste aller Wissensdatenbanken in Ihrem Foundry IQ-Dienst.

    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

    Eine Beispielantwort könnte wie folgt aussehen:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.

    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

    Eine Beispielantwort könnte wie folgt aussehen:

     {
       "Name": "earth-knowledge-base",
       "KnowledgeSources": [
         {
           "Name": "earth-knowledge-source"
         }
       ],
       "Models": [
         {}
       ],
       "RetrievalReasoningEffort": {},
       "OutputMode": {},
       "ETag": "\u00220x8DE278629D782B3\u0022",
       "EncryptionKey": null,
       "Description": null,
       "RetrievalInstructions": null,
       "AnswerInstructions": null
     }
    
  3. Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie, wenn Sie über mehrere Wissensquellen verfügen, die Wissensbasis, um die Quelle zu entfernen. In diesem Beispiel wird das Löschen gezeigt.

    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

  4. Löschen Sie die Wissensquelle.

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

    Reference:SearchIndexClient

  1. Erhalten Sie eine Liste aller Wissensbasen auf Ihrem Foundry IQ Service.

    # 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

    Eine Beispielantwort könnte wie folgt aussehen:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.

    # 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

    Eine Beispielantwort könnte wie folgt aussehen:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie, wenn Sie über mehrere Wissensquellen verfügen, die Wissensbasis, um die Quelle zu entfernen. In diesem Beispiel wird das Löschen gezeigt.

    # 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

  4. Löschen Sie die Wissensquelle.

    # 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

  1. Erhalten Sie eine Liste aller Wissensbasen auf Ihrem Foundry IQ Service.

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

    Referenz:Wissensdatenbanken - Liste

    Eine Beispielantwort könnte wie folgt aussehen:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.

    ### Get a knowledge base definition
    GET {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Referenz:Wissensdatenbanken – Abrufen

    Eine Beispielantwort könnte wie folgt aussehen:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie, wenn Sie über mehrere Wissensquellen verfügen, die Wissensbasis, um die Quelle zu entfernen. In diesem Beispiel wird das Löschen gezeigt.

    ### Delete a knowledge base
    DELETE {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Referenz:Knowledge Bases - Löschen

  4. Löschen Sie die Wissensquelle.

    ### Delete a knowledge source
    DELETE {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Referenz:Wissensquellen - Löschen