Azure AI 搜尋服務的索引子疑難排解指引

  • 發行項

有時候，索引子會遇到未產生錯誤的問題，或是發生在其他 Azure 服務上的問題，例如在驗證或連線期間。 本文著重於疑難排解沒有任何訊息引導的索引子問題， 也會針對索引編製期間使用非搜尋資源遇到的錯誤進行疑難解答。

注意

如果您需要調查 Azure AI 搜尋服務錯誤，請參閱針對常見的索引子錯誤和警告進行疑難排解。

針對已限制資源的連線進行疑難排解

針對 Azure 網路安全性下的資料來源，索引子建立連線的方式會受到限制。 目前，索引子可以透過使用共用私人連結的私人端點存取 IP 防火牆後方或虛擬網路上的受限資料來源。

防火牆規則

Azure 儲存體、Azure Cosmos DB 和 Azure SQL 提供可設定的防火牆。 防火牆封鎖要求時，不會有特定錯誤訊息。 一般而言，防火牆錯誤為泛型。 常見錯誤包括：

  • The remote server returned an error: (403) Forbidden
  • This request is not authorized to perform this operation
  • Credentials provided in the connection string are invalid or have expired

有兩個選項可讓索引子存取這類執行個體中的這些資源：

  • 為搜尋服務的 IP 位址和AzureCognitiveSearch服務標籤的 IP 位址範圍設定輸入規則。 可以從以下連結中找到為每種資料來源類型設定 IP 位址範圍限制的詳細資訊：

  • 作為最後手段或暫時措施，可停用防火牆以允許所有網路的存取。

限制：只有在您的搜尋服務和儲存體帳戶位於不同區域時，IP 位址範圍限制才能運作。

除了資料擷取之外，索引子也會透過技能集和自訂技能傳送輸出要求。 如需以 Azure 函式為基礎的自訂技能，請注意 Azure 函式也有 IP 位址限制。 要允許執行自訂技能的 IP 位址清單包括搜尋服務的 IP 位址，以及 AzureCognitiveSearch 服務標籤的 IP 位址範圍。

網路安全性群組 (NSG) 規則

當索引子存取 SQL 受控執行個體上的資料，或當 Azure VM 作為自訂技能的 Web 服務 URI 時，網路安全性群組會決定是否允許要求。

針對位於虛擬網路上的外部資源，請為 AzureCognitiveSearch 服務標籤設定輸入 NSG 規則。

如需連線至虛擬機器的詳細資訊，請參閱在 Azure VM 上設定到 SQL Server 的連線。

網路錯誤

通常，網路錯誤為泛型。 常見錯誤包括：

  • A network-related or instance-specific error occurred while establishing a connection to the server
  • The server was not found or was not accessible
  • Verify that the instance name is correct and that the source is configured to allow remote connections

當您收到上述任一錯誤時：

  • 透過嘗試直接而不是透過搜尋服務連線至來源，確保可以存取來源
  • 檢查 Azure 入口網站中的資源是否有任何目前的錯誤或中斷
  • 檢查 Azure 狀態中是否有任何網路中斷
  • 確認您正在使用公用 DNS 進行名稱解析，而不是 Azure 私人 DNS

Azure SQL Database 無伺服器編製索引 (錯誤碼 40613)

如果 SQL 資料庫位於無伺服器計算層，請確保索引子連線至資料庫時資料庫正在執行 (而不是暫停)。

如果資料庫暫停，搜尋服務的第一次登入應該要自動恢復資料庫，但反而會傳回錯誤，指出資料庫無法使用，錯誤碼為 40613。 執行資料庫之後，請重試登入以建立連線能力。

Microsoft Entra 條件式存取原則

當您建立 SharePoint Online 索引器時，有一個步驟要求您在提供裝置程式代碼之後登入您的 Microsoft Entra 應用程式。 如果您收到訊息 "Your sign-in was successful but your admin requires the device requesting access to be managed"，索引子可能因為條件式存取原則而遭到 SharePoint 文件庫封鎖。

