共用方式為

建立一個索引化的 SharePoint 知識來源

備註

這項功能目前處於公開預覽狀態。 此預覽版在沒有服務等級協議的情況下提供，不建議用於生產工作負載。 可能不支援特定功能，或可能已經限制功能。 欲了解更多資訊，請參閱Microsoft Azure預覽補充使用條款。

使用indexed SharePoint knowledge source來索引並查詢代理檢索流程中的SharePoint內容。 知識來源 獨立建立，並在 知識庫中被引用，並作為代理或聊天機器人在查詢時呼叫 擷取動作 時的基礎資料。

當你建立索引 SharePoint 知識庫時，你可以指定一個 SharePoint 連接字串、模型和屬性，以自動生成以下 Azure AI 搜尋服務 物件。

  • 一個指向 SharePoint 網站的資料來源。
  • 一套技能組合，可以分割並可選擇向量化多模態內容。
  • 儲存擴充內容並符合代理程式擷取準則的索引。
  • 使用先前物件來驅動編製索引和擴充管線的索引子。

使用支援

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

先決條件

檢查現有的知識來源

知識來源是一個頂層、可重複使用的物件。 瞭解現有的知識來源有助於重複使用或命名新物件。

執行以下程式碼，依名稱和類型列出知識來源。

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

您也可以按名稱傳回單一知識來源以檢閱其 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));

以下 JSON 是一個針對索引 SharePoint 知識來源的範例回應。

{
  "name": "my-indexed-sharepoint-ks",
  "kind": "indexedSharePoint",
  "description": "A sample indexed SharePoint knowledge source",
  "encryptionKey": null,
  "indexedSharePointParameters": {
    "connectionString": "<redacted>",
    "containerName": "defaultSiteLibrary",
    "query": null,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "minimal",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<redacted>",
          "deploymentId": "text-embedding-3-large",
          "apiKey": "<redacted>",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": null,
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": null
    },
    "createdResources": {
      "datasource": "my-indexed-sharepoint-ks-datasource",
      "indexer": "my-indexed-sharepoint-ks-indexer",
      "skillset": "my-indexed-sharepoint-ks-skillset",
      "index": "my-indexed-sharepoint-ks-index"
    }
  },
  "indexedOneLakeParameters": null
}

備註

敏感性資訊已被遮蔽。 產生的資源會出現在回應的結尾。

建立知識來源

執行以下程式碼建立一個索引化的 SharePoint 知識來源。

// Create an IndexedSharePoint knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

var chatCompletionParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var embeddingParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiEmbeddingDeployment,
    ModelName = aoaiEmbeddingModel
};

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    DisableImageVerbalization = false,
    ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    }
};

var sharePointParams = new IndexedSharePointKnowledgeSourceParameters(
    connectionString: sharePointConnectionString,
    containerName: "defaultSiteLibrary")
{
    IngestionParameters = ingestionParams
};

