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

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

当错误计数超过 maxFailedItems 时，索引编制操作停止。

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

本文中的错误信息可帮助你解决错误，使索引编制能够继续。

出现警告时不会停止索引编制，但它们确实表示出现了可能导致意外结果的状况。 是否采取措施取决于具体的数据和场景。

若要验证索引器状态并标识 Azure 门户中的错误，请按照以下步骤进行操作：

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

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

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

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 设置为非 0 值，则索引器将在以后的运行中绕过该文档，使索引编制能够继续。 如果无法跳过任何文档，或者此错误一直出现，请考虑将文档分解为较小的文档，以便在索引器的单次执行中处理能够取得部分进展。

如果索引器在尝试将数据投影到知识存储时失败，则会发生此错误。 这种失败可能会持续出现但可修复；或者，可能是投影输出接收器的暂时性失败，在这种情况下，需要等待并重试才能解决这种失败。 下面是一系列已知失败状态及其可能的解决方法。

技能执行失败，因为对 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 支持的语言
• 翻译工具支持的语言
• 文本 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 个字符，标准层为 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 个字符，这会影响模型预测。

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