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


Индексирование данных из файлов и ярлыков OneLake

Из этой статьи вы узнаете, как настроить индексатор файлов OneLake для извлечения данных, доступных для поиска, и метаданных из lakehouse на вершине OneLake.

Используйте этот индексатор для следующих задач:

  • Индексирование и добавочное индексирование данных: индексатор может индексировать файлы и связанные метаданные из путей к данным в лейкхаусе. Он обнаруживает новые и обновленные файлы и метаданные с помощью встроенного обнаружения изменений. Вы можете настроить обновление данных по расписанию или по запросу.
  • Обнаружение удаления: индексатор может обнаруживать удаления с помощью пользовательских метаданных для большинства файлов и ярлыков. Для этого требуется добавить метаданные в файлы для обозначения того, что они были "обратимо удалены", что позволяет удалить их из индекса поиска. В настоящее время невозможно обнаружить удаления в файлах ярлыков Google Cloud Storage или Amazon S3, так как пользовательские метаданные не поддерживаются для этих источников данных.
  • Примененный ИИ через наборы навыков: наборы навыков полностью поддерживаются индексатором файлов OneLake. Сюда входят ключевые функции, такие как встроенная векторизация , которая добавляет блоки данных и шаги внедрения.
  • Режимы синтаксического анализа: индексатор поддерживает режимы синтаксического анализа JSON, если требуется проанализировать массивы JSON или строки в отдельные документы поиска.
  • Совместимость с другими функциями: индексатор OneLake предназначен для эффективной работы с другими функциями индексатора, такими как сеансы отладки, кэш индексатора для добавочных обогащений и хранилища знаний.

Используйте REST API 2024-05-01-preview, бета-версию пакета Azure SDK или импорт и векторизацию данных в портал Azure для индексирования из OneLake.

В этой статье используются ИНТЕРФЕЙСы REST API для иллюстрации каждого шага.

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

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

Индексатор файлов OneLake может извлекать текст из следующих форматов документов:

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

Следующие сочетания клавиш OneLake поддерживаются индексатором файлов OneLake:

Ограничения в этой предварительной версии

  • Типы файлов Parquet (включая delta parquet) в настоящее время не поддерживаются.

  • Удаление файлов не поддерживается для сочетаний клавиш Amazon S3 и Google Cloud Storage.

  • Этот индексатор не поддерживает содержимое расположения таблицы рабочей области OneLake.

  • Этот индексатор не поддерживает SQL-запросы, но запрос, используемый в конфигурации источника данных, предназначен исключительно для добавления папки или ярлыка для доступа.

  • Нет поддержки приема файлов из рабочей области "Моя рабочая область " в OneLake, так как это личный репозиторий для каждого пользователя.

Подготовка данных к индексации

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

  • Поместите файлы в виртуальную папку. Определение источника данных индексатора включает параметр "query", который может быть вложенным папкой Lakehouse или ярлыком. Если это значение указано, индексируются только те файлы в вложенной папке или ярлыке в lakehouse.

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

  • Включите или исключите произвольные файлы. Если вы хотите пропустить определенный файл по какой-либо причине, вы можете добавить свойства и значения метаданных в файлы в oneLake lakehouse. При обнаружении этого свойства индексатор пропускает файл или его содержимое в выполнении индексирования.

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

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

Индексирование метаданных файла

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

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

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

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

  • metadata_storage_name (Edm.String) — имя файла. Например, если у вас есть файл /mydatalake/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 содержимого большого двоичного объекта, если он доступен.

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

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

Предоставить разрешения

Индексатор OneLake использует проверку подлинности маркера и доступ на основе ролей для подключений к OneLake. Разрешения назначаются в OneLake. Нет требований к разрешениям для физических хранилищ данных, соответствующих ярлыкам. Например, если вы индексируете из AWS, вам не нужно предоставлять разрешения службы поиска в AWS.

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

  1. Настройте системное или управляемое пользователем удостоверение для служба ИИ.

    На следующем снимке экрана показано управляемое системой удостоверение для службы поиска с именем onelake-demo.

    Снимок экрана: удостоверение системы службы поиска в портал Azure.

    Снимок экрана: управляемое пользователем удостоверение для той же службы поиска.

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

  2. Предоставьте разрешение на доступ службы поиска к рабочей области Fabric. Служба поиска делает подключение от имени индексатора.

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

    На следующем снимка экрана показано назначение роли участника с помощью системного управляемого удостоверения.

    Снимок экрана: назначение роли участника для удостоверения системы службы поиска в портал Azure.

    Снимок экрана: назначение роли участника с помощью системного управляемого удостоверения:

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

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