var knowledgeSource = new IndexedSharePointKnowledgeSource(
    name: "my-indexed-sharepoint-ks",
    indexedSharePointParameters: sharePointParams)
{
    Description = "A sample indexed SharePoint knowledge source."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

來源特定屬性

你可以傳遞以下屬性來建立索引化的 SharePoint 知識來源。

名稱 Description 類型 可編輯 為必填項目
Name 知識來源的名稱必須在知識來源集合中唯一，並遵循Azure AI 搜尋服務中物件的命名指引。 繩子 否 Yes
Description 知識來源的描述。 繩子 Yes 否
EncryptionKey 用來加密知識來源與產生物件中敏感性資訊的客戶自控金鑰。 物體 Yes 否
IndexedSharePointKnowledgeSourceParameters 針對索引SharePoint知識來源的特定參數：connectionString、containerName，以及 query。 物體 否 否
connectionString 連接到 SharePoint 網站的連接字串。 欲了解更多資訊，請參閱 連接字串語法。 繩子 Yes Yes
containerName 需要存取的 SharePoint 資料庫。 可從 defaultSiteLibrary 網站預設文件庫中索引內容，或 allSiteLibraries 索引網站上所有文件庫的內容。 暫時忽略 useQuery 。 繩子 否 Yes
query 可選的query 用於篩選SharePoint內容。 繩子 Yes 否

ingestion_parameters 屬性

僅可針對已編製索引的知識來源傳遞下列 ingestionParameters 屬性，以控制如何內嵌與處理內容。

名稱 Description 類型 可編輯 為必填項目
Identity 在產生的索引子中要使用的受控識別。 物體 Yes 否
DisableImageVerbalization 啟用或停用影像語言化的使用。 預設為 False，這會啟用影像語言化。 設定為 True 即可停用影像語言化。 布林值 否 否
ChatCompletionModel 用於將影像語言化或擷取內容的聊天完成模型。 支援的模型有 gpt-4o、gpt-4o-mini、gpt-4.1、gpt-4.1-mini、gpt-4.1-nano、gpt-5、gpt-5-mini 和 gpt-5-nano。 產生的技能中會包括 GenAI 提示技能。 設定此參數也需要將 DisableImageVerbalization 設定為 False。 物體 只有 ApiKey 和 DeploymentName 是可編輯 否
EmbeddingModel 在編製索引與查詢時，將文字與影像內容向量化的文字內嵌模型。 支援的模型有 text-embedding-ada-002、text-embedding-3-small 和 text-embedding-3-large。 Azure OpenAI 嵌入技能將包含在生成的技能集中，而 Azure OpenAI 向量器 將包含在生成的索引中。 物體 只有 ApiKey 和 DeploymentName 是可編輯 否
ContentExtractionMode 控制如何從檔案中擷取內容。 預設為 minimal，會對文字與影像使用標準內容擷取。 設定為 standard，用於使用Azure內容理解技能進行進階文件破解與分塊，該技能將包含在生成的技能組中。 只有在 standard 的情況下，才可以指定 AiServices 和 AssetStore 參數。 繩子 否 否
AiServices 用來在 Foundry Tools 中存取 Azure 內容瞭解的 Microsoft Foundry 資源。 設定此參數前必須將 ContentExtractionMode 設定為 standard。 物體 只有 ApiKey 是可編輯 Yes
AssetStore 用來儲存已擷取影像的 Blob 容器。 設定此參數前必須將 ContentExtractionMode 設定為 standard。 物體 否 否
IngestionSchedule 將排程資訊新增至產生的索引子。 您也可以稍後 新增排程 ，以自動重新整理資料。 物體 Yes 否
IngestionPermissionOptions 隨內容一併內嵌的文件層級權限。 指定 UserIds、 GroupIds，或 RbacScope 在索引中儲存權限的元資料。 關於特定來源的指引，請參見 從 Blob 儲存體擷取 RBAC 權限 及 從 ADLS Gen2 擷取 ACLs。 欲在查詢時強制執行這些權限，請參閱 「在查詢時強制執行權限」。 Array 否 否

檢查內嵌狀態

執行以下程式碼以監視擷取的進度與健康情況，包括那些產生索引器管線並填入搜尋索引的知識來源的索引器狀態。

// Get knowledge source ingestion status
using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

// Get the knowledge source status
var statusResponse = await indexClient.GetKnowledgeSourceStatusAsync(knowledgeSourceName);
var status = statusResponse.Value;

// Serialize to JSON for display
var json = JsonSerializer.Serialize(status, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

對於包括擷取參數且正在內嵌內容的要求，其回應可能如下列範例所示。

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

檢閱已建立的物件

當你建立索引化的 SharePoint 知識來源時，你的搜尋服務也會建立索引器、索引器、技能組和資料來源。 不建議您編輯這些物件，因為引入錯誤或不相容性可能會中斷管線。

建立知識來源之後，回應會列出已建立的物件。 這些物件是根據固定的範本建立的，其名稱是根據知識來源的名稱而建立的。 您無法變更物件名稱。

我們建議使用 Azure 入口網站來驗證輸出產生。 工作流程為：

  1. 檢查索引子是否有成功或失敗訊息。 連線或配額錯誤會出現在這裡。
  2. 檢查索引中是否有可搜尋的內容。 使用 Search Explorer 來執行查詢。
  3. 檢查技能集，了解如何將您的內容進行分塊和選擇性向量化。
  4. 請檢查資料來源以取得連線詳細資料。 我們的範例使用 API 金鑰以簡化流程，但你也可以使用 Microsoft Entra ID 來進行認證，並用基於角色的存取控制來授權。

指派至知識庫

如果你對知識來源感到滿意，就繼續下一步：在 知識庫中指定知識來源。

對於指定索引SharePoint知識來源的知識庫，請務必將 includeReferenceSourceData 設為 true。 此步驟是將來源文件 URL 提取進引文所必需。

設定知識庫之後，請使用 retrieve 動作來查詢知識來源。

小提示

要強制執行文件層級的權限，請在建立此知識來源時設定 IngestionPermissionOptions，然後在檢索請求中包含使用者的存取憑證。 欲了解更多資訊，請參閱 查詢時強制執行權限。

刪除知識來源

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

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

若要刪除知識來源：

  1. 取得搜尋服務上所有知識庫的清單。

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

    範例回應可能如下所示：

     Knowledge Bases:
   - earth-knowledge-base
   - hotels-sample-knowledge-base
   - my-demo-knowledge-base

  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
 }

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

  4. 刪除知識來源。

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

備註

這項功能目前處於公開預覽狀態。 此預覽版在沒有服務等級協議的情況下提供，不建議用於生產工作負載。 可能不支援特定功能，或可能已經限制功能。 欲了解更多資訊，請參閱Microsoft Azure預覽補充使用條款。

使用indexed SharePoint knowledge source來索引並查詢代理檢索流程中的SharePoint內容。 知識來源 獨立建立，並在 知識庫中被引用，並作為代理或聊天機器人在查詢時呼叫 擷取動作 時的基礎資料。

當您建立已編制索引的 SharePoint 知識來源時，您應指定一個 SharePoint 連接字串、模型和屬性，以自動生成以下 Azure AI 搜索物件：

  • 一個指向 SharePoint 網站的資料來源。
  • 一套技能組合，可以分割並可選擇向量化多模態內容。
  • 儲存擴充內容並符合代理程式擷取準則的索引。
  • 使用先前物件來驅動編製索引和擴充管線的索引子。

使用支援

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

先決條件

檢查現有的知識來源

知識來源是一個頂層、可重複使用的物件。 瞭解現有的知識來源有助於重複使用或命名新物件。

執行以下程式碼，依名稱和類型列出知識來源。

# List knowledge sources by name and type
import requests
import json

endpoint = "{search_url}/knowledgesources"
params = {"api-version": "2025-11-01-preview", "$select": "name, kind"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

您也可以按名稱傳回單一知識來源以檢閱其 JSON 定義。

# Get a knowledge source definition
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

以下 JSON 是一個針對索引 SharePoint 知識來源的範例回應。

{
  "name": "my-indexed-sharepoint-ks",
  "kind": "indexedSharePoint",
  "description": "A sample indexed SharePoint knowledge source",
  "encryptionKey": null,
  "indexedSharePointParameters": {
    "connectionString": "<redacted>",
    "containerName": "defaultSiteLibrary",
    "query": null,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "minimal",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<redacted>",
          "deploymentId": "text-embedding-3-large",
          "apiKey": "<redacted>",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": null,
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": null
    },
    "createdResources": {
      "datasource": "my-indexed-sharepoint-ks-datasource",
      "indexer": "my-indexed-sharepoint-ks-indexer",
      "skillset": "my-indexed-sharepoint-ks-skillset",
      "index": "my-indexed-sharepoint-ks-index"
    }
  },
  "indexedOneLakeParameters": null
}

備註

敏感性資訊已被遮蔽。 產生的資源會出現在回應的結尾。

建立知識來源

執行以下程式碼建立一個索引化的 SharePoint 知識來源。

# Create an indexed SharePoint knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import IndexedSharePointKnowledgeSource, IndexedSharePointKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

knowledge_source = IndexedSharePointKnowledgeSource(
    name = "my-indexed-sharepoint-ks",
    description = "A sample indexed SharePoint knowledge source.",
    encryption_key = None,
    indexed_share_point_parameters = IndexedSharePointKnowledgeSourceParameters(
        connection_string = "connection_string",
        container_name = "defaultSiteLibrary",
        query = None,
        ingestion_parameters = KnowledgeSourceIngestionParameters(
            identity = None,
            disable_image_verbalization = False,
            chat_completion_model = KnowledgeBaseAzureOpenAIModel(
                azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
                    # TRIMMED FOR BREVITY
                )
            ),
            embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
                azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                    # TRIMMED FOR BREVITY
                )
            ),
            content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
            ingestion_schedule = None,
            ingestion_permission_options = None
        )
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

