如何排解 Azure AI 搜尋服務 中常見的索引器錯誤與警告

本文提供您在 Azure AI 搜尋中索引及 AI 豐富過程中可能遇到的常見錯誤與警告的資訊與解決方案。

當錯誤數超過 maxFailedItems 時，索引就會停止。 要讓索引器跳過失敗文件，請設定 maxFailedItemsandmaxFailedItemsPerBatch。

警告不會停止索引，但它們會顯示可能導致意外結果的狀況。 你是否採取行動取決於數據和你的情境。

具體索引器錯誤在哪裡可以找到？

要驗證索引器狀態並識別錯誤：

1. 請前往 Azure 入口網站的搜尋服務。

2. 在左側展開 搜尋管理>索引器 並選擇索引器。

3. 在 執行歷史中，選擇狀態。 所有狀態，包括成功狀態，都包含執行細節。

4. 如果有錯誤，請將滑鼠移到錯誤訊息上。 螢幕右側會出現一個視窗，顯示錯誤的詳細資訊。

瞬態誤差

由於各種原因，例如暫時性的網路通訊中斷、長時間執行程序的逾時，或特定文件細節，索引器執行時常見出現暫時錯誤或警告。 然而，這些錯誤是暫時性的，應在後續索引器執行時解決。

為了有效管理這些錯誤，我們建議 將索引器設定一個排程，例如每五分鐘執行一次，下一次執行在完成第一次執行後五分鐘開始，並遵守服務 的最大執行時間限制 。 定期運行有助於修正短暫錯誤或警告。

如果錯誤在多次索引執行中持續存在，通常不是暫時性問題。 在這種情況下，請參考下方清單尋找可能的解決方案。

錯誤性質

Error: Could not read document

索引器無法從資料來源讀取該文件。 這可能因以下原因而發生：

Error: Could not extract content or metadata from your document

使用 Blob 資料來源的索引器無法從文件中擷取內容或元資料（例如 PDF 檔案）。 這可能因以下原因而發生：

Error: Could not parse document

索引器從資料來源讀取文件，但在將文件內容轉換成指定的欄位映射結構時出現問題。 這可能因以下原因而發生：

Error: Could not map output field 'xyz' to search index due to deserialization problem while applying mapping function 'abc'

輸出映射失敗可能是因為輸出資料格式與你使用的映射函式不符。 例如，對二進位資料套用 Base64Encode 映射函數會產生此錯誤。 要解決此問題，可以重新執行索引器而不指定映射函數，或確保映射函式與輸出欄位資料型態相容。 詳情請參見 輸出場映射 。

Error: Could not execute skill

索引程式無法在技能組中執行一項技能。

Error: Could not execute skill because the Web API request failed

技能執行失敗是因為呼叫網頁 API 失敗。 通常，這類失敗發生在使用自訂技能時，這時你需要除錯自訂程式碼來解決問題。 如果失敗是因為內建技能，請參考錯誤訊息以協助修復問題。

偵錯此問題時，請務必注意此技能的任何技能輸入警告。 你的 Web API 端點可能失敗，是因為索引器傳入了意外輸入。

Error: Could not execute skill because Web API skill response is invalid

技能執行失敗，因為呼叫網頁 API 時回傳了無效回應。 通常，這類失敗發生在使用自訂技能時，這時你需要除錯自訂程式碼來解決問題。 如果失敗是因為內建技能，請提出 支援單 以獲得協助。

Error: Type of value has a mismatch with column type. Couldn't store in 'xyz' column. Expected type is 'abc'

如果你的資料來源欄位資料型別與你想映射的索引欄位不同，可能會遇到這個錯誤。 檢查你的資料來源欄位資料型別，並確保它們正確 對應到你的索引型別。

Error: Skill did not execute within the time limit

你可能會遇到兩種錯誤訊息，每種情況都應該以不同的方式處理。 根據導致錯誤的技能，請依照以下指示操作。

內建 Foundry Tools 技能

