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

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。

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

创建索引器时立即运行。除非在禁用状态下创建索引器，否则此选项是默认值。
按计划运行以便按固定间隔调用执行。
按需运行，无需重置。

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

索引器如何连接到Azure资源

索引器是少数明确对其他 Azure 资源进行出站调用的子系统之一。根据所使用的外部数据源，可以使用密钥或角色对连接进行身份验证。

在Azure角色方面，索引器没有单独的标识：从搜索引擎到另一个Azure资源的连接使用搜索服务的系统或用户分配的托管标识，以及目标Azure资源的角色分配。如果索引器连接到虚拟网络上的Azure资源，则应为该连接创建共享的专用链接。

注意

索引器使用服务级别权限而不是用户权限运行。即使您为了限制对特定索引的访问而分配了角色，索引器仍然可以写入搜索服务的任何索引。有关详细信息，请参阅每个索引的范围和索引器操作。

索引器执行

搜索服务为每个搜索单元运行一个索引器作业。每个搜索服务都以一个搜索单位开头，但每个新分区或副本都会增加服务的搜索单位。可以在 Azure 门户的 Overview 页的 Essential 部分检查搜索单位计数。如果需要并发处理，请确保搜索单元包含足够的副本。索引器不会在后台运行，因此，如果服务面临压力，您可能会比平时更频繁地遇到查询速度变慢的情况。

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

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

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

索引器执行环境

索引器作业在托管的执行环境中运行。目前有两个环境：

专用执行环境在特定于搜索服务的搜索群集上运行。
多租户环境包含由 Microsoft 管理和保护的内容处理器，且无需额外付费。此环境会卸载计算密集型处理，因此服务特定的资源仍可用于日常操作。大多数技能组尽可能在多租户环境中执行。此环境为默认值。

“计算密集型处理”是指在内容处理器和索引器作业上运行的用于处理大量文档或大型文档的技能集。启发式方法和系统信息决定了多租户内容处理器上的非技能集相关处理，且不受客户控制。

您可以通过将索引器和技能集处理专门绑定到您的搜索群集，来防止在 Standard2 或更高版本的服务上使用多租户环境。将executionEnvironment索引器定义中的参数设置为始终在专用执行环境中运行索引器。

IP 防火墙会阻止多租户环境，因此，如果有防火墙，请创建允许多租户处理器连接的规则。

索引器限制因环境而异：

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

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

² 如果需要两个多小时来处理所有数据，请启用更改检测并计划索引器以 5 分钟间隔运行，以便在由于超时而停止索引时快速恢复索引。有关更多策略，请参阅为大型数据集编制索引。

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

无需重置即可运行

运行索引器操作仅检测并处理它需要将搜索索引与基础数据源中的更改同步的内容。增量索引首先查找内部高水印来查找上次更新的搜索文档。本文档将成为索引器开始处理数据源中新增和已更新文档的起点。

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

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

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

若要重新处理所有文档，需要重置索引器。

重置索引器

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

若要重建全部或部分索引，请使用对象层次结构中逐级向下各个层级提供的重置 API：

重置索引器清除高水印并执行所有文档的完整重新索引。
重新同步索引器（预览版）对所有文档执行高效的部分重新索引。
重置文档（预览版）重新编制特定文档或文档列表的索引。
重置技能（预览版）调用针对特定技能的技能处理过程。

重置后，使用 Run 命令重新处理新文档和现有文档。无法通过重置并运行来删除那些在数据源中没有对应项的孤立搜索文档。若要删除特定文档，请参阅 “删除搜索索引” 或 “文档 - 索引”中的文档。

注意

表不能为空。如果使用 TRUNCATE TABLE 清除行，索引器的重置和重新运行不会删除相应的搜索文档。若要删除孤立的搜索文档，必须通过删除操作来编制索引。

如何重置并运行索引器

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

当你在重置后执行 "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);
}

如何重置技能（预览）

重置技能请求在下次索引器运行期间有选择地处理一个或多个技能。对于具有技能集的索引器，可以重置单个技能以强制重新处理该技能，以及依赖于其输出的任何下游技能。如果启用了扩充缓存，请求也会刷新它。

对于启用了缓存的索引器，可以显式请求处理索引器无法检测到的技能更新。例如，如果进行外部更改（如自定义技能的修订），请使用此 API 重新运行技能。该过程通过使用缓存中的可重用数据以及根据更新的技能的新内容刷新输出，例如知识存储或搜索索引。

使用最新的预览 API。

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

可以指定单个技能，如前面的示例所示，但如果其中任一技能需要从未列出的技能（#2 到 #4）输出，则进程将运行未列出的技能，除非缓存可以提供必要的信息。为了使该条件成立，技能 #2 到 #4 的缓存增强结果不得依赖于 #1（#1 已被列为要重置的项）。

如果未指定任何技能，该过程将执行整个技能集，如果启用了缓存，也会刷新缓存。

请注意，接下来请运行索引器来调用实际处理。

如何重置文档（预览版）

索引器 - 重置文档（预览版）API 接受文档密钥列表，以便可以刷新特定文档。如果指定重置参数，它们只会确定处理的内容，而不考虑基础数据中的其他更改。例如，如果自上次运行索引器以来已添加或更新了 20 个 blob，但你仅重置一个文档，则索引器仅处理该文档。

基于每个文档，索引器使用数据源中的值和元数据刷新搜索文档中的所有字段。无法选取要刷新的字段。

