執行或重設索引器、技能或文件

註

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

在 Foundry IQ(Azure AI 搜尋服務)中,您可以透過多種方式執行索引器:

本文說明如何按需求執行索引器,包括有重置和無重置的情況。 它也描述了索引器的執行、持續時間與並行性。

索引器如何連接 Azure 資源

索引器是少數會直接呼叫其他 Azure 資源的子系統之一。 根據外部資料來源,你可以使用金鑰或角色來驗證連線。

就 Azure 角色而言,索引器沒有獨立的身份:從搜尋引擎連接到另一個 Azure 資源,會使用 Foundry IQ 服務的系統或使用者指派的管理身份,並對目標 Azure 資源進行角色指派。 受控識別會驗證該連線;它不會隔離網路路徑。 對於受網路保護的目標,請檢查 共用私有連結的資格 及目標所支援的存取選項。 S3 HD 和 Serverless 不支援外發共用私有連結。

註

索引器以服務層級權限運作,而非使用者權限。 索引器可以寫入 Foundry IQ 服務中的任何索引,即使您已指派角色限制對特定索引的存取。 欲了解更多資訊,請參閱 「按索引範圍與索引器操作」。

索引器運行

在符合資格的 Dedicated 服務上進行私人執行時,Foundry IQ 服務會在每個 搜尋單元上執行一個索引子工作。 每新增一個分割區或複本,都會增加您服務的搜尋單元。 您可以在 Azure 入口網站的 概覽 頁面的基本資訊區查看搜尋單位數。 索引器會共享服務資源,因此如果服務承受壓力,你可能會遇到比平常更多的查詢限流。

S3 HD 與無伺服器索引器僅能在多租戶環境中執行。 它們在每個 24 小時 UTC 視窗中,每項服務共享 48 小時累積執行時數,且每執行有兩小時的獨立限制。 搜尋單元的並發性並不是其容量模型。 請參閱 Serverless 與 S3 HD 上的索引器執行 及 監控累積執行時間。

以下螢幕圖顯示符合資格的專用服務中用於私有執行並行的搜尋單元數量。

概覽頁面中「基本資訊」區塊的螢幕截圖,顯示搜尋單位。

一旦索引器執行開始,你就無法暫停或停止它。 當沒有更多文件可載入或刷新,或達到 最大執行時間限制 時,索引器執行會停止。

你可以同時執行多個索引器,前提是容量足夠,但每個索引器本身是單一實例。 在索引器已執行中啟動新實例會產生以下錯誤: "Failed to run indexer "<indexer name>" error: "Another indexer invocation is currently in progress; concurrent invocations are not allowed."

索引器執行環境

索引器工作是在受管理的執行環境中執行。 目前有兩種環境:

  • 私有執行環境會在專屬於您的 Foundry IQ 服務的搜尋叢集上執行。

  • 多租戶環境包含內容處理器,由 Microsoft 管理並確保其安全。 此環境卸下計算密集的處理能力,使服務專屬資源仍可用於例行操作。 只要可行,大多數技能都會在多租用戶環境中執行。 這個環境是預設的。 符合資格的付費無伺服器服務會產生 索引器執行計算單元的使用量;共享執行並不會對專用服務或免費服務產生這種費用。

    計算密集型處理 指的是在內容處理器上執行的技能組合,以及處理大量文件或大型文件的索引器作業。 啟發學習法與系統資訊會決定多租用戶內容處理器上的非技能處理方式,且不受客戶控制。

您可以將索引器與技能集處理專屬固定在搜尋叢集上,以防止符合資格的 Standard2 或更高等級專用服務(不含 S3 HD)使用多租戶環境。 在索引器定義中設定 executionEnvironment 參數,使索引器始終在私有執行環境中執行。

IP 防火牆 會阻擋多租戶環境,因此如果您有防火牆,請建立允許多租戶處理器連線的 規則 。

