运行或重置索引器、技能或文档

项目
10/21/2024

在 Azure AI 搜索中，可通过多种方式运行索引器：

在创建索引器时立即运行，假定它不是在“禁用”模式下创建的。
按计划运行以便按固定间隔调用执行。
按需运行（使用或不使用“重置”）。

本文介绍如何在有和没有重置的情况下按需运行索引器。它还描述了索引器执行、持续时间和并发。

索引器如何连接到 Azure 资源

索引器是少数几个公开向其他 Azure 资源进行出站调用的子系统之一。就 Azure 角色而言，索引器没有单独的标识：从搜索引擎到另一个 Azure 资源的连接是使用搜索服务的系统或用户分配的托管标识建立的。如果索引器连接到虚拟网络上的 Azure 资源，则你应为该连接创建共享专用链接。有关安全连接的详细信息，请参阅 Azure AI 搜索中的安全性。

索引器执行

搜索服务为每个搜索单元运行一个索引器作业。每个搜索服务都以一个搜索单位开头，但每个新分区或副本都会增加服务的搜索单位。可以在“概述”页的门户的“基本”部分中查看搜索单位计数。如果需要并发处理，请确保具有足够的副本。索引器不会在后台运行，因此，如果服务承受较大压力，则可能会检测到比平常多的查询限制。

以下屏幕截图显示了搜索单位数，它确定可以一次运行多少个索引器。

索引器开始执行后，无法暂停或停止它。当没有更多文档可加载或刷新时，或者当达到最长运行时间限制时，索引器执行将停止。

可在假定容量充足的情况下一次运行多个索引器，但每个索引器本身就是一个实例。在索引器已在执行时启动新实例会生成以下错误："Failed to run indexer "<indexer name>" error: "Another indexer invocation is currently in progress; concurrent invocations are not allowed."

索引器作业在托管的执行环境中运行。目前有两个环境。你无法控制或配置要使用的环境。 Azure AI 搜索会根据作业组成以及服务将索引器作业移动到内容处理器的能力（某些安全功能会阻止多租户环境）来确定环境。

索引器执行环境包括：

在特定于搜索服务的内容处理器上运行的专用执行环境。
具有内容处理器的多租户环境，由 Azure 管理和保护，无额外费用。此环境用于卸载计算密集型处理，使服务特定的资源可用于日常操作。尽可能在多租户环境中执行大多数索引器作业。

索引器限制因环境而异：

工作负荷	最大持续时间	最大作业数	执行环境
专用执行	24 小时	每个搜索单元一个索引器作业 ¹。	编制索引不在后台运行。相反，搜索服务会根据正在进行的查询和对象管理操作（例如创建或更新索引）来平衡所有索引作业。运行索引器时，如果索引量很大，应该会出现一定的查询延迟。
多租户	2 小时 ²	不确定 ³	由于内容处理群集是多租户的，因此会添加内容处理器来满足需求。如果在按需或计划执行中遇到延迟，则可能是因为系统正在添加处理器或等待处理器变为可用。

¹ 搜索单位可以是分区和副本的灵活组合，但索引器作业并不相互关联。换言之，如果你有 12 个单位，则无论搜索单位如何部署，你都可以在专用执行中并发运行 12 个索引器作业。

² 如果处理所有数据需要两个小时以上，请启用更改检测并将索引器计划为每隔两小时运行。有关更多策略，请参阅为大型数据集编制索引。

³“不确定”表示限制不是由作业数目量化的。某些工作负荷（如技能组处理）可以并行运行，这可能会导致出现许多作业，即使只涉及一个索引器。尽管环境不施加约束，但搜索服务的索引器限制仍然适用。

无需重置即可运行

运行索引器操作只检测并处理将搜索索引与基础数据源中的更改同步所需的内容。增量索引首先定位内部高使用标记，找到上次更新的搜索文档，该文档将成为索引器对数据源中的新文档和更新文档执行索引的起点。

更改检测对于确定数据源中的新增功能或更新的功能至关重要。索引器使用基础数据源的更改检测功能来确定数据源中的新内容或已更新的内容。

Azure 存储通过其 LastModified 属性提供内置更改检测。
必须先为其他数据源（如 Azure SQL 或 Azure Cosmos DB）配置更改检测，然后索引器才能读取新行和更新行。

