Индексирование данных из Azure Data Lake Storage 2-го поколения

Статья
09/01/2024

Из этой статьи вы узнаете, как настроить индексатор , который импортирует содержимое из Azure Data Lake Storage (ADLS) 2-го поколения и делает его доступным для поиска в Службе искусственного интеллекта Azure. Входные данные индексатора — это большие двоичные объекты в одном контейнере. Выходные данные — это индекс поиска с содержимым, доступным для поиска, и метаданными, хранящимися в отдельных полях.

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

Пример кода в C#см. в разделе Index Data Lake 2-го поколения с помощью идентификатора Microsoft Entra на GitHub.

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

ADLS 2-го поколения с включенным иерархическим пространством имен. ADLS 2-го поколения доступен через служба хранилища Azure. При настройке учетной записи хранения у вас есть возможность включить иерархическое пространство имен, упорядочивать файлы в иерархию каталогов и вложенных подкаталогов. Включив иерархическое пространство имен, включите ADLS 2-го поколения.
Уровни доступа для ADLS 2-го поколения включают горячий, холодный и архивный. Доступ к индексаторам поиска может получить только горячий и холодный.
Большие двоичные объекты, содержащие текст. Если у вас есть двоичные данные, можно включить обогащение ИИ для анализа изображений. Содержимое BLOB-объектов не может превышать ограничения индексатора для уровня службы поиска.
Разрешения на чтение служба хранилища Azure. Строка подключения "полный доступ" включает ключ, который предоставляет доступ к содержимому, но если вы используете роли Azure, убедитесь, что управляемое удостоверение службы поиска имеет разрешения средства чтения данных BLOB-объектов хранилища.
Используйте клиент REST, чтобы сформулировать вызовы REST, аналогичные приведенным в этой статье.

Примечание.

ADLS 2-го поколения реализует модель управления доступом, которая поддерживает управление доступом на основе ролей Azure (Azure RBAC) и списки управления доступом, такие как POSIX(ACL) на уровне BLOB-объектов. Поиск по искусственному интеллекту Azure не поддерживает разрешения на уровне документа. Все пользователи имеют одинаковый уровень доступа ко всем искомому и извлекаемому содержимому в индексе. Если разрешения на уровне документа являются обязательными для приложения, рассмотрите возможность обрезки безопасности в качестве потенциального решения.

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

Индексатор ADLS 2-го поколения может извлекать текст из следующих форматов документов:

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-файле, чтобы создать один документ поиска для каждой строки.

Индексация метаданных 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, который может использоваться пользовательскими навыками для получения доступа к большому двоичному объекту. Этот маркер не должен храниться для последующего использования, так как он может истекать.

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

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

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

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

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

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

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

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

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

Индексаторы могут подключаться к контейнеру 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-адрес должен иметь разрешения "Список" и "Чтение" для контейнеров и объектов (в данном случае — больших двоичных объектов).

Примечание.

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

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

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

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

{
    "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 для хранения извлеченного текста из каждого файла через свойство "содержимое" большого двоичного объекта. Вам не требуется использовать это имя, но это позволяет воспользоваться преимуществами неявных сопоставлений полей.
Добавьте поля для стандартных свойств метаданных. Индексатор может считывать пользовательские свойства метаданных, стандартные свойства метаданных и свойства метаданных для конкретного содержимого.

Настройка и запуск индексатора ADLS 2-го поколения

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

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

{
  "name" : "my-adlsgen2-indexer",
  "dataSourceName" : "my-adlsgen2-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) в REST API.

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

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

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

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":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-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, индексатор попытается индексировать его метаданные, даже если содержимое не может быть индексировано. Ограничения размера больших двоичных объектов указаны в разделе Ограничения службы.

Ограничения

В отличие от индексаторов BLOB-объектов, индексаторы ADLS 2-го поколения не могут использовать маркеры SAS уровня контейнера для перечисления и индексирования содержимого из учетной записи хранения. Это связано с тем, что индексатор проверяет, включена ли у учетной записи хранения иерархические пространства имен, вызывая API свойств Filesystem — Get properties API. Для учетных записей хранения, в которых иерархические пространства имен не включены, клиентам рекомендуется использовать индексаторы BLOB-объектов, чтобы обеспечить выполнение перечисления больших двоичных объектов.
Если свойство metadata_storage_path сопоставляется с полем ключа индекса, большие двоичные объекты не гарантированно будут переиндексированы при переименовании каталога. Если вы хотите переиндексировать большие двоичные объекты, которые являются частью переименованных каталогов, обновите LastModified метки времени для всех из них.

Следующие шаги

Теперь можно запустить индексатор, состояние монитора или запланировать выполнение индексатора. Следующие статьи относятся к индексаторам, которые извлекает содержимое из служба хранилища Azure:

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