來源特定屬性

你可以傳遞以下屬性來建立索引化的 SharePoint 知識來源。

名稱 Description 類型 可編輯 為必填項目
name 知識來源的名稱必須在知識來源集合中唯一，並遵循Azure AI 搜尋服務中物件的命名指引。 繩子 否 Yes
description 知識來源的描述。 繩子 Yes 否
encryption_key 用來加密知識來源與產生物件中敏感性資訊的客戶自控金鑰。 物體 Yes 否
indexed_share_point_parameters 針對索引SharePoint知識來源的特定參數：connection_string、container_name，以及 query。 物體 否 否
connection_string 連接到 SharePoint 網站的連接字串。 欲了解更多資訊，請參閱 連接字串語法。 繩子 Yes Yes
container_name 需要存取的 SharePoint 資料庫。 可從 defaultSiteLibrary 網站預設文件庫中索引內容，或 allSiteLibraries 索引網站上所有文件庫的內容。 暫時忽略 useQuery 。 繩子 否 Yes
query 可選的query 用於篩選SharePoint內容。 繩子 Yes 否

ingestion_parameters 屬性

僅可針對已編製索引的知識來源傳遞下列 ingestionParameters 屬性，以控制如何內嵌與處理內容。

名稱 Description 類型 可編輯 為必填項目
identity 在產生的索引子中要使用的受控識別。 物體 Yes 否
disable_image_verbalization 啟用或停用影像語言化的使用。 預設為 False，這會啟用影像語言化。 設定為 True 即可停用影像語言化。 布林值 否 否
chat_completion_model 用於將影像語言化或擷取內容的聊天完成模型。 支援的模型有 gpt-4o、gpt-4o-mini、gpt-4.1、gpt-4.1-mini、gpt-4.1-nano、gpt-5、gpt-5-mini 和 gpt-5-nano。 產生的技能中會包括 GenAI 提示技能。 設定此參數也需要將 disable_image_verbalization 設定為 False。 物體 只有 api_key 和 deployment_name 是可編輯 否
embedding_model 在編製索引與查詢時，將文字與影像內容向量化的文字內嵌模型。 支援的模型有 text-embedding-ada-002、text-embedding-3-small 和 text-embedding-3-large。 Azure OpenAI 嵌入技能將包含在生成的技能集中，而 Azure OpenAI 向量器 將包含在生成的索引中。 物體 只有 api_key 和 deployment_name 是可編輯 否
content_extraction_mode 控制如何從檔案中擷取內容。 預設為 minimal，會對文字與影像使用標準內容擷取。 設定為 standard，用於使用Azure內容理解技能進行進階文件破解與分塊，該技能將包含在生成的技能組中。 只有在 standard 的情況下，才可以指定 ai_services 和 asset_store 參數。 繩子 否 否
ai_services 用來在 Foundry Tools 中存取 Azure 內容瞭解的 Microsoft Foundry 資源。 設定此參數前必須將 content_extraction_mode 設定為 standard。 物體 只有 api_key 是可編輯 Yes
asset_store 用來儲存已擷取影像的 Blob 容器。 設定此參數前必須將 content_extraction_mode 設定為 standard。 物體 否 否
ingestion_schedule 將排程資訊新增至產生的索引子。 您也可以稍後 新增排程 ，以自動重新整理資料。 物體 Yes 否
ingestion_permission_options 隨內容一併內嵌的文件層級權限。 指定 user_ids、 group_ids，或 rbac_scope 在索引中儲存權限的元資料。 關於特定來源的指引，請參見 從 Blob 儲存體擷取 RBAC 權限 及 從 ADLS Gen2 擷取 ACLs。 欲在查詢時強制執行這些權限，請參閱 「在查詢時強制執行權限」。 Array 否 否

