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

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

最佳做法

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

索引器旨在按计划运行

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

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

• 内置索引器被设计为能够随着时间的推移处理所有文档，如果当前运行未能处理，则在后续的计划运行中会继续尝试，以避免出现永久性错误。 它们提供了一种方便、低/无代码的方式来为常见方案编制数据索引，从而实现更快的开发和简化维护。 但是，如果它们具有 AI 扩充功能，则它们不会针对非常大的工作负荷进行优化。 有关如何处理大型数据集的指导，请参阅 如何为大型数据集编制索引。
• 如果解决方案需要严格控制索引时间线，请改用推送 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

有 2 个选项可让索引器访问此类实例中的这些资源：

• 为搜索服务的 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 地址范围。

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

   对于本练习，假定搜索服务是 Azure 公有云，应下载 Azure 公共 JSON 文件。

   

   在 JSON 文件中，假定搜索服务位于中国北部，多租户索引器执行环境的 IP 地址列表如下。

       {
         "name": "AzureCognitiveSearch.chinanorth",
         "id": "AzureCognitiveSearch.chinanorth",
         "properties": {
           "changeNumber": 1,
           "region": "chinaeast",
           "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=2025-09-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=2025-09-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

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

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

以下时间线说明了文档在何种条件下会被处理两次，并标出了每个操作及对应反应操作。 以下时间线揭示了该问题：

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

并行索引

当多个索引器同时运行时，一些索引器通常会进入队列，等待可用资源开始执行。 可并发运行的索引器数量取决于多个因素。 如果索引器未与技能集关联，则并行运行的能力依赖于在 AI 搜索服务中设置的副本和分区数。

另一方面，如果索引器与某个技能组关联，它会在 AI 搜索的内部群集中运行。 在这种情况下，并发运行的能力取决于技能组的复杂性以及是否有其他技能组同时运行。 内置索引器旨在从源中可靠地提取数据，因此，如果按计划运行，则不会错过任何数据。 但是，预计并行化和横向扩展的索引器进程需要一些时间才能完成。

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

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

另请参阅

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