許多內建的認知技能，如語言偵測、實體辨識或 OCR，皆由 Foundry Tools API 端點支持。 有時這些端點會發生暫時性問題，導致請求超時。對於這類暫時性問題，除了等待並再次嘗試之外，別無他法。 作為緩解措施，可以考慮將索引器設置為按排程運行。 排定的索引會從上次停止的位置繼續。 假設暫時性問題已解決，索引與認知技能處理應能在下一次預定運行中繼續進行。

如果你在同一份內建認知技能文件中持續看到這個錯誤，請提出 支援單 以獲得協助，因為這並非預期中的。

自訂技能

如果您遇到自訂技能的逾時錯誤，可以嘗試幾件事。 首先，檢視你的自訂技能，確保它沒有陷入無限循環，且能穩定回傳結果。 一旦確認結果返回後，檢查執行時間。 如果你沒有在自訂技能定義中明確設定 timeout 數值，那麼預設 timeout 是 30 秒。 如果 30 秒不夠讓你的技能執行，你可以在自訂技能定義中指定更高的 timeout 數值。 這裡有一個自訂技能定義的範例，超時時間設為 90 秒：

  {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "uri": "<your custom skill uri>",
        "batchSize": 1,
        "timeout": "PT90S",
        "context": "/document",
        "inputs": [
          {
            "name": "input",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "output",
            "targetName": "output"
          }
        ]
      }

你可以設定 timeout 參數的最大值是 230 秒。 如果你的自訂技能無法在 230 秒內穩定執行，你可以考慮減少自訂技能的執行量 batchSize ，讓它在一次執行中處理的文件數量更少。 如果你已經設定 batchSize 為 1，你需要重寫技能，讓它能在 230 秒內執行，或者拆分成多個自訂技能，讓單一自訂技能的執行時間最多為 230 秒。 請參考 自訂技能文件 以獲得更多資訊。

Error: Could not 'MergeOrUpload' | 'Delete' document to the search index

文件被讀取並處理，但索引器無法將其加入搜尋索引。 這可能因以下原因而發生：

Error: Could not index document because some of the document's data was not valid

該文件由索引器讀取與處理，但由於索引欄位配置與索引器擷取及處理的資料不符，無法將其加入搜尋索引。 這可能因以下原因而發生：

在所有這些情況下，請參考 「支援的資料型別 」和「 索引器資料型別映射 」，以確保你正確建立索引結構並設定了適當的 索引器欄位映射。 錯誤訊息包含有助於追蹤不匹配來源的細節。

Error: Integrated change tracking policy cannot be used because table has a composite primary key

這適用於 SQL 資料表，通常發生在金鑰被定義為複合金鑰，或資料表定義了唯一的叢集索引（例如 SQL 索引，而非 Azure 搜尋索引）時。 主要原因是金鑰屬性被修改為 唯一叢集索引中的複合主鍵。 在這種情況下，請確保你的 SQL 表格沒有唯一的叢集索引，或是將金鑰欄位對應到保證不會重複值的欄位。

Error: Could not process document within indexer max run time

當索引器無法在允許的執行時間內完成資料來源單一文件的處理時，就會發生此錯誤。 當使用技能組合時，最大遊戲時間會較短。 當發生此錯誤時，如果你將 maxFailedItems 設定為非 0，索引器會在未來執行時繞過該文件，以便索引能繼續進行。 如果你無法跳過任何文件，或是經常遇到這個錯誤，可以考慮將文件拆分成較小的文件，這樣在單一索引器執行中就能部分進展。

Error: Could not project document

此錯誤發生在索引器嘗試將 資料投影到知識庫 時，嘗試失敗。 這個故障可能是持續且可修復的，或者是投影輸出匯的暫時性故障，你可能需要等待並重試才能解決。 以下是一組已知的失敗狀態和可能的解決方案。

Error: The cognitive service for skill '<skill-name>' has been throttled

技能執行失敗，因為呼叫 Foundry Tools 的頻率被限制。 通常，這類失敗發生在技能過多同時執行時。 如果你使用 Microsoft.Search.Documents 客戶端函式庫來執行索引器，可以使用 SearchIndexingBufferedSender 來取得失敗步驟的自動重試。 否則，你可以 重置並重新執行索引器。

