Azure AI 搜索索引器故障排除指南

有时，索引器会遇到的问题不产生错误，或在其他 Azure 服务上发生，例如在身份验证期间或连接时。 本文重点介绍如何在没有任何消息指导你时排查索引器问题。 它还介绍了如何对索引编制期间使用的非搜索资源的错误进行故障排除。

最佳做法

以下是使用索引器时的一些最佳做法和建议：

索引器旨在按计划运行

• 若要进行可靠的索引编制，请将索引器配置为 按常规计划运行。 计划任务会自动获取由于暂时性错误、网络中断或临时服务问题而在先前运行中未能处理的文档。 此方法有助于保持数据一致性，并最大程度地减少手动干预的需求。
• 对于 大型数据源，初始枚举和索引可能需要数小时甚至数天。 按计划运行索引器可确保进程持续，并自动重试错误。 避免只依赖手动或按需索引器运行，因为这些选项不提供相同的可靠性或暂时性错误恢复。

索引器随着时间的推移竭尽所能提供索引

• 内置索引器可在不出现永久性错误的情况下处理文档，并会在后续计划运行中重试。 它们为常见方案提供方便、低代码或无代码方式来为数据编制索引，从而实现更快的开发和简化维护。 当索引器运行技能集时，每个运行都有固定的执行时间限制。 在 多租户执行环境中 运行的索引器具有两小时的最大运行时间。 此限制是最常见的情况，当技能集不需要共享专用链接时使用。 配置为使用 共享专用链接 的索引器在专用执行环境中运行，最大为 24 小时。 有关完整表，请参阅 索引器限制。 如果每个文档技能集处理阻止索引器在时间限制之前完成，它将停止并保留未处理的剩余文档。 当文档卷、文件大小、技能组复杂性或执行环境阻止索引器在其最长运行时内完成时，无法保证完成处理。 对数据源进行分区可以降低此风险，但不会消除此风险，尤其是在以后向分区中添加大量文件时。 这是预期的行为。 有关管理大型数据集和支持增量恢复的策略，请参阅 索引大型数据集 和 计划索引器。 如果解决方案需要严格控制索引器何时处理文档，请使用本文中的推送 API 替代方法。
• 如果解决方案需要严格控制索引时间线，请改用推送 API，例如文档索引 REST API 或 IndexDocuments 方法（用于 .NET 的 Azure SDK）。 这些选项可让你完全控制索引管道。
• 索引器有时会偏离计划进度。 虽然这种情况并不常见，并且存在自动恢复机制，但恢复可能需要一些时间。 这是预期的行为。

排查与受限资源的连接问题

对于 Azure 网络安全下的数据源，索引器在建立连接的方式方面受到限制。 目前，索引器可以通过专用终结点使用共享专用链接访问 IP 防火墙后面或虚拟网络上的受限数据源。

在专用连接上连接到 Azure AI 服务资源时出错

如果出现错误代码 403 并显示以下消息，则技能集中资源终结点的指定方式可能有问题：

• "A Virtual Network is configured for this resource. Please use the correct endpoint for making requests. Check https://aka.ms/cogsvc-vnet for more details."

如果您为连接到 Azure AI 服务资源配置了 共享专用链接，且终结点缺少自定义子域，则会发生此错误。 自定义子域是终结点的第一部分。 如果在 AI 服务门户中而不是 Azure 门户创建了资源，则可能缺少自定义域。

如果 AI 服务资源与 Azure AI 搜索不在同一区域， 请使用无键连接 来附加资源。

防火墙规则

Azure 存储、Azure Cosmos DB 和 Azure SQL 提供可配置的防火墙。 防火墙阻止请求时没有特定的错误消息。 通常情况下，防火墙错误是通用的。 一些常见错误包括：

• The remote server returned an error: (403) Forbidden
• This request is not authorized to perform this operation
• Credentials provided in the connection string are invalid or have expired

若要允许索引器访问这些资源，请使用以下选项之一：

