在 Azure AI 搜尋服務中啟用累加擴充的快取

發行項
03/18/2024

重要

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

本文說明如何將快取新增至擴充管線，以便能修改下游擴充步驟，而無須每次都全部重建。根據預設，技能集沒有狀態，而要其任一部分，都需要徹底重新執行索引子。透過擴充快取，索引子可根據在技能集或索引子定義中偵測到的變更，判斷必須重新整理文件樹狀結構的哪些部分。現有的已處理輸出會保留，並盡可能重複使用。

快取的內容會使用您提供的帳戶資訊放在 Azure 儲存體中。當您執行索引子時，會建立名為 ms-az-search-indexercache-<alpha-numerc-string> 的容器。我們應將其視為由搜尋服務管理且不可修改的內部元件。

如果您不熟悉設定索引子，請先參閱索引子概觀，然後再參考技能集以了解擴充管線。如需更多關於重要概念的背景資訊，請參閱累加擴充。

必要條件

Azure 儲存體可用來儲存快取的擴充。儲存體帳戶必須是一般用途 v2。

必須要有預覽 API 或 Beta Azure SDK，才能在索引子上啟用快取。入口網站目前不提供快取擴充的選項。

警告

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

在新的索引子上啟用

對於新的索引子，請在呼叫建立或更新索引子 (2021-04-30-Preview) 時，在索引子定義承載中新增 "cache" 屬性。您也可以使用先前的預覽 API 版本 2020-06-30-Preview。

POST https://[service name].search.windows.net/indexers?api-version=2021-04-30-Preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
        }
    }

在現有的索引子上啟用

對於已有技能集的現有索引子，請使用下列步驟來新增快取。作為一次性作業，徹底重設並重新執行索引子以載入快取。

步驟 1：取得索引子定義

請從具有下列元件的有效工作索引子開始：資料來源、技能集、索引。使用 API 用戶端，傳送 GET Indexer 要求以擷取索引子。當您使用預覽 API 版本來取得索引子時，設定為 null 的 "cache" 屬性會自動新增至定義。

GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

步驟 2：設定快取屬性

在索引定義中修改 "cache"，以包含下列必要和選擇性屬性：

(必要) storageConnectionString 必須設定為 Azure 儲存體連接字串。
(選擇性) enableReprocessing 布林屬性 (預設為 true)，指出累加擴充已啟用。如果您想要在其他資源密集的作業 (例如編製新文件的索引) 執行期間暫停累加處理，請設定為 false，且稍後再切換回 true。

POST https://[service name].search.windows.net/indexers?api-version=2021-04-30-Preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

步驟 3：重設索引子

設定現有索引子的累加擴充時必須重設索引子，以確保所有文件都處於一致狀態。對這項工作可以使用入口網站或 API 用戶端。

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

步驟 4：儲存索引子

使用 PUT 要求更新索引子 (2021-04-30-Preview) ，其中，要求本文包含 "cache"。

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]
    {
        "name" : "<YOUR-INDEXER-NAME>",
        ...
        "cache": {
            "storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        }
    }

如果您現在對索引子發出另一個 GET 要求，服務的回應將會在快取物件中包含 ID 屬性。此索引子所處理之每個文件的所有快取結果和中繼狀態所在的容器，會在其名稱附加英數字元字串。識別碼將用來唯一指定 Blob 儲存體中的快取。

    "cache": {
        "ID": "<ALPHA-NUMERIC STRING>",
        "enableReprocessing": true,
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-STORAGE-KEY>;EndpointSuffix=core.windows.net"
    }

步驟 5：執行索引子

若要執行索引子，您可以使用入口網站或 API。在入口網站中，從索引子清單中選取索引子，然後按一下 [執行]。使用入口網站的優點之一，是可以監視索引子狀態、記下作業的持續時間，以及處理的文件數目。入口網站頁面每隔幾分鐘會重新整理一次。

或者，您可以使用 REST 來執行索引子：

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

注意

重設並重新執行索引子會導致完全重建，而使內容可供快取。所有認知擴充都會在所有文件上重新執行。載入快取後，就會開始從快取重複使用擴充的內容。

檢查快取的輸出

在 Azure 儲存體中的 Blob 容器下尋找快取。容器名稱將是 ms-az-search-indexercache-<some-alphanumeric-string>。

快取由索引子建立和使用。其內容不是常人可讀的。

若要確認快取是否正常運作，請修改技能集並執行索引子，然後比較執行時間和文件計數的前後計量。

技能集若包含掃描文件的影像分析和光學字元辨識 (OCR)，就是很好的測試案例。如果您修改下游文字技能或任何與影像無關的技能，索引子可以從快取中擷取所有先前處理的影像和 OCR 內容，而僅更新及處理您的編輯指定的文字相關變更。您可以預期索引子執行文件計數會降低、執行時間會縮短，且帳單上的費用會較少。

cog-search-demo 教學課程中使用的檔案集是有用的測試案例，因為其中包含 14 個不同類型的檔案，包括 JPG、PNG、HTML、DOCX、PPTX 和其他類型。在文字翻譯技能中將 en 變更為 es 或其他語言，以進行累加擴充的概念證明測試。

常見錯誤

如果您忘記在要求上指定預覽 API 版本，就會發生下列錯誤：

"The request is invalid. Details: indexer : A resource without a type name was found, but no expected type was specified. To allow entries without type information, the expected type must also be specified when the model is specified."

如果遺漏索引子需求，也會發生「400 不正確的要求」錯誤。錯誤訊息會指定任何遺漏的相依性。

下一步

累加擴充適用於包含技能集的索引子，對索引和知識存放區都能提供可重複使用的內容。下列連結提供關於快取和技能集的詳細資訊。