Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
重要
豐富化快取目前處於公開預覽階段,並受 Microsoft Azure 預覽版補充使用條款的約束。
有關此功能專屬的預覽條款,請參閱 預覽功能。
豐富快取(預覽)是一種可選功能,用來儲存在技能組執行過程中產生的豐富內容。 它會在各次執行之間保留內容,因此只有已變更的技能和文件需要重新處理。 它不是技能集輸出、索引器狀態或索引文件的備份。
您會在 Azure 儲存體中建立擴充快取。 快取包含來自文件破解的輸出,加上每個文件各項技能的輸出。 雖然快取會產生費用(使用 Azure 儲存空間),但整體增強處理成本仍然較低,因為儲存的成本低於影像提取與人工智慧處理的成本。
如果您設定了擴充快取,本文將說明如何管理技能和資料來源更新,讓您從快取的擴充內容中獲得最大效益。
先決條件
限制
注意事項
如果您使用 SharePoint 索引器,請避免增量豐富化。 在某些情況下,快取會失效。 要重新載入,請執行 索引器重置並完全重建。
大型資料來源還有額外的快取限制。
注意事項
對於大型資料來源,當出現長時間執行的技能、重複中斷或頻繁的技能失敗時,擴充快取可能會增加重新處理的總量。 索引器優先考量正確性而非最小化重處理,因此因反覆中斷而產生的快取積壓會放大重試行為。
為了從不斷增加的快取積壓中恢復,請將資料來源分割成較小的容器或虛擬資料夾。 然後使用指向同一索引的 平行索引器 。 要解除快取關聯,請在索引器上將屬性設 cache 為 null。
快取配置
實際上,快取會儲存在您 Azure 儲存體帳戶中的一個 Blob 容器中,而資料表則儲存在同一個儲存體帳戶中 (每個索引器各有一個資料表)。 每個索引器都會被分配一個唯一且不可變的快取識別碼,對應其所使用的容器。
快取是在你指定 cache 屬性並執行索引器時建立的。 只能快取擴充內容。 如果索引子未附加技能集,則快取不適用。
以下範例展示了啟用快取的索引器。 如需完整說明,請參見 配置增強快取 。
POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2026-11-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,以覆寫技能評估:
- 呼叫 更新技能組 並修改技能組定義。
- 在請求中附加參數
disableCacheReprocessingChangeDetection=true。 - 提交變更。
設定此參數後,只會認可技能定義的更新。 這項變更未針對其對現有快取的影響進行評估。 使用預覽 API 版本 2020-06-30-Preview 或更新版本。 使用最新的預覽 API。
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2026-11-01-preview&disableCacheReprocessingChangeDetection
繞過資料來源驗證檢查
大多數對資料來源定義的變更會使快取失效。 不過,對於你知道變更不應該使快取失效的情況——例如更改連接字串或旋轉儲存帳號的金鑰——可以在 ignoreResetRequirement 上加上 參數。 將此參數設為 true,允許提交完成,且不會觸發重置條件,導致所有物件從頭重建並填充。
PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2026-11-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-11-01-preview
{
"documentKeys" : [
"key1",
"key2",
"key3"
]
}
使快取失效的變更
啟用快取時,索引器會檢查管線組成是否有變動,決定哪些內容可以重複使用,哪些內容需要重新處理。 本節列出會使快取失效的變更,接著是觸發增量處理的變更。
失效變更是指會使整個快取失效的變更。 例如,更新你的資料來源會被視為無效的變更。 以下是索引子管線任何部分中會使快取失效之變更的完整清單:
- 變更資料來源類型
- 變更資料來源容器
- 變更資料來源憑證
- 變更資料來源變更偵測原則
- 變更資料來源刪除偵測原則
- 變更索引器欄位映射
- 更改索引器參數:
- 解析模式
- 排除的檔案名稱副檔名
- 已編製索引的檔案名稱副檔名
- 僅為過大文件編製儲存體中繼資料索引
- 分隔文字標頭
- 定界文本分隔符
- 文件根目錄
- 影像動作(影像擷取方式的變更)
觸發增量處理的變更
增量處理會評估你的技能組合定義,並決定哪些技能要重複執行。 它會選擇性地更新文件樹中受影響的部分。 以下是會帶來增量擴充的完整變更清單:
- 變更技能類型(更新技能的 OData 類型)
- 更新技能專屬參數,如網址、預設值或其他參數
- 變更技能輸出,例如當技能回傳額外或不同的輸出時
- 變更技能輸入,導致不同的祖系或技能鏈結。
- 如果您更新了會提供輸入給此技能的技能,則任何上游技能失效也會使快取失效。
- 更新知識庫的投影位置,導致文件重新投影
- 變更知識存放區的投影設定,這會導致重新投影文件
- 更改索引器上的輸出欄位映射,導致文件重新投影到索引中
用於快取的 API
預覽 API 會在索引器上提供額外的屬性。 使用最新的預覽 API。
請針對技能和資料來源使用正式推出版本。 除了參考文件外,詳見 「配置快取以逐步增強」 以了解操作順序的詳細資訊。
建立或更新技能集(api-version=2026-11-01-preview)(請求上的新增 URI 參數)
建立或更新資料來源(api-version=2026-11-01-preview) 當您呼叫此 API 並取得預覽版 API 時,它會提供一個名為
ignoreResetRequirement的新參數。 當您的更新動作不應使快取失效時,請將此參數設為true。 請節制使用ignoreResetRequirement,因為這可能導致資料不一致,且不易被察覺。