Индексирование данных из Хранилища BLOB-объектов Azure

Статья
09/01/2024

В этой статье вы узнаете, как настроить индексатор, который импортирует содержимое из Хранилище BLOB-объектов Azure и делает его доступным для поиска в службе "Поиск ИИ Azure". Входные данные индексатора — это большие двоичные объекты в одном контейнере. Выходные данные — это индекс поиска с содержимым, доступным для поиска, и метаданными, хранящимися в отдельных полях.

В этой статье описано , как создать индексатор с информацией, относяющейся к хранилищу BLOB-объектов. В нем используются ИНТЕРФЕЙСы REST API для демонстрации трех частей рабочего процесса, общего для всех индексаторов: создание источника данных, создание индекса, создание индексатора. Извлечение данных происходит при отправке запроса create Indexer.

Индексаторы BLOB-объектов часто используются как для обогащения ИИ, так и для обработки на основе текста. В этой статье рассматриваются индексаторы для индексирования на основе текста, где только текстовое содержимое и метаданные обрабатываются для сценариев полнотекстового поиска.

Необходимые компоненты

Хранилище BLOB-объектов Azure, производительность уровня "Стандартный" (версия 2 общего назначения).
Уровни доступа включают горячий, холодный, холодный и архивный. Индексаторы могут получать большие двоичные объекты на горячих, холодных и холодных уровнях доступа.
Большие двоичные объекты, предоставляющие текстовое содержимое и метаданные. Если большие двоичные объекты содержат двоичное содержимое или неструктурированный текст, рассмотрите возможность добавления обогащения ИИ для обработки изображений и естественного языка. Содержимое BLOB-объектов не может превышать ограничения индексатора для уровня службы поиска.
Поддерживаемая конфигурация сети и доступ к данным. Как минимум, в служба хранилища Azure требуются разрешения на чтение. Хранилище строка подключения, включающее ключ доступа, предоставляет доступ для чтения к содержимому хранилища. Если вместо этого вы используете имена входа и роли Microsoft Entra, убедитесь, что у управляемого удостоверения службы поиска есть разрешения средства чтения данных BLOB-объектов хранилища.

По умолчанию поиск и хранилище принимают запросы с общедоступных IP-адресов. Если сетевая безопасность не является немедленной проблемой, можно индексировать данные БОЛЬШИХ двоичных объектов с помощью только строка подключения и разрешений на чтение. Когда вы будете готовы к добавлению защиты сети, ознакомьтесь со сведениями о доступе индексатора к содержимому, защищенному функциями безопасности сети Azure, для получения рекомендаций по доступу к данным.
Используйте клиент REST, чтобы сформулировать вызовы REST, аналогичные приведенным в этой статье.

Поддерживаемые форматы документов

Индексатор больших двоичных объектов может извлечь текст из документов следующих форматов:

CSV (см. раздел индексирование больших двоичных объектов CSV)
EML
EPUB
GZ
HTML
JSON (см. индексирование BLOB-объектов JSON);
KML (XML для географических представлений)
Форматы Microsoft Office: DOCX/DOC/DOCM, XLSX/XLSM, PPTX/PPT/PPTM, MSG (outlook emails), XML (как 2003, так и 2006 WORD XML)
Форматы открытых документов: ODT, ODS, ODP
PDF
обычные текстовые файлы (см. также индексирование обычного текста);
RTF
XML
ZIP

Определите, какие большие двоичные объекты нужно индексировать

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

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

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

Имя свойства	Значение свойства	Описание
"AzureSearch_Skip"	`"true"`	Указывает индексатору больших двоичных объектов пропустить весь большой двоичный объект. Не извлекаются ни метаданные, ни содержимое. Это полезно, когда обработка определенного большого двоичного объекта постоянно завершается сбоем и индексирование прерывается.
"AzureSearch_SkipContent"	`"true"`	Пропускает содержимое и извлекает только метаданные. это эквивалентно параметру, описанному `"dataToExtract" : "allMetadata"` в параметрах конфигурации , только что в пределах определенного большого двоичного объекта.

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

Индексатор обычно создает один документ поиска для каждого большого двоичного объекта, где текстовое содержимое и метаданные записываются в качестве полей, доступных для поиска в индексе. Если большие двоичные объекты являются целыми файлами, их можно проанализировать в несколько документов поиска. Например, можно проанализировать строки в CSV-файле, чтобы создать один документ поиска для каждой строки.

