在 Foundry IQ(Azure AI 搜尋服務)中監控索引器的狀態與結果

Note

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

您可以在 Azure 入口網站中或以程式設計方式透過 REST 呼叫或 Azure SDK 監視索引子處理。 除了索引子本身的狀態之外,您還可以檢閱開始和結束時間,以及來自特定執行的詳細錯誤和警告。

使用 Azure 入口網站監視

您可以在 Foundry IQ 服務的入口網站頁面中查看所有索引器目前的狀態。 Azure 入口網站頁面每隔幾分鐘重新整理一次,因此您看不到新索引器立即執行的證據。 選取頁面頂端的 [重新整理],以立即擷取最新的檢視。

索引器清單

地位 說明
進行中 表示作用中的執行。 Azure 入口網站會報告部分資訊。 編製索引進行時,您可以觀看回應中的成功的文件值會成長。 處理大量資料的索引子可能需要很長的時間來執行。 例如,處理數百萬個來源文件的索引子可以執行 24 小時,然後幾乎立即重新開始以從其離開的位置接著執行。 因此,大量索引子的狀態可能一律會在 Azure 入口網站中指出進行中。 即使索引子執行中,也會提供有關進行中的進度和先前執行的詳細資料。
Success 表示執行成功。 如果錯誤數目小於索引子的 [失敗項目數上限] 設定,即使個別文件發生錯誤,索引子執行仍可以成功。
失敗 錯誤數目超過 最大失敗項目,索引已停止。
重置 索引子的內部變更追蹤狀態已重設。 索引器會以完整方式執行、重新整理所有檔,而不只是具有較新時間戳的檔。

你可以在列表中選擇索引器,查看該索引器目前及近期的發行詳情。

若要查看特定執行的詳細日誌,請選擇該執行的 狀態 值( 例如失敗),然後選擇「以 CSV 下載」。

索引器摘要與執行歷史

索引子摘要圖表會顯示最近執行中所處理文件數目的圖表。

執行詳細資料清單會顯示最近執行的最多 50 個結果。 在清單中選取執行結果,以查看該執行的特定資料。 這包括其開始和結束時間,以及發生的任何錯誤和警告。

索引器執行細節

如果在執行期間發生檔特定問題,則會列在 [錯誤] 和 [警告] 字段中。

含有錯誤的索引器詳細資料

某些索引子類型的警告很常見,而且不一定會指出問題。 例如,使用 Foundry Tools 的索引器會在圖片或 PDF 檔案中沒有可處理文字時,會報告警告。

如需調查索引子錯誤和警告的詳細資訊,請參閱索引子疑難排解指導。

使用 Azure 監視計量監視

Foundry IQ 是 Azure 監視器 中的一個受監控資源,這表示您可以使用 Metrics Explorer 查看索引器處理文件數量及技能呼叫的基本指標。 這些計量可用來監視索引子進度和設定警示。

計量檢視可以依一組預先定義的維度篩選或分割。 若要了解與計量已處理的文件計數和技能執行叫用計數相關的維度,請參閱計量維度。

下列螢幕擷取畫面會顯示服務內索引子在一小時內處理的文件數目,依索引子名稱分割。

索引器文件處理次數指標

您也可以設定圖形,以查看相同小時間隔內的技能叫用數目。

索引器技能呼叫指標

使用取得索引子狀態監視 (REST API)

使用穩定版 2026-10-01 REST API 執行索引器並監控其狀態。 啟用 無金鑰驗證,並將 搜尋服務參與者 指派給呼叫者。 取得該範圍的 https://search.azure.com/.default 權杖,並將其包含在每個請求的 Authorization: Bearer <access-token> 標頭中。 管理員 API 金鑰是另一種選擇。

若要啟動按需執行,請使用認證標頭發送 POST https://<search-service-name>.search.windows.net/indexers('<indexer-name>')/search.run?api-version=2026-10-01 。 執行索引器 在接受執行要求時會傳回 HTTP 202。 已接受並不代表執行已完成,或已回報最終的運算消耗。

使用 Get Indexer Status 擷取狀態及近期執行紀錄:

GET https://<search-service-name>.search.windows.net/indexers('<indexer-name>')/search.status?api-version=2026-10-01
Authorization: Bearer <access-token>

HTTP 200 會回傳整體索引器狀態、最後一次(或進行中)索引器調用,以及最近的執行歷史。 以下回應摘錄說明這些獨立的狀態欄位:

