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

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

最佳做法

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

索引器旨在按计划运行

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

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

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

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

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

在专用连接上连接到 Microsoft Foundry 资源时出错

如果出现错误代码 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 Foundry 资源配置了共享专用链接，并且终结点缺少自定义子域，则会发生此错误。 自定义子域是终结点的第一部分（例如，http://my-custom-subdomain.services.ai.azure.com）。 如果在 Foundry 门户中而不是 Azure 门户创建了资源，则自定义域可能缺失。

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

使用共享专用链接时出错

如果出现错误代码 403 并显示以下消息，则索引器可能是通过公共终结点而不是已获批准的共享专用链接进行连接：

Unexpected error validating provided resource. {"error":{"code":"403","message":"Public access is disabled. Please configure private endpoint."}}

如果未将索引器配置为使用专用执行环境，则可能会出现此错误。 确认共享专用链接已获批准，将索引器的 executionEnvironment 设置为 private，并验证连接是否使用了正确的资源终结点和 组 ID。

防火墙规则

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 时，网络安全组将确定是否允许请求传入。

对于驻留在虚拟网络上的外部资源，请为 服务标记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.windows.net。 可以在 Azure 门户中找到 FQDN。

   

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

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

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

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

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

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

   

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

       {
         "name": "AzureCognitiveSearch.WestCentralUS",
         "id": "AzureCognitiveSearch.WestCentralUS",
         "properties": {
           "changeNumber": 1,
           "region": "westcentralus",
           "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.windows.net/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.windows.net/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 Cosmos DB一致性级别中所述的拓扑。
• 数据源为 Azure SQL 数据库，选作“高水位标记”的列类型为 datetime2。

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

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

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

在实践中，此场景仅在你针对特定数据源在数分钟内手动调用按需索引器时出现。 这在对同一文档多次运行相同技能后可能会导致数字不匹配（例如，索引器执行统计信息显示索引器总共处理了 345 个文档，但数据源和索引中显示有 340 个文档）或可能会增加计费。 建议使用计划来运行索引器。

并行索引

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

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

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

如果在 文档上设置敏感度标签，则可能无法为它们编制索引。 如果出现错误，请先删除这些标签，然后再建立索引。

相关内容

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