索引器的限制因環境而異:

工作量 最大持續時間 工作數上限 執行環境
私人處決 24小時 每個搜尋單位一個索引器工作1。 索引不會在背景執行。 相反地,Foundry IQ 服務會在所有索引工作與持續進行的查詢及物件管理動作(例如建立或更新索引)之間取得平衡。 執行索引器時,如果索引卷很大,你應該預期 會有一些查詢延遲 。
多租戶 2小時 2 不確定 3 由於內容處理叢集為多租戶,系統會新增內容處理器以滿足需求。 如果你在按需或排程執行中遇到延遲,通常是因為系統正在新增處理器,或是在等待新的處理器可用。

1 搜尋單元可以是分割區與複本的 靈活組合 ,但索引工作並不綁定於其中一方。 換句話說,如果你有 12 個單位,無論搜尋單位如何部署,都可以同時執行 12 個索引器工作。

2 若處理所有資料需超過兩小時,請 啟用變更偵測 ,並 排程索引器 以 5 分鐘間隔運行,以便在因逾時而停止時迅速恢復索引。 更多策略請參見 「索引大型資料集 」。

3 「未定」意指這個上限不是以工作數量來量化的。 某些工作負載,如技能集處理,可以平行執行,即使只有一個索引器,也可能產生許多工作。 雖然環境不會施加限制,但您的 Foundry IQ 服務的 索引器限制 仍然適用。

不重置即可運行

執行索引器操作只會偵測並處理它需要的部分,以同步搜尋索引與底層資料來源的變更。 累加式索引會先找出內部高水位線,以尋找最後更新的搜尋文件。 此文件成為索引器執行資料來源中新文件與更新文件的起點。

變更偵測 對於判斷資料來源中哪些是新增或更新的,至關重要。 索引器利用底層資料來源的變更偵測功能來判斷資料來源中有哪些新內容或更新內容。

  • Azure 儲存體 內建了透過 LastModified 屬性進行變更偵測的功能。

  • 其他資料來源,如 Azure SQL 或 Azure Cosmos DB,則需要先設定變更偵測,索引器才能讀取新資料列與更新資料列。

若底層內容不變,執行操作則無效。 此時,索引器的執行歷史顯示 0\0 文件已處理中。

要重新處理所有文件,你需要重置索引器。

重置索引器

初始執行後,索引器會透過內部 高水位標記追蹤哪些搜尋文件被索引。 該標記不會對外公開,但索引器內部知道它上次停止的位置。

若要重建全部或部分索引,請使用物件階層中遞減層級的重置 API:

重置後,接著執行執行指令重新處理新舊文件。 您無法透過重設並執行,移除在資料來源中沒有對應項目的孤立搜尋文件。 若要刪除特定文件,請參見 「在搜尋索引中刪除文件 」或 「文件-索引」。

註

桌子不能空著。 如果你用 TRUNCATE TABLE 來清除資料列,重設索引器並執行索引器並不會移除對應的搜尋文件。 若要移除孤立的搜尋文件,您必須使用刪除動作為其編製索引。

如何重置並執行索引器

重置會清除高水位標記。 搜尋索引中的所有文件都會被標記為完全覆寫,不會進行內嵌更新或合併到現有內容。 對於具有技能和擴充快取(預覽版)的索引器,重設索引也會隱式重設技能。

實際工作發生在你重置後執行 Run 指令時。

  • 所有找到底層來源的新文件都會加入搜尋索引。
  • 所有同時存在於資料來源與搜尋索引的文件,都會被覆蓋在搜尋索引中。
  • 任何由技能組合創造的豐富內容都會被重建。 如果啟用了增強緩存,該緩存將被刷新。

如前所述,重置是一種被動操作:您必須接著執行「Run」請求來重建索引。

重設/執行作業適用於搜尋索引或知識存放區、特定文件或投影,以及在重設明確或隱含包含技能時,適用於快取的擴充。