檢查內嵌狀態

執行以下程式碼以監控資料匯入進度與健康狀態，包括知識來源的索引器狀態，此索引器會產生索引器管線並填充搜尋索引。

# Check knowledge source ingestion status
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}/status"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

對於包括擷取參數且正在內嵌內容的要求，其回應可能如下列範例所示。

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

檢閱已建立的物件

當你建立索引化的 SharePoint 知識來源時，你的搜尋服務也會建立索引器、索引器、技能組和資料來源。 不建議您編輯這些物件，因為引入錯誤或不相容性可能會中斷管線。

建立知識來源之後，回應會列出已建立的物件。 這些物件是根據固定的範本建立的，其名稱是根據知識來源的名稱而建立的。 您無法變更物件名稱。

我們建議使用 Azure 入口網站來驗證輸出產生。 工作流程為：

  1. 檢查索引子是否有成功或失敗訊息。 連線或配額錯誤會出現在這裡。
  2. 檢查索引中是否有可搜尋的內容。 使用 Search Explorer 來執行查詢。
  3. 檢查技能集，了解如何將您的內容進行分塊和選擇性向量化。
  4. 請檢查資料來源以取得連線詳細資料。 我們的範例使用 API 金鑰以簡化流程，但你也可以使用 Microsoft Entra ID 來進行認證，並用基於角色的存取控制來授權。