如果通过技能集丰富文档并且它已缓存数据，索引器将只调用指定文档的技能集，并更新已重新处理的文档的缓存。

首次测试此 API 时，以下 API 可帮助你验证并测试行为。使用最新的预览 API。

使用预览 API 版本调用“索引器 - 获取状态”，以检查重置状态和执行状态。可以在状态响应的末尾找到有关重置请求的信息。
使用预览 API 版本调用“索引器 - 重置文档”，以指定要处理的文档。
```
POST https://[service name].search.azure.cn/indexers/[indexer name]/resetdocs?api-version=2026-05-01-preview
{
    "documentKeys" : [
        "1001",
        "4452"
    ]
}
```
- API 接受两种类型的文档标识符作为输入：用于唯一标识搜索索引中的文档的文档键，以及唯一标识数据源中的文档的数据源文档标识符。正文应包含文档键列表或索引器在数据源中查找的数据源文档标识符列表。调用 API 会添加文档密钥或数据源文档标识符以重置为索引器元数据。在下一次计划或按需运行索引器时，索引器仅处理重置文档。
- 如果使用文档键来重置文档，并且文档密钥在索引器字段映射中被引用，索引器将使用字段映射在基础数据源中找到相应的字段。
- 请求中提供的文档键是搜索索引中的值，与数据源中的相应字段不同。如果你不确定键值，请发送查询以返回值。可以使用 select 来仅返回文档键字段。
- 对于被索引器解析为多个搜索文档的 Blob（其中 parsingMode 设置为 jsonLines 或 jsonArrays，或 delimitedText），索引器会生成文档键，而你可能并不知道该键。在此情况下，查询文档键以返回正确的值。
- 如果希望索引器停止尝试处理重置文档，请设置 "documentKeys" 或 "datasourceDocumentIds" 设置为空列表 []。此操作使索引器基于高水位标记恢复常规索引。将忽略无效的文档键或不存在的文档键。
调用运行索引器（任何 API 版本）来处理指定文档。索引器仅为这些特定文档编制索引。
再次调用运行索引器以从上次的高水位标记开始处理。
调用搜索文档，用于检查已更新的值，如果你不确定值，此 API 还会返回文档键。如果你要限制在响应中显示的字段，请使用 "select": "<field names>"。

覆盖文档密钥列表

如果使用不同键多次调用重置文档 API，则会将新密钥添加到文档密钥重置列表中。如果使用参数设置为 true 调用 API overwrite ，则当前列表将替换为新列表：

POST https://[service name].search.azure.cn/indexers/[indexer name]/resetdocs?api-version=2026-05-01-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,
    "resyncInitialTrackingState": null,
    "resyncFinalTrackingState": null,
    "resetDocumentKeys": [
        "200",
        "630"
    ]
}

查看“模式”：

对于“重置技能”，请将“mode”设置为 indexingAllDocs，因为就 AI 扩充所填充的字段而言，可能所有文档都会受到影响。

对于重新同步索引器，请将“mode”设置为 indexingResync. 索引器检查所有文档，并重点介绍数据源中感兴趣的数据以及目标索引中感兴趣的字段。

对于重置文档，请将“mode”设置为 indexingResetDocs。索引器将保持此状态，直到它处理完 reset documents 调用中提供的所有文档键。在此期间，在操作正在进行时，不会执行其他索引器作业。要在文档键列表中找到所有文档，需要解析每个文档以定位并匹配相应的键。如果数据集很大，此过程可能需要一段时间。如果 Blob 容器包含数百个 blob，并且要重置的文档位于末尾，则在索引器首先检查所有其他 Blob 之前，索引器不会找到匹配的 blob。
索引器重新处理文档后，再次运行“获取索引器状态”。索引器将返回到 indexingAllDocs 模式，并在下次运行时处理任何新的或更新的文档。

检查 S3 HD 搜索服务的索引器运行时配额

适用于标准 3 级高密度（S3 HD）定价层上的搜索服务。

为了帮助你监视相对于 24 小时窗口的索引器运行时间，获取服务统计信息和获取索引器状态现在返回响应中的详细信息。

跟踪累积运行时配额

跟踪搜索服务的累积索引器运行时使用情况，并确定当前 24 小时时段内剩余的运行时配额。

将 GET 请求发送到搜索服务资源提供程序。有关设置 REST 客户端和获取访问令牌的帮助，请参阅 “连接到搜索服务”。

GET {{search-endpoint}}/servicestats?api-version=2026-05-01-preview 
  Content-Type: application/json
  Authorization: Bearer {{accessToken}}

响应包括 indexersRuntime 属性、显示过去 24 小时内的开始时间和结束时间、使用的秒数、剩余的秒数和累积运行时。

跟踪索引器运行时配额

返回单个索引器的相同信息。

GET {{search-endpoint}}/indexers/hotels-sample-indexer/search.status?api-version=2026-05-01-preview 
  Content-Type: application/json
  Authorization: Bearer {{accessToken}}

响应包括一个 runtime 属性，其中显示了开始时间和结束时间、使用的秒数和剩余的秒数。

后续步骤

重置 API 用于告知下次索引器运行的范围。若要执行实际处理，您需要触发一次按需索引器运行，或等待计划作业完成处理。运行完成后，索引器将返回到正常处理，无论是按计划还是按需处理。

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

Last updated on 2026-07-27