重置也適用於建立與更新操作。 此作業不會觸發刪除或清除搜尋索引中的孤立文件。 欲了解更多刪除文件的資訊,請參閱 文件 - 索引。

重置操作無法撤銷。

  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 在 概覽 頁面,選擇 索引器 標籤。

  3. 選擇索引器。

  4. 選擇 重置 指令,然後選擇 「是 」來確認該動作。

  5. 重新整理頁面以顯示狀態。 您可以選擇該項目查看其詳細資訊。

  6. 選擇 執行 以開始索引器處理,或等待下一次排程執行。

    索引器執行入口網站頁面的截圖,重設指令已被標示。

如何重置技能(預覽)

重置技能請求在下一次索引器執行時,選擇性地處理一項或多項技能。 對於具有技能的索引器,您可以重設個別技能,以強制只重新處理該技能,以及任何依賴其輸出的下游技能。 如果你啟用了 擴充快取,該請求也會重新整理該快取。

對於啟用快取的索引器,你可以明確請求處理索引器無法偵測的技能更新。 例如,如果你做了外部修改,例如自訂技能的修訂,請使用這個 API 來重新執行該技能。 此程序會利用快取中的可重複使用資料,以及根據更新後的技能產生的新內容,重新整理輸出結果,例如知識儲存或搜尋索引。

使用 最新的預覽 API。

POST /skillsets/[skillset name]/resetskills?api-version=2026-11-01-preview
{
    "skillNames" : [
        "#1",
        "#5",
        "#6"
    ]
}