指派至知識庫

如果你對知識來源感到滿意，就繼續下一步：在 知識庫中指定知識來源。

對於指定索引SharePoint知識來源的知識庫，請務必將 includeReferenceSourceData 設為 true。 此步驟是將來源文件 URL 提取進引文所必需。

設定知識庫之後，請使用 retrieve 動作來查詢知識來源。

小提示

要強制執行文件層級的權限，請在建立此知識來源時設定 ingestion_permission_options，然後在檢索請求中包含使用者的存取憑證。 欲了解更多資訊，請參閱 查詢時強制執行權限。

刪除知識來源

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

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

若要刪除知識來源：

  1. 取得搜尋服務上所有知識庫的清單。

    # Get knowledge bases
import requests
import json

endpoint = "{search_url}/knowledgebases"
params = {"api-version": "2025-11-01-preview", "$select": "name"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

    範例回應可能如下所示：

     {
     "@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
import requests
import json

endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

    範例回應可能如下所示：

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

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

備註

這項功能目前處於公開預覽狀態。 此預覽版在沒有服務等級協議的情況下提供，不建議用於生產工作負載。 可能不支援特定功能，或可能已經限制功能。 欲了解更多資訊，請參閱Microsoft Azure預覽補充使用條款。

使用indexed SharePoint knowledge source來索引並查詢代理檢索流程中的SharePoint內容。 知識來源 獨立建立，並在 知識庫中被引用，並作為代理或聊天機器人在查詢時呼叫 擷取動作 時的基礎資料。

當您建立已編制索引的 SharePoint 知識來源時，您應指定一個 SharePoint 連接字串、模型和屬性，以自動生成以下 Azure AI 搜索物件：

  • 一個指向 SharePoint 網站的資料來源。
  • 一套技能組合，可以分割並可選擇向量化多模態內容。
  • 儲存擴充內容並符合代理程式擷取準則的索引。
  • 使用先前物件來驅動編製索引和擴充管線的索引子。

使用支援

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

先決條件

檢查現有的知識來源

知識來源是一個頂層、可重複使用的物件。 瞭解現有的知識來源有助於重複使用或命名新物件。

使用 知識來源 - 取得 （REST API） 依名稱和類型列出知識來源。

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version=2025-11-01-preview&$select=name,kind
api-key: {{api-key}}

您也可以按名稱傳回單一知識來源以檢閱其 JSON 定義。

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

以下 JSON 是一個針對索引 SharePoint 知識來源的範例回應。

{
  "name": "my-indexed-sharepoint-ks",
  "kind": "indexedSharePoint",
  "description": "A sample indexed SharePoint knowledge source",
  "encryptionKey": null,
  "indexedSharePointParameters": {
    "connectionString": "<redacted>",
    "containerName": "defaultSiteLibrary",
    "query": null,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "minimal",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<redacted>",
          "deploymentId": "text-embedding-3-large",
          "apiKey": "<redacted>",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": null,
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": null
    },
    "createdResources": {
      "datasource": "my-indexed-sharepoint-ks-datasource",
      "indexer": "my-indexed-sharepoint-ks-indexer",
      "skillset": "my-indexed-sharepoint-ks-skillset",
      "index": "my-indexed-sharepoint-ks-index"
    }
  },
  "indexedOneLakeParameters": null
}

備註

敏感性資訊已被遮蔽。 產生的資源會出現在回應的結尾。

建立知識來源

使用 Knowledge Sources - Create or Update （REST API） 建立或更新索引 SharePoint 知識來源。

POST {{search-url}}/knowledgesources/my-indexed-sharepoint-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
    "name": "my-indexed-sharepoint-ks",
    "kind": "indexedSharePoint",
    "description": "A sample indexed SharePoint knowledge source.",
    "encryptionKey": null,
    "indexedSharePointParameters": {
        "connectionString": "{{sharepoint-connection-string}}",
        "containerName": "defaultSiteLibrary",
        "query": null,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": false,
            "ingestionSchedule": null,
            "ingestionPermissionOptions": [],
            "contentExtractionMode": "minimal"
        }
    }
}