• 为搜索服务的 IP 地址和 AzureCognitiveSearch服务标记的 IP 地址范围配置入站规则。 在以下链接中可以找到有关对每种数据源类型配置 IP 地址范围限制的详细信息：

  • Azure 存储
  • Azure Cosmos DB
  • Azure SQL

• 作为最后手段或临时措施，允许从所有网络进行访问来禁用防火墙。

限制：仅当你的搜索服务和存储帐户位于不同的区域时，IP 地址范围限制才适用。

除了数据检索之外，索引器还通过技能集和自定义技能发送出站请求。 对于基于 Azure 函数的自定义技能，请注意 Azure 函数也有 IP 地址限制。 允许通过自定义技能执行的 IP 地址列表包括您的搜索服务的 IP 地址以及服务标记 AzureCognitiveSearch 的 IP 地址范围。

网络安全组 (NSG) 规则

当索引器访问 SQL 托管实例上的数据时，或者当 Azure VM 用作自定义技能的 Web 服务 URI 时，网络安全组将确定是否允许请求传入。

对于驻留在虚拟网络上的外部资源，请为 服务标记 配置入站 NSG 规则AzureCognitiveSearch。

有关连接到虚拟机的详细信息，请参阅配置与 Azure VM 上的 SQL Server 的连接。

网络错误

通常，网络错误是通用的。 一些常见错误包括：

• A network-related or instance-specific error occurred while establishing a connection to the server
• The server was not found or was not accessible
• Verify that the instance name is correct and that the source is configured to allow remote connections

当出现以下任一错误时：

• 确保您能够访问源，可尝试直接连接到该源，而不是通过搜索服务进行连接。
• 在 Azure 门户中检查资源是否存在任何当前错误或中断。
• 检查Azure 状态中是否有任何网络中断。
• 验证是否使用公共 DNS 进行名称解析，而不是Azure 专用 DNS。

Azure SQL 数据库无服务器索引（错误代码 40613）

如果 SQL 数据库在无服务器计算层上，请确保在索引器连接到该数据库时，该数据库正在运行（未暂停）。

如果数据库已暂停，则搜索服务中的第一次登录会自动恢复数据库，但会返回一个错误，指出数据库不可用，并给出错误代码 40613。 在数据库运行后，请重试登录以建立连接。

Microsoft Entra 条件访问策略

创建 SharePoint 索引器时，有一个步骤要求你在提供设备代码后登录到 Microsoft Entra 应用。 如果你收到一条消息，显示“"Your sign-in was successful but your admin requires the device requesting access to be managed"”，则索引器可能被某个条件访问策略阻止访问 SharePoint 文档库。

若要更新策略并允许索引器访问文档库，请执行以下操作：

1. 打开 Azure 门户并搜索 Microsoft Entra 条件访问。

2. 在左侧菜单上选择“策略”。 如果你没有查看此页的权限，则需要查找有访问权限或可获取访问权限的用户。

3. 确定阻止 SharePoint 索引器访问文档库的策略。 可能会阻止索引器的策略包括您在 “用户和组” 部分的索引器创建步骤中用于进行身份验证的用户帐户。 此策略还可能包含以下条件：

   • 限制 Windows 平台。
   • 限制“移动应用和桌面客户端”。
   • 将 设备状态 设置为 “是”。

4. 确认哪个策略正在阻止索引器后，请为索引器提供豁免。 首先检索搜索服务 IP 地址。

   首先，获取搜索服务的完全限定域名 (FQDN)。 FQDN 类似于 <your-search-service-name>.search.azure.cn。 可以在 Azure 门户中找到 FQDN。

   

   有了 FQDN 后，通过执行 FQDN 的 nslookup（或 ping）来获取搜索服务的 IP 地址。 在以下示例中，您将 150.0.0.1 添加到 Azure 存储防火墙上的一条入站规则中。 更新防火墙设置后，搜索服务索引器可能需要长达 15 分钟才能访问Azure 存储帐户。

   nslookup contoso.search.azure.cn
   Server:  server.example.org
   Address:  10.50.10.50
   
   Non-authoritative answer:
   Name:    <name>
   Address:  150.0.0.1
   Aliases:  contoso.search.azure.cn
   

