建立 Fabric Data Agent 知識來源（預覽）

Note

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

Important

標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。

當你連接 Fabric IQ 時，可能會產生成本，資料也可能被傳送到Azure合規範圍之外，並依照適用的服務條款和資料處理政策處理。

Fabric Data Agent 知識來源 (預覽版) 會將您的 Microsoft Fabric Data Agent 連線到 Azure AI 搜尋服務中的代理式擷取管線。知識來源獨立建立，並在知識庫中被引用，並在執行時查詢知識庫時作為基礎資料。

資料代理扮演虛擬分析師的角色，針對您的 Microsoft Fabric 資料產生並執行查詢，以回傳自然語言的答案、表格與圖表。這使得 Fabric Data Agent 的知識來源對於高流量資料和分析查詢非常有用。

與索引知識來源不同，Fabric Data Agent 的知識來源在檢索時直接查詢即時資料。不需要資料擷取流程。查詢需要一個終端使用者存取權杖，檢索引擎會利用此憑證代表終端使用者查詢 Fabric 資料代理。

使用支援

Azure portal	Microsoft Foundry 入口網站	.NET SDK	Python SDK	Java 開發套件	JavaScript SDK	REST API
✔️	✔️	✔️	✔️	✔️	✔️	✔️

先決條件

任何區域內提供主動檢索的 Azure AI 搜尋服務服務。
具有資料代理程式的 Microsoft Fabric 工作區。
你的搜尋服務和工作空間必須在同一個 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

搜尋服務 REST API 的 2026-08-01 預覽版。
對於無金鑰認證，請在Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。

資料治理與合規

Fabric IQ 會在您工作區所在區域的 Microsoft Fabric 合規界限內處理請求。當你透過 Fabric IQ 路由代理查詢時，以下承諾會適用。

資料存放位置

Fabric IQ 會在您的 Microsoft Fabric 工作區所在區域內擷取並處理資料。查詢執行時，資料不會跨越區域邊界。適用的區域及其合規範圍由您工作空間的地點決定。有關支援區域清單及各區域所符合的合規框架，請參見 Microsoft Fabric 區域可用性。

Note

如果您的 Azure AI 搜尋服務服務位於與 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}");
}

參考資料：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})")

參考資料：SearchIndexClient

### 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));

參考資料：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))

參考資料：SearchIndexClient

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

參考資料：知識來源 - 取得

以下 JSON 是 Fabric Data Agent 知識來源的範例回應。

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

建立知識來源

執行以下程式碼以建立 Fabric Data Agent 知識來源。

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 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);

參考資料：SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    FabricDataAgentKnowledgeSource,
    FabricDataAgentKnowledgeSourceParameters,
)

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

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)

參考資料：SearchIndexClient

### Create a Fabric Data Agent knowledge source
PUT {{search-endpoint}}/knowledgesources/my-fabric-data-agent-ks?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
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}"
  }
}

參考資料：知識來源 - 建立或更新

指派至知識庫

如果你對知識來源感到滿意，就把它加入知識庫。

Important

Fabric Data Agent 的知識來源不支援 minimal擷取推理作業。請改用 low 或 medium。

查詢知識庫

知識庫設定完成後，呼叫擷取動作或 MCP 端點來查詢 Fabric Data Agent 內容。此知識來源具有獨特的查詢時間權限強制與回應特性。

在查詢過程中強制執行權限

Fabric Data Agent 知識來源會使用代理者流程 (OBO) 權杖流程。您會在擷取要求的 x-ms-query-source-authorization 標頭中傳遞使用者存取權杖。權杖範圍必須限定為 Azure AI 搜尋服務對象 (https://search.azure.com/.default)。擷取引擎會將此權杖交換為 Microsoft Fabric 範圍的權杖，並使用該權杖代表使用者查詢 Fabric Data Agent。

檢索請求時也必須使用標準的 Azure AI 搜尋服務認證。 x-ms-query-source-authorization憑證是分開傳遞的，並不取代服務認證。

關於傳遞權杖的說明，請參閱在查詢時強制執行權限 (預覽版)。

Fabric Data Agent 專用回應欄位

Fabric Data Agent 知識來源會在每個 sourceData 項目的 references 物件中傳回結果，並在 activity 陣列中傳回查詢診斷。 sourceData 包含：

fabricAnswer資料代理人的自然語言回答。
fabricEmbeddedResources：任何嵌入的資源，例如表格和圖表，當查詢產生結構化輸出時。

以下範例展示了包含 Fabric Data Agent 知識來源參考及其對應活動記錄的檢索回應。關於解讀檢索回應的更廣泛指引，請參見「檢視回應」。

Tip

若要接收參考的 sourceData，請在擷取要求的 includeReferenceSourceData 中，將知識來源項目上的 true 設定為 knowledgeSourceParams。

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

刪除知識來源

在刪除知識來源之前，必須刪除所有引用該來源的知識庫，或更新知識庫定義以移除該參考。對於產生索引與索引管線的知識來源，所有 產生的物件 也會被刪除。不過，如果你用現有的索引建立知識來源，你的索引不會被刪除。

如果你嘗試刪除正在使用的知識來源，該動作會失敗，並回傳一份受影響的知識庫清單。

刪除知識來源：

取得你搜尋服務中所有知識庫的清單。

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

參考資料：SearchIndexClient

範例回應可能如下所示：

 {
     "@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);

參考資料：SearchIndexClient

範例回應可能如下所示：

 {
   "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.");

參考資料：SearchIndexClient

刪除知識來源。

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

參考資料：SearchIndexClient

取得你搜尋服務中所有知識庫的清單。

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

參考資料：SearchIndexClient

範例回應可能如下所示：

 {
     "@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)

參考資料：SearchIndexClient

範例回應可能如下所示：

 {
   "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.")

參考資料：SearchIndexClient

刪除知識來源。

# 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.")

參考資料：SearchIndexClient

取得你搜尋服務中所有知識庫的清單。

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

參考資料：知識來源 - 刪除

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-17

建立 Fabric Data Agent 知識來源（預覽）

使用支援

先決條件

資料治理與合規

資料存放位置

合規性認證

檢查現有的知識來源

建立知識來源

指派至知識庫

查詢知識庫

在查詢過程中強制執行權限

Fabric Data Agent 專用回應欄位

刪除知識來源

相關內容

意見反應

其他資源