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

註

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

使用 REST API 建立2026-11-01-preview,以匯入 Microsoft OneLake 檔案,並保留 Foundry IQ(Azure AI 搜尋服務)中的來源權限。 知識來源 會獨立建立,並在 知識庫中被引用,並在 執行時查詢知識庫時作為基礎資料。

Important

本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。

有關 Foundry IQ(Azure AI 搜尋服務)專屬的預覽條款,請參閱預覽功能。

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

當您建立已編製索引的 OneLake 知識來源時,Foundry IQ 會自動產生下列物件:

  • 代表湖存放庫的資料來源。
  • 一套技能集,可以將 Lakehouse 的多模態內容分割並選擇性地向量化。
  • 一個儲存豐富內容且符合代理檢索標準的索引。
  • 使用先前物件來驅動編製索引和擴充管線的索引子。

產生的索引器符合 OneLake 索引器。 其先決條件、支援的任務、文件格式和限制也適用於 OneLake 知識來源。 請參閱 OneLake 索引器說明文件和 索引器限制。 一般捷徑擷取支援與權限感知擷取是分開的,後者在此預覽中排除了捷徑衍生的內容。 若所產生的技能組呼叫外部服務,該技能的輸入與服務限制也會適用。

先決條件

  • Azure 公有雲中、位於提供代理式擷取的區域的 Foundry IQ 服務。

  • 完成 OneLake 索引器先決條件 及 資料準備。

  • 完成 OneLake 權限保留的先決條件。 Foundry IQ 服務必須具有 系統指派的受控識別。 將此身份指派為 Fabric 工作區中的管理員角色。

  • 允許建立知識來源。 建議使用分配給你的使用者帳號的搜尋服務貢獻者和搜尋索引資料貢獻者角色來設定無密鑰認證,或使用管理員 API 金鑰。

  • 一個 REST 用戶端。 本文中的請求請使用搜尋服務 REST API 版本 2026-11-01-preview。 若要進行無金鑰驗證,請取得用於 標頭的 Authorization。

  • 如果您將 contentExtractionMode 設定為 standard,請使用位於 Foundry Tools 支援內容理解的區域中的 Microsoft Foundry 資源,以及其 https://<resource-name>.services.ai.azure.com 端點。 部署嵌入模型,若啟用影像語言化,則部署多模態聊天模型。 本文範例使用 minimal 並停用影像轉述。

  • 對 Azure OpenAI 嵌入或影像描述進行受控識別呼叫時,請將 Cognitive Services OpenAI User 指派給 Azure OpenAI 或其上層 Foundry 資源上與 resourceUri 相符的所選身分識別。 擷取服務權限是分開的。 請參閱 「指派角色」。

  • 若要進行私人內嵌,請使用符合 共享私有連結工作負載需求的合格 S2、S3、L1 或 L2 專用服務。 使用Microsoft.Fabric/privateLinkServicesForFabric目標與群組 ID(如workspace中所述),建立並核准指向 Fabric 工作區的共用私有連結。 為您的管線所使用的任何受保護的擷取作業、模型或其他 Azure 相依性設定核准的連結。

限制

Serverless 與 S3 HD 不支援私有索引器執行或對外連線 Search 共用私人連結。 網路安全邊界配置控制支援的公用端點存取;但不會啟用私人執行。

啟用 OneLake 權限匯入後,可省略資產儲存、豐富快取及圖譜擷取設定。 有關支援的技能及其他預覽限制,請參閱 OneLake 權限保留限制。

檢查現有的知識來源

知識來源是一個頂層且可重複使用的物件。 在選擇名稱或建立新物件之前,請先檢查現有的知識來源。

傳送 GET /knowledgesources?api-version=2026-11-01-preview&$select=name,kind 至您的搜尋端點。

若要檢視單一定義,請傳送 GET /knowledgesources/<knowledge-source-name>?api-version=2026-11-01-preview。 請在每個請求中包含您的驗證標頭。

建立知識來源

使用以下 REST 請求建立知識來源。 此範例使用最少的內容擷取,停用影像語音化,並啟用 OneLake 權限保留。

保留 OneLake 權限(預覽)

在 indexedOneLakeParameters.ingestionParameters.ingestionPermissionOptions 中同時設定 oneLakeParentFolders 和 oneLakeLakehouseId。 不同於直接 OneLake 資料來源中的 indexerPermissionOptions,若要建立安全索引的 OneLake 知識來源,這兩個值必須同時提供。

請將您的 Foundry IQ 服務名稱、存取權杖、工作區 ID 和 lakehouse ID 替換為您的值。

