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

暂时性错误

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

若要有效地管理这些错误，建议 为索引器制定计划 ，例如，每五分钟运行一次。 这意味着下一次运行将在第一次运行完成后五分钟开始，同时遵循 最大运行时限制 。 定期计划的运行有助于快速纠正任何暂时性错误或警告。

如果你注意到多个索引器运行上存在错误，则可能不是暂时性问题。 在这种情况下，请参阅下面的列表了解可能的解决方案。 请注意，务必确保索引计划符合索引器限制指南中所述的限制。

从 API 版本 2019-05-06 开始，将会构建项级索引器错误和警告，使原因和后续措施变得更明朗。 这些信息包含以下属性：

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

由于对 Web API 的调用失败，未能执行技能。 通常，此类失败是在使用自定义技能时发生的，在这种情况下，需要调试自定义代码才能解决问题。 如果失败来源于某个内置技能，请参考错误消息以获得解决问题的帮助。

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

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

由于对 Web 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

在两种情况下可能会出现此错误消息，每种情况应以不同的方式进行处理。 请根据返回此错误的技能，按照以下说明予以解决。

内置 Azure AI 服务技能

许多内置认知技能（例如语言检测、实体识别或 OCR）由 Azure AI 服务 API 终结点提供支持。 有时，这些终结点会出现暂时性问题，因而请求超时。对于暂时性的问题，除了等待一段时间后重试以外，并没有其他补救措施。 作为缓解措施，请考虑将索引器设置为 按计划运行 。 计划的索引编制将从中断的位置继续。 假设解决了暂时性问题，在下一次计划的运行时，索引编制和认知技能处理应可继续进行。

如果内置认知技能的同一文档仍然出现此错误，请提交 支持票证 以获得帮助，因为此错误无法预期。

自定义技能

如果在使用自定义技能时遇到超时错误，可以尝试多种解决办法。 首先，检查该自定义技能，确保它未陷入无限循环，并且可持续返回结果。 确认返回结果后，请检查执行持续时间。 如果未在自定义技能定义中显式设置 timeout 值，则默认的 timeout 为 30 秒。 如果 30 秒不足以完成技能的执行，可以在自定义技能定义中指定一个更高的 timeout 值。 下面是将超时设置为 90 秒的自定义技能定义示例：

可为 timeout 参数设置的最大值为 230 秒。 如果自定义技能无法在 230 秒内以一致的方式执行，你可以考虑减小自定义技能的 batchSize ，以减少它在单次执行中处理的文档数。 如果已将 batchSize 设置为 1，则需要重写技能，使其能够在 230 秒内完成执行；或者将其拆分为多个自定义技能，使任何一个自定义技能的最长执行时间为 230 秒。 有关详细信息，请查看 自定义技能文档 。

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

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

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

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

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

Error: Expected IndexAction metadata

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

Warning: Skill input was invalid

技能的某项输入缺少、类型错误或无效。 你可能会看到以下信息：

Warning: Skill input was truncated

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

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

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

Warning: Web API skill response contains warnings

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

Warning: The current indexer configuration does not support incremental progress

只有 Azure Cosmos DB 数据源才会出现此警告。

索引编制过程中的增量操作可确保由于暂时性故障或执行时间限制而中断索引器执行时，索引器能够在下次运行时从中断位置运行，而不是从头开始重新为整个集合编制索引。 在为大型集合编制索引时，这一点尤其重要。

可以使用按 _ts 列排序的文档，来预测未完成的索引编制作业的恢复能力。 索引器使用时间戳来确定下一次要选取哪个文档。 如果缺少 _ts 列，或者索引器无法确定某个自定义查询是否按该列排序，则索引器将从开头开始，同时会出现此警告。

可以使用 assumeOrderByHighWaterMarkColumn 配置属性重写此行为，以启用增量进度并消除此警告。

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

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

表存储服务 对 实体属性 的大小施加了限制。 字符串最多只能包含 32,000 个字符。 如果所要投影的行中的字符串属性超过 32,000 个字符，只会保留前 32,000 个字符。 若要解决此问题，请避免投影其字符串属性超过 32,000 个字符的行。

Warning: Truncated extracted text to X characters

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

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

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

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

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 （文本前面的一系列字节）确定。

若要解决此警告，请确定此 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.

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

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

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