排查 Azure AI 搜索中的常见索引器错误和警告

本文提供有关在 Azure AI 搜索中索引编制和 AI 扩充期间可能会遇到的常见错误和警告的信息和解决方案。

当错误计数超过 “maxFailedItems”时，索引停止。

如果希望索引器忽略这些错误（并跳过“失败的文档”），请考虑根据此处的说明更新maxFailedItems和maxFailedItemsPerBatch。

本文中的错误信息可以帮助你解决错误，从而允许索引继续。

警告不会停止索引，但它们确实指示可能导致意外结果的条件。 是否采取措施取决于数据和您的情境。

若要验证索引器状态并识别 Azure 门户中的错误，请执行以下步骤：

1. 登录到 Azure 门户并查找你的搜索服务。

2. 在左侧，展开 “搜索管理>索引器 ”并选择一个索引器。

3. 在 “执行历史记录”下，选择状态。 所有状态（包括 Success）都有有关执行的详细信息。

4. 如果出现错误，请将鼠标悬停在错误消息上。 屏幕右侧会显示一个窗格，其中显示了有关错误的详细信息。

由于各种原因（例如暂时性网络通信中断、长时间运行的进程超时或特定文档细微差别），在索引器运行期间经常遇到暂时性错误或警告。 但是，这些错误是临时的，应在后续索引器运行中解决。

为了有效管理这些错误，我们建议将 索引器按计划运行，例如，每隔五分钟运行一次，下一次运行将在完成第一次运行后五分钟开始，并遵循服务 的最大运行时限制 。 定期安排的运行有助于纠正瞬时错误或警告。

如果错误在多次索引器运行中持续存在，它可能不是暂时性的问题。 在这种情况下，请参阅下面的列表了解潜在的解决方案。

索引器无法从数据源读取文档。 此错误的可能原因包括：

具有 Blob 数据源的索引器无法从文档中提取内容或元数据（例如 PDF 文件）。 此错误的可能原因包括：

索引器从数据源读取文档，但将文档内容转换为指定的字段映射架构时出现问题。 此错误的可能原因包括：

输出映射可能已失败，因为所使用的映射函数不适合输出数据的格式。 例如，对 Base64Encode 二进制数据应用映射函数将生成此错误。 若要解决此问题，请在不指定映射函数的情况下重新运行索引器，或确保映射函数与输出字段数据类型兼容。 有关详细信息，请参阅 输出字段映射 。

索引器无法执行技能集中定义的技能。

技能执行失败，因为对 Web API 的调用失败。 通常，使用自定义技能时会发生此类故障，在这种情况下，需要调试自定义代码来解决该问题。 如果失败来自内置技能，请查看错误消息以寻求解决问题的帮助。

调试此问题时，请务必注意此 技能的任何技能输入警告 。 Web API 终结点可能失败，因为索引器正在传递意外输入。

技能执行失败，因为对 Web API 的调用返回了无效的响应。 通常，使用自定义技能时会发生此类故障，在这种情况下，需要调试自定义代码来解决该问题。 如果失败来自内置技能，请提交 客服请求单 以获取帮助。

如果数据源具有与尝试在索引中映射的字段不同的数据类型的字段，则可能会遇到此错误。 检查数据源字段数据类型，并确保它们 正确映射到索引数据类型。

在以下两种情况下，可能会遇到此错误消息，每个错误消息应以不同的方式处理。 根据是什么技能返回了此错误，按照以下说明进行操作。

许多内置认知技能（如语言检测、实体识别或 OCR）都由 Azure AI 服务 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 秒。 有关详细信息，请查看 自定义技能文档 。

文档已读取和处理，但索引器无法将其添加到搜索索引。 此错误的可能原因包括：

文档由索引器读取和处理，但由于索引字段的配置与索引器提取和处理的数据不匹配，因此无法将其添加到搜索索引。 此错误的可能原因包括：

在所有这些情况下，请参阅索引器 支持的数据类型 和 数据类型映射 ，以确保正确生成索引架构并设置适当的 索引器字段映射。 错误消息包含可帮助跟踪不匹配源的详细信息。

这适用于 SQL 表，通常发生在键被定义为复合键，或者表定义了唯一聚集索引的情况下（指的是 SQL 索引，而不是 Azure 搜索索引）。 主要原因是将键属性修改为 唯一聚集索引中的复合主键。 在这种情况下，请确保 SQL 表没有唯一的聚集索引，或者将键字段映射到保证不具有重复值的字段。

当索引器无法在允许的执行时间内完成从数据源处理单个文档时，会发生此错误。 使用技能集时，最长运行时间较短。 发生此错误时，如果 maxFailedItems 设置为非零值，索引器会在后续运行中跳过该文档，以确保索引继续进行。 如果您不能跳过任何文档，或如果反复遇到此错误，请考虑将文档拆分为较小的部分，以便在一次索引执行中实现部分进度。

当索引器尝试将数据 投影到知识存储 并且尝试失败时，会发生此错误。 此故障可以一致且可修复，也可能是投影输出接收器的暂时性故障，可能需要等待并重试才能解决。 下面是一组已知的故障状态和可能的解决方法。

技能执行失败，因为对 Azure AI 服务的调用受到限制。 通常，当并行执行过多技能时，会发生此类故障。 如果使用 Microsoft.Search.Documents 客户端库运行索引器，则可以使用 SearchIndexingBufferedSender 在失败的操作上自动重试。 否则，可以 重置并重新运行索引器。