PUT https://<search-service>.search.windows.net/knowledgesources/my-secured-onelake-ks?api-version=2026-11-01-preview
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "my-secured-onelake-ks",
  "kind": "indexedOneLake",
  "indexedOneLakeParameters": {
    "fabricWorkspaceId": "<fabric-workspace-id>",
    "lakehouseId": "<lakehouse-id>",
    "ingestionParameters": {
      "contentExtractionMode": "minimal",
      "disableImageVerbalization": true,
      "ingestionPermissionOptions": [
        "oneLakeParentFolders",
        "oneLakeLakehouseId"
      ]
    }
  }
}

有關權限設定及其限制條件,請參閱 「設定索引的 OneLake 知識來源」。

建立回應會在 indexedOneLakeParameters.createdResources 下列出所產生的物件。 知識來源會產生啟用權限的索引、欄位映射以及區塊投影。 你不需要分別設定這些映射。 有關產生欄位需求與查詢時間授權,請參閱保留 OneLake 權限。

可選設定會使用下列屬性路徑:

  • indexedOneLakeParameters.targetPath:限制擷取至 Lakehouse 中的資料夾。 由捷徑衍生的內容仍排除在權限感知檢索之外。
  • indexedOneLakeParameters.ingestionParameters.embeddingModel:設定可選的內容向量化。
  • indexedOneLakeParameters.ingestionParameters.chatCompletionModel:設定聊天完成模型以進行圖片口語化或上下文擷取。 範例中會停用影像描述。
  • indexedOneLakeParameters.ingestionParameters.ingestionSchedule:使用 interval 和可選的 startTime 設定來源變更輪詢。 在符合條件的執行時間停止後自動繼續與此輪詢間隔無關。 無論是排程還是接續執行,都不會確認權限的新近狀態。

新增選擇性設定時,請保留這兩個權限選項。 網路存取模式預設為 public;對於符合資格的專用配置,請參閱 「限制擷取至私人網路」。

限制擷取權限僅限於私人網路

已建立索引的 OneLake 知識來源私人擷取功能,已在符合條件的 Dedicated 服務中透過 REST API 2026-10-01 正式推出。 本文範例中的 OneLake 權限保留另行要求 2026-11-01-preview。

在建立請求中,將 indexedOneLakeParameters.ingestionParameters.networkAccessMode 設為 private。

  1. 完成 私人網路的必要條件。

  2. 在建立知識來源的請求中,將 networkAccessMode 設為 private。 您只能在建立過程中設定此屬性,包括在穩定版 2026-10-01 API 中。 若要稍後變更儲存模式,請刪除並重新建立知識來源。 符合資格的 Blob、ADLS Gen2 和 Azure SQL 來源則可改用臨時生成索引器的網路覆寫。 此例外不適用於已建立索引的 SharePoint 或其他來源類型。

    如果服務層級或執行時不支援私有執行,或沒有所需的共享私有連結,建立可能會失敗。 Serverless 和 S3 HD 不支援私人執行。 網路安全邊界設定 控制支援的公用端點存取,而非私人執行。

  3. 確認產生的索引器 parameters.configuration.executionEnvironment 為 private。

  4. 確認每個所需的共用私有連結都已核准、配置完成,且指向正確的相依資源。 僅成功建立並不代表連結已獲核准或已設定目標對象。 如果入口網站檢查無法解決跨訂閱資源,請手動驗證目標資源及 Foundry IQ 服務的核准與準備狀態。

  5. 輪詢知識來源狀態直到 lastSynchronizationState.endTime 有值為止。 確認 itemsUpdatesFailed 為 0,然後驗證連接器專屬的來源內容。 如果相依項目無法存取,同步就會失敗。

設定標準擷取

若要使用 Content Understanding 來進行版面擷取與語意分塊,而非前述範例中的 minimal 擷取,請將 contentExtractionMode 設為 standard,並使用您的 Foundry 資源端點設定 aiServices。 使用 先決條件 中所述的資源和部署。

標準擷取會產生 Content Understanding 費用;啟用影像描述時,還會產生模型使用費用。 如需更多資訊,請參閱 計費與影像描述控制項。

使用自動語言分析器(預覽)

若要啟用自動按語言分析器,請設定 indexedOneLakeParameters.ingestionParameters.contentExtractionMode 為 minimal。 設定indexedOneLakeParameters.ingestionParameters.aiServices.uri為您的 Microsoft Foundry 資源端點。 Foundry IQ 會偵測每個來源文件的語言,並套用相符的 Microsoft 語言分析器。 你不會在知識來源定義或查詢中指定分析器。