Составной или внедренный документ (например, ZIP-архив, документ Word со встроенной электронной почтой Outlook, содержащий вложения или . MSG-файл с вложениями) также индексируется как один документ. Например, все изображения, извлеченные из вложений файла MSG, будут возвращены в поле normalized_images. Если у вас есть изображения, попробуйте добавить обогащение ИИ, чтобы получить больше служебной программы поиска из этого содержимого.

Текстовое содержимое документа извлекается в строковое поле с именем content. Можно также извлечь стандартные и пользовательские метаданные.

Индексация метаданных BLOB-объектов

Метаданные BLOB-объектов также можно индексировать, и это полезно, если вы считаете, что какие-либо из стандартных или пользовательских свойств метаданных полезны в фильтрах и запросах.

Свойства метаданных, указанные пользователем, извлекаются подробно. Чтобы получить значения, необходимо определить поле в индексе поиска типа Edm.String с тем же именем, что и ключ метаданных большого двоичного объекта. Например, если у большого двоичного объекта есть ключ метаданных Sensitivity со значением High, необходимо определить поле Sensitivity в индексе поиска и заполнить его значением High.

Стандартные свойства метаданных BLOB-объектов можно извлечь в аналогичные именованные и типизированные поля, как показано ниже. Индексатор BLOB-объектов автоматически создает сопоставления внутренних полей для этих свойств метаданных BLOB-объектов, преобразовав исходное дефисированное имя ("metadata-storage-name") в символично эквивалентное имя ("metadata_storage_name").

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

metadata_storage_name (Edm.String) — имя файла большого двоичного объекта. Например, для большого двоичного объекта /my-container/my-folder/subfolder/resume.pdf значение этого поля — resume.pdf.
metadata_storage_path (Edm.String) — полный универсальный код ресурса (URI) большого двоичного объекта, включая учетную запись хранения. Например: https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf
metadata_storage_content_type (Edm.String) — тип контента, указанный в коде для отправки большого двоичного объекта. Например, application/octet-stream.
metadata_storage_last_modified (Edm.DateTimeOffset) — последняя измененная метка времени для большого двоичного объекта. Поиск ИИ Azure использует эту метку времени для идентификации измененных BLOB-объектов, чтобы избежать повторного индексирования всего после первоначального индексирования.
metadata_storage_size (Edm.Int64) — размер большого двоичного объекта в байтах.
metadata_storage_content_md5 (Edm.String) — хэш MD5 содержимого большого двоичного объекта, если он доступен.
metadata_storage_sas_token (Edm.String) — временный маркер SAS, который может использоваться пользовательскими навыками для получения доступа к большому двоичному объекту. Этот маркер не должен храниться для последующего использования, так как он может истекать.

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

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

В настоящее время индексирование тегов индекса BLOB-объектов не поддерживается этим индексатором.

Определение источника данных

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

Создайте или обновите источник данных, чтобы задать его определение:

{
    "name" : "my-blob-datasource",
    "type" : "azureblob",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
}

Задайте для параметра type "azureblob" (обязательный).
Задайте для параметра "Учетные данные" значение служба хранилища Azure строка подключения. В следующем разделе описаны поддерживаемые форматы.
Задайте для контейнера BLOB-объектов значение container и используйте "query" для указания всех вложенных папок.

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

Поддерживаемые учетные данные и строка подключения

Индексаторы могут подключаться к контейнеру BLOB-объектов с помощью следующих подключений.

Строка подключения учетной записи хранения полного доступа
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Вы можете получить строка подключения на странице учетной записи хранения в портал Azure, выбрав ключи доступа в области навигации слева. Не забудьте выбрать полную строка подключения и не только ключ.

Управляемое удостоверение строка подключения
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Для этого строка подключения не требуется ключ учетной записи, но необходимо ранее настроить службу поиска для подключения с помощью управляемого удостоверения.

Подписанный URL-адрес учетной записи хранения** (SAS) строка подключения
`{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }`
Подписанный URL-адрес должен иметь разрешения "Список" и "Чтение" для контейнеров и объектов (в данном случае — больших двоичных объектов).

Подписанный URL-адрес контейнера
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
Подписанный URL-адрес должен иметь разрешения "Список" и "Чтение" для контейнера. Дополнительные сведения см. в разделе "Использование подписанных URL-адресов".

