為 blob 和檔案編製索引以產生多個搜尋文件

備註

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

適用於: Blob 索引器、 檔案索引器(預覽版)

根據預設,索引子會將 Blob 或檔案的內容視為單一搜尋檔。 如果您想要在搜尋索引中取得更細微的表示法,您可以設定 parsingMode 值,以從一個 Blob 或檔案建立多個搜尋檔。 產生許多搜尋文件的 解析模式 值包括 delimitedText(用於 CSV)、jsonArray 或 jsonLines(用於 JSON),以及 markdown 的子模式 oneToMany 用於 Markdown。

當您使用任何這些剖析模式時,出現的新搜尋文件必須具有唯一的文件索引鍵,且在判斷該值的來源時會出現問題。 父 Blob 至少包含一個以metadata_storage_path property形式呈現的唯一值,但如果它將該值分配給多個搜尋文檔,則該鍵在索引中不再是唯一的。

為了解決此問題,blob 索引器會產生唯一識別碼 AzureSearch_DocumentKey,用於識別從單一 blob 父項建立的每個子搜尋文件。 本文說明此功能的運作方式。

一對多文件唯一識別碼

文件鍵用於識別索引中的每一份文件。 預設的 Blob 索引鍵對應使用 metadata_storage_path,但實際生效的索引鍵也取決於剖析模式和對應。 請檢視本文所述的解析後匹配鍵行為,而非假設預設對應總是選擇最終身份。

在一對多搜尋文件的情況中,無法使用以 metadata_storage_path property 為基礎的隱含文件索引鍵。 作為一個變通方法,Foundry IQ(Azure AI 搜尋服務)可以為從 blob 中擷取的每個實體產生文件金鑰。 系統會產生一個名為的 AzureSearch_DocumentKey 金鑰,並將其新增至每個搜尋文件。 索引器會追蹤從每個 Blob 建立的「許多文件」,並且可以在隨著時間來源資料變更時,針對搜尋索引進行更新。

根據預設,當未指定索引鍵索引欄位的明確欄位對應時,會使用 AzureSearch_DocumentKey 欄位對應函式,與 base64Encode 進行對應。

產生的金鑰或 Base64 轉換並非授權邊界。 如果來源內容提供金鑰,請檢視誰可以控制該金鑰,以及其他 blob 或索引器是否可以使用相同的值。 單一膠點內的獨特性是不夠的。 請參閱 「保護文件身份與權限來源」。

過大的 Blob 只產生一份僅包含中繼資料的文件

當 Blob 索引器使用一對多解析模式且 indexStorageMetadataOnlyForOversizedDocuments 設定為 true時,過大 blob 會繞過內容分割器。 索引器只輸出一份僅包含元資料的文件,而非每內容列只輸出一份文件。

該文件沒有剖析後的內容鍵或列序數。 其原始金鑰來源會回退為 metadata_storage_path。 現有的鍵轉換,包括 Base64 編碼,可以變更寫入索引鍵欄位的值。

正常大小的 blob 會保留其既有的鍵行為:由設定內容衍生的鍵,或是根據 blob 路徑與列序數產生 AzureSearch_DocumentKey 的鍵。 下表說明包含兩種大小的資料夾。 它顯示的是原始金鑰來源,而非最終編碼的索引金鑰。

原始內容 產生的文件 原始金鑰來源
一個正常大小的 JSON Lines blob,包含兩行及產生的鍵。 兩份內容文件。 blob 路徑加上對應的列序數,例如 {blob-path};{row-ordinal}。
一個具有設定過且唯一內容金鑰的正常大小 blob。 每解析資料列一份文件。 每一列已設定的內容金鑰。
一個啟用僅含中繼資料的備援的超大型 blob。 一份僅包含元資料的文件。 metadata_storage_path,且不包含資料列序數。

列舉順序不會改變鍵選擇。 正常大小的 blob 會保留其內容或產生的鍵值,不論它出現在超大 blob 之前還是之後。

當您將一對多解析模式與 indexStorageMetadataOnlyForOversizedDocuments結合時,不支援 ACL 匯入。 此限制適用於 JSON 行、JSON 陣列、分隔文字,以及一對多 Markdown 解析。

如果一個 blob 從「正常大小」變成「超大」,或從「過大」變為「正常大小」,其金鑰選擇就會改變。 存放在舊鍵下的文件不會自動刪除,且可保留先前的內容與 ACL 值。 不要以為建立替換紀錄就能移除舊紀錄或其授權。 規劃明確的 文件刪除 或適當的 索引重建,並保留 文件身分識別與權限信任邊界。

關於設定設定與來源大小限制,請參閱 處理索引器失敗。

Example

假設索引定義具有下列欄位:

  • id
  • temperature
  • pressure
  • timestamp

您的 Blob 容器中的 blob 結構如下:

Blob1.json