Error: Expected IndexAction metadata

「預期 IndexAction 元資料」錯誤表示當索引器嘗試讀取文件以判斷應採取的行動時，卻未在文件中找到對應的元資料。 通常，當索引器新增或移除註解快取且未重置索引器時，會發生此錯誤。 為了解決這個問題，你應該 重置並重新執行索引器。

Warning: Skill input was invalid

技能輸入缺失、類型錯誤，或是無效。 你可能會看到以下資訊：

• Could not execute skill

• Skill executed but may have unexpected results

認知技能包含必要的輸入和可選的輸入。 例如， 關鍵詞萃取技能 有兩個必填輸入 text， languageCode且沒有可選輸入。 自訂技能輸入都被視為可選輸入。

如果缺少必要的輸入或輸入類型不正確，該技能會被跳過並產生警告。 略過的技能不會產生輸出。 如果下游技能取用略過技能的輸出，可能會產生其他警告。

如果缺少可選輸入，技能仍會執行，但可能會因缺少輸入而產生意想不到的輸出。

這兩種情況下，這個警告都是因為你的資料格式。 例如，如果你有一份包含firstName、middleName、lastName這些欄位的人物資訊的文件，有些文件可能沒有middleName的條目。 如果您將 middleName 作為管線中技能的輸入傳遞，則此技能輸入有時遺漏是預期情況。 您需要評估您的資料與情境，以判斷是否因警告需要採取任何行動。

如果你想為缺少的輸入提供預設值，可以用 條件技能 產生預設值，然後用 條件技能 的輸出作為技能輸入。

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == null" },
        { "name": "whenTrue", "source": "= 'en'" },
        { "name": "whenFalse", "source": "= $(/document/language)" }
    ],
    "outputs": [ { "name": "output", "targetName": "languageWithDefault" } ]
}

Warning: Skill input 'languageCode' has the following language codes 'X,Y,Z', at least one of which is invalid.

傳遞至下游技能選用 languageCode 輸入的一或多個值不受支援。 如果你將 LanguageDetectionSkill 的輸出傳給後續技能，而輸出的語言數量超過這些下游技能所支援的數量，這種情況就可能發生。

請注意，如果傳遞無效的 countryHint 輸入給 LanguageDetectionSkill，您也可能會收到類似的警告通知。 如果發生這種情況，請驗證你從資料來源輸入的欄位是否包含有效的 ISO 3166-1 alpha-2 兩字母國家代碼。 如果有些是有效的，有些是無效的，請按照以下指引繼續，但請將languageCode替換為countryHint並將defaultLanguageCode替換為defaultCountryHint，以符合你的使用情境。

如果你知道你的資料集全部都在同一種語言裡，你應該移除 LanguageDetectionSkill 和 languageCode skill 輸入，改用 defaultLanguageCode 該技能的 skill 參數，前提是該語言支援該技能。

如果你知道資料集包含多種語言，因此需要 LanguageDetectionSkill 和 languageCode 輸入，可以考慮加一個 條件技能 ，過濾掉不支援語言的文字，再把文字傳給後續技能。 以下是 EntityRecognitionSkill 可能的範例：

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == 'de' || $(/document/language) == 'en' || $(/document/language) == 'es' || $(/document/language) == 'fr' || $(/document/language) == 'it'" },
        { "name": "whenTrue", "source": "/document/content" },
        { "name": "whenFalse", "source": "= null" }
    ],
    "outputs": [ { "name": "output", "targetName": "supportedByEntityRecognitionSkill" } ]
}

以下是目前支援且可產生此錯誤訊息之各技能語言的部分參考：

• EntityRecognitionSkill 支援的語言
• EntityLinkingSkill 支援的語言
• KeyPhraseExtractionSkill 支援的語言
• LanguageDetectionSkill 支援的語言
• PIIDetectionSkill 支援的語言
• SentimentSkill 支援的語言
• 翻譯支援語言
• Text SplitSkill 支援的語言：da, de, en, es, fi, fr, it, ko, pt

Warning: Skill input was truncated

