管理擴充快取（預覽版）

Note

Azure AI 搜尋服務 可透過 Azure 入口網站、REST API 及 Azure SDK 取得。 它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

重要

標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務 預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。

豐富快取（預覽）是一種可選功能，用來儲存在技能組執行過程中產生的豐富內容。 它會在各次執行之間保留內容，因此只有已變更的技能和文件需要重新處理。 它不是技能集輸出、索引器狀態或索引文件的備份。

您會在 Azure 儲存體中建立擴充快取。 快取包含來自文件破解的輸出，加上每個文件各項技能的輸出。 雖然快取會產生費用（使用 Azure 儲存空間），但整體增強處理成本仍然較低，因為儲存的成本低於影像提取與人工智慧處理的成本。

如果您設定了擴充快取，本文將說明如何管理技能和資料來源更新，讓您從快取的擴充內容中獲得最大效益。

先決條件

限制

注意事項

如果您使用 SharePoint 索引器 (預覽)，請避免使用增量擴充。 在某些情況下，快取會失效。 要重新載入，請執行 索引器重置並完全重建。

大型資料來源還有額外的快取限制。

注意事項

對於大型資料來源，當出現長時間執行的技能、重複中斷或頻繁的技能失敗時，擴充快取可能會增加重新處理的總量。 索引器優先考量正確性而非最小化重處理，因此因反覆中斷而產生的快取積壓會放大重試行為。

為了從不斷增加的快取積壓中恢復，請將資料來源分割成較小的容器或虛擬資料夾。 然後使用指向同一索引的 平行索引器 。 要解除快取關聯，請在索引器上將屬性設 cache 為 null。

快取配置

實際上，快取會儲存在您 Azure 儲存體帳戶中的一個 Blob 容器中，而資料表則儲存在同一個儲存體帳戶中 (每個索引器各有一個資料表)。 每個索引器都會被分配一個唯一且不可變的快取識別碼，對應其所使用的容器。

快取是在你指定 cache 屬性並執行索引器時建立的。 只能快取擴充內容。 如果索引子未附加技能集，則快取不適用。

以下範例展示了啟用快取的索引器。 如需完整說明，請參見 配置增強快取 。

POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2026-08-01-preview
    {
        "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 (預設值) 時，如果技能更新會影響快取文件，則重新執行索引子時，索引子會重新處理這些文件。

當錯誤時，索引器不會重新處理現有文件，這會優先處理新內容。 僅暫時設 enableReprocessing 為假。 大多數時候保持真實，能確保新舊文件在現有技能定義下依然有效。

跳過技能評估

修改技能通常和重新處理該技能是相輔相成的。 不過，某些技能的變更不應該觸發重新處理。 例如，將自訂技能部署到新地點或使用新的存取金鑰。 這些改動通常是周邊的調整，不會影響技能輸出的實質內容。

如果您知道技能變更只是表面上的變更，請將 disableCacheReprocessingChangeDetection 參數設為 true，以覆寫技能評估：

  1. 呼叫 更新技能組 並修改技能組定義。
  2. 在請求中附加參數 disableCacheReprocessingChangeDetection=true 。
  3. 提交變更。

設定此參數後，只會認可技能定義的更新。 這項變更未針對其對現有快取的影響進行評估。 使用預覽 API 版本 2020-06-30-Preview 或更新版本。 使用最新的預覽 API。

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

繞過資料來源驗證檢查

大多數對資料來源定義的變更會使快取失效。 不過，對於你知道變更不應該使快取失效的情況——例如更改連接字串或旋轉儲存帳號的金鑰——可以在 ignoreResetRequirement 上加上 參數。 將此參數設為 true，允許提交完成，且不會觸發重置條件，導致所有物件從頭重建並填充。

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

強制技能集評估

快取的目的是避免不必要的處理作業。 但假設你對一個索引器偵測不到的技能做了變更（例如修改外部程式碼中的某項，例如自訂技能）。

在這種情況下，請使用 Reset Skills API 強制重新處理特定技能，包括任何依賴該技能輸出的後續技能。 此 API 接受帶有應被取消並標記為重新處理的技能清單的 POST 請求。 重設技能後，接著使用執行索引子要求來調用管線處理。

重新快取特定文件

如果你 重置索引器，搜尋語料庫中的所有文件都會被重新處理。

在只有少數文件需要重新處理的情況下，使用 重置文件（預覽） 強制重新處理特定文件。 重設文件時，索引子會使該文件的快取失效。 索引器接著透過從資料來源讀取文件來進行處理。 欲了解更多資訊，請參閱 「執行或重置索引器、技能與文件」。

若要重設特定文件，請在請求中包含從搜尋索引讀取的文件鍵清單。 如果鍵對應到外部資料來源中的欄位，則使用搜尋索引中的值。

根據您呼叫 API 的方式不同，請求會將金鑰清單附加、覆寫，或加入佇列：

  • 用不同鍵多次呼叫 API，會將新鍵附加到需要重設的文件鍵清單中。

  • 呼叫 API 時，若將 overwrite 查詢字串參數設為 true，會以請求承載的內容覆寫目前要重設的文件金鑰清單。

  • 呼叫 API 會將文件鍵加入索引器執行的工作佇列中。 當索引器下一次被調用時，無論是排程還是按需，它都會優先處理重設文件鍵，然後再處理來自資料來源的其他變更。

以下範例說明重設文件請求：

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

使快取失效的變更

啟用快取時，索引器會檢查管線組成是否有變動，決定哪些內容可以重複使用，哪些內容需要重新處理。 本節列出會使快取失效的變更，接著是觸發增量處理的變更。

失效變更是指會使整個快取失效的變更。 例如，更新你的資料來源會被視為無效的變更。 以下是索引子管線任何部分中會使快取失效之變更的完整清單：

  • 變更資料來源類型
  • 變更資料來源容器
  • 變更資料來源憑證
  • 變更資料來源變更偵測原則
  • 變更資料來源刪除偵測原則
  • 變更索引器欄位映射
  • 更改索引器參數：
    • 解析模式
    • 排除的檔案名稱副檔名
    • 已編製索引的檔案名稱副檔名
    • 僅為過大文件編製儲存體中繼資料索引
    • 分隔文字標頭
    • 定界文本分隔符
    • 文件根目錄
    • 影像動作（影像擷取方式的變更）

觸發增量處理的變更

增量處理會評估你的技能組合定義，並決定哪些技能要重複執行。 它會選擇性地更新文件樹中受影響的部分。 以下是會帶來增量擴充的完整變更清單：

  • 變更技能類型（更新技能的 OData 類型）
  • 更新技能專屬參數，如網址、預設值或其他參數
  • 變更技能輸出，例如當技能回傳額外或不同的輸出時
  • 變更技能輸入，導致不同的祖系或技能鏈結。
  • 如果您更新了會提供輸入給此技能的技能，則任何上游技能失效也會使快取失效。
  • 更新知識庫的投影位置，導致文件重新投影
  • 變更知識存放區的投影設定，這會導致重新投影文件
  • 更改索引器上的輸出欄位映射，導致文件重新投影到索引中

用於快取的 API

預覽 API 會在索引器上提供額外的屬性。 使用最新的預覽 API。

請針對技能和資料來源使用正式推出版本。 除了參考文件外，詳見 「配置快取以逐步增強」 以了解操作順序的詳細資訊。

  • Last updated on