{ "temperature": 100, "pressure": 100, "timestamp": "2024-02-13T00:00:00Z" }
{ "temperature" : 33, "pressure" : 30, "timestamp": "2024-02-14T00:00:00Z" }

Blob2.json

{ "temperature": 1, "pressure": 1, "timestamp": "2023-01-12T00:00:00Z" }
{ "temperature" : 120, "pressure" : 3, "timestamp": "2022-05-11T00:00:00Z" }

當您建立索引子並將 parsingMode 設定為 jsonLines - 而不指定索引鍵欄位的任何明確欄位對映時,會隱含地套用下列對映。

{
    "sourceFieldName" : "AzureSearch_DocumentKey",
    "targetFieldName": "id",
    "mappingFunction": { "name" : "base64Encode" }
}

此設定會產生消除歧義的文件索引鍵,類似於下圖 (為了簡潔起見,base64 編碼的 ID 縮短) 。

ID 溫度 pressure 時間戳記
aHR0 ...YjEuanNvbjsx 100 100 2024-02-13T00:00:00Z
aHR0 ...YjEuanNvbjsy 33 30 2024-02-14T00:00:00Z
aHR0 ...YjIuanNvbjsx 1 1 2023-01-12T00:00:00Z
aHR0 ...YjIuanNvbjsy 120 3 2022-05-11T00:00:00Z

索引鍵欄位的自訂欄位對應

假設索引定義與上一個範例相同,假設您的 Blob 容器具有具有下列結構的 Blob:

Blob1.json

recordid, temperature, pressure, timestamp
1, 100, 100,"2024-02-13T00:00:00Z" 
2, 33, 30,"2024-02-14T00:00:00Z" 

Blob2.json

recordid, temperature, pressure, timestamp
1, 1, 1,"2023-01-12T00:00:00Z"
2, 120, 3,"2022-05-11T00:00:00Z" 

當您使用 delimitedTextparsingMode 建立索引子,您可能會覺得將欄位對應函式設定至下列索引鍵欄位十分自然:

{
    "sourceFieldName" : "recordid",
    "targetFieldName": "id"
}

不過,此對應不會導致索引中顯示四個檔,因為欄位recordid在 Blob 中不是唯一的。 因此,我們建議您使用從 AzureSearch_DocumentKey 屬性套用至關鍵索引欄位的隱式欄位映射,以進行「一對多」剖析模式。

如果您想要設定明確的欄位對應,請確定所有 Blob 中每個個別實體的 sourceField 都不同。

備註

確保 AzureSearch_DocumentKey 每個擷取實體的唯一性所使用的方法可能會變更,因此您不應該依賴其值來滿足應用程式的需求。

在資料中指定索引鍵欄位

假設索引定義與上一個範例相同,且 parsingMode 設定為 jsonLines,未指定任何明確的欄位對應,則對應會類似於第一個範例,您的 Blob 容器應該具有下列結構的 Blob:

這些輸入說明了跨 Blob 的重複鍵值,這並非建議用於分開記錄的配置。

Blob1.json

{ "id": "1", "temperature": 100, "pressure": 100, "timestamp": "2024-02-13T00:00:00Z" }
{ "id": "2", "temperature": 33, "pressure": 30, "timestamp": "2024-02-14T00:00:00Z" }

Blob2.json

{ "id": "1", "temperature": 1, "pressure": 1, "timestamp": "2023-01-12T00:00:00Z" }
{ "id": "2", "temperature": 120, "pressure": 3, "timestamp": "2022-05-11T00:00:00Z" }

每份文件都包含 id 該欄位,您在索引中將其定義為 key 欄位。 在這種情況下,系統會為文件產生 一個 AzureSearch_DocumentKey ,但並不會將其作為金鑰。 取而代之的是,欄位 id 的值會對應到關鍵欄位。

與上一個範例類似,此對應不會導致索引中顯示四個檔,因為欄位id在 Blob 中不是唯一的。 發生此狀況時,任何指定 的 id JSON 項目都會導致與現有文件合併,而不是上傳新文件。 然後,索引會反映具有指定id的項目的最新狀態。

局限性

從檔案中的一行建立索引中的檔專案時,如本文所述,從檔案中刪除該行不會自動從索引中移除對應的專案。 若要刪除文件項目,您必須使用 REST API 刪除作業手動將刪除要求提交至索引。

更改金鑰對應也可能讓紀錄仍歸於舊金鑰。 產生的金鑰、重設或權限重新整理不會建立文件所有權。 請將金鑰選擇置於授權的擷取寫入者手中。 請參閱 保護文件身分與權限來源。

後續步驟

如果您尚未熟悉 blob 索引的基本結構與工作流程,建議先閱讀使用 Foundry IQ 進行 Azure Blob 儲存體 索引。 如需不同 Blob 內容類型剖析模式的詳細資訊,請檢閱下列文章。