認知技能限制了一次可分析的文字長度。 如果文字輸入超過限制，文本會在豐富前被截斷。 技能會執行，但不會涵蓋您的所有資料。

在下面的範例 LanguageDetectionSkill 中，如果輸入超過字元限制， 'text' 輸入欄位可能會觸發此警告。 輸入限制可參考 技能參考文件。

 {
    "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
    "inputs": [
      {
        "name": "text",
        "source": "/document/text"
      }
    ],
    "outputs": [...]
  }

如果你想確保所有文字都被分析，可以考慮使用 分割技能。

Warning: Web API skill response contains warnings

索引器在技能組執行了該技能，但 Web API 請求的回應顯示有警告。 檢視警告內容，了解您的資料如何受到影響，以及是否需要進一步處理。

Warning: The current indexer configuration does not support incremental progress

此警告僅發生在 Azure Cosmos 資料庫的資料來源。

索引過程中的增量進展確保若索引器執行因短暫失敗或執行時間限制而中斷，索引器下次執行時能從中止處繼續，而不必從頭重新索引整個集合。 當索引大型集合時，這尤其重要。

能夠恢復未完成的索引工作，取決於文件必須依據 _ts 欄位排序。 索引器會利用時間戳決定接下來要選取哪份文件。 如果 _ts 欄位遺失，或索引器無法判斷自訂查詢是否被排序，索引器會從起始開始，你會看到這個警告。

你可以透過配置 assumeOrderByHighWaterMarkColumn 屬性來覆蓋此行為，實現增量進度並抑制此警告。

欲了解更多資訊，請參閱 增量進度與自訂查詢。

Warning: Some data was lost during projection. Row 'X' in table 'Y' has string property 'Z' which was too long.

Table Storage 服務對實體屬性的大小有限制。 字串可有 32,000 字元或更少。 若投影的字串屬性超過 32,000 字元，則僅保留前 32,000 個字元。 為了避開此問題，請避免投影32,000字元以上的字串屬性的列。

Warning: Truncated extracted text to X characters

索引器限制了從單一文件中可擷取的文字量。 這個限制取決於價格層級：免費層為32,000字元，基本層64,000字元，標準層400萬字元，標準層S2 800萬字元，標準層S3 1,600萬字元。 被截斷的文字不會被索引。 為了避免這個警告，試著將含有大量文字的文件拆解成多個較小的文件。

欲了解更多資訊，請參閱索引器限制。

Warning: Could not map output field 'X' to search index

引用不存在或空資料的輸出欄位映射會為每份文件產生警告，並導致索引欄位為空。 若要解決此問題，請再次檢查輸出欄位對應來源路徑是否可能有錯字，或使用條件式技能設定預設值。 詳情請參見 輸出場映射 。

Warning: The data change detection policy is configured to use key column 'X'

資料變更偵測政策 對用來偵測變更的欄位有特定要求。 其中一項要求是，每當來源項目變更時，該欄位必須更新。 另一個要求是該欄的新值必須大於先前的值。 金鑰欄位不符合這個要求，因為它們不會在每次更新時改變。 為了解決此問題，請選擇變更偵測策略的其他欄位。

Warning: Document text appears to be UTF-16 encoded, but is missing a byte order mark

索引器的解析模式需要先知道文字是如何編碼的，才能進行解析。 最常見的兩種文字編碼方式是 UTF-16 和 UTF-8。 UTF-8 是一種可變長度編碼，每個字元長度介於 1 位元組到 4 位元組之間。 UTF-16 是一種固定長度編碼，每個字元長度為 2 位元組。 UTF-16 有兩種不同的變體，big endian 和 little endian。 文字編碼由 byte order mark文字前的一串位元組決定。

若不存在位元組順序標記，則假設文字編碼為 UTF-8。

要繞過這個警告，請先確定這個 blob 的文字編碼，並加上適當的位元組順序標記。

Warning: Azure Cosmos DB collection 'X' has a Lazy indexing policy. Some data may be lost

採用 懶惰 索引政策的集合無法持續被查詢，導致索引器缺少資料。 為了繞過這個警告，請將你的索引政策改為「一致性」。