來源特定屬性

你可以傳遞以下屬性來建立索引化的 SharePoint 知識來源。

名稱 Description 類型 可編輯 為必填項目
name 知識來源的名稱必須在知識來源集合中唯一，並遵循Azure AI 搜尋服務中物件的命名指引。 繩子 否 Yes
kind 知識來源的種類，在此案例下為 indexedSharePoint。 繩子 否 Yes
description 知識來源的描述。 繩子 Yes 否
encryptionKey 用來加密知識來源與產生物件中敏感性資訊的客戶自控金鑰。 物體 Yes 否
indexedSharePointParameters 針對索引SharePoint知識來源的特定參數：connectionString、containerName，以及 query。 物體 否 Yes
connectionString 連接到 SharePoint 網站的連接字串。 欲了解更多資訊，請參閱 連接字串語法。 繩子 Yes 否
containerName 需要存取的 SharePoint 資料庫。 可從 defaultSiteLibrary 網站預設文件庫中索引內容，或 allSiteLibraries 索引網站上所有文件庫的內容。 暫時忽略 useQuery 。 繩子 否 Yes
query 可選的query 用於篩選SharePoint內容。 繩子 Yes 否

ingestionParameters 屬性

僅可針對已編製索引的知識來源傳遞下列 ingestionParameters 屬性，以控制如何內嵌與處理內容。