Примечание.

Если используются учетные данные SAS, то необходимо периодически обновлять учетные данные источника данных с помощью обновленных подписей, чтобы не истек их срок действия. Если срок действия учетных данных на основе подписанного URL-адреса истек, индексатор выдает сообщение об ошибке "Credentials provided in the connection string are invalid or have expired" (Учетные данные, указанные в строке подключения, недействительны или устарели).

Добавление полей поиска в индекс

В индексе поиска добавьте поля, чтобы принять содержимое и метаданные больших двоичных объектов Azure.

Создайте или обновите индекс , чтобы определить поля поиска, которые будут хранить содержимое и метаданные BLOB-объектов:

POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
{
    "name" : "my-search-index",
    "fields": [
        { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
        { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },        
    ]
}

Создайте поле ключа документа ("key": true"). Для содержимого BLOB-объектов лучшие кандидаты являются свойствами метаданных.
- metadata_storage_path (по умолчанию) полный путь к объекту или файлу. Поле ключа ("ID" в этом примере) будет заполнено значениями из metadata_storage_path, так как это значение по умолчанию.
- metadata_storage_name, доступный только в том случае, если имена уникальны. Если вы хотите, чтобы это поле было ключом, перейдите "key": true к этому определению поля.
- Настраиваемое свойство метаданных, которое добавляется в большие двоичные объекты. Для этого варианта требуется, чтобы при передаче это свойство метаданных добавлялось ко всем большим двоичным объектам. Так как ключ является обязательным свойством, все большие двоичные объекты, в которых отсутствует значение, не будут проиндексированы. При использовании настраиваемого свойства метаданных в качестве ключа следует избегать внесения изменений в это свойство. При изменении свойства ключа индексаторы добавят дубликаты документов для того же BLOB-объекта.
Свойства метаданных часто включают символы, такие как / и -недопустимые для ключей документов. Однако индексатор автоматически кодирует свойство метаданных ключа без необходимости в конфигурации или сопоставлении полей.
Добавьте поле content для хранения извлеченного текста из каждого файла через свойство "содержимое" большого двоичного объекта. Вам не требуется использовать это имя, но это позволяет воспользоваться преимуществами неявных сопоставлений полей.
Добавьте поля для стандартных свойств метаданных. Индексатор может считывать пользовательские свойства метаданных, стандартные свойства метаданных и свойства метаданных для конкретного содержимого.

Настройка и запуск индексатора BLOB-объектов

Когда индекс и источник данных уже созданы, можно создать индексатор. Конфигурация индексатора задает входные данные, параметры и свойства, управляющие поведением во время выполнения. Можно также указать, какие части большого двоичного объекта следует индексировать.

Создайте или обновите индексатор , предоставив ему имя и ссылаясь на источник данных и целевой индекс:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer",
  "dataSourceName" : "my-blob-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Задайте значение batchSize , если значение по умолчанию (10 документов) является недоиспользующим или подавляющим доступными ресурсами. Размеры пакетов по умолчанию зависят от источника данных. Индексирование BLOB-объектов задает размер пакета в 10 документов при распознавании большего среднего размера документа.
В разделе "Конфигурация" укажите, какие большие двоичные объекты индексируются на основе типа файла, или оставьте неопределенным, чтобы получить все большие двоичные объекты.

Для "indexedFileNameExtensions"этого укажите разделенный запятыми список расширений файлов (с главной точкой). Сделайте то же самое, "excludedFileNameExtensions" чтобы указать, какие расширения следует пропустить. Если одно и то же расширение находится в обоих списках, он будет исключен из индексирования.
В разделе "Конфигурация" задайте значение dataToExtract, чтобы управлять индексированием частей больших двоичных объектов:
- ContentAndMetadata указывает, что все метаданные и текстовое содержимое, извлеченные из большого двоичного объекта, индексируются. Это значение по умолчанию.
- "storageMetadata" указывает, что индексируются только стандартные свойства BLOB-объектов и пользовательские метаданные .
- "allMetadata" указывает, что стандартные свойства BLOB-объектов и все метаданные для найденных типов контента извлекаются из содержимого БОЛЬШОго двоичного объекта и индексируются.
В разделе "Конфигурация" задайте параметр "parsingMode". Режим синтаксического анализа по умолчанию — один документ поиска для каждого большого двоичного объекта. Если большие двоичные объекты являются обычным текстом, можно повысить производительность, переключившись на синтаксический анализ обычного текста . Если требуется более детализированный анализ, который сопоставляет большие двоичные объекты с несколькими документами поиска, укажите другой режим. Синтаксический анализ "один ко многим" поддерживается для больших двоичных объектов, состоящих из следующих:
- Документы JSON
- CSV-файлы;
Укажите сопоставления полей, если существуют различия в имени или типе поля, или если в индексе поиска требуется несколько версий исходного поля.

В индексировании BLOB-объектов часто можно опустить сопоставления полей, так как индексатор имеет встроенную поддержку сопоставления свойств "содержимого" и метаданных с аналогичными именованными и типизированными полями в индексе. Для свойств метаданных индексатор автоматически заменит дефисы символами - подчеркивания в индексе поиска.
Дополнительные сведения о других свойствах см. в статье "Создание индексатора ". Полный список описаний параметров см. в разделе REST API.

Индексатор запускается автоматически при его создании. Это можно предотвратить, задав для параметра "Отключено" значение true. Чтобы управлять выполнением индексатора, запустите индексатор по запросу или поместите его в расписание.

Индексирование данных из нескольких контейнеров BLOB-объектов Azure в один индекс

Помните, что индексатор может индексировать только данные из одного контейнера. Если требуется индексировать данные из нескольких контейнеров и объединить их в один индекс поиска ИИ, это можно сделать, настроив несколько индексаторов, все направлены на один и тот же индекс. Обратите внимание на максимальное количество индексаторов, доступных на номер SKU.

Чтобы проиллюстрировать, рассмотрим пример двух индексаторов, извлечение данных из двух разных источников данных, именованных my-blob-datasource1 и my-blob-datasource2. Каждый источник данных указывает на отдельный контейнер BLOB-объектов Azure, но оба направляются к одному индексу с именем my-search-index.

Первый пример определения индексатора:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Второе определение индексатора, которое выполняется в параллельном примере:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Проверка состояния индексатора

Чтобы отслеживать состояние индексатора и журнал выполнения, отправьте запрос состояния индексатора:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-01
  Content-Type: application/json  
  api-key: [admin key]

Ответ включает состояние и количество обработанных элементов. Он должен выглядеть примерно так:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

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

Обработка ошибок

Некоторые распространенные ошибки, которые возникают при индексировании: неподдерживаемые типы содержимого, отсутствующее содержимое или большие двоичные объекты слишком большого размера.

По умолчанию индексатор BLOB-объектов останавливается, как только он обнаруживает большой двоичный объект с неподдерживаемым типом контента (например, звуковым файлом). Для пропуска определенных типов контента можно использовать параметр "excludedFileNameExtensions". Однако может потребоваться продолжить индексирование даже при возникновении ошибок, а позже выполнить отладку отдельных документов. Дополнительные сведения об ошибках индексатора см. в разделах Руководство по устранению проблем с индексатором и Ошибки и предупреждения индексатора.

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

PUT /indexers/[indexer name]?api-version=2024-07-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}

Параметр	Допустимые значения	Description
"maxFailedItems"	-1, null или 0, положительное целое число	Вы также можете продолжить индексирование, если ошибки возникают в какой-либо момент обработки — при анализе больших двоичных объектов или при добавлении документов в индекс. Задайте для этих свойств количество допустимых сбоев. Значение `-1` разрешает обработку независимо от того, сколько ошибок произошло. В противном случае значение является положительным целым числом.
MaxFailedItemsPerBatch	-1, null или 0, положительное целое число	Аналогично приведенному выше, но используется для пакетного индексирования.
FailOnUnsupportedContentType	true или false	Если индексатор не может определить тип контента, укажите, следует ли продолжить или завершить задание.
FailOnUnprocessableDocument	true или false	Если индексатор не может обработать документ другого поддерживаемого типа контента, укажите, следует ли продолжить или завершить задание.
"indexStorageMetadataOnlyForOversizedDocuments"	true или false	Большие двоичные объекты слишком большого размера по умолчанию считаются ошибками. Если этот параметр имеет значение true, индексатор попытается индексировать его метаданные, даже если содержимое не может быть индексировано. Ограничения размера больших двоичных объектов указаны в разделе Ограничения службы.

Поделиться через