如果基础内容未更改，则运行操作不起作用。在这种情况下，索引器执行历史记录将指示已处理 0\0 个文档。

需要按下一部分所述重置索引器才能完整地进行重新处理。

重置索引器

在初次运行后，索引器将通过内部的“高水位线”跟踪已编制索引的搜索文档。标记永远不会公开，但索引器在内部知道它上次停止的位置。

如果需要重新生成全部或部分索引，可以通过重置清除索引器的高使用标记。重置 API 可以在对象层次结构中按递减级别提供：

重置索引器清除高使用标记并对所有文档执行完整重新索引
重置文档（预览版）重新索引特定文档或文档列表
重置技能（预览版）为特定技能调用技能处理

重置后，使用 Run 命令重新处理新文档和现有文档。无法通过重置/运行操作删除数据源中没有对应搜索文档的孤立搜索文档。如果需要删除文档，请参阅“文档 - 索引”。

如何重置并运行索引器

重置会清除高使用标记。搜索索引中的所有文档都会标记为完全覆盖，而不会内联更新或合并到现有内容中。对于具有技能组和扩充缓存的索引器，重置索引还会隐式重置技能组。

重置后执行 Run 命令时，会发生以下实际操作：

在基础源中找到的所有新文档会添加到搜索索引中。
在搜索索引中覆盖同时存在于数据源和搜索索引的所有文档。
重新生成通过技能组创建的任何扩充内容。刷新扩充缓存（如果已启用）。

如前所述，重置是一种被动操作：必须接着发出 Run 请求才能重新生成索引。

如果重置显式或隐式包含技能，则重置/运行操作适用于搜索索引或知识库、特定文档或投影以及缓存的扩充项。

重置也适用于创建和更新操作。它不会对搜索索引中的孤立文档触发删除或清理。有关删除文档的详细信息，请参阅“文档 - 索引”。

重置索引器后，无法撤消此操作。

登录到 Azure 门户，然后打开搜索服务页面。
在“概述”页上，选择“索引”选项卡。
选择索引器。
选择“重置”命令，然后选择“是”确认该操作。
刷新页面以显示状态。你可以选择该项以查看其详细信息。
选择“运行”开始索引器处理，或等待下一个计划的执行。

下面的示例演示重置索引器和运行索引器 REST 调用。使用获取索引器状态检查结果。

任何这些调用都没有参数或属性。

POST /indexers/[indexer name]/reset?api-version=[api-version]

POST /indexers/[indexer name]/run?api-version=[api-version]

GET /indexers/[indexer name]/status?api-version=[api-version]

下面的示例（来自 azure-search-dotnet-samples/multiple-data-sources/）演示了 Azure .NET SDK 中的 ResetIndexers 和 RunIndexers 方法。

// Reset the indexer if it already exists
try
{
    await indexerClient.GetIndexerAsync(blobIndexer.Name);
    //Rest the indexer if it exsits.
    await indexerClient.ResetIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 404) { }

await indexerClient.CreateOrUpdateIndexerAsync(blobIndexer);

// Run indexer
Console.WriteLine("Running Blob Storage indexer...\n");