名稱 Description 類型 可編輯 為必填項目
identity 在產生的索引子中要使用的受控識別。 物體 Yes 否
disableImageVerbalization 啟用或停用影像語言化的使用。 預設為 false，這會啟用影像語言化。 設定為 true 即可停用影像語言化。 布林值 否 否
chatCompletionModel 用於將影像語言化或擷取內容的聊天完成模型。 支援的模型有 gpt-4o、gpt-4o-mini、gpt-4.1、gpt-4.1-mini、gpt-4.1-nano、gpt-5、gpt-5-mini 和 gpt-5-nano。 產生的技能中會包括 GenAI 提示技能。 設定此參數也需要將 disableImageVerbalization 設定為 false。 物體 只有 apiKey 和 deploymentId 是可編輯 否
embeddingModel 在編製索引與查詢時，將文字與影像內容向量化的文字內嵌模型。 支援的模型有 text-embedding-ada-002、text-embedding-3-small 和 text-embedding-3-large。 Azure OpenAI 嵌入技能將包含在生成的技能集中，而 Azure OpenAI 向量器 將包含在生成的索引中。 物體 只有 apiKey 和 deploymentId 是可編輯 否
contentExtractionMode 控制如何從檔案中擷取內容。 預設為 minimal，會對文字與影像使用標準內容擷取。 設定為 standard，用於使用Azure內容理解技能進行進階文件破解與分塊，該技能將包含在生成的技能組中。 只有在 standard 的情況下，才可以指定 aiServices 和 assetStore 參數。 繩子 否 否
aiServices 用來在 Foundry Tools 中存取 Azure 內容瞭解的 Microsoft Foundry 資源。 設定此參數前必須將 contentExtractionMode 設定為 standard。 物體 只有 apiKey 是可編輯 Yes
assetStore 用來儲存已擷取影像的 Blob 容器。 設定此參數前必須將 contentExtractionMode 設定為 standard。 物體 否 否
ingestionSchedule 將排程資訊新增至產生的索引子。 您也可以稍後 新增排程 ，以自動重新整理資料。 物體 Yes 否
ingestionPermissionOptions 隨內容一併內嵌的文件層級權限。 指定 userIds、 groupIds，或 rbacScope 在索引中儲存權限的元資料。 關於特定來源的指引，請參見 從 Blob 儲存體擷取 RBAC 權限 及 從 ADLS Gen2 擷取 ACLs。 欲在查詢時強制執行這些權限，請參閱 「在查詢時強制執行權限」。 Array 否 否

檢查內嵌狀態

使用 知識來源 - 狀態 (REST API) 來監視擷取進度與健康情況，包括會產生索引子管線並填入搜尋索引之知識來源的索引子狀態。

### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

對於包括擷取參數且正在內嵌內容的要求，其回應可能如下列範例所示。

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

檢閱已建立的物件

當你建立索引化的 SharePoint 知識來源時，你的搜尋服務也會建立索引器、索引器、技能組和資料來源。 不建議您編輯這些物件，因為引入錯誤或不相容性可能會中斷管線。

建立知識來源之後，回應會列出已建立的物件。 這些物件是根據固定的範本建立的，其名稱是根據知識來源的名稱而建立的。 您無法變更物件名稱。

我們建議使用 Azure 入口網站來驗證輸出產生。 工作流程為：

  1. 檢查索引子是否有成功或失敗訊息。 連線或配額錯誤會出現在這裡。
  2. 檢查索引中是否有可搜尋的內容。 使用 Search Explorer 來執行查詢。
  3. 檢查技能集，了解如何將您的內容進行分塊和選擇性向量化。
  4. 請檢查資料來源以取得連線詳細資料。 我們的範例使用 API 金鑰以簡化流程，但你也可以使用 Microsoft Entra ID 來進行認證，並用基於角色的存取控制來授權。

指派至知識庫

如果你對知識來源感到滿意，就繼續下一步：在 知識庫中指定知識來源。

對於指定索引SharePoint知識來源的知識庫，請務必將 includeReferenceSourceData 設為 true。 此步驟是將來源文件 URL 提取進引文所必需。

設定知識庫之後，請使用 retrieve 動作來查詢知識來源。

小提示

要強制執行文件層級的權限，請在建立此知識來源時設定 ingestionPermissionOptions，然後在檢索請求中包含使用者的存取憑證。 欲了解更多資訊，請參閱 查詢時強制執行權限。

刪除知識來源

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

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

若要刪除知識來源：

  1. 取得搜尋服務上所有知識庫的清單。

    ### Get knowledge bases
GET {{search-endpoint}}/knowledgebases?api-version=2025-11-01-preview&$select=name
api-key: {{api-key}}

    範例回應可能如下所示：

     {
     "@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-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

    範例回應可能如下所示：

     {
   "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-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

  4. 刪除知識來源。

    ### Delete a knowledge source
DELETE {{search-endpoint}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

相關內容

  • Last updated on