若要更新原則並允許索引子存取文件庫：

  1. 開啟 Azure 入口網站並搜尋 Microsoft Entra 條件式存取。

  2. 在左側功能表中，選取 [原則]。 如果您沒有檢視此頁面的存取權，則必須尋求具有存取權或取得存取權的人員協助。

  3. 判斷哪個原則封鎖 SharePoint Online 索引器存取文檔庫。 可能封鎖索引子的原則包括您在 [使用者和群組] 部分的索引子建立步驟期間，用於驗證的使用者帳戶。 原則也可能具有下列 [條件]：

    • 限制 [Windows] 平台。
    • 限制 [行動應用程式與桌面用戶端]。
    • 將 [裝置狀態] 設定為 [是]。

  4. 確認封鎖索引子的原則之後，請為索引子提供豁免。 第一步是擷取搜尋服務 IP 位址。

    首先取得搜尋服務的完整網域名稱 (FQDN)。 FQDN 格式如下：<your-search-service-name>.search.windows.net。 您可以在 Azure 入口網站中找到 FQDN。

    取得服務 FQDN

    取得 FQDN 後，請執行 FQDN 的 nslookup (或 ping) 以查詢搜尋服務的 IP 位址。 在下列範例中，您將向 Azure 儲存體防火牆上的輸入規則新增「150.0.0.1」。 更新防火牆設定後，搜尋服務索引子可能需要 15 分鐘的時間才能存取 Azure 儲存體帳戶。

    nslookup contoso.search.windows.net
Server:  server.example.org
Address:  10.50.10.50

Non-authoritative answer:
Name:    <name>
Address:  150.0.0.1
Aliases:  contoso.search.windows.net

  5. 取得您所在區域的索引子執行環境的 IP 位址範圍。

    其他 IP 位址用於源自索引子的多租用戶執行環境的要求。 您可以從服務標籤取得此 IP 位址範圍。

    AzureCognitiveSearch 服務標籤的 IP 位址範圍可以透過探索 API 或可下載的 JSON 檔案取得。

    在此練習中，假設搜尋服務是 Azure 公用雲端，則應該下載 Azure 公用 JSON 檔案。

    下載 JSON 檔案

    在 JSON 檔案中，假設搜尋服務位於美國中西部，則下列列出多租用戶索引子執行環境的 IP 位址清單。

        {
      "name": "AzureCognitiveSearch.WestCentralUS",
      "id": "AzureCognitiveSearch.WestCentralUS",
      "properties": {
        "changeNumber": 1,
        "region": "westcentralus",
        "platform": "Azure",
        "systemService": "AzureCognitiveSearch",
        "addressPrefixes": [
          "52.150.139.0/26",
          "52.253.133.74/32"
        ]
      }
    }

  6. 回到 Azure 入口網站的 [條件式存取] 頁面，從左側功能表中選取 [具名位置]，然後選取 [+ IP 範圍位置]。 為新的具名位置命名，並為您在最後兩個步驟中收集的搜尋服務和索引子執行環境新增 IP 範圍。 1

    • 針對您的搜尋服務 IP 位址，由於其只接受有效的 IP 範圍，因此您可能需要在 IP 位址結尾新增「/32」。
    • 請記住，針對索引子執行環境 IP 範圍，您只需要為搜尋服務所在的區域新增 IP 範圍。

  7. 從原則中排除新的具名位置：

    1. 在左側功能表中，選取 [原則]。
    2. 選取封鎖索引子的原則。
    3. 選取 [條件]。
    4. 選取 [位置]。
    5. 選取 [排除]，然後新增新的 [具名位置]。
    6. 儲存變更。

  8. 請稍候幾分鐘，讓原則更新並強制執行新的原則規則。

  9. 再次嘗試建立索引子：

    1. 傳送您所建立資料來源物件的更新要求。
    2. 重新傳送索引子建立要求。 使用新的程式碼登入，然後傳送另一個索引子建立要求。

編製索引不支援的文件類型