Warning: The document contains very long words (longer than 64 characters). These words may result in truncated and/or unreliable model predictions.

此警告來自 Foundry Tools 的語言服務。 在某些情況下，可以安全地忽略這個警告，例如長字串只是個很長的網址。 請注意，當一個單字超過64個字元時，會被截斷成64個字元，這會影響模型的預測。

Error: Cannot write more bytes to the buffer than the configured maximum buffer size

索引器有 文件大小限制。 請確保資料來源中的文件大小小於服務層級所規定的支援大小限制。

Error: Failed to compare value 'X' of type M to value 'Y' of type N.

這個錯誤通常發生在 Azure SQL 索引器中，當所使用的 dataChangeDetectionPolicy 來源欄位類型與索引器預期不符時，尤其是開啟 convertHighWaterMarkToRowVersion 時。

例如，如果用於變更偵測的欄位是 datetime 型別，但由於啟用了 convertHighWaterMarkToRowVersion，索引器預期的是 rowversion 類型，這種不匹配將導致錯誤。

檢查來源中「高水位標記」欄位的資料型態，並相應更新索引器設定。 驗證並更新後，重置並重啟索引器以處理欄位值。

Error: Access denied to Virtual Network/Firewall rules

此錯誤通常由以下原因之一引起：

• 根據你的設定，indexer 需要對 Azure 資源設置防火牆限制。 這些資源可能包括：資料來源、Azure 儲存體 帳號（用於除錯工作、增量豐富或知識庫）、Azure Function（用於網頁 API 自訂技能）或 AI 豐富過程中使用的 Microsoft Foundry 部署。
• 私有端點配置會阻擋索引器對這些資源的存取。

請透過檢視資源配置，確保索引器能存取你的設定元件，確認它們允許流量到所有所需服務：

• 防火牆與 IP 限制設定
• 共享私有連結設定

Error: Credentials provided in the connection string are invalid or have expired

此錯誤發生於 Azure AI 搜尋服務 索引器無法使用提供的連線字串進行認證，或無法存取儲存帳號以驗證憑證時發生。

Error: Invalid AAD tenant

當 Microsoft 365 索引器中的 SharePoint 無法認證擁有該 SharePoint 網站的 Microsoft Entra 租戶時，這則訊息可能會出現。 TenantId在 SharePoint 資料來源的 連接字串 中是可選的，但你提供的任何值都必須是該站點的 Microsoft Entra 租戶 ID（GUID）。 這個租用戶不一定是您搜尋服務所關聯的 Microsoft Entra 租用戶。

請依照以下指引解決錯誤：

• 對於跨租戶 SharePoint 連線，請在連接字串中將 SharePoint 網站的 Microsoft Entra 租戶 ID 指定為 TenantId。
• 若要在相同的 Microsoft Entra 租用戶內建立連線，請提供 SharePoint 網站的租用戶 ID，或啟用搜尋服務的系統指派受控身分識別。 當您省略 TenantId 時，索引持會使用與該身分相關的 Microsoft Entra 資源租用戶。
• 若明確的 TenantId 或資源租用戶皆不可用，索引子會報告：Ensure service managed identity is enabled for your service, or TenantId is specified in your 連接字串.

格式不正確且不是 GUID 的值，可能會在您建立或更新資料來源時導致失敗。 錯誤的 Microsoft Entra 租用戶若有良好格式的 ID，可能會通過資料來源驗證，但在索引子驗證時會失敗。 對於執行失敗，請前往 Azure 入口網站的搜尋服務，選擇搜尋管理>索引器，選擇索引器，並檢視其執行歷史與狀態細節。

關於 連接字串 格式及尋找 SharePoint 網站 Microsoft Entra 租戶 ID 的說明，請參見「在 Microsoft 365 索引器中配置 SharePoint」。

Error: Error detecting index schema from data source

用來設定索引器的 Azure 入口網站體驗無法從資料來源取得結構資訊。 這可能是因為短暫的連線問題或網路設定限制，導致 Azure AI 搜尋服務 無法存取來源。