Azure AI 搜尋服務中的累加擴充和快取

文章
09/03/2024

重要

此功能在補充使用規定下處於公開預覽狀態。預覽 REST API 支援此功能。

「累加擴充」是指在技能集執行期間使用快取的擴充，以便僅有新的和變更的技能和文件會對 Azure AI 服務的 API 呼叫引發隨用處理費用。快取包含文件萃取的輸出，以及每個文件的每個技能輸出。雖然快取可計費 (快取會使用 Azure 儲存體)，但擴充的整體成本會降低，因為儲存體的成本小於影像擷取和 AI 處理。

為了確保資料來源資料與索引之間的同步處理，請務必了解唯一資料來源變更和刪除追蹤必要條件。本指南特別說明如何在技能處理方面管理累加修改，以及如何利用快取來達到此目的。

當您啟用快取，索引子會評估您的更新，以判斷是否可以從快取提取現有的擴充。來自文件萃取階段的影像和文字內容，加上上游或正交您編輯的技能輸出，可能可重複使用。

技能集處理完成後，重新整理的結果會寫回至快取，也會寫回至搜尋索引或知識存放區。

限制

警告

如果使用的是 SharePoint Online 索引子 (預覽)，您應該避免累加擴充。在某些情況下，快取會變成無效，因此如果您選擇重新載入索引子，需要重設和執行索引子。

快取組態

實際上，快取會儲存在 Azure 儲存體帳戶的 Blob 容器中，每個索引子分別儲存。每個索引子都會獲派唯一且不可變的快取識別碼，此識別碼會對應至其使用的容器。

當您指定 "cache" 屬性並執行索引子時，就會建立快取。只能快取擴充的內容。如果您的索引子沒有附加的技能集，則不會套用快取。

下列範例說明已啟用快取的索引子。如需完整指示，請參閱啟用擴充快取。

若要使用快取屬性，當您建立或更新索引子時，可以使用 2020-06-30-preview 或更新版本。我們建議最新的預覽版 API。