如果您正在為 Azure Blob 儲存體中的內容編製索引，並且容器包含不支援內容類型的 Blob，索引子會略過該文件。 在其他情況下，個別文件可能會發生問題。

在此情況下，您可以設定設定選項，以允許在個別文件出現問題時繼續進行索引子處理。

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2023-11-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false, "failOnUnprocessableDocument" : false } }
}

遺漏文件

索引子會從外部資料來源擷取文件或資料列，並建立搜尋文件，然後由搜尋服務編製索引。 有時候，資料來源中存在的文件無法出現在搜尋索引中。 由於以下原因，可能會出現此非預期的結果：

  • 文件已在索引子執行後更新。 若您的索引子是根據排程執行，最後會重新執行並擷取文件。
  • 索引子在擷取文件之前逾時。 存在處理時間限制上限，超過後便不會處理任何文件。 您可以在入口網站中檢查索引子狀態，或透過呼叫取得索引子狀態 (REST API)。
  • 欄位對應或 AI 擴充已變更文件，其在搜尋索引中的表達方式與您預期的不同。
  • 變更追蹤值錯誤，或遺漏必要條件。 如果您的高水位線值是設定為未來時間的日期，則索引子將會略過早於此日期的任何文件。 您可以使用索引子狀態中的「initialTrackingState」和「finalTrackingState」欄位決定索引子的變更追蹤狀態。 Azure SQL 和 MySQL 的索引子必須在來源資料表的高水位線資料行上具有索引，否則索引子所使用的查詢可能會逾時。

提示

如果遺漏文件，請檢查您所使用的查詢，以確保其不會排除有問題的文件。 若要查詢特定文件，請使用查閱文件 REST API。

Blob 儲存體遺漏內容

Blob 索引子會從容器的 Blob 中尋找並擷取文字。 擷取文字的某些問題包括：

  • 文件僅包含掃描的影像。 具有非文字內容的 PDF Blob (例如掃描的影像 (JPG)) 不會在標準 Blob 編製索引管線中產生結果。 若您具有包含文字元素的影像內容，您可以使用 OCR 或影像分析來尋找及擷取文字。

  • Blob 索引子已設為只為中繼資料建立索引。 若要擷取內容，Blob 索引子必須設為同時擷取內容和中繼資料：

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "dataToExtract" : "contentAndMetadata" } }
}

Azure Cosmos DB 遺漏內容

Azure AI 搜尋服務針對 Azure Cosmos DB 編製索引具有隱含相依性。 若您在 Azure Cosmos DB 中關閉自動編製索引，Azure AI 搜尋服務雖然會傳回成功狀態，但卻無法為容器內容建立索引。 如需如何檢查設定及開啟編製索引的指示，請參閱管理 Azure Cosmos DB 中的編製索引。

資料來源與索引之間的文件計數差異

索引子顯示的文件計數可能會與資料來源、索引本身或程式碼中的計數不同。 以下是發生此行為的一些可能原因：

  • 索引在顯示實際文件計數時可能會延遲，特別是在入口網站中。
  • 索引子具有已刪除的文件原則。 如果文件在遭刪除之前已編製索引，則索引子端會將這些文件列入計數。
  • 如果資料來源中的識別碼資料行並非唯一的。 這適用於具有資料行概念的資料來源，例如 Azure Cosmos DB。
  • 如果資料來源定義與用來估計記錄數目的查詢不同。 例如，您正在資料庫中查詢資料庫記錄計數，而在資料來源定義查詢中，您可能只選取要編製索引的記錄子集。
  • 管線的每個元件會以不同的間隔檢查計數：資料來源、索引子和索引。
  • 資料來源有一個對應至許多文件的檔案。 當編製索引 Blob 及「parsingMode」設定為 jsonArray 和 jsonLines 時，可能會發生此狀況。

文件已處理多次