Источник данных определяется как независимый ресурс, чтобы его можно было использовать несколькими индексаторами. Для создания источника данных необходимо использовать REST API 2024-05-01-preview.

  1. Используйте REST API создания или обновления источника данных, чтобы задать его определение. Это наиболее важные шаги определения.

  2. Задайте значение "type" "onelake" (обязательно).

  3. Получите GUID рабочей области Microsoft Fabric и GUID lakehouse:

    • Перейдите в lakehouse, который вы хотите импортировать данные из URL-адреса. Он должен выглядеть примерно так: "https://msit.powerbi.com/groups/00000000-0000-0000-0000-000000000000/lakehouses/11111111-1111-1111-1111-111111111111?experience=power-bi". Скопируйте следующие значения, используемые в определении источника данных:

    • Скопируйте GUID рабочей области, который будет вызываться {FabricWorkspaceGuid}сразу после "группы" в URL-адресе. В этом примере будет 000000000000-0000-0000-0000-0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

      Снимок экрана: GUID рабочей области Fabric в портал Azure.

    • Скопируйте GUID Lakehouse, который будет вызываться {lakehouseGuid}сразу после "lakehouses" в URL-адресе. В этом примере это будет 11111111-1111-1111-1111-1111-1111111111.

      Снимок экрана: GUID Lakehouse в портал Azure.

  4. Задайте "credentials" идентификатор GUID рабочей области Microsoft Fabric, заменив {FabricWorkspaceGuid} значение, скопированное на предыдущем шаге. Это OneLake для доступа к управляемому удостоверению, который вы настроили позже в этом руководстве.

    "credentials": {  
    "connectionString": "ResourceId={FabricWorkspaceGuid}"  
    }
    
  5. Задайте для "container.name" GUID Lakehouse, заменив {lakehouseGuid} значение, скопированное на предыдущем шаге. Используется "query" для указания вложенной папки или ярлыка lakehouse.

      "container": {  
        "name": "{lakehouseGuid}",  
        "query": "{optionalLakehouseFolderOrShortcut}"  
      }
    
  6. Задайте метод проверки подлинности с помощью управляемого удостоверения, назначаемого пользователем, или перейдите к следующему шагу для управляемого системой удостоверения.

    {    
      "name": "{dataSourceName}",  
      "description": "description",  
      "type": "onelake",  
      "credentials": {  
        "connectionString": "ResourceId={FabricWorkspaceGuid}"  
      },  
      "container": {  
        "name": "{lakehouseGuid}",  
        "query": "{optionalLakehouseFolderOrShortcut}"  
      },  
      "identity": {  
        "@odata.type": "Microsoft.Azure.Search.DataUserAssignedIdentity",  
        "userAssignedIdentity": "{userAssignedManagedIdentity}"  
      }  
    }
    

    Это userAssignedIdentity значение можно найти, доступ к ресурсу {userAssignedManagedIdentity} в разделе "Свойства" и вызывается Id.

    Снимок экрана: свойство идентификатора, назначаемое пользователем.

    Пример:

    {    
      "name": "mydatasource",  
      "description": "description",  
      "type": "onelake",  
      "credentials": {  
        "connectionString": "ResourceId=00000000-0000-0000-0000-000000000000"  
      },  
      "container": {  
        "name": "11111111-1111-1111-1111-111111111111",  
        "query": "folder_name"  
      },  
      "identity": {  
        "@odata.type": "Microsoft.Azure.Search.DataUserAssignedIdentity",  
        "userAssignedIdentity": "/subscriptions/333333-3333-3333-3333-33333333/resourcegroups/myresourcegroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/demo-mi"  
      }  
    }
    
  7. При необходимости используйте управляемое удостоверение, назначаемое системой. Идентификатор удаляется из определения при использовании управляемого удостоверения, назначаемого системой.

    {    
      "name": "{dataSourceName}",  
      "description": "description",  
      "type": "onelake",  
      "credentials": {  
        "connectionString": "ResourceId={FabricWorkspaceGuid}"  
      },  
      "container": {  
        "name": "{lakehouseGuid}",  
        "query": "{optionalLakehouseFolderOrShortcut}"  
      }  
    }
    

    Пример:

    {    
      "name": "mydatasource",  
      "description": "description",  
      "type": "onelake",  
      "credentials": {  
        "connectionString": "ResourceId=00000000-0000-0000-0000-000000000000"  
      },  
      "container": {  
        "name": "11111111-1111-1111-1111-111111111111",  
        "query": "folder_name"  
      }
    } 
    

Обнаружение удалений с помощью пользовательских метаданных

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

Чтобы включить автоматическое удаление файлов, используйте настраиваемые метаданные, чтобы указать, следует ли удалить документ поиска из индекса.

Рабочий процесс требует трех отдельных действий:

  • Обратимое удаление файла в OneLake
  • Индексатор удаляет документ поиска в индексе
  • "Жесткое удаление" файла в OneLake

"Обратимое удаление" сообщает индексатору, что делать (удалить документ поиска). Если сначала удалить физический файл в OneLake, индексатор не будет считывать и соответствующий документ поиска в индексе не будет потерян.

