Tworzenie źródła wiedzy Fabric Ontology (wersja zapoznawcza)

Note

Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te funkcje lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

Ważna

Źródło wiedzy Ontology w usłudze Fabric jest dostępne w publicznej wersji zapoznawczej i podlega Dodatkowym warunkom korzystania z wersji zapoznawczych Microsoft Azure. Aby zapoznać się z terminami wersji zapoznawczej specyficznymi dla tej funkcji, zobacz Funkcjonalność w wersji zapoznawczej. Informacje o terminach stosowanych podczas nawiązywania połączenia z zewnętrznymi źródłami danych znajdziesz w sekcji Zewnętrzne źródła danych.

Po połączeniu z usługą Fabric IQ mogą zostać naliczone opłaty, a dane mogą być przesyłane poza granice zgodności platformy Azure i przetwarzane zgodnie z obowiązującymi warunkami świadczenia usług oraz zasadami przetwarzania danych.

Źródło wiedzy ontologii Fabric (wersja zapoznawcza) łączy ontologię Microsoft Fabric z potokiem wyszukiwania agentowego w Foundry IQ (Wyszukiwanie AI platformy Azure). Źródła wiedzy są tworzone niezależnie, uwzględniane w bazie wiedzy i używane jako dane ugruntowujące, gdy baza wiedzy jest odpytywana w czasie wykonywania.

Ontologie opisują to, jak firma definiuje swoje dane, encje i relacje, umożliwiając agentom udzielanie odpowiedzi w kategoriach biznesowych zamiast opierania się na analizie surowych tabel i kolumn.

W przeciwieństwie do indeksowanych źródeł wiedzy źródła wiedzy Fabric Ontology odpytują dane na żywo bezpośrednio w momencie pobierania. Potok importu danych nie jest potrzebny. Zapytania wymagają tokenu dostępu użytkownika końcowego, którego mechanizm pobierania używa do uwierzytelniania w usłudze Microsoft Fabric w imieniu wywołującego.

Wsparcie użytkowania

Azure portal portal Microsoft Foundry zestaw SDK .NET Python SDK Java SDK JavaScript SDK REST API
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Wymagania wstępne

  • Najnowszy pakiet Azure.Search.Documents wersji zapoznawczej: dotnet add package Azure.Search.Documents --prerelease

  • W przypadku uwierzytelniania bezkluczowego pakiet Azure.Identity: dotnet add package Azure.Identity

  • Najnowszy pakiet azure-search-documents wersji zapoznawczej: pip install --pre azure-search-documents

  • W przypadku uwierzytelniania bezkluczowego pakiet azure-identity: pip install azure-identity

Nadzór i zgodność danych

Fabric IQ przetwarza żądania w granicach zgodności platformy Microsoft Fabric dla regionu Twojego obszaru roboczego. Poniższe zobowiązania mają zastosowanie podczas kierowania zapytań agenta za pośrednictwem Fabric IQ.

Miejsce przechowywania danych

Fabric IQ pobiera i przetwarza dane w regionie, w którym znajduje się obszar roboczy Microsoft Fabric. Dane nie przekraczają granic regionalnych podczas wykonywania zapytania. Odpowiedni region i jego zakres zgodności są określane przez lokalizację obszaru roboczego. Aby uzyskać listę obsługiwanych regionów i standardów zgodności, które spełnia dany region, zobacz Dostępność regionów usługi Microsoft Fabric.

Note

Jeśli usługa Foundry IQ znajduje się w innym regionie Azure niż obszar roboczy Fabric, wyniki zapytania są zwracane między regionami. Przed połączeniem z obszarem roboczym usługi Fabric znajdującym się w innym regionie sprawdź dostępność regionów usługi Microsoft Fabric oraz wymagania organizacji dotyczące rezydencji danych.

Certyfikaty zgodności

Fabric IQ dziedziczy certyfikaty zgodności Microsoft Fabric dla regionu obszaru roboczego. Aby uzyskać informacje o dokumentacji zgodności, raportach z audytów i ramach zgodności mających zastosowanie w poszczególnych regionach, zobacz Dostępność regionów usługi Microsoft Fabric.

Sprawdzanie istniejących źródeł wiedzy

Źródłem wiedzy jest obiekt najwyższego poziomu wielokrotnego użytku. Znajomość istniejących źródeł wiedzy jest przydatna w przypadku ponownego użycia lub nazewnictwa nowych obiektów.

Uruchom następujący kod, aby wyświetlić listę źródeł wiedzy według nazwy i typu.

// 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}}

Odwołanie:Źródła wiedzy — lista

Możesz również zwrócić pojedyncze źródło wiedzy według nazwy, aby przejrzeć jego definicję 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}}
Authorization: Bearer {{token}}

Odwołanie:Źródła wiedzy — pobieranie

Poniższy kod JSON to przykładowa odpowiedź dla źródła wiedzy Fabric Ontology.

{
  "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"
  }
}

Tworzenie źródła wiedzy

Uruchom następujący kod, aby utworzyć źródło wiedzy Fabric Ontology.

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}"
  }
}

Odwołanie:Źródła wiedzy — tworzenie lub aktualizowanie

Przypisywanie do bazy wiedzy

Jeśli źródło wiedzy jest zadowalające, dodaj je do bazy wiedzy.

Note

Źródła wiedzy ontologii w usłudze Fabric nie obsługują minimalwnioskowania podczas wyszukiwania. Użyj polecenia low lub medium zamiast tego.

Wykonywanie zapytań w bazie wiedzy