對於無金鑰驗證,省略 indexedOneLakeParameters.ingestionParameters.aiServices.apiKey。 將您 Microsoft Foundry 資源上的 認知服務使用者 角色指派給您 Foundry IQ 服務的受控識別。

支援的語言包括英語、日語、法語、西班牙語、德語、荷蘭語、義大利語、巴西葡萄牙語、歐洲葡萄牙語、簡體中文、繁體中文及韓語。

對於多語言內容,Foundry IQ 會根據主要偵測語言選擇分析器。 當語言不支援或不確定時,它會使用標準分析器。

啟用此選項後,產生的索引會包含每種支援語言的專屬語言內容欄位,即使您的資料不包含這些語言。 在導入過程中,Foundry IQ 會根據偵測到的語言,將文件路由至對應的欄位。 未使用的欄位不含索引內容,且對儲存空間的影響極小,但仍會計入 索引欄位限制。 在規劃欄位數量與 儲存容量時,請將這些欄位納入考量。

語言偵測在 免費 AI 豐富化分配後可計費。

檢查吞食狀態

將驗證標頭傳送 GET /knowledgesources/my-secured-onelake-ks/status?api-version=2026-11-01-preview 至您的搜尋端點。

檢視同步狀態、目前和先前的同步狀態,以及文件層級的錯誤。 利用 索引器狀態與執行歷史 來調查擷取失敗。 成功匯入並不代表來源權限變更已生效。 請參閱權限與路徑時效性。

檢視產生的物件

產生的資料來源、技能集、索引器與索引皆依據知識來源名稱命名。 你不能變更這些名稱。 避免直接編輯物件,因為變更可能會破壞索引器管線。

使用來自 indexedOneLakeParameters.createdResources 的產生物件名稱來擷取每個定義。 將 GET /<resource-collection>/<generated-object-name>?api-version=2026-11-01-preview 連同您的驗證標頭傳送至您的搜尋端點。 資源集合為 indexers、 datasources、 skillsets和 indexes。

  1. 請附上驗證標頭傳送 GET /indexers/<generated-indexer-name>/status?api-version=2026-11-01-preview 。 檢查 lastResult 和 executionHistory 的執行狀態與錯誤訊息,包括連線或配額錯誤。 請參閱「使用取得索引器狀態進行監控」。
  2. 檢查資料來源以驗證 lakehouse 連線及受管理身份設定。
  3. 檢查技能組,了解內容如何分塊並可選擇向量化。
  4. 檢查索引的內容與權限欄位。 確認產生的欄位映射與區塊投影是否保留來源位置的中繼資料。

指派至知識庫

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

對於任何指定已索引 OneLake 知識來源的知識庫,請設 includeReferenceSourceData 為 true。 此設定是將來源文件 URL 拉入引用中所必需的。

查詢知識庫

設定知識庫後, 呼叫擷取動作或 MCP 端點 查詢知識來源。

強制執行文件層級權限 (預覽版)

使用 2026-11-01-preview 進行 OneLake 權限感知要求。 請將請求使用者的存取權杖包含在 x-ms-query-source-authorization 中,如同「在查詢時強制執行權限(預覽)」一文所述。 請依照 OneLake 查詢與測試指引 檢查允許與拒絕的使用者。

Surface 文件內嵌影像(預覽)

當已設定 ingestionPermissionOptions 時,不支援影像服務,因此請勿將 assetStore 新增至本文中的安全知識來源。 關於無需權限擷取的情況,請參閱 在 agentic retrieval 中顯示 Surface 文件內嵌影像(預覽)。

刪除知識來源

在刪除知識來源之前,請刪除任何引用該來源的知識庫,或更新知識庫定義以移除該參考。 如果來源仍在使用中,刪除失敗,並回傳受影響的知識庫清單。

  1. 傳送 GET /knowledgebases?api-version=2026-11-01-preview 以列出知識庫。 使用 GET /knowledgebases/<knowledge-base-name>?api-version=2026-11-01-preview 檢查每個定義是否包含對知識來源的引用。
  2. 更新知識庫以移除參照。 或者,如果你不再需要那個知識庫,也可以直接傳送 DELETE /knowledgebases/<knowledge-base-name>?api-version=2026-11-01-preview 。
  3. 發送 DELETE /knowledgesources/my-secured-onelake-ks?api-version=2026-11-01-preview 以刪除知識來源。 請在每個請求中包含您的驗證標頭。

刪除已索引的 OneLake 知識來源,也會刪除其產生的資料來源、技能集、索引器與索引。 它不會刪除 Microsoft Fabric 中的來源湖庫或檔案。