你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

管理扩充缓存（预览版）

注释

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。 它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

重要

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

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

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

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

先决条件

限制

谨慎

如果使用SharePoint索引器（预览版），请避免增量扩充。 在某些情况下，缓存将失效。 若要重新加载，请执行索引器重置和完全重建。

大型数据源具有额外的缓存限制。

谨慎

对于大型数据源，当发生长时间运行的技能、重复中断或频繁的技能失败时，扩充缓存可能会增加总再处理量。 索引器将正确性优先于最小化重新处理，因此缓存积压工作会放大重试行为。

若要从不断增长的缓存积压工作中恢复，请将数据源分区为较小的容器或虚拟文件夹。 然后使用指向同一索引的 并行索引器 。 若要取消关联缓存，请将 cache 索引器的属性设置为 null。

缓存配置

在物理上，缓存存储在 Azure 存储帐户中的 Blob 容器和表格内，每个索引器对应一个缓存。 为每个索引器分配一个唯一且不可变的缓存标识符，该标识符对应于所使用的容器。

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

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

POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2026-08-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.windows.net/skillsets/[skillset name]?api-version=2026-08-01-preview&disableCacheReprocessingChangeDetection

绕过数据源验证检查

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

PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2026-08-01-preview&ignoreResetRequirement

强制技能集评估

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

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

重新缓存特定文档

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

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

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

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

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

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

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

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

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

使缓存失效的更改

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

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

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

触发增量处理的更改

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

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

用于缓存的 API

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

技能集和数据源应使用正式发布版本。 除了参考文档，请参阅 配置用于增量扩充的缓存 ，了解有关操作顺序的详细信息。

  • Last updated on