try
{
    await indexerClient.RunIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
    Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

如何重置技能（预览）

对于具有技能组的索引器，可以重置单项技能以强制处理该技能以及依赖其输出的任何下游技能。扩充缓存（如果已启用）也会刷新。

重置技能当前仅限 REST，可通过 2020-06-30-preview 或更高版本获得。建议使用最新的预览版 API。

POST /skillsets/[skillset name]/resetskills?api-version=2024-05-01-preview
{
    "skillNames" : [
        "#1",
        "#5",
        "#6"
    ]
}

可按以上示例中所示指定单个技能，但如果其中任一技能需要未列出的技能（#2 到 #4）的输出，则除非缓存可以提供必要的信息，否则未列出的技能将会运行。若要做到这一点，技能 #2 到 #4 的已缓存扩充不得依赖于 #1（列为要重置的技能）。

如果未指定任何技能，则执行整个技能组；如果已启用缓存，则还会刷新缓存。

记住接着使用“运行索引器”来调用实际处理。

如何重置文档（预览版）

索引器 - 重置文档接受文档键列表，因此你可以刷新特定的文档。如果已指定重置参数，这些参数将成为要处理哪些内容的唯一决定因素，而不管基础数据发生了其他哪些更改。例如，如果自上次索引器运行以来添加或更新了 20 个 Blob，但你只重置了一个文档，则只会处理该文档。

对于每个文档，将使用数据源中的值刷新该搜索文档中的所有字段。无法选取要刷新的字段。

如果文档已通过技能组扩充并包含缓存的数据，则只会对指定的文档调用该技能组，并为已重新处理的文档更新缓存。

首次测试此 API 时，以下 API 可帮助你验证并测试行为。你可以使用 API 预览版 2020-06-30-preview 及更高版本。建议使用最新的预览版 API。

使用预览 API 版本调用“索引器 - 获取状态”，以检查重置状态和执行状态。可以在状态响应的末尾找到有关重置请求的信息。
使用预览 API 版本调用“索引器 - 重置文档”，以指定要处理的文档。
```
POST https://[service name].search.azure.cn/indexers/[indexer name]/resetdocs?api-version=2024-05-01-preview
{
    "documentKeys" : [
        "1001",
        "4452"
    ]
}
```
- 请求中提供的文档键是搜索索引中的值，这些值可能不同于数据源中的相应字段。如果你不确定键值，请发送查询以返回值。可以使用 select 来仅返回文档键字段。
- 对于分析为多个搜索文档的 blob（例如 parsingMode 设置为 jsonLines 或 jsonArrays 或 delimitedText），则文档键是由索引器生成的，你可能不知道该键。在此情况下，查询文档键以返回正确的值。
调用运行索引器（任何 API 版本）来处理指定文档。仅为这些特定文档编制索引。
再次调用运行索引器以从上一个高使用标记开始处理。
调用搜索文档，用于检查已更新的值，如果你不确定值，此 API 还会返回文档键。如果你要限制在响应中显示的字段，请使用 "select": "<field names>"。

覆盖文档键列表

结合不同的键多次调用重置文档 API 会将新键追加到文档键重置列表。如果调用 API 并将 overwrite 参数设置为 true，则会用新的列表覆盖当前列表：

POST https://[service name].search.azure.cn/indexers/[indexer name]/resetdocs?api-version=2020-06-30-Preview
{
    "documentKeys" : [
        "200",
        "630"
    ],
    "overwrite": true
}

检查重置状态“currentState”

若要检查重置状态并查看哪些文档键已排队等待处理，请执行以下步骤。

使用预览 API 调用“获取索引器状态”。

预览版 API 将返回 currentState 部分，该部分位于响应的末尾。

"currentState": {
    "mode": "indexingResetDocs",
    "allDocsInitialTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
    "allDocsFinalTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
    "resetDocsInitialTrackingState": null,
    "resetDocsFinalTrackingState": null,
    "resetDocumentKeys": [
        "200",
        "630"
    ]
}

查看“模式”：

对于“重置技能”，“模式”应设置为 indexingAllDocs（因为通过 AI 扩充填充的字段所在的所有文档都可能会受影响）。

对于“重置文档”，“模式”应设置为 indexingResetDocs。索引器会将此状态保持到已处理重置文档调用中提供的所有文档键，在这段时间，在该操作正在进行时不会执行任何其他索引器作业。在文档键列表中查找所有文档需要破解每个文档，以查找键并根据该键进行匹配，如果数据集较大，这可能需要一段时间。如果 Blob 容器包含数百个 Blob，而你想要重置的文档放在最后，则索引器只有在事先检查了所有其他 Blob 之后，才能找到匹配的 Blob。
重新处理文档后，再次运行“获取索引器状态”。索引器将恢复 indexingAllDocs 模式，并且在下次运行时，将处理任何新文档或已更新的文档。

后续步骤

重置 API 用于告知下次索引器运行的范围。在实际处理中，你需要调用按需索引器运行，或者允许计划的作业完成工作。运行完成后，索引器将恢复正常处理，不管是按计划的处理还是按需处理。

重置并重新运行索引器作业后，可以从搜索服务监视状态，或者通过资源日志记录获取详细信息。

通过