你可以指定個別技能,如前述範例所示,但如果這些技能需要輸出未列出的技能(#2 到 #4),程序會執行未列出的技能,除非快取能提供必要資訊。 若要讓此條件成立,技能 #2 到 #4 的快取擴充不得相依於 #1 (列為要重設的技能)。

如果你沒有指定任何技能,程序會執行整個技能組,如果啟用快取,也會刷新快取。

記得後續使用 Run Indexer 來啟動實際處理。

如何重設文件(預覽)

索引器 - 重設文件(預覽)API 接受文件鍵列表,讓你能重新整理特定文件。 如果你指定重置參數,它們只會決定哪些要處理,不管底層資料有沒有其他變動。 舉例來說,如果自上次索引器執行以來新增或更新了 20 個 blob,但你只重置了一份文件,索引器就只處理那份文件。

以每份文件為單位,索引器會以資料來源的值與元資料刷新搜尋文件中的所有欄位。 你無法挑選要刷新哪些欄位。

如果資料來源是 Azure Data Lake Storage (ADLS) Gen2,且 blobs 與權限元資料相關聯,索引器會在底層資料權限變動時,將這些權限重新匯入搜尋索引中。 欲了解更多資訊,請參閱 使用 ADLS Gen2 索引器重新索引 ACL 與 RBAC 範圍。

如果你透過技能組豐富文件且有快取資料,索引器會只針對指定文件調用技能組,並更新重處理文件的快取。

當你第一次測試這個 API 時,以下的 API 可以幫助你驗證並測試這些行為。 使用最新的預覽 API。

  1. 呼叫具有預覽 API 版本的 索引器 - 獲取狀態 以檢查重置狀態和執行狀態。 您可以在狀態回應的最後找到關於重置請求的資訊。

  2. 呼叫 索引器 - 以預覽 API 版本重設文件 ,指定要處理哪些文件。

    POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2026-11-01-preview
    {
        "documentKeys" : [
            "1001",
            "4452"
        ]
    }
    
    • API 接受兩種類型的文件識別碼作為輸入:用於唯一識別搜尋索引文件的文件鍵,以及唯一識別資料來源文件識別碼的資料來源文件識別碼。 主體應包含文件鍵項 清單或 索引器在資料來源中尋找的資料來源文件識別碼清單。 叫用 API 會將要重設的文件索引鍵或資料來源文件識別碼新增至索引子中繼資料。 在下一次排程或按需執行索引器時,索引器只會處理重置文件。

    • 如果你使用文件鍵來重置文件,且你的文件鍵在索引器欄位映射中被參考,索引器則會利用欄位映射來定位底層資料來源中的適當欄位。

    • 你在請求中提供的文件鍵是來自搜尋索引的值,這可能與資料來源中對應的欄位不同。 如果你不確定鍵值,可以 發送查詢 回傳該值。 你可以用 select 來只回傳文件鍵欄位。

    • 對於會被索引器剖析成多個搜尋文件的 blob(當 parsingMode 設為 jsonLines 或 jsonArrays,或 delimitedText 時),索引器會產生文件索引鍵,而你可能不知道該索引鍵。 在本情境中,查詢文件索引鍵以傳回正確值。

    • 如果你想讓索引器停止嘗試處理重設文件,請設定 "documentKeys" 或 "datasourceDocumentIds" 為空清單 []。 此舉導致索引器恢復基於高水位點的常規索引。 無效的文件鍵或不存在的文件鍵會被忽略。

  3. 呼叫 Run Indexer (任何 API 版本)來處理你指定的文件。 索引器僅索引特定文件。

  4. 再呼叫一次 Run Indexer ,從最後一個高水位點開始處理。

  5. 請致電 搜尋文件 查詢更新值,若不確定值,也請回傳文件鍵。 如果你想限制回應中出現的欄位,可以使用。"select": "<field names>"

覆寫文件鍵列表

如果你多次用不同鍵呼叫 Reset Documents API,新的鍵會被加入被重置的文件鍵清單。 如果你呼叫 API 並將 overwrite 參數設為 true,目前的清單會被新的清單取代:

POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2026-11-01-preview
{
    "documentKeys" : [
        "200",
        "630"
    ],
    "overwrite": true
}

如何重新同步索引器

Resync 索引器支援 REST API 2026-10-01中的僅重新同步權限。 以下程序適用於 ADLS Gen2 權限匯入。 其他來源請查看其特定來源的支援與更新需求。

當目標索引中所有文件的特定欄位與資料來源資料一致時,索引器即被視為與其資料來源同步。 通常,索引器會在成功完成初始執行後實現同步。 如果你從資料來源刪除文件,索引器依此定義仍保持同步。 然而,在下一次索引器執行時,若啟用刪除追蹤,目標索引中對應的文件會被移除。

如果你修改資料來源中的文件,索引器就會變得不同步。 一般來說,變更追蹤機制會在下一次執行時重新同步索引器。 例如,在 Azure 儲存體 中,修改 Blob 會更新其上次修改時間,因此索引器可在下一次執行時重新為該 Blob 建立索引,因為更新後的時間會超過前一次執行所設定的高水位標記。

變更 ADLS Gen2 檔案或目錄 ACL 不會改變該檔案的最後修改時間。 refreshAllAcls 預設為啟用,這些變更會在符合資格的正常執行中大約每天處理一次,而非每次排程執行。 有關範圍、節奏及選擇退出的影響,請參閱 自動 ACL 刷新。

使用權限重新同步以進行完整來源 ACL 一致化,無需等待自動清查。 Reset 和 reset-docs 則有不同的用途:它們會重新處理內容並重新執行豐富化。 Reset-docs 仍是獨立的預覽操作。

重新同步請求會將下一次手動或排程執行的權限處理排入佇列;接受並不代表同步已經完成。 重新同步會更新現有記錄的權限欄位,以及已正確映射的投影區塊,且不重新產生內容或嵌入。 它不會回填缺少的來源路徑上下文、移除過時的文件金鑰,或強制查詢授權快取重新整理。

如何重新同步並執行索引器

  1. 確認資料來源已啟用權限擷取,且索引與投影包含 所需的來源與權限欄位。

  2. 等索引器閒置為止。 重新同步請求會與目前正在執行的作業發生衝突。

  3. 呼叫 索引器 - 重新同步 與 options: ["permissions"]。

    POST https://[service name].search.windows.net/indexers/[indexer name]/resync?api-version=2026-10-01
    Authorization: Bearer <search-service-token>
    Content-Type: application/json
    
    {
        "options" : [
            "permissions"
        ]
    }
    
    • options欄位是必填的。 目前唯一支援的選項是 permissions。 也就是說,只有目標索引中的權限篩選欄位會被更新。
  4. 呼叫 執行索引器,或等待下一次排程執行。

  5. 監控 取得索引器狀態 ,直到重新同步執行完成。 檢查錯誤與警告;部分失敗後,部分文件仍可能保留較舊的權限。 找出原因並重試受支援的重新整理作業。

  6. 以文件及投影區塊核對具代表性的允許與拒絕使用者。 請參閱「監控並驗證同步」。

  7. 再次執行索引器,或等待其排程,以恢復從上一次高水位開始的正常內容變更追蹤。

檢查重置狀態「currentState」

要檢查重置狀態並查看哪些文件鍵正排隊處理,請依照以下步驟操作:

  1. 透過預覽 API 呼叫 「取得索引器狀態 」。

    預覽 API 會回傳位於回應末尾的 currentState 區段。

    "currentState": {
        "mode": "indexingResetDocs",
        "allDocsInitialTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
        "allDocsFinalTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
        "resetDocsInitialTrackingState": null,
        "resetDocsFinalTrackingState": null,
        "resyncInitialTrackingState": null,
        "resyncFinalTrackingState": null,
        "resetDocumentKeys": [
            "200",
            "630"
        ]
    }
    
  2. 檢查「模式」:

    對於重置技能,請將「模式」設為indexingAllDocs,因為就 AI 擴充所填入的各欄位而言,可能所有文件都會受到影響。

    對於重新同步索引器,請將「mode」設為 indexingResync。 索引器會檢查所有文件,並專注於資料來源中感興趣的資料及目標索引中感興趣的欄位。

    對於重設文件,請將「mode」設為 indexingResetDocs。 索引器會維持此狀態,直到處理完 reset documents 呼叫中提供的所有文件索引鍵。 在此期間,當此作業進行時,不會執行其他索引器工作。 要找到文件鍵列表中的所有文件,需要破解每份文件以定位並匹配該鍵。 如果資料集很大,這個過程可能會花上一段時間。 如果 blob 容器中包含數百個 blob,而你想要重設的文件位於最後面,索引子必須先檢查完其他所有 blob,才會找到相符的 blob。

  3. 索引器重新處理文件後,再次執行「取得索引器狀態」。 索引器會回到該 indexingAllDocs 模式,並在下一次執行時處理任何新增或更新的文件。

檢查 S3 HD 與 Serverless Foundry IQ 服務的索引器執行配額

在標準 3 高密度(S3 HD)與 Serverless Foundry IQ 服務中,所有索引器在 每個 24 小時 UTC 視窗內,每項服務共享 48 個累積執行時數。 每次執行都有獨立的 兩小時上限。

關於 2026-10-01 狀態與服務統計資料工作流程,請參閱 「監視累計執行時間」。 該指引說明了每個索引器與服務範圍的使用情況、共享剩餘執行時,以及如何處理可選或空值。 關於配額耗盡與規劃,請參閱《無伺服器與 S3 HD 上的索引器執行》。

下一步

重置 API 用於通知下一次索引器執行的範圍。 若要實際進行處理,您需要叫用隨選索引子執行,或讓排程作業完成工作。 該次執行完成後,索引器會恢復正常處理,不論是依排程或隨選處理。

在您重設並重新執行索引工作後,您可以透過 Foundry IQ 服務監控狀態,或透過資源記錄取得詳細資訊。