{
    "status":"running",
    "lastResult": {
        "status":"success",
        "errorMessage":null,
        "startTime":"2018-11-26T03:37:18.853Z",
        "endTime":"2018-11-26T03:37:19.012Z",
        "errors":[],
        "itemsProcessed":11,
        "itemsFailed":0,
        "initialTrackingState":null,
        "finalTrackingState":null
     },
    "executionHistory":[ {
        "status":"success",
         "errorMessage":null,
        "startTime":"2018-11-26T03:37:18.853Z",
        "endTime":"2018-11-26T03:37:19.012Z",
        "errors":[],
        "itemsProcessed":11,
        "itemsFailed":0,
        "initialTrackingState":null,
        "finalTrackingState":null
    }]
}

執行歷程記錄最多包含 50 個最近的執行,其會以反向時間順序排序 (最新優先)。

頂層 status 描述的是索引器本身,而非單次執行。 整體 running 表示索引器已正確設定且可供執行;但不代表執行已啟動。 整體 error 而言,表示這是一個索引器層級的問題。

status 在 lastResult 中或 executionHistory 項目描述個別執行。 一個正在執行的執行作業會回報 inProgress。 已完成的執行會回報 success 或 transientFailure (可重試的失敗執行)。

當索引器被重設以刷新其變更追蹤狀態時,系統會新增一個獨立的 reset 執行歷史條目及狀態。

如需狀態碼和索引子監視資料的詳細資訊,請參閱取得索引子狀態。

執行時間停止後監控進度

若要監視自動內容處理的後續執行,請使用 lastResult 和 executionHistory,將因配額而停止的執行與同一索引器上的後續作業建立關聯:

  1. 找出其 errorMessage 顯示索引器執行時間配額已達的執行。 這樣的中斷執行可以回報 transientFailure;無法僅憑此狀態判定為配額停止。
  2. 拿它 endTime 跟後來的執行 startTime 值比較一下。 排隊的續程可能不會立即顯示為活動執行。
  3. 稍後檢查 status、itemsProcessed、itemsFailed、errors 及 errorMessage 的值,以確認進度或是否反覆失敗。 項目數量描述每次執行,而非唯一索引文件的累積數量。

這些觀察顯示了停止及隨後的處理;僅憑時間點無法證明後續執行是系統生成、排程或按需請求。 不要以為每次 transientFailure 都會觸發配額延續,或認為整體 running 意味著未完成的工作已經完成。

如果重複執行無進展,請參閱「 排除未完成擷取問題」。

監控累積運行時間

在 S3 HD 與 Serverless 上,所有索引器在 24 小時 UTC 視窗內,每個 服務共享 48 個累積執行時數 。 此配額與單一多租戶執行的兩小時限制是分開的。

2026-10-01穩定 API 提供兩種執行時視圖:

反應性質 範圍與解釋
取得索引器狀態: runtime.usedSeconds 此索引器在回應視窗中使用的秒數。
取得服務統計資料: indexersRuntime.usedSeconds 服務中所有索引器在回應視窗內所使用的秒數。
任一執行時物件: remainingSeconds 服務中所有索引器共用的剩餘秒數,而非為單一索引器預留的預算。
任一執行時物件: beginningTime, endingTime 24 小時 UTC 計算視窗的邊界。 比較同一視窗的觀察結果。
取得服務統計資料: limits.maxCumulativeIndexerRuntimeSeconds 服務回報的累計上限,單位為秒。 此回應屬性無法由使用者設定。

使用相同的驗證方式呼叫 Get Service Statistics:

GET https://<search-service-name>.search.windows.net/servicestats?api-version=2026-10-01
Authorization: Bearer <access-token>

以下示範性的 HTTP 200 回應摘要顯示整個服務的使用時間為 7,200 秒,且有 172,800 秒(48 小時)的限制。 其他服務統計資料略去:

{
  "limits": {
    "maxCumulativeIndexerRuntimeSeconds": 172800
  },
  "indexersRuntime": {
    "usedSeconds": 7200,
    "remainingSeconds": 165600,
    "beginningTime": "2026-11-04T00:00:00Z",
    "endingTime": "2026-11-05T00:00:00Z"
  }
}

若要比較一個索引器的使用情況與整個服務的使用情況,請呼叫 取得索引器狀態:

GET https://<search-service-name>.search.windows.net/indexers('<indexer-name>')/search.status?api-version=2026-10-01
Authorization: Bearer <token>

以下示範性的 HTTP 200 回應節錄顯示,該索引器在與服務範例相同的視窗中使用了 3,600 秒。 其他索引器狀態欄位被省略:

