在 Azure AI 搜索中为增量扩充启用缓存

项目
04/12/2024

重要

此功能根据补充使用条款处于公开预览状态。预览版 REST API 支持此功能

本文说明了如何将缓存添加到扩充管道，以便能够修改下游扩充步骤，而无需每次更改后都要完全重新生成。默认情况下，技能集是无状态的，更改其任何构成部分都要从头到尾地重新运行索引器。使用扩充缓存时，索引器可以根据技能集或索引器定义中检测到的更改，确定必须刷新文档树的哪些组成部分。现有的已处理输出将会保留，在可能的情况下可供重复使用。

使用提供的帐户信息将缓存的内容放置在 Azure 存储中。在运行索引器时，将创建名为 ms-az-search-indexercache-<alpha-numerc-string> 的容器。应将此容器视为搜索服务管理的内部组件，不得对它进行修改。

先决条件

用于存储缓存扩充的 Azure 存储。存储帐户必须是常规用途 v2。
对于仅 Blob 索引，如果在从数据源中删除 Blob 时需要从缓存和索引中删除已同步的文档，请在索引器中启用删除策略。如果没有此策略，则不支持从缓存中删除文档。

你应该熟悉如何设置索引。从索引器概述开始，然后继续学习技能集来了解扩充管道。有关重要概念的更多背景信息，请参阅增量扩充。

注意

如果使用 SharePoint Online 索引器（预览版），则应避免增量扩充。在某些情况下，缓存会失效，如果要重新加载缓存，则需要重置并运行索引器。

在新索引器上启用

可以使用 Azure 门户、预览 API 或 beta 版 Azure SDK 在索引器上启用扩充缓存。

Azure 门户
REST

在左侧，选择“索引器”，然后选择“添加索引器”。
提供索引器名称和现有索引、数据源和技能集。
启用增量缓存并设置 Azure 存储帐户。

在新索引器上，调用创建或更新索引器 (2021-04-30-Preview) 时，在索引器定义有效负载中添加“cache”属性。还可使用以前的预览 API 版本 2020-06-30-Preview。

POST https://[service name].search.azure.cn/indexers?api-version=2021-04-30-Preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
    "fieldMappings" : [],
    "outputFieldMappings": [],
    "parameters": []
    }

在现有索引器上启用

对于已具有技能集的现有索引器，请使用以下步骤添加缓存。请作为一次性操作来重置并完全重新运行索引器以加载缓存。

步骤 1：获取索引器定义

从包含以下组件的有效工作索引器开始：数据源、技能集和索引。使用 API 客户端，发送 GET Indexer 请求以检索索引器。使用预览版 API 获取索引器时，会自动将一个设置为 null 的“cache”属性添加到定义中。

GET https://[YOUR-SEARCH-SERVICE].search.azure.cn/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

步骤 2：设置缓存属性

在索引定义中，修改“cache”以包含以下必需属性和可选属性：

（必需）必需将 storageConnectionString 设置为 Azure 存储的连接字符串。
（可选）enableReprocessing 布尔属性（默认值为 true），表示启用增量扩充。如果要在其他资源密集型操作（例如，为新文档编制索引）正在进行时暂停增量处理，则可以先设置为 false，然后再切换回 true。

POST https://[service name].search.azure.cn/indexers?api-version=2021-04-30-Preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

步骤 3：重置索引器

为现有索引器设置增量扩充时需要重置索引器，以确保所有文档处于一致状态。可以使用门户或 API 客户端来执行此任务。

POST https://[YOUR-SEARCH-SERVICE].search.azure.cn/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

步骤 4：保存索引器

使用 PUT 请求来更新索引器 (2021-04-30-Preview)，其中请求的正文包括“cache”。

PUT https://[YOUR-SEARCH-SERVICE].search.azure.cn/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]
    {
        "name" : "<YOUR-INDEXER-NAME>",
        ...
        "cache": {
            "storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        }
    }

如果现在针对索引器发出另一个 GET 请求，服务的响应包含缓存对象中的 ID 属性。将字母数字字符串追加到容器的名称，该容器包含此索引器处理的每个文档的所有缓存结果和中间状态。 ID 用于唯一命名 Blob 存储中的缓存。

    "cache": {
        "ID": "<ALPHA-NUMERIC STRING>",
        "enableReprocessing": true,
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-STORAGE-KEY>;EndpointSuffix=core.chinacloudapi.cn"
    }

步骤 5：运行索引器

可以使用门户或 API 运行索引器。在门户上的“索引器”列表中选择该索引器，然后选择“运行”。使用门户的一个优势是可以监视索引器状态、观察作业持续时间以及处理的文档数。门户页面每隔几分钟刷新一次。

或者，可以使用 REST 运行索引器：

POST https://[YOUR-SEARCH-SERVICE].search.azure.cn/indexers/[YOUR-INDEXER-NAME]/run?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

注意

重置和重新运行索引器会导致完全重新生成，以便能够缓存内容。所有认知扩充将针对所有文档重新运行。加载缓存后，便会开始从缓存中重新使用扩充内容。

检查缓存的输出

在 Azure 存储中的 Blob 容器下找到缓存。容器名称为 ms-az-search-indexercache-<some-alphanumeric-string>。

缓存由索引器创建和使用。缓存内容不具有用户可读性。

要验证缓存是否可操作，请修改技能集并运行索引器，然后比较执行时间和文档计数的前后指标。

包括扫描文档的图像分析和光学字符识别 (OCR) 在内的技能集是很好的测试用例。如果修改下游文本技能或者与图像无关的任何技能，则索引器可以从缓存中检索所有以前处理的图像和 OCR 内容，仅更新并处理你在编辑内容中指示的文本相关更改。你可以期望在索引器执行文档计数中看到更少的文档、执行时间更短以及账单费用降低。

cog-search-demo 教程中使用的文件集是一个有用的测试用例，因为它包含 14 个各种格式的文件，JPG、PNG、HTML、DOCX、PPTX 和其他类型。在文本翻译技能中，将 en 更改为 es 或另一种语言，以对增量扩充进行概念证明测试。

常见错误

如果忘记在请求中指定预览 API 版本，则会发生以下错误：

"The request is invalid. Details: indexer : A resource without a type name was found, but no expected type was specified. To allow entries without type information, the expected type must also be specified when the model is specified."

如果缺少索引器要求，也会出现“400 错误请求”错误。错误消息会具体说明任何缺少的依赖项。

后续步骤

增量扩充为索引和知识存储提供可重用的内容，适用于包含技能集的索引器。以下链接提供了有关缓存和技能集的更多信息。