В OneLake и поиске ИИ Azure необходимо выполнить действия, но нет других зависимостей функций.

  1. В файле Lakehouse добавьте в файл пользовательскую пару "ключ-значение метаданных", чтобы указать, что файл помечен для удаления. Например, можно присвоить свойству IsDeleted значение false. Если вы хотите удалить файл, измените его на true.

    Снимок экрана: файл с пользовательскими метаданными для IsDeleted.

  2. В поиске ИИ Azure измените определение источника данных, чтобы включить свойство dataDeletionDetectionPolicy. Например, следующая политика считает файл удаленным, если он имеет свойство метаданных IsDeleted со значением true:

    PUT https://[service name].search.windows.net/datasources/file-datasource?api-version=2024-05-01-preview
    {
        "name" : "onelake-datasource",
        "type" : "onelake",
         "credentials": {  
            "connectionString": "ResourceId={FabricWorkspaceGuid}"  
        },  
        "container": {  
            "name": "{lakehouseGuid}",  
            "query": "{optionalLakehouseFolderOrShortcut}"  
        },  
        "dataDeletionDetectionPolicy" : {
            "@odata.type" :"#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
            "softDeleteColumnName" : "IsDeleted",
            "softDeleteMarkerValue" : "true"
        }
    }
    

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

Некоторые ключевые моменты включают:

  • Планирование запуска индексатора помогает автоматизировать этот процесс. Мы рекомендуем планировать все сценарии добавочного индексирования.

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

  • Помните, что обнаружение удаления не поддерживается для сочетаний клавиш Amazon S3 и Google Cloud Storage из-за зависимости от пользовательских метаданных.

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

В индексе поиска добавьте поля для принятия содержимого и метаданных файлов озера данных OneLake.

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

    {
        "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 }     
        ]
    }
    
  2. Создайте поле ключа документа ("key": true"). Для содержимого файла лучшие кандидаты являются свойствами метаданных.

    • metadata_storage_path (по умолчанию) полный путь к объекту или файлу. Поле ключа ("ID" в этом примере) заполняется значениями из metadata_storage_path, так как это значение по умолчанию.

    • metadata_storage_name, доступный только в том случае, если имена уникальны. Если вы хотите, чтобы это поле было ключом, перейдите "key": true к этому определению поля.

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

    Свойства метаданных часто включают символы, такие как / и -недопустимые для ключей документов. Так как индексатор имеет свойство base64EncodeKeys (true по умолчанию), он автоматически кодирует свойство метаданных без необходимости сопоставления конфигурации или поля.

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

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

Настройка и запуск индексатора файлов OneLake

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

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

    {
      "name" : "my-onelake-indexer",
      "dataSourceName" : "my-onelake-datasource",
      "targetIndexName" : "my-search-index",
      "parameters": {
          "batchSize": null,
          "maxFailedItems": null,
          "maxFailedItemsPerBatch": null,
          "base64EncodeKeys": null,
          "configuration": {
              "indexedFileNameExtensions" : ".pdf,.docx",
              "excludedFileNameExtensions" : ".png,.jpeg",
              "dataToExtract": "contentAndMetadata",
              "parsingMode": "default"
          }
      },
      "schedule" : { },
      "fieldMappings" : [ ]
    }
    
  2. Установите значение batchSize, если по умолчанию (10 документов) используется или подавляющий доступные ресурсы. Размеры пакетов по умолчанию зависят от источника данных. Индексирование файлов задает размер пакета в 10 документов при распознавании большего среднего размера документа.

  3. В разделе "Конфигурация" укажите, какие файлы индексируются на основе типа файла, или оставьте неопределенным, чтобы получить все файлы.

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

  4. В разделе "Конфигурация" задайте параметр dataToExtract, чтобы контролировать, какие части файлов индексируются:

    • Значение по умолчанию — contentAndMetadata. Он указывает, что все метаданные и текстовое содержимое, извлеченные из файла, индексируются.

    • StorageMetadata указывает, что индексируются только стандартные свойства файлов и пользовательские метаданные . Хотя свойства задокументированы для больших двоичных объектов Azure, свойства файла одинаковы для OneLkae, за исключением связанных метаданных SAS.

    • "allMetadata" указывает, что стандартные свойства файлов и все метаданные для найденных типов контента извлекаются из содержимого файла и индексируются.

  5. В разделе "Конфигурация" установите параметр "parsingMode", если файлы должны быть сопоставлены с несколькими документами поиска, или если они состоят из обычного текста, документов JSON или CSV-файлов.

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

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

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

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

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

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

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

Ошибки, которые часто возникают во время индексирования, включают неподдерживаемые типы контента, отсутствующие содержимое или перегруженные файлы. По умолчанию индексатор файлов OneLake останавливается, как только он обнаруживает файл с неподдерживаемым типом контента. Однако индексирование может потребоваться продолжить, даже если возникают ошибки, а затем отлаживать отдельные документы позже.

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

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

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

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

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