Настройка кэша обогащения

2025-07-28

Important

Эта функция предоставляется в общедоступной предварительной версии в соответствии с дополнительными условиями использования. Предварительная версия REST API поддерживает эту функцию.

В этой статье объясняется, как добавить кэширование в конвейер обогащения, чтобы можно было изменять подчиненные шаги обогащения без необходимости перестраивать все время. По умолчанию набор навыков не имеет состояния, и изменение любой его части требует полного повторного запуска индексатора. С помощью кэша обогащения индексатор может определить, какие части дерева документов необходимо обновить на основе изменений, обнаруженных в определениях набора навыков или индексатора. Существующие обработанные выходные данные сохраняются и повторно используются везде, где это возможно.

Кэшированное содержимое помещается в хранилище Azure с помощью предоставленных сведений об учетной записи. Контейнер с именем ms-az-search-indexercache-<alpha-numerc-string> создается при запуске индексатора. Его следует рассматривать как внутренний компонент, управляемый службой поиска, и не следует изменять.

Prerequisites

служба хранилища Azure для хранения кэшированных обогащений. Учетная запись хранения должна быть общего назначения версии 2.
Для индексирования БОЛЬШИХ двоичных объектов только в том случае, если требуется синхронизированное удаление документа из кэша и индекса при удалении больших двоичных объектов из источника данных, включите политику удаления в индексаторе. Без этой политики удаление документов из кэша не поддерживается.

Вы должны быть знакомы с настройкой индексаторов и наборов навыков. Начните с обзора индексатора, а затем перейдите к наборам навыков, чтобы узнать о конвейерах обогащения.

Limitations

Caution

Если вы используете индексатор SharePoint Online (предварительная версия), следует избежать добавочного обогащения. При определенных обстоятельствах кэш становится недействительным, требуя сброса индексатора и полного перестроения, если вы решите перезагрузить его.

Permissions

Для поиска ИИ Azure требуется доступ на запись в службу хранилища Azure. Если вы используете управляемое удостоверение для службы поиска, убедитесь, что оно назначено ролям участника данных BLOB-объектов хранилища и участника данных таблицы хранилища. Дополнительные сведения см. в статье "Подключение к службе хранилища Azure" с помощью управляемого удостоверения (поиск azure AI).

Включение новых индексаторов

Вы можете использовать портал Azure, предварительные API или предварительные пакеты SDK Azure для включения кэша обогащения на индексаторе.

Azure portal
REST

Слева выберите индексаторы и нажмите кнопку "Добавить индексатор".
Укажите имя индексатора и существующий индекс, источник данных и набор навыков.
Включите добавочное кэширование и задайте учетную запись служба хранилища Azure.

В новых индексаторах добавьте свойство cache в полезные данные определения индексатора при вызове операций создания или обновления индексатора.

Мы рекомендуем использовать последнюю предварительную версию Create or Update Indexer (2025-05-01-preview).

POST https://[service name].search.windows.net/indexers?api-version=2025-05-01-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 для получения индексатора. При использовании предварительной версии API для выполнения запроса GET индексатора свойство cache, значение которого задано как null, автоматически добавляется в определение.

GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2025-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Шаг 2. Установка свойства кэша

В определении индекса измените, cache чтобы включить следующие обязательные и необязательные свойства:

(обязательно) storageConnectionString необходимо задать значение служба хранилища Azure строка подключения.
(Необязательно) enableReprocessing логическое свойство (true по умолчанию) указывает, что добавочное обогащение включено. false Установите значение, если вы хотите приостановить добавочную обработку во время других операций с ресурсоемкими операциями, такими как индексирование новых документов, выполняется, а затем переключитесь на true более позднюю версию.

POST https://[service name].search.windows.net/indexers?api-version=2025-05-01-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. Сброс индексатора

Сброс индексатора требуется при настройке добавочного обогащения для существующих индексаторов, чтобы убедиться, что все документы находятся в согласованном состоянии. Для этой задачи можно использовать портал Azure или клиент API.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2025-05-01-preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

Шаг 4. Сохранение индексатора

Обновите индексатор с помощью запроса PUT, в котором содержится cacheтекст запроса.

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2025-05-01-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 свойство в объект кэша. Строка добавляется к имени контейнера, содержащего все кэшированные результаты и промежуточное состояние каждого документа, обработанного этим индексатором. Идентификатор используется для уникального имени кэша в хранилище BLOB-объектов.

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

Шаг 5. Запуск индексатора

Для запуска индексатора можно использовать портал Azure или API. В портал Azure в списке индексаторов выберите индексатор и нажмите кнопку "Выполнить". Одним из преимуществ использования портал Azure является мониторинг состояния индексатора, запишите длительность задания и количество обрабатываемых документов. Страницы портала обновляются каждые несколько минут.

Кроме того, для запуска индексатора можно использовать REST.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

Note

Сброс и повторный запуск индексатора приводят к полной сборке, чтобы содержимое можно было кэшировать. Все неудачные когнитивные обогащения будут перезапущены во всех документах. Повторное использованием обогащенного содержимого из кэша начинается после загрузки кэша.

Проверка кэшированных выходных данных

Найдите кэш в служба хранилища Azure в контейнере BLOB-объектов. Контейнер имеет имя ms-az-search-indexercache-<some-alphanumeric-string>.

Кэш создается и используется индексатором. Его содержимое не доступно для чтения.

Чтобы проверить, работает ли кэш, измените набор навыков и запустите индексатор, а затем сравните метрики до и после выполнения для времени выполнения и подсчета документов.

Наборы навыков, включающие анализ изображений и оптическое распознавание символов (OCR) отсканированных документов, делают хорошие тестовые случаи. При изменении нижнего текстового навыка или любого навыка, не связанного с изображением, индексатор может получить все ранее обработанные изображения и содержимое OCR из кэша, обновляя и обрабатывая только изменения, связанные с текстом, указанные в изменениях. Вы можете ожидать, что меньше документов в счетчике документов выполнения индексатора, меньше времени выполнения и меньше расходов на счет.

Набор файлов , используемый в руководствах по cog-search-demo, является полезным тестовый случай, так как он содержит 14 файлов различных форматов JPG, PNG, HTML, DOCX, PPTX и других типов. Перейдите en на es другой язык в навыке перевода текста для проверки концепции добавочного обогащения.

Common errors

Следующая ошибка возникает, если вы забыли указать версию 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 также возникает, если отсутствует требование индексатора. Сообщение об ошибке указывает отсутствующие зависимости.

Next step

Добавочное обогащение применимо к индексаторам, содержащим наборы навыков, предоставляя повторное содержимое для индексов и хранилищ знаний. Следующая ссылка содержит дополнительные сведения об управлении кэшем.

Управление кэшем обогащения