5. 获取你所在区域的索引器执行环境的 IP 地址范围。

   额外的 IP 地址用于来自索引器的多租户执行环境的请求。 可以从服务标记获取此 IP 地址范围。

   可以通过AzureCognitiveSearch 或可下载的 JSON 文件获取服务标记的 IP 地址范围。

   在本练习中，假设搜索服务是Azure公有云，请下载Azure公共 JSON 文件。

   

   从 JSON 文件中，假设搜索服务位于中国北部，则会列出多租户索引器执行环境的 IP 地址列表。

       {
         "name": "AzureCognitiveSearch.chinanorth3",
         "id": "AzureCognitiveSearch.chinanorth3",
         "properties": {
           "changeNumber": 1,
           "region": "chinaeast2",
           "platform": "Azure",
           "systemService": "AzureCognitiveSearch",
           "addressPrefixes": [
             "52.150.139.0/26",
             "52.253.133.74/32"
           ]
         }
       }
   

6. 返回到 Azure 门户的“条件访问”页，从左侧菜单中选择“命名位置”，然后选择“+ IP 范围位置” 。 为新的命名位置提供一个名称，并为你在最后两个步骤中收集的搜索服务和索引器执行环境添加 IP 范围。 1

   • 对于搜索服务 IP 地址，可能需要将“/32”添加到 IP 地址的末尾，因为它只接受有效的 IP 范围。
   • 请注意，对于索引器执行环境 IP 范围，只需添加搜索服务所在区域的 IP 范围。

7. 从策略中排除新的命名位置：

   1. 在左侧菜单上选择“策略”。
   2. 选择阻止索引器的策略。
   3. 选择“条件”。
   4. 选择“位置”。
   5. 选择排除，然后添加新的命名位置。
   6. 保存更改。

8. 请等待几分钟，以使策略更新并强制执行新的策略规则。

9. 再次尝试创建索引器：

   1. 为你创建的数据源对象发送更新请求。
   2. 重新发送索引器创建请求。 使用新代码登录，然后发送另一个索引器创建请求。

索引不受支持的文档类型

如果要为 Azure Blob 存储 中的内容编制索引，并且容器包含不受支持的内容类型的 blob 对象，则索引器会跳过该文档。 在其他情况下，个别文档可能会出现问题。

在这种情况下，可以 设置配置选项 ，以便在单个文档出现问题时允许索引器处理继续。

PUT https://[service name].search.azure.cn/indexers/[indexer name]?api-version=2026-04-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false, "failOnUnprocessableDocument" : false } }
}

缺少文档

索引器从外部 数据源 中提取文档或行，并创建搜索服务为其编制索引的 搜索文档。 有时，数据源中存在的文档无法在搜索索引中显示。 存在以下任一原因时，就可能出现这种意外结果：

• 运行索引器后更新了文档。 如果索引器按计划运行，它最终会重新运行并拾取该文档。
• 索引器在文档被引入之前已超时。 存在最大处理时间限制，在此之后将不会处理任何文档。 可在 Azure 门户中或通过调用获取索引器状态 (REST API) 来查看索引器状态。
• 字段映射 或 AI 扩充 更改了文档及其在搜索索引中的表达方式与预期的不同。
• 更改跟踪值错误或缺少前提条件。 如果高水印值设置为将来的时间，索引器将跳过任何早于日期的文档。 可以使用 initialTrackingState 中的 finalTrackingState 和 字段来确定索引器的更改跟踪状态。 Azure SQL 和 MySQL 的索引器需要在源表的高水位标记列上设置索引，否则索引器进行的查询可能会超时。

Blob 存储中的内容丢失了

Blob 索引器可查找并提取容器中 Blob 的文本。 提取文本时出现的一些问题包括：

• 文档仅包含扫描的图像。 包含扫描图像 (JPG) 之类的非文本内容的 PDF Blob 不会在标准 Blob 索引管道中生成结果。 如果图像内容包含文本元素，则可通过 OCR 或图像分析来查找并提取文本。

