Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
Important
Fabric Ontology 知識來源目前處於公開預覽,並受 Microsoft Azure 預覽版補充使用條款規範。
有關此功能專屬的預覽條款,請參閱 預覽功能。
有關連接外部資料來源時適用的術語,請參閱「外部資料來源」。
當你連接 Fabric IQ 時,可能會產生成本,資料也可能被傳送到Azure合規範圍之外,並依照適用的服務條款和資料處理政策處理。
Fabric Ontology 知識來源(預覽版)會將您的 Microsoft Fabric 本體連接至 Foundry IQ(Azure AI 搜尋服務)中的代理式擷取管線。 知識來源 會獨立建立,並在 知識庫中被引用,並在 執行時查詢知識庫時作為基礎資料。
本體論捕捉企業如何定義其資料、實體與關係,讓客服人員能以商業用語回答,而非僅靠原始表格和欄位推理。
與索引知識來源不同,Fabric Ontology 知識來源會在檢索時直接查詢即時資料。 不需要資料擷取流程。 查詢需要一個終端使用者存取權杖,檢索引擎會用此憑證代表呼叫者與 Microsoft Fabric 進行認證。
使用支援
| Azure portal | Microsoft Foundry 入口網站 | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
先決條件
任何 提供代理檢索的區域內的 Foundry IQ 服務。
具有 Ontology 所需租用戶設定和 Ontology 項目的 Microsoft Fabric 工作區。
您的 Foundry IQ 服務與工作區必須位於相同的 Microsoft Entra ID 租戶中。
允許建立知識來源。 設定無金鑰驗證,並將搜尋服務參與者角色指派給您的使用者帳戶(建議),或使用管理員 API 金鑰。
最新的
Azure.Search.Documents預覽套件:dotnet add package Azure.Search.Documents --prerelease對於無鑰匙認證,套件如下
Azure.Identity:dotnet add package Azure.Identity
最新的
azure-search-documents預覽套件:pip install --pre azure-search-documents對於無鑰匙認證,套件如下
azure-identity:pip install azure-identity
Search Service REST API 的 2026-11-01-preview 版本。
對於無金鑰認證,請在
Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。
資料治理與合規
Fabric IQ 會在您工作區所在區域的 Microsoft Fabric 合規界限內處理請求。 當你透過 Fabric IQ 路由代理查詢時,以下承諾會適用。
資料存放位置
Fabric IQ 會在您的 Microsoft Fabric 工作區所在區域內擷取並處理資料。 查詢執行時,資料不會跨越區域邊界。 適用的區域及其合規範圍由您工作空間的地點決定。 有關支援區域清單及各區域所符合的合規框架,請參見 Microsoft Fabric 區域可用性。
Note
如果您的 Foundry IQ 服務位於與 Fabric 工作區不同的 Azure 區域,查詢結果會跨區域回傳。 在連接不同區域的Fabric工作空間前,請先檢視Microsoft Fabric區域可用性及貴組織的資料駐留要求。
合規性認證
Fabric IQ 繼承了 Microsoft Fabric 在工作空間區域的合規認證。 有關合規文件、稽核報告及適用於各區域的框架,請參見 Microsoft Fabric 區域可用性。
檢查現有的知識來源
知識來源是一個頂層且可重複使用的物件。 了解現有的知識來源對於重用或命名新物件都很有幫助。
執行以下程式碼,依名稱和類型列出知識來源。
// 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}");
}
# 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})")
### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}
參考資料:知識來源 - 列表
你也可以以名稱回傳單一知識來源,以檢視其 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));
# 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))
### Get a knowledge source definition
GET {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{token}}
參考資料:知識來源 - 取得
以下 JSON 是一個針對 Fabric 本體知識來源的範例回應。
{
"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"
}
}
建立知識來源
執行以下程式碼建立 Fabric 本體知識來源。
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);
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)
### 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}"
}
}
參考:知識來源 - 建立或更新
指派至知識庫
如果你對知識來源感到滿意,就 把它加入知識庫。
Note
Fabric Ontology 知識來源不支援 minimal擷取推理工作。 請改用 low 或 medium。
查詢知識庫
知識庫設定完成後,呼叫擷取作業或 MCP 端點以查詢 Fabric Ontology 內容。 此知識來源具有獨特的查詢時間權限強制與回應特性。
在查詢過程中強制執行權限
Fabric Ontology 知識來源會使用代理者流程 (OBO) 權杖流程。 您會在擷取要求的 x-ms-query-source-authorization 標頭中傳遞使用者存取權杖。 該代幣的範圍必須限定為 Foundry IQ 對象(https://search.azure.com/.default)。 擷取引擎會將此權杖交換為 Microsoft Fabric 範圍的權杖,並使用該權杖代表使用者查詢 Ontology 項目。
擷取請求時也必須使用標準 Foundry IQ 驗證。
x-ms-query-source-authorization憑證是分開傳遞的,並不取代服務認證。
關於傳遞權杖的說明,請參閱在查詢時強制執行權限 (預覽版)。
Fabric 本體論專屬回應領域
Fabric Ontology 知識來源會在每個 sourceData 項目的 references 物件中傳回結果,並在 activity 陣列中傳回查詢診斷。
sourceData 內容包括:
-
fabricAnswer:本體論的自然語言答案。 -
fabricRawData:支撐該答案的結構化資料以 CSV 格式回傳。
下列範例顯示包含 Fabric Ontology 知識來源參考及其對應活動記錄的擷取回應。 關於解讀檢索回應的更廣泛指引,請參見「檢視回應」。
Tip
若要接收參考的 sourceData,請在擷取要求的 includeReferenceSourceData 中,將知識來源項目上的 true 設定為 knowledgeSourceParams。
{
"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
}
]
}
刪除知識來源
在刪除知識來源之前,必須刪除所有引用該來源的知識庫,或更新知識庫定義以移除該參考。 對於產生索引與索引管線的知識來源,所有 產生的物件 也會被刪除。 不過,如果你用現有的索引建立知識來源,你的索引不會被刪除。
如果你嘗試刪除正在使用的知識來源,該動作會失敗,並回傳一份受影響的知識庫清單。
刪除知識來源:
取得您 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}"); }範例回應可能如下所示:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }取得一個獨立的知識庫定義,以檢查是否有知識來源的參考。
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);範例回應可能如下所示:
{ "Name": "earth-knowledge-base", "KnowledgeSources": [ { "Name": "earth-knowledge-source" } ], "Models": [ {} ], "RetrievalReasoningEffort": {}, "OutputMode": {}, "ETag": "\u00220x8DE278629D782B3\u0022", "EncryptionKey": null, "Description": null, "RetrievalInstructions": null, "AnswerInstructions": null }要麼刪除知識庫,要麼如果你有多個知識來源,就更新知識庫來移除該來源。 這個例子顯示刪除。
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.");刪除知識來源。
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
取得您 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}")範例回應可能如下所示:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }取得一個獨立的知識庫定義,以檢查是否有知識來源的參考。
# 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)範例回應可能如下所示:
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks" } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }要麼刪除知識庫,要麼如果你有多個知識來源,就更新知識庫來移除該來源。 這個例子顯示刪除。
# 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.")刪除知識來源。
# 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.")
取得您 Foundry IQ 服務中所有知識庫的清單。
### Get knowledge bases GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name Authorization: Bearer {{token}}參考資料:知識庫 - 列出
範例回應可能如下所示:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }取得一個獨立的知識庫定義,以檢查是否有知識來源的參考。
### Get a knowledge base definition GET {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}參考:知識庫 - 取得
範例回應可能如下所示:
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks" } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }要麼刪除知識庫,要麼如果你有多個知識來源,就更新知識庫來移除該來源。 這個例子顯示刪除。
### Delete a knowledge base DELETE {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}參考資料:知識庫 - 刪除
刪除知識來源。
### Delete a knowledge source DELETE {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}參考資料:知識來源 - 刪除