POST https://[search service name].search.windows.net/indexers?api-version=2024-05-01-rreview
    {
        "name": "myIndexerName",
        "targetIndexName": "myIndex",
        "dataSourceName": "myDatasource",
        "skillsetName": "mySkillset",
        "cache" : {
            "storageConnectionString" : "<Your storage account connection string>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

快取管理

快取的生命週期由索引子所管理。如果索引子遭到刪除，其快取也會一併刪除。如果索引子上的 cache 屬性設定為 Null，或連接字串有所變更，則會在下一個索引子執行時刪除現有的快取。

雖然累加擴充的設計目的是要偵測和回應變更，您無須介入，但可以使用參數叫用特定行為：

設定新文件的優先權
略過技能集檢查
略過資料來源檢查
強制進行技能集評估

設定新文件的優先權

cache 屬性包含 enableReprocessing 參數。該屬性用來控制處理快取中已顯示的傳入文件。若為 True (預設)，當您重新執行索引子時，快取中已經存在的文件會進行重新處理 (假設您的技能更新會影響該文件)。

若為 false，則不會重新處理現有文件，而會有效地設定優先權，將新的傳入內容優先於現有內容。您應只暫時將 enableReprocessing 設定為 false。在大部分情況下，將 enableReprocessing 設定為 true 可確保所有文件和現有文件皆根據目前的技能集定義有效。

略過技能集評估

通常會同時修改技能並重新處理該技能。不過，技能的某些變更不應導致重新處理 (例如，將自訂技能部署至新位置，或使用新的存取金鑰部署自訂技能)。通常這些周邊修改不會影響技能輸出的本質。

如果您知道技能變更只在表面上進行，您應該將 disableCacheReprocessingChangeDetection 參數設定為 true，以覆寫技能評估：

呼叫更新技能集並修改技能集定義。
在要求上附加 "disableCacheReprocessingChangeDetection=true" 參數。
提交變更。

設定此參數可確保只會認可技能集定義的更新，且不會評估變更對現有快取的影響。使用預覽 API 版本 2020-06-30-Preview 或更新版本。我們建議最新的預覽版 API。

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2024-05-01-preview&disableCacheReprocessingChangeDetection

略過資料來源驗證檢查

對資料來源定義所做的大部分變更都會讓快取失效。不過，若您知道某案例的變更不應讓快取失效，例如變更連接字串或輪替儲存體帳戶上的金鑰 - 請在資料來源更新上附加ignoreResetRequirement 參數。將此參數設定為 true 可執行認可，而不需要觸發重設條件，不會需要從頭開始重建和填入所有物件。

PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2024-05-01-preview&ignoreResetRequirement

強制進行技能集評估

快取的目的是要避免不必要的處理流程，但假設您針對索引子不會進行偵測的技能進行變更 (例如變更外部程式碼中的某個項目，例如自訂技能)。

在此情況下，您可以使用重設技能來強制重新處理特定技能，包括依賴該技能輸出的任何下游技能。此 API 會接受 POST 要求，其中包含應失效並標示要重新處理的技能清單。重設技能之後，請遵循執行索引子要求來叫用管線處理。

重新快取特定文件

重設索引子會導致搜尋主體中的所有文件進行重新處理。

在只需要重新處理少數文件的情況下，請使用重設文件 (預覽) 以強制重新處理特定文件。重設文件時，索引子會讓該文件的快取失效，然後從資料來源讀取該快取進行重新處理。如需詳細資訊，請參閱執行或重設索引子、技能和文件。

若要重設特定文件，要求會提供從搜尋索引讀取的文件索引鍵清單。如果索引鍵可對應至外部資料源中的欄位，則您提供的值應為搜尋索引中使用的值。

根據您呼叫 API 的方式，要求會附加、覆寫或排入索引鍵清單佇列：

使用不同索引鍵多次呼叫 API，會將新的索引鍵附加至文件索引鍵重設清單。
將 "overwrite" 查詢字串參數設定為 true 並呼叫 API 將會覆寫使用要求承載重設的文件索引鍵的目前清單。
呼叫 API 只會在索引子執行的工作佇列中新增文件索引鍵。下次叫用索引子時，會依排程或視需要排定，優先處理重設文件索引鍵，再處理資料來源的任何其他變更。

下列範例說明重設文件要求：

POST https://[search service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2024-05-01-preview
    {
        "documentKeys" : [
            "key1",
            "key2",
            "key3"
        ]
    }

讓快取失效的變更

啟用快取之後，索引子會評估管線組合中的變更，以判斷可以重複使用哪些內容，以及需要重新處理的內容。本節中列舉會讓快取立即失效的變更，以及蕙觸發累加處理的變更。

失效變更是指會讓整個快取都不再有效的變更。舉例來說，讓您的資料來源進行更新的變更，即為失效變更。以下是完整清單，列出索引子管線中會使快取失效的任何部分變更：

變更資料來源類型
變更資料來源容器
變更資料來源認證
變更資料來源變更偵測原則
變更資料來源刪除偵測原則
變更索引子欄位對應
變更索引子參數：
- 剖析模式
- 排除的副檔名
- 已編製索引的副檔名
- 僅針對過大的文件編製儲存體中繼資料的索引
- 分隔符號文字標頭
- 分隔符號文字分隔符號
- 文件根目錄
- 影像動作 (影像擷取方式的變更)

觸發累加處理的變更

累加處理會評估您的技能集定義，並判斷要重新執行哪些技能，選擇性更新文件樹狀結構受影響的部分。以下是導致累加擴充的變更完整清單：

變更技能類型 (更新技能的 OData 類型)
技能的特定參數已更新，例如 URL、預設值或其他參數
技能輸出變更，即技能傳回了額外或不同的輸出
技能輸入變更會導致不同的上階，也就是說技能鏈結已變更
如果為任何上游技能提供輸入的技能已更新，則此上游技能將會失效
更新知識存放區投射位置，導致文件重新投射
變更知識存放區投射，導致文件重新投射
索引子的輸出欄位對應已變更，導致文件重新投射至索引

用於快取的 API

REST API 版本 2020-06-30-Preview 或更新版本透過索引子上的額外屬性提供累加擴充。我們建議最新的預覽版 API。

技能集和資料來源可以使用正式發行的版本。除了參考文件之外，請參閱設定累加擴充的快取，以取得作業順序的詳細資料。

建立或更新索引子 (api-version=2024-05-01-preview)
重設技能 (api-version=2024-05-01-preview)
建立或更新技能 (api-版本=2024-07-01) (要求上的新 URI 參數)
使用預覽 API 版本呼叫時，建立或更新資料來源 (api-版本=2024-07-01) 會提供名為 "ignoreResetRequirement" 的新參數，當您的更新動作不應讓快取失效時，應將此參數設定為 true。使用 "ignoreResetRequirement" 時應有所節制，因為這可能會在您的資料中導致不易偵測到且非預期的不一致。

下一步

累加擴充是一項強大的功能，可擴充技能集和 AI 擴充的變更追蹤。累加擴充可讓您在逐一查看技能集設計時重複使用現有的已處理內容。在下一個步驟中，在您的索引子上啟用快取。

啟用累加擴充的快取

分享方式：