索引子會採用保守的緩衝策略，以確保在編製索引期間會挑選資料來源中的每個新文件及已變更文件。 在某些情況下，這些緩衝區可能會重疊，造成索引子為文件編製索引兩次或多次，導致已處理的文件計數超過資料來源中文件的實際數目。 此行為不會影響儲存在索引中的資料，例如複製文件，只是可能需要較長的時間才能達到最終一致性。 當下列任一條件成立時，特別容易發生這種情況：

  • 快速連續發出隨需索引子要求
  • 資料來源的拓撲包含多個複本和分割區 (此處討論其中一個範例)
  • 資料來源是 Azure SQL 資料庫，且選為「高水位線」的資料行類型為 datetime2

索引子不適合執行快速連續多次叫用。 如果您需要快速更新，支援的方法是將更新推送至索引，同時更新資料來源。 針對隨選處理，建議您以五分鐘或更長的時間間隔來調整要求，並依排程執行索引子。

具有 30 秒緩衝區的重複文件處理範例

以下時間軸會說明文件處理兩次的條件，其中會記下每個動作及計數器動作。 下列時間軸說明這個問題：

時間軸 (hh:mm:ss) Event 索引子高水位線 註解
00:01:00 將 doc1 寫入具有最終一致性的資料來源 null 文件時間戳記為 00:01:00。
00:01:05 將 doc2 寫入具有最終一致性的資料來源 null 文件時間戳記為 00:01:05。
00:01:10 索引子啟動 null
00:01:11 索引子會在 00:01:10 之前查詢所有變更；索引子查詢的複本只會知道 doc2；僅擷取 doc2 null 索引子在開始時間戳之前會要求所有變更，但實際上會收到子集。 這一行為需要回溯緩衝區期間。
00:01:12 索引子第一次處理 doc2 null
00:01:13 索引子結束 00:01:10 高水位線會更新為目前索引子執行的開始時間戳記。
00:01:20 索引子啟動 00:01:10
00:01:21 索引子會查詢 00:00:40 與 00:01:20 之間的所有變更；索引子查詢的複本會同時注意 doc1 和 doc2；擷取 doc1 和 doc2 00:01:10 索引子要求目前高水位線減去 30 秒緩衝區之間的所有變更，以及目前索引子執行的開始時間戳記。
00:01:22 索引子第一次處理 doc1 00:01:10
00:01:23 索引子第二次處理 doc2 00:01:10
00:01:24 索引子結束 00:01:20 高水位線會更新為目前索引子執行的開始時間戳記。
00:01:32 索引子啟動 00:01:20
00:01:33 索引子會查詢 00:00:50 與 00:01:32 之間的所有變更；擷取 doc1 和 doc2 00:01:20 索引子要求目前高水位線減去 30 秒緩衝區之間的所有變更，以及目前索引子執行的啟動時間戳記。
00:01:34 索引子第二次處理 doc1 00:01:20
00:01:35 索引子第三次處理 doc2 00:01:20
00:01:36 索引子結束 00:01:32 高水位線會更新為目前索引子執行的開始時間戳記。
00:01:40 索引子啟動 00:01:32
00:01:41 索引子會查詢 00:01:02 與 00:01:40 之間的所有變更；擷取 doc2 00:01:32 索引子要求目前高水位線減去 30 秒緩衝區之間的所有變更，以及目前索引子執行的啟動時間戳記。
00:01:42 索引子第四次處理 doc2 00:01:32
00:01:43 索引子結束 00:01:40 請注意，此索引子執行在上次寫入資料來源之後啟動超過 30 秒，也已處理 doc2。 這是預期的行為，因為如果排除 00:01:35 之前的所有索引子執行，這會成為處理 doc1 和 doc2 的第一個且唯一的執行。

實際上，只有針對特定資料來源在幾分鐘內手動叫用隨選索引子時，才會發生此案例。 這可能會導致數字不相符 (例如，索引子會根據索引子執行統計資料處理總計 345 份文件，但是資料來源和索引中有 340 份文件)，或者如果您對相同文件多次執行相同技能，則可能會增加帳單。 使用排程執行索引子是慣用的建議。

使用敏感度標籤編製索引文件

如果您已在文件上設定敏感度標籤，則可能無法將文件編製索引。 如果出現錯誤，請在編製索引之前移除標籤。

另請參閱