• Blob 索引器配置为仅索引元数据。 若要提取内容，必须将 Blob 索引器配置为 同时提取内容和元数据：

PUT https://[service name].search.azure.cn/indexers/[indexer name]?api-version=2026-04-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "dataToExtract" : "contentAndMetadata" } }
}

Azure Cosmos DB 中的内容缺失

Azure AI 搜索对 Azure Cosmos DB 索引存在隐式依赖。 如果在 Azure Cosmos DB 中关闭自动索引，Azure AI 搜索会返回成功状态，但无法索引容器内容。 有关如何查看设置和启用索引功能的说明，请参阅管理 Azure Cosmos DB 中的索引编制。

数据源和索引之间的文档计数差异

索引器显示的文档计数可能与数据源、索引本身或您的代码中的计数不同。 下面是发生此行为的一些可能原因：

• 索引在显示实际文档计数时可能会出现滞后，尤其是在 Azure 门户中。
• 索引器有已删除文档策略。 如果文档在删除之前已编制索引，则索引器将计数已删除的文档。
• 如果数据源中的 ID 列不唯一。 此条件适用于具有列概念的数据源，例如Azure Cosmos DB。
• 如果数据源定义的查询与您用于估算记录数的查询不同。 例如，在数据库中，你正在查询数据库记录计数，而在数据源定义查询中，你可能只选择要编制索引的记录子集。
• 管道中的各个组件（数据源、索引器和索引）的计数会以不同的时间间隔进行检查。
• 数据源有一个映射到多个文档的文件。 在编制 blob 索引时，并且“parsingMode”设置为jsonArray和jsonLines时，这种情况可能会出现。

经过多次处理的文档

索引器使用保守的缓冲策略，确保在编制索引期间，数据源中的每个新的和更改的文档都会被取用。 在某些情况下，这些缓冲区可能会重叠，导致索引器对同一文档建立两次或更多次索引。 因此，已处理的文档计数大于数据源中实际文档数。 此行为不会影响索引中存储的数据（例如复制文档），只有可能需要更长的时间才能达到最终一致性。 如果满足以下任一条件，则这种情况会尤其普遍：

• 按需索引器请求会在短时间内连续发出。
• 数据源的拓扑包括多个副本和分区（ 此处讨论了一个此类示例）。
• 数据源是 Azure SQL 数据库，选为“高水印”的列的类型为 datetime2。

索引器不是用来连续多次调用的。 如果需要快速更新，则支持的方法是将更新推送到索引，同时更新数据源。 对于按需处理，请将请求间隔控制在五分钟或更长时间，并定期运行索引器。

包含 30 秒缓冲区的重复文档处理的示例

以下时间线说明了文档处理两次的条件。 它会记录下每一个动作及其反制动作。 以下时间线揭示了该问题：

实际上，仅当在特定数据源的几分钟内手动调用按需索引器时，才会发生这种情况。 这可能会导致数字不匹配（例如索引器根据索引器执行统计信息共处理了 345 个文档，但是数据源和索引中有 340 个文档），或者如果多次为同一文档运行相同的技能，则可能会增加计费。 建议使用计划来运行索引器。

并行索引

当多个索引器同时运行时，某些索引器通常会输入队列并等待可用资源，然后再启动。 多个因素决定了可并发运行的索引器数。 如果索引器未链接到 技能集，则 AI 搜索服务中的 副本和分区 数决定了可以并行运行的索引器数。

如果将索引器与技能集相关联，它将在 AI 搜索内部群集中运行。 技能组的复杂性以及其他技能集是否同时运行确定可并发运行的索引器数。 内置索引器可靠地从源中提取数据，因此，如果数据按计划运行，则不会错过任何数据。 但是，索引器处理并行化和横向扩展需要一些时间才能完成。

使用敏感度标签为文档编制索引

如果你对文档设置了敏感度标签，可能无法为其编制索引。 如果遇到错误，请删除索引前的标签。

相关内容

• 排查常见索引器错误和警告问题
• 监视基于索引器的索引过程
• 为大型数据集编制索引