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

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

当错误计数超过 maxFailedItems 时，索引停止。 若要让索引器跳过失败的文档，请配置 maxFailedItemsandmaxFailedItemsPerBatch。

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

在哪里可以找到特定的索引器错误？

验证索引器状态并识别错误：

1. 请在 Azure 门户中打开您的搜索服务。

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

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

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

技能执行失败，因为对 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

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

内置 Foundry Tools 功能

许多内置认知技能（如语言检测、实体识别或 OCR）都由 Foundry 工具 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 工具的调用受到限制。 通常，当并行执行过多技能时，会发生此类故障。 如果您使用 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 的输出传递到后续技能，并且输出包含的语言比这些下游技能支持的语言多，则可能会出现这种情况。

请注意，如果向 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

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 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 个字符，标准 S2 为 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系列字节确定。

如果没有字节顺序标记，则假定文本编码为 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 工具的语言服务传递的。 在某些情况下，可以放心地忽略此警告，例如，如果长字符串只是一个长 URL。 请注意，当单词超过 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，但索引器需要 rowversion 类型，因为 convertHighWaterMarkToRowVersion 已启用，那么不匹配可能会导致错误。

检查源中“高水印”列的数据类型，并相应地更新索引器配置。 验证并更新后，重置并重新运行索引器以处理列值。

Error: Access denied to Virtual Network/Firewall rules

此错误通常由以下任一原因导致：

• 索引器所需的 Azure 资源的防火墙限制，具体取决于配置。 这些资源可能包括： 数据源、Azure 存储帐户（用于 调试会话、 增量扩充 或 知识存储）、Azure 函数（用于 Web API 自定义技能），或Microsoft AI 扩充期间使用的 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 搜索无法访问源。