“预期的 IndexAction 元数据”错误意味着当索引器尝试读取文档以识别应执行的作时，它找不到文档上的任何相应元数据。 通常，当索引器添加或删除批注缓存而不重置索引器时，会发生此错误。 若要解决此问题，应 重置并重新运行索引器。

技能输入缺失、类型错误或其他无效情况。 你可能会看到以下信息：

• 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" } ]
}

不支持传递到下游技能中的可选 languageCode 输入参数的一个或多个值。 如果将 LanguageDetectionSkill 的输出传递到后续技能，并且输出包含的语言比这些下游技能支持的语言多，则可能会出现这种情况。

请注意，如果向 LanguageDetectionSkill 传递无效 countryHint 输入，则还可以收到类似于此警告的警告。 如果发生这种情况，请验证你用于该输入的数据源中的字段是否包含有效的 ISO 3166-1 alpha-2 两个字母国家/地区代码。 如果有些有效而有些无效，请继续遵循以下指南，但将languageCode替换为countryHint，将defaultLanguageCode替换为defaultCountryHint以符合您的用例。

如果知道数据集全部采用一种语言，则应删除 LanguageDetectionSkill 和 languageCode 技能输入，并 defaultLanguageCode 改用该技能的技能参数，假设该技能支持该语言。

如果知道数据集包含多种语言，因此需要 LanguageDetectionSkill 和 languageCode 输入，请考虑添加 ConditionalSkill 以在传递文本到下游技能之前筛选出不支持的语言文本。 以下是 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

认知技能限制一次可以分析的文本长度。 如果文本输入超出限制，则会在扩充文本之前截断文本。 技能会执行，但不会处理所有数据。

在下面的 LanguageDetectionSkill 示例中，'text' 输入字段在输入超出字符限制时可能会触发此警告。 可以在 技能参考文档中找到输入限制。

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

如果要确保分析所有文本，请考虑使用 拆分技能。

索引器在技能组中运行技能，但来自 Web API 请求的响应表明存在警告。 查看警告，了解您的数据受到的影响以及是否需要采取进一步措施。

此警告仅适用于 Azure Cosmos DB 数据源。

索引编制期间的增量进度可确保如果索引器执行因暂时性故障或执行时间限制而中断，索引器可以在下次运行时从头开始恢复整个集合的中断位置，而无需从头开始重新编制索引。 为大型集合编制索引时，这一点尤其重要。

能够恢复未完成的索引作业取决于文档按_ts列排序。 索引器使用时间戳来确定下一步要选取的文档。 _ts如果列缺失，或者索引器无法确定自定义查询是否按它排序，索引器将从头开始，你将看到此警告。

可以使用assumeOrderByHighWaterMarkColumn配置属性重写此行为，从而启用增量进度并禁止显示此警告。

有关详细信息，请参阅 增量进度和自定义查询。

表存储服务对实体属性的大小有限制。 字符串可以包含 32,000 个字符或更少。 如果投影的字符串属性超过 32,000 个字符的行，则只保留前 32,000 个字符。 若要解决此问题，请避免将字符串属性长度超过 32,000 个字符的行进行投影。

索引器限制可从任意一个文档中提取多少文本。 此限制取决于定价层：免费层为 32,000 个字符，基本层为 64,000 个字符，标准 S2 为 400 万个字符，标准 S2 为 800 万个字符，标准 S3 为 1600 万个字符。 截断的文本不会编制索引。 若要避免出现此警告，请尝试将包含大量文本的文档拆分为多个较小的文档。

有关详细信息，请参阅 索引器限制。

引用不存在/null 数据的输出字段映射将为每个文档生成警告，并生成空索引字段。 若要解决此问题，请仔细检查输出字段映射源路径是否存在可能的拼写错误，或使用 条件技能设置默认值。 有关详细信息，请参阅 输出字段映射 。

数据更改检测策略 对用于检测更改的列具有特定要求。 其中一项要求是每次更改源项时都会更新此列。 另一个要求是，此列的新值大于以前的值。 键列不满足此要求，因为它们不会在每次更新时更改。 为了解决此问题，请选择用于更改检测策略的其他列。

索引器分析模式需要知道文本在分析之前如何编码。 编码文本的两种最常见方法是 UTF-16 和 UTF-8。 UTF-8 是可变长度编码，其中每个字符长度介于 1 字节和 4 字节之间。 UTF-16 是固定长度编码，其中每个字符长度为 2 字节。 UTF-16 具有两个不同的变体， big endian 以及 little endian。 文本编码由文本之前的一 byte order mark系列字节确定。

如果没有字节顺序标记，则假定文本编码为 UTF-8。

若要解决此警告，请确定此 Blob 的文本编码是什么，并添加相应的字节顺序标记。

无法一致地查询具有 延迟 索引策略的集合，从而导致索引器缺少数据。 若要解决此警告，请将索引策略更改为“一致”。

此警告是从 Azure AI 服务的语言服务传递的。 在某些情况下，可以放心地忽略此警告，例如，如果长字符串只是一个长 URL。 请注意，当单词超过 64 个字符时，它将被截断为 64 个字符，这可能会影响模型预测。

索引器具有 文档大小限制。 确保数据源中的文档小于支持的大小限制，如服务层所述。