管理扩充缓存

注释

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

重要

根据补充使用条款，此功能为公共预览版。 预览版 REST API 支持此功能。

扩充缓存是一项可选功能，用于存储技能集执行期间创建的扩充内容。 它会在多次运行之间保留内容，因此只需重新处理已更改的技能和文档。 它不是技能集输出、索引器状态或索引文档的备份。

在 Azure 存储 中创建扩充缓存。 缓存包含文档破解输出，以及针对每个文档使用每个技能后的输出。 尽管缓存是计费的（它使用 Azure 存储），但由于存储成本低于图像提取和 AI 处理，因此，扩充的总体成本得已降低。

如果配置扩充缓存，本文介绍如何管理技能更新和数据源更新，以便从缓存扩充中获得最大实用工具。

先决条件

局限性

注意

如果使用 SharePoint Online 索引器，应避免增量扩充。 在某些情况下，如果选择重新加载索引器，缓存将变为无效，需要 索引器重置和完全重新生成。

缓存配置

在物理上，缓存存储在 Azure 存储帐户中的 Blob 容器和表中，每个索引器对应一个。 每个索引器会分配有唯一不可变的缓存标识符，这个标识符对应它所用的容器。

指定 cache 属性并运行索引器时，将创建缓存。 仅缓存扩充的内容。 如果索引器没有附加的技能组，则缓存不适用。

以下示例演示了一个已启用缓存的索引器。 有关完整说明，请参阅 配置扩充缓存 。

POST https://[YOUR-SEARCH-SERVICE-NAME].search.azure.cn/indexers?api-version=2026-05-01-preview
    {
        "name": "myIndexerName",
        "targetIndexName": "myIndex",
        "dataSourceName": "myDatasource",
        "skillsetName": "mySkillset",
        "cache" : {
            "storageConnectionString" : "<Your storage account connection string>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

缓存管理

索引器管理缓存生命周期。 如果删除索引器，则还会删除其缓存。 如果将索引器cache的属性设置为 null 或更改连接字符串，则会在下一个索引器运行期间删除现有缓存。

虽然增量扩充旨在检测和响应更改，但无需干预即可，但你可以设置参数以调用特定行为：

指定新文档的优先级

该 cache 属性包含一个 enableReprocessing 参数，用于控制是否重新处理缓存的内容。 如果该值为 true（默认值），则在重新运行索引器时，如果技能更新影响到这些文档，索引器会重新处理缓存的文档。

如果该值为 false，索引器不会重新处理现有文档，从而优先处理新内容。 将enableReprocessing仅暂时设置为 false。 在大多数情况下，保持其真实可确保新文档和现有文档对当前技能集定义保持有效。

绕过技能集评估

修改技能通常与重新处理该技能并手。 但是，对技能的一些更改不应触发重新处理。 例如，将自定义技能部署到新位置或使用新的访问密钥。 这些更改通常是外围修改，不会影响技能输出的实质内容。

如果知道对技能的更改是表面的，请将 disableCacheReprocessingChangeDetection 参数设置为 true 来替代技能评估：

  1. 调用更新技能组并修改技能组定义。
  2. 在 disableCacheReprocessingChangeDetection=true 请求上追加参数。
  3. 提交更改。

设置该参数后，仅会提交对技能集定义的更新。 未评估该更改对现有缓存的影响。 使用 API 预览版 2020-06-30-Preview 或更高版本。 使用最新的预览 API。

PUT https://[servicename].search.azure.cn/skillsets/[skillset name]?api-version=2026-05-01-preview&disableCacheReprocessingChangeDetection

绕过数据源验证检查

对数据源定义的大多数更改使缓存失效。 但是，如果你知道某项更改不会使缓存失效 - 例如，在存储帐户中更改连接字符串或轮换密钥 - 请在ignoreResetRequirement中追加 参数。 将此参数设置为 true 以允许提交完成，而不触发重置条件，导致从头开始重新生成和填充所有对象。

PUT https://[search service].search.azure.cn/datasources/[data source name]?api-version=2026-05-01-preview&ignoreResetRequirement

强制技能集评估

缓存的目的是避免不必要的处理。 但是，假设你对索引器未检测到的技能进行更改（例如，更改外部代码中的内容，如自定义技能）。

在这种情况下，请使用 重置技能 API 强制重新处理特定技能，包括依赖于该技能输出的任何下游技能。 此 API 接受 POST 请求以及应该失效且标记为重新处理的技能列表。 重置技能后，请求运行索引器来调用管道处理。

重新缓存特定文档

如果 重置索引器，则重新处理搜索库中的所有文档。

如果只有少数文档需要重新处理，请使用 重置文档（预览版） 强制重新处理特定文档。 重置文档时，索引器会使该文档的缓存失效。 然后，索引器通过从数据源读取文档来重新处理文档。 有关详细信息，请参阅运行或重置索引器、技能和文档。

若要重置特定文档，请在请求中包含从搜索索引读取的文档键列表。 如果键映射到外部数据源中的字段，请使用搜索索引中的值。

根据调用 API 的方式，请求会追加、覆盖或排队密钥列表：

  • 使用不同键多次调用 API 会将新密钥追加到要重置的文档密钥列表中。

  • 将查询字符串参数 overwrite 设置为 true 来调用 API 时，会使用请求负载覆盖当前要重置的文档键列表。

  • 调用 API 会将文档键添加到索引器执行的工作队列。 下次调用索引器（按计划或按需）时，它会优先处理重置文档键，然后再处理来自数据源的任何其他更改。

以下示例演示重置文档请求：

POST https://[search service name].search.azure.cn/indexers/[indexer name]/resetdocs?api-version=2026-05-01-preview
    {
        "documentKeys" : [
            "key1",
            "key2",
            "key3"
        ]
    }

使缓存失效的更改

启用缓存时，索引器会检查管道组合中的更改，以确定它可以重用哪些内容，以及哪些内容需要重新处理。 本部分列出了使缓存失效的更改，后跟触发增量处理的更改。

使整个缓存失效的更改称为失效性更改。 例如，更新数据源是一项无效更改。 下面是索引器管道的任何部分更改的完整列表，这些更改使缓存失效：

  • 更改数据源类型
  • 更改数据源容器
  • 更改数据源凭据
  • 更改数据源更改检测策略
  • 更改数据源删除检测策略
  • 更改索引器字段映射
  • 更改索引器参数：
    • 分析模式
    • 排除的文件扩展名
    • 已编制索引的文件扩展名
    • 仅为超大文档的存储元数据编制索引
    • 分隔的文本标题
    • 分隔的文本分隔符
    • 文档根
    • 图像操作（对图像提取方式的更改）

触发增量处理的更改

增量处理会评估你的技能集定义，并确定需要重新运行哪些技能。 它会有选择地更新文档树的受影响部分。 下面是导致增量扩充的更改的完整列表：

  • 更改技能类型（更新该技能的 OData 类型）
  • 更新特定于技能的参数，例如 URL、默认值或其他参数
  • 更改技能输出，例如技能返回其他或不同的输出时
  • 更改导致不同祖先或技能链接的技能输入
  • 如果你更新了向此技能提供输入的技能，则任何上游技能都会失效
  • 更新知识存储投影位置，这会导致重新投影文档
  • 更改知识存储投影，这会导致重新投影文档
  • 更改索引器的输出字段映射，这会导致将文档重新投影到索引

用于缓存的 API

预览 API 为索引器提供额外的属性。 使用最新的预览 API。

技能集和数据源应使用正式发布版本。 除参考文档以外，另请参阅为增量扩充配置缓存来详细了解操作顺序。

  • Last updated on