Azure AI 搜索中的增量扩充和缓存
重要
此功能根据补充使用条款处于公开预览状态。 预览版 REST API 支持此功能。
增量扩充是指在执行技能组期间使用缓存的扩充，以便仅新的和已更改的技能与文档引发 AI 处理。 缓存包含文档破解输出，以及针对每个文档使用每个技能后的输出。 尽管缓存是计费的（它使用 Azure 存储），但由于存储成本低于图像提取和 AI 处理，因此，扩充的总体成本得已降低。
启用缓存时，索引器会评估更新，以确定是否可以从缓存中拉取现有扩充。 从文档破解阶段获得的图像和文本内容以及上游技能输出或与编辑内容不相关的技能输出，都可能可重复使用。
技能集处理完成后，刷新的结果将写回到缓存，还会写回到搜索索引或知识存储。
缓存配置
在物理上，缓存存储在 Azure 存储帐户中的 Blob 容器内，每个索引器对应一个缓存。 每个索引器会分配有唯一不可变的缓存标识符，这个标识符对应它所用的容器。
在指定“cache”属性并运行索引器时，会创建缓存。 仅缓存扩充的内容。 如果索引器没有附加的技能组，则缓存不适用。
以下示例演示了一个已启用缓存的索引器。 有关完整说明，请参阅启用扩充缓存。
若要使用缓存属性，可以在创建或更新索引器时使用 2020-06-30-preview 或更高版本。 建议使用最新的预览版 API。
POST https://[search service name].search.azure.cn/indexers?api-version=2024-05-01-rreview
{
"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。 在大多数情况下，将 enableReprocessing 设置为 true 可确保所有新文档和现有文档在当前技能组定义下有效。
绕过技能集评估
修改技能和重新处理该技能通常是一起进行的。 但是，对技能进行的一些更改不应导致重新处理（例如，将自定义技能部署到新位置，或使用新的访问密钥）。 这些外围修改很可能不会对技能输出本身的实质造成真正影响。
如果你知道对技能的更改确实是表面性的，应该通过将 disableCacheReprocessingChangeDetection 参数设置为 true 来重写技能评估：
- 调用更新技能组并修改技能组定义。
- 将“disableCacheReprocessingChangeDetection=true”参数追加到请求中。
- 提交更改。
设置此参数可以确保仅提交对该技能组定义的更新，而不会评估更改对现有缓存的影响。 使用 API 预览版 2020-06-30-Preview 或更高版本。 建议使用最新的预览版 API。
PUT https://[servicename].search.azure.cn/skillsets/[skillset name]?api-version=2024-05-01-preview&disableCacheReprocessingChangeDetection
绕过数据源验证检查
对数据源定义进行的大部分更改都会使缓存失效。 但是，如果你知道某项更改不会使缓存失效 - 例如，在存储帐户中更改连接字符串或轮换密钥 - 请在数据源更新中追加 ignoreResetRequirement 参数。 将此参数设置为 true 可让提交操作继续，而不会触发重置条件，导致重新生成并从头开始填充所有对象。
PUT https://[search service].search.azure.cn/datasources/[data source name]?api-version=2024-05-01-preview&ignoreResetRequirement
强制技能集评估
缓存的目的是避免不必要的处理，但假设你要对索引器不会检测的技能进行更改（例如，在外部代码中更改某项内容，如自定义技能）。
在这种情况下，可以使用重置技能来强制重新处理特定的技能，包括依赖于该技能的输出的任何下游技能。 此 API 接受 POST 请求以及应该失效且标记为重新处理的技能列表。 重置技能后，请求运行索引器来调用管道处理。
重新缓存特定文档
重置索引器将导致重新处理搜索语料库中的所有文档。
在只需要重新处理几个文档的情况下，请使用重置文档（预览版）强制执行对特定文档的重新处理。 重置文档时，索引器将使该文档的缓存失效，并通过从数据源中读取它来重新处理文档。 有关详细信息，请参阅运行或重置索引器、技能和文档。
若要重置特定文档，请求会提供从搜索索引中读取的文档键列表。 如果将键映射到外部数据源中的字段，则提供的值应为搜索索引中使用的值。
根据调用 API 的方式，请求将追加、覆盖键列表或对其排队：
结合不同的键多次调用 API 会将新键追加到文档键重置列表。
如果调用 API 并将“overwrite”查询字符串参数设置为 true，则会覆盖要使用请求有效负载重置的文档键的当前列表。
调用 API 只会导致将文档键添加到索引器执行的工作队列中。 下一次调用索引器时，无论是按计划还是按需调用，它都将优先处理重置文档键，然后再处理数据源中的任何其他更改。
以下示例演示重置文档请求：
POST https://[search service name].search.azure.cn/indexers/[indexer name]/resetdocs?api-version=2024-05-01-preview
{
"documentKeys" : [
"key1",
"key2",
"key3"
]
}
使缓存失效的更改
启用缓存后，索引器将评估管道组合中的更改，以确定可以重复使用的内容以及需要重新处理的内容。 本部分先后列举了会使缓存彻底失效的更改，以及会触发增量处理的更改。
使更改失效意味着整个缓存不再有效。 例如，在更新数据源时就存在使更改失效的情况。 下面是使缓存失效的对索引器管道任何部分的更改的完整列表：
- 更改数据源类型
- 更改数据源容器
- 更改数据源凭据
- 更改数据源更改检测策略
- 更改数据源删除检测策略
- 更改索引器字段映射
- 更改索引器参数：
- 分析模式
- 排除的文件扩展名
- 已编制索引的文件扩展名
- 仅为超大文档的存储元数据编制索引
- 分隔的文本标题
- 分隔的文本分隔符
- 文档根
- 图像操作（对图像提取方式的更改）
触发增量处理的更改
增量处理将评估技能集定义，确定要重新运行的技能，并选择性地更新文档树的受影响部分。 下面是导致增量扩充的更改的完整列表：
- 更改技能类型（更新技能的 OData 类型）
- 更新特定于技能的参数，例如 URL、默认值或其他参数
- 技能输出更改，技能返回其他输出或不同的输出
- 技能输入更改导致产生不同宗系，技能链发生更改
- 如果为任何上游技能提供输入的技能已更新，则此上游技能将会失效
- 更新知识存储投影位置导致重新投影文档
- 更改知识存储投影导致重新投影文档
- 更改索引器结果中的输出字段映射导致将文档重新投影到索引
用于缓存的 API
REST API 版本 2020-06-30-Preview 或更高版本通过索引器上的额外属性提供增量扩充。 建议使用最新的预览版 API。
技能组和数据源可以使用正式版。 除参考文档以外，另请参阅为增量扩充配置缓存来详细了解操作顺序。
创建或更新技能组 (api-version=2024-07-01)（请求上的新 URI 参数）
创建或更新数据源 (api-version=2024-07-01)，使用 API 预览版调用时，会提供名为“ignoreResetRequirement”的新参数，当更新操作不应使缓存失效时，应将该参数的值设置为 true。 请尽量少用“ignoreResetRequirement”，因为它可能会导致意外的数据不一致性，而这种不一致性不容易检测到。
后续步骤
增量扩充是非常强大的功能，可将更改跟踪扩展到技能集和 AI 扩充。 当你迭代技能集设计时，增量扩充可让你重复使用现有的已处理内容。 下一步，在索引器上启用缓存。