Использование индексатора BLOB-объектов или источника знаний для приема метаданных областей RBAC (предварительная версия)

Примечание

Поиск с использованием ИИ Azure доступна через портал Azure, REST API и Azure SDKs. Он также лежит в основе Foundry IQ — управляемого слоя знаний, который преобразует корпоративный контент в многократно используемые базы знаний с учетом разрешений доступа для агентов на портале Microsoft Foundry.

Important

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

служба хранилища Azure обеспечивает доступ на основе ролей к контейнерам в хранилище BLOB-объектов, где роли, такие как Storage Data Reader или Storage Blob Data Участник определяет, имеет ли кто-то доступ к содержимому. Поиск с использованием ИИ Azure поддерживает прием разрешений пользователей (предварительная версия) вместе с приемом документов, чтобы можно было использовать эти разрешения для управления доступом к результатам поиска. Если у пользователя нет разрешений на определенный каталог или файл в служба хранилища Azure, этот пользователь не сможет получить доступ к соответствующим документам в результатах Поиск с использованием ИИ Azure, даже если у вас есть назначение Search Index Data Readerна индекс.

  • Начиная с версии 2025-05-01-preview и более поздних, метаданные областей RBAC можно получать с помощью индексатора Blob-объектов.
  • Версия 2025-11-01-preview и более поздние версии обеспечивают эквивалентную поддержку источников знаний Blob в служба хранилища Azure.

Область RBAC устанавливается на уровне контейнера и распространяется на все блобы (документы) через наследование разрешений. Область RBAC фиксируется во время индексирования в виде метаданных разрешений. Api push-уведомлений можно использовать для отправки и индексирования содержимого и метаданных разрешений вручную (см. раздел "Разрешения индексирования с помощью REST API push") или использовать индексатор или источник знаний для автоматизации приема данных. В этой статье рассматривается автоматизация индексирования.

Во время запроса идентификатор вызывающего объекта включается в заголовок запроса с помощью x-ms-query-source-authorization параметра. Удостоверение должно соответствовать метаданным разрешений для документов, чтобы пользователь мог видеть результаты поиска.

В этой статье рассматриваются подходы к автоматизации индексирования, основанные на этом фундаменте:

Необходимые условия

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

  • Поиск с использованием ИИ Azure, любой регион, но для поддержки управляемых удостоверений необходимо иметь оплачиваемый уровень (базовый и более высокий). Служба поиска должна быть настроена для доступа на основе ролей и должна иметь управляемое удостоверение (система или пользователь).

  • служба хранилища Azure, производительность уровня "Стандартный" (общего назначения версии 2) на горячих, холодных и архивных уровнях доступа с контейнерами или блобами, защищёнными с помощью RBAC.

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

Ограничения

Настройка хранилища Blob

Убедитесь, что контейнер BLOB-объектов использует доступ на основе ролей.

  1. Войдите на портал Azure и найдите учетную запись хранения.

  2. Разверните контейнеры и выберите контейнер с BLOB-объектами, которые нужно индексировать.

  3. Выберите контроль доступа (IAM) для проверки назначений ролей. Пользователи и группы с средством чтения данных BLOB-объектов хранилища или участника данных BLOB-объектов хранилища имеют доступ к поиску документов в индексе после индексации контейнера.

Авторизация

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

Помните, что служба поиска должна иметь следующее:

Авторизация

Для выполнения индексатора клиент, который делает вызов API, должен иметь разрешение Search Service Contributor для создания объектов, Search Index Data Contributor для импорта данных и Search Index Data Reader для запроса индекса. См. Подключение к Поиск с использованием ИИ Azure с использованием ролей.

Настройка источника знаний

Если вы используете источник знаний, определения в источнике знаний используются для создания полного конвейера индексирования (индексатора, источника данных и индекса). Область RBAC обнаруживается и автоматически включается в созданный индекс. Если требуется наследование разрешений в индексируемом содержимом, не нужно изменять какие-либо созданные объекты.

Ключевые моменты конфигурации, которые делают это работоспособным для этого сценария:

  • isADLSGen2 имеет значение false, что означает, что источником данных является Хранилище BLOB-объектов Azure.
  • ingestionPermissionOptions указывает rbacScope.
# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": false,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
            "ingestionPermissionOptions": ["rbacScope"],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}

Справка: Создание или обновление источника знаний (REST API)

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

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

Создание источника данных

  • Тип источника данных должен быть azureblob.

  • Режим синтаксического анализа источника данных должен быть по умолчанию.

  • Источник данных должен иметь indexerPermissionOptions и rbacScope.

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

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
        "name": "<your-container-name>",
        "query": "<optional-query-used-for-selecting-specific-blobs>"
    }
}

Пример схемы JSON с управляемым пользователем удостоверением в строка подключения:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
        "name": "<your-container-name>",
        "query": "<optional-query-used-for-selecting-specific-blobs>"
    },
    "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Создание полей разрешений в индексе

В Поиск с использованием ИИ Azure убедитесь, что индекс содержит определения полей для метаданных разрешений. Метаданные разрешений можно индексировать, если indexerPermissionOptions указано в определении источника данных.

Рекомендуемые атрибуты схемы области RBAC:

  • Поле области RBAC со значением permissionFilter rbacScope.
  • Свойство permissionFilterOption для включения фильтрации во время запроса.
  • Использование строковых полей для метаданных разрешений
  • Задайте filterable значение true для всех полей.

Обратите внимание, что retrievable имеет значение «ложь». Вы можете задать значение true во время разработки, чтобы проверить наличие разрешений, но не забудьте вернуть значение false перед развертыванием в рабочей среде, чтобы удостоверения субъектов безопасности не отображались в результатах.

Пример схемы JSON:

{
  ...
  "fields": [
    ...
    { 
        "name": "RbacScope", 
        "type": "Edm.String", 
        "permissionFilter": "rbacScope", 
        "filterable": true, 
        "retrievable": false 
    }
  ],
  "permissionFilterOption": "enabled"
}

Настройка индексатора

Сопоставления полей в индексаторе задают путь к данным полям в индексе. Для полей назначения и назначения, которые различаются по имени или типу данных, требуется явное сопоставление полей. Следующие поля метаданных в Хранилище BLOB-объектов Azure могут потребовать сопоставления полей, если вы изменяете имя поля:

  • metadata_rbac_scope (Edm.String) — область контейнера RBAC.

Укажите fieldMappings в индексаторе, чтобы перенаправить метаданные разрешений в целевые поля во время индексирования.

Пример схемы JSON:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Запуск индексатора

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

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

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

Предполагая отсутствие ошибок, индекс теперь заполнен, и вы можете продолжить с выполнением запросов и тестированием.

Отслеживание удаления

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

См. также

  • Last updated on