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

Статья
04/02/2024

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

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

Служба поиска на уровне "Базовый" или выше.
Ресурс Azure, принимаюющий входящие запросы из имени входа Microsoft Entra с допустимым назначением ролей.

Поддерживаемые сценарии

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

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

Сценарий	Управляемое удостоверение системы	Управляемое удостоверение, назначаемое пользователем (предварительная версия)
Подключения индексатора к поддерживаемым источникам^{данных Azure 1}³	Да	Да
Azure Key Vault для ключей, управляемых клиентом	Да	Да
Сеансы отладки (размещенные в служба хранилища Azure)¹	Да	Нет
Кэш обогащения (размещен в служба хранилища Azure)^1,2	Да	Да
Хранилище знаний (размещено в служба хранилища Azure)¹	Да	Да
Пользовательские навыки (размещенные в Функции Azure или эквивалентных)	Да	Да
Навык внедрения Azure OpenAI	Да	Да
Векторизатор Azure OpenAI	Да	Да

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

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

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

Создание управляемого удостоверения системы

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

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

Войдите в портал Azure и найдите службу поиска.
В разделе Параметры выберите пункт Удостоверение.
На вкладке " Назначенная системой" в разделе "Состояние" выберите "Вкл.".
Выберите Сохранить.

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

См. статью "Создание или обновление службы " (REST API управления)".

Rest API управления можно использовать вместо портала, чтобы назначить управляемое удостоверение, назначаемое пользователем.

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

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

Подтверждение и идентификатор объекта для управляемого удостоверения системы возвращается в ответе.

Создание управляемого удостоверения, назначаемого пользователем (предварительная версия)

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

Внимание

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

Портал Azure
REST API

Войдите на портал Azure
Щелкните + Создать ресурс.
В строке поиска "Поиск по службам и marketplace" выполните поиск по запросу "управляемое удостоверение, назначаемое пользователем", а затем выберите Создать.
Выберите подписку, группу ресурсов и регион. Введите описательное имя удостоверения.
Нажмите кнопку "Создать " и дождитесь завершения развертывания ресурса.

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

Rest API управления можно использовать вместо портала, чтобы назначить управляемое удостоверение, назначаемое пользователем. Не забудьте использовать версию 2021-04-01-preview для этой задачи.

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

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2021-04-01-preview
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

Задайте свойство identity, чтобы указать полное управляемое удостоверение:
- "type" — это тип удостоверения. Допустимые значения: SystemAssigned, UserAssigned или SystemAssigned, UserAssigned для обоих. Значение "Нет" приведет к очистке всех ранее назначенных удостоверений из службы поиска.
- "userAssignedIdentities" содержит сведения о назначаемом пользователем управляемом удостоверении. Это удостоверение уже должно существовать , прежде чем можно указать его в запросе службы создания или обновления.

Разрешить доступ к брандмауэру

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

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

Назначение роли

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

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

Следующие действия предназначены для служба хранилища Azure. Если ресурс — Azure Cosmos DB или AZURE SQL, эти действия аналогичны.

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

На странице "Роль" выберите роли, необходимые для службы поиска:

Задача	Назначение ролей
Индексирование BLOB-объектов с помощью индексатора	Добавление средства чтения данных BLOB-объектов служба хранилища
Индексирование ADLS 2-го поколения с помощью индексатора	Добавление средства чтения данных BLOB-объектов служба хранилища
Индексирование таблиц с помощью индексатора	Добавление средства чтения и доступа к данным
Индексирование файлов с помощью индексатора	Добавление средства чтения и доступа к данным
Запись в хранилище знаний	Добавьте служба хранилища DataContributor для проекций объектов и файлов, а также средства чтения и доступа к данным для проекций таблиц.
Запись в кэш обогащения	Добавление участника данных BLOB-объектов служба хранилища
Сохранение состояния сеанса отладки	Добавление участника данных BLOB-объектов служба хранилища
Внедрение данных (векторизация) с помощью моделей внедрения Azure OpenAI	Добавление пользователя OpenAI в Cognitive Services

На странице "Участники" выберите "Управляемое удостоверение".
Выберите участников. На странице "Выбор управляемого удостоверения" выберите подписку, а затем отфильтруйте по типу службы, а затем выберите службу. Для выбора будут доступны только те службы, у которых есть управляемое удостоверение.
Выберите Проверить + назначить.

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

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

Источник данных BLOB-объектов (система):

Источник данных индексатора содержит свойство credentials, определяющее способ подключения к источнику данных. В следующем примере показана строка подключения указание уникального идентификатора ресурса учетной записи хранения. Идентификатор Microsoft Entra будет проходить проверку подлинности запроса с помощью системного управляемого удостоверения службы поиска. Обратите внимание, что строка подключения не включает контейнер. В определении источника данных имя контейнера указывается в свойстве "container" (не отображается), а не в строка подключения.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

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

Запрос поиска для служба хранилища Azure также можно выполнить в управляемом удостоверении, назначаемом пользователем, в настоящее время в предварительной версии. Удостоверение пользователя службы поиска указывается в свойстве identity. Для задания удостоверения можно использовать портал или REST Предварительная версия API версии 2021-04-30-Preview.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"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. В служба хранилища Azure хранилище знаний создаст проекции в виде больших двоичных объектов и таблиц. Строка подключения — это уникальный идентификатор ресурса учетной записи хранения. Обратите внимание, что строка не включает контейнеры или таблицы в путь. Они определены в определении внедренной проекции, а не в строка подключения.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

Кэш обогащения:

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

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Сеанс отладки:

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

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Пользовательский навык:

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

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Навык внедрения Azure OpenAI и векторизатор Azure OpenAI:

Интерфейс Azure OpenAI, встраивающий навыки и векторизаторы в поиск ИИ, нацелен на конечную точку службы Azure OpenAI, в котором размещена модель внедрения. Конечная точка указана в определении навыка внедрения Azure OpenAI и (или) в определении векторизатора OpenAI Azure. Управляемое системой удостоверение используется, если настроено и если apikey и authIdentity пусты. Свойство authIdentity используется только для управляемого удостоверения, назначаемого пользователем.

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002"
      }
    }
  ]