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

Статья
09/11/2024

Внимание

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

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

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

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

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

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

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

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

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

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

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

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

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

³ Подключения к Azure OpenAI, Azure AI Studio и Функции Azure с помощью навыков и векторизаторов: настраиваемый навык, настраиваемый векторизатор Azure OpenAI, векторизатор Azure OpenAI, навык AML и векторизатор моделей Azure AI Studio.

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

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

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

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

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

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

Дополнительные сведения см. в статье "Создание службы поиска с управляемым удостоверением, назначаемого системой" (Azure PowerShell).

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

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

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

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"
  }
}

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

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

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

Внимание

Часть этого сценария доступна в общедоступной предварительной версии в разделе "Дополнительные условия использования". REST API для управления предварительной версии предоставляет конфигурацию управляемого удостоверения, назначаемого пользователем, для поиска ИИ Azure.

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

Ниже приведены действия.

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

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

Связывание управляемого удостоверения, назначаемого пользователем, поддерживается в портал Azure, в предварительных версиях REST API управления и в бета-версиях пакетов SDK, которые предоставляют эту функцию.

Портал Azure
REST API

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

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

Для назначения управляемого удостоверения, назначаемого пользователем, можно использовать REST API управления предварительной версией. Используйте версии 2021-04-01-preview API или более поздней версии. В этом примере используется 2024-06-01-preview.

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

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2024-06-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 для обоих. Значение None очищает все ранее назначенные удостоверения из службы поиска.
- "userAssignedIdentities" содержит сведения о назначаемом пользователем управляемом удостоверении. Это удостоверение уже должно существовать , прежде чем можно указать его в запросе службы обновления.

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

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

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

Следующие шаги иллюстрируют рабочий процесс назначения ролей. Этот пример предназначен для Azure OpenAI. Сведения о других ресурсах Azure см. в статье "Подключение к служба хранилища Azure", "Подключение к Azure Cosmos DB" или "Подключение к SQL Azure".

Войдите в портал Azure с помощью учетной записи Azure и перейдите к ресурсу Azure OpenAI.
Выберите элемент управления доступом в меню слева.
Выберите Добавить, затем выберите Добавить назначение ролей.
В разделе "Роли функции задания" выберите "Пользователь OpenAI" Cognitive Services и нажмите кнопку "Далее".
В разделе "Участники" выберите управляемое удостоверение и выберите "Участники".
Фильтруйте по подписке и типу ресурсов (служба ), а затем выберите управляемое удостоверение службы поиска.
Выберите Проверить + назначить.

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

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

Для этих подключений можно использовать общедоступную версию REST API и пакеты azure SDK.

Совет

Большинство этих объектов можно создать в портал Azure, указав управляемое удостоверение, назначаемое системой или пользователем, а затем просмотреть определение JSON, чтобы получить строка подключения.

Источник данных 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.

"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. Строка подключения — это уникальный идентификатор ресурса учетной записи хранения. Обратите внимание, что строка не включает контейнеры или таблицы в путь. Они определены в определении внедренной проекции, а не в строка подключения.

"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",
  "modelName": "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",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

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

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

Проверка доступа к брандмауэру

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

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

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