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

  • 项目

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

注意

如果有 Azure AI 搜索错误要调查，请改为参阅排查常见索引器错误和警告。

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

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

防火墙规则

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 地址范围限制的详细信息：

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

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

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

网络安全组 (NSG) 规则

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

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

有关连接到虚拟机的详细信息，请参阅配置与 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。

    Obtain service 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 文件。

    Download JSON file

    在 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=2023-11-01
Content-Type: application/json
api-key: [admin key]

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

缺少文档

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

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

提示

如果文档丢失，请检查正在使用的查询，确保其中未排除相关文档。 若要查询特定文档，请使用查找文档 REST API。

Blob 存储中缺少内容

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

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

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

PUT https://[service name].search.azure.cn/indexers/[indexer name]?api-version=2020-06-30
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 中的索引编制。

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

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

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

经过多次处理的文档

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

  • 按需索引器请求会快速连续发出
  • 数据源的拓扑包括多个副本和分区（此处探讨了其中一个示例）
  • 数据源是 Azure SQL 数据库，选择为“高水印线”的列的类型为 datetime2

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

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

下面以时间线的形式说明了文档经过两次处理的情况，时间线上标注了每个操作以及计数器操作。 以下时间线揭示了该问题：

时间线 (hh:mm:ss) 事件 索引器高水位线 评论
00:01:00 按 doc1 最终一致性写入数据源 null 文档时间戳为 00:01:00。
00:01:05 按 doc2 最终一致性写入数据源 null 文档时间戳为 00:01:05。
00:01:10 索引器开始 null
00:01:11 索引器查询 00:01:10 之前的所有更改；索引器查询的副本恰好只能感知 doc2；仅检索到 doc2 null 索引器请求开始时间戳之前的所有更改，但实际上接收到这些更改的子集。 此行为需要有回溯缓冲时段。
00:01:12 索引器第一次处理 doc2 null
00:01:13 索引器结束 00:01:10 高水位线更新为当前索引器执行的开始时间戳。
00:01:20 索引器开始 00:01:10
00:01:21 索引器查询 00:00:40 和 00:01:20 之间的所有更改；索引器查询的副本恰好能同时感知 doc1 和 doc2；检索 doc1 和 doc2 00:01:10 索引器请求“当前高水位线减去 30 秒缓冲”与“当前索引器执行的开始时间戳”之间的所有变化。
00:01:22 索引器第一次处理 doc1 00:01:10
00:01:23 索引器第二次处理 doc2 00:01:10
00:01:24 索引器结束 00:01:20 高水位线更新为当前索引器执行的开始时间戳。
00:01:32 索引器开始 00:01:20
00:01:33 索引器查询 00:00:50 与 00:01:32 之间的所有更改；检索 doc1 和 doc2 00:01:20 索引器请求“当前高水位线减去 30 秒缓冲”与“当前索引器执行的开始时间戳”之间的所有变化。
00:01:34 索引器第二次处理 doc1 00:01:20
00:01:35 索引器第三次处理 doc2 00:01:20
00:01:36 索引器结束 00:01:32 高水位线更新为当前索引器执行的开始时间戳。
00:01:40 索引器开始 00:01:32
00:01:41 索引器查询 00:01:02 和 00:01:40 之间的所有更改；检索 doc2 00:01:32 索引器请求“当前高水位线减去 30 秒缓冲”与“当前索引器执行的开始时间戳”之间的所有变化。
00:01:42 索引器第四次处理 doc2 00:01:32
00:01:43 索引器结束 00:01:40 请注意，此“索引器执行”在上一次写入数据源之后已开始超过 30 秒，并处理了 doc2。 这是预期的行为，因为如果消除了 00:01:35 之前的所有索引器执行，这将成为处理 doc1 和 doc2 的第一个以及唯一一个执行。

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

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

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

另请参阅