建立 Fabric Data Agent 知識來源(預覽)

Note

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

Important

Fabric Data Agent 知識來源目前處於公開預覽階段,並受 Microsoft Azure 預覽版補充使用條款規範。

有關此功能專屬的預覽條款,請參閱 預覽功能。

有關連接外部資料來源時適用的術語,請參閱「外部資料來源」。

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

Fabric Data Agent 知識來源(預覽版)將您的 Microsoft Fabric Data Agent 連接到 Foundry IQ(Azure AI 搜尋服務)中的代理式擷取管線。 知識來源是獨立建立的,會在 知識庫中加以參考,並在知識庫於執行階段查詢時作為接地資料使用。

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

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

使用支援

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

先決條件

  • 最新的 Azure.Search.Documents 預覽套件:dotnet add package Azure.Search.Documents --prerelease

  • 對於無鑰匙認證,套件如下 Azure.Identity : dotnet add package Azure.Identity

資料治理與合規

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

參考: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-11-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 標頭中傳遞使用者存取權杖。 該代幣的範圍必須限定為 Foundry IQ 對象(https://search.azure.com/.default)。 擷取引擎會將此權杖交換為 Microsoft Fabric 範圍的權杖,並使用該權杖代表使用者查詢 Fabric Data Agent。

擷取請求時也必須使用標準 Foundry IQ 驗證。 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
    }
  ]
}

刪除知識來源

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

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

刪除知識來源:

  1. 取得您 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}");
    }
    

    參考:SearchIndexClient

    範例回應可能如下所示:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  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
     }
    
  3. 要麼刪除知識庫,要麼如果你有多個知識來源,就更新知識庫來移除該來源。 這個例子顯示刪除。

    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

  4. 刪除知識來源。

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

    參考:SearchIndexClient

  1. 取得您 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}")
    

    參考:SearchIndexClient

    範例回應可能如下所示:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  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"
       }
     }
    
  3. 要麼刪除知識庫,要麼如果你有多個知識來源,就更新知識庫來移除該來源。 這個例子顯示刪除。

    # 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

  4. 刪除知識來源。

    # 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

  1. 取得您 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"
         }
         ]
     }
    
  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"
       }
     }
    
  3. 要麼刪除知識庫,要麼如果你有多個知識來源,就更新知識庫來移除該來源。 這個例子顯示刪除。

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

    參考資料:知識庫 - 刪除

  4. 刪除知識來源。

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

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