Po skonfigurowaniu bazy wiedzy zwłań akcję pobierania lub punkt końcowy MCP do wykonywania zapytań dotyczących zawartości Fabric Ontology. To źródło wiedzy ma unikalne mechanizmy egzekwowania uprawnień w czasie wykonywania zapytania oraz charakterystykę odpowiedzi.

Wymuszanie uprawnień w czasie wykonywania zapytania

Źródła wiedzy ontologii w usłudze Fabric korzystają z przepływu tokenów w imieniu użytkownika (OBO). Przekazujesz token dostępu użytkownika końcowego w nagłówku x-ms-query-source-authorization w żądaniu pobrania. Token musi być ograniczony do odbiorcy Foundry IQ (https://search.azure.com/.default). Mechanizm pobierania wymienia ten token na token o zakresie Microsoft Fabric i używa go do wysyłania zapytań do elementu ontologii w imieniu użytkownika końcowego.

Standardowe uwierzytelnianie Foundry IQ jest również wymagane w żądaniu pobierania. Token x-ms-query-source-authorization jest przekazywany oddzielnie i nie zastępuje uwierzytelniania usługi.

Aby uzyskać instrukcje dotyczące przekazywania tokenu, zobacz Wymuszanie uprawnień w czasie zapytania (wersja zapoznawcza).

Pola odpowiedzi specyficzne dla Fabric Ontology

Źródła wiedzy ontologii w usłudze Fabric zwracają wyniki w obiekcie sourceData w każdym wpisie references oraz diagnostykę zapytań w tablicy activity. sourceData zawiera:

  • fabricAnswer: Odpowiedź języka naturalnego ontologii.
  • fabricRawData: Dane ustrukturyzowane, które stanowiły podstawę odpowiedzi, zwrócone w formacie CSV.

Poniższy przykład przedstawia odpowiedź operacji pobierania zawierającą odwołanie do źródła wiedzy Fabric Ontology oraz odpowiadający mu rekord aktywności. Aby uzyskać szersze wskazówki dotyczące interpretowania odpowiedzi operacji pobierania, zobacz Przejrzyj odpowiedź.

Tip

Aby otrzymywać sourceData odniesienia, ustaw wartość includeReferenceSourceData na true we wpisie źródła wiedzy w elemencie knowledgeSourceParams w żądaniu pobierania.

{
  "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
    }
  ]
}

Usuwanie źródła wiedzy

Aby można było usunąć źródło wiedzy, należy usunąć dowolną bazę wiedzy, która odwołuje się do źródła wiedzy, lub zaktualizować definicję bazy wiedzy, aby usunąć odwołanie. W przypadku źródeł wiedzy, które generują potok indeksu i indeksatora, wszystkie wygenerowane obiekty również są usuwane. Jeśli jednak użyto istniejącego indeksu do utworzenia źródła wiedzy, indeks nie zostanie usunięty.

Jeśli spróbujesz usunąć używane źródło wiedzy, akcja zakończy się niepowodzeniem i zwróci listę baz wiedzy, których dotyczy problem.

Aby usunąć źródło wiedzy:

  1. Pobierz listę wszystkich baz wiedzy w usłudze Foundry IQ.

    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

    Przykładowa odpowiedź może wyglądać następująco:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Uzyskaj pojedynczą definicję bazy wiedzy, aby sprawdzić odwołania do źródeł wiedzy.

    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

    Przykładowa odpowiedź może wyglądać następująco:

     {
       "Name": "earth-knowledge-base",
       "KnowledgeSources": [
         {
           "Name": "earth-knowledge-source"
         }
       ],
       "Models": [
         {}
       ],
       "RetrievalReasoningEffort": {},
       "OutputMode": {},
       "ETag": "\u00220x8DE278629D782B3\u0022",
       "EncryptionKey": null,
       "Description": null,
       "RetrievalInstructions": null,
       "AnswerInstructions": null
     }
    
  3. Usuń bazę wiedzy lub, jeśli masz wiele źródeł wiedzy, zaktualizuj bazę wiedzy, aby usunąć źródło. W tym przykładzie pokazano usunięcie.

    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. Usuń źródło wiedzy.

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

    Reference:SearchIndexClient

  1. Pobierz listę wszystkich baz wiedzy w usłudze Foundry IQ.

    # 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

    Przykładowa odpowiedź może wyglądać następująco:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Uzyskaj pojedynczą definicję bazy wiedzy, aby sprawdzić odwołania do źródeł wiedzy.

    # 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

    Przykładowa odpowiedź może wyglądać następująco:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Usuń bazę wiedzy lub, jeśli masz wiele źródeł wiedzy, zaktualizuj bazę wiedzy, aby usunąć źródło. W tym przykładzie pokazano usunięcie.

    # 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. Usuń źródło wiedzy.

    # 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. Pobierz listę wszystkich baz wiedzy w usłudze Foundry IQ.

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

    Dokumentacja:Bazy wiedzy — lista

    Przykładowa odpowiedź może wyglądać następująco:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Uzyskaj pojedynczą definicję bazy wiedzy, aby sprawdzić odwołania do źródeł wiedzy.

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

    Odwołanie:Bazy wiedzy — pobieranie

    Przykładowa odpowiedź może wyglądać następująco:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Usuń bazę wiedzy lub, jeśli masz wiele źródeł wiedzy, zaktualizuj bazę wiedzy, aby usunąć źródło. W tym przykładzie pokazano usunięcie.

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

    Odwołanie:Bazy wiedzy — usuwanie

  4. Usuń źródło wiedzy.

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

    Odwołanie:Źródła wiedzy — usuwanie