{
  "runtime": {
    "usedSeconds": 3600,
    "remainingSeconds": 165600,
    "beginningTime": "2026-11-04T00:00:00Z",
    "endingTime": "2026-11-05T00:00:00Z"
  }
}

這個索引器的 3,600 秒已使用時間,是所有索引器總共使用的 7,200 秒的一部分。 兩個回應都顯示相同的剩餘 165,600 秒,因為這個額度是在整個服務層級共用的。 每個索引器的 runtime.usedSeconds 加上共用的 runtime.remainingSeconds,不一定需要等於服務上限。

在穩定 2026-10-01 合約中, runtime 和 indexersRuntime 都是可選的。 不要以為每個服務都會公開這些物件。 當物件存在時,usedSeconds、beginningTime 和 endingTime 是必需的。

remainingSeconds 以及 limits.maxCumulativeIndexerRuntimeSeconds 為可選且可空。 明確處理遺失值,而非預設為零:

回應範例 監控行為
runtime 或 indexersRuntime 不存在 將執行階段資料顯示為該回應無法使用,而不是顯示為使用量為零。
remainingSeconds 不存在或 null 存在於執行時物件中 將剩餘執行時間顯示為不可用,而非零或為該索引器預留的預算。 保留回報的使用量和視窗。
limits.maxCumulativeIndexerRuntimeSeconds 不存在或 null 將報告的限制顯示為不可用,而非零。 沒有已知上限,不要計算配額百分比。

利用這些觀察來管理配額,而非計算費用。 執行秒數不是計算單元。 對於符合資格的付費無伺服器索引器執行,請 將彙總計算使用量與執行歷史相關聯;執行回應標頭並非完整的每次執行計費記錄。

解讀內容理解結果

對於 內容理解 管線,檢查技能層級錯誤、遺失區塊輸出,以及整體執行狀態。 其預設 的八分鐘分析輪詢時段 與索引器執行時間是分開的。 輪詢逾時不一定會讓整個執行過程失敗,而處理過的文件計數也無法證明所有預期區塊都產生出來了。 在重試可能產生額外費用的工作前,請使用 「疑難排解內容理解」分析 。

使用 .NET 監視

下列 C# 範例會寫入索引子狀態的相關資訊,以及其對主控台最近 (或進行中) 執行的結果。

static void CheckIndexerStatus(SearchIndexerClient indexerClient, SearchIndexer indexer)
{
    try
    {
        string indexerName = "hotels-sql-idxr";
        SearchIndexerStatus execInfo = indexerClient.GetIndexerStatus(indexerName);

        Console.WriteLine("Indexer has run {0} times.", execInfo.ExecutionHistory.Count);
        Console.WriteLine("Indexer Status: " + execInfo.Status.ToString());

        IndexerExecutionResult result = execInfo.LastResult;

        Console.WriteLine("Latest run");
        Console.WriteLine("Run Status: {0}", result.Status.ToString());
        Console.WriteLine("Total Documents: {0}, Failed: {1}", result.ItemCount, result.FailedItemCount);

        TimeSpan elapsed = result.EndTime.Value - result.StartTime.Value;
        Console.WriteLine("StartTime: {0:T}, EndTime: {1:T}, Elapsed: {2:t}", result.StartTime.Value, result.EndTime.Value, elapsed);

        string errorMsg = (result.ErrorMessage == null) ? "none" : result.ErrorMessage;
        Console.WriteLine("ErrorMessage: {0}", errorMsg);
        Console.WriteLine(" Document Errors: {0}, Warnings: {1}\n", result.Errors.Count, result.Warnings.Count);
    }
    catch (Exception e)
    {
        // Handle exception
    }
}

控制台中的輸出看起來像這樣:

Indexer has run 18 times.
Indexer Status: Running
Latest run
  Run Status: Success
  Total Documents: 7, Failed: 0
  StartTime: 11:29:31 PM, EndTime: 11:29:31 PM, Elapsed: 00:00:00.2560000
  ErrorMessage: none
  Document Errors: 0, Warnings: 0

請注意,有兩個不同的狀態值。 最上層狀態是索引子本身的狀態。 執行中索引子狀態表示索引子已正確設定且可供執行,而不是目前正在執行。

索引子的每個執行也會有自己的狀態,指出該特定執行正在進行 (執行中),或已完成,出現 Success 或 TransientError 狀態。

當索引子重設以重新整理其變更追蹤狀態時,會新增具有 Reset 狀態的個別歷程記錄項目。

後續步驟

如需狀態碼和索引子監視資訊的詳細資訊,請參閱下列 API 參考: