在 Azure AI 搜索中配置搜索服务以使用托管标识进行连接

项目
08/12/2024

重要

用户分配的托管标识分配目前以公共预览版提供，使用它需要遵守《补充使用条款》。管理预览版 REST API 为 Azure AI 搜索提供用户分配的托管标识分配。对系统分配的托管标识的支持已正式发布。

你可以将 Microsoft Entra ID 和角色分配用于从 Azure AI 搜索到在索引或查询期间提供数据、应用的 AI 或矢量化的资源的出站连接。

若要在出站连接上使用角色，请先将搜索服务配置为使用系统分配的托管标识或用户分配的托管标识作为Microsoft Entra 租户中搜索服务的安全原则。获得托管标识后，你可以为授权的访问分配角色。使用托管标识和角色分配，便无需在连接字符串或代码中传递机密和凭据。

先决条件

基本层或更高层的搜索服务（任何区域中）。
一种 Azure 资源，用于接受来自具有有效角色分配的 Microsoft Entra 安全主体的传入请求。

支持的方案

Azure AI 搜索可以连接到其系统分配的或用户分配的托管标识下的其他 Azure 资源。

对系统分配的托管标识的搜索服务配置已正式发布。
用户分配的托管标识的搜索服务配置目前以公共预览版提供，使用它需要遵守补充使用条款。
托管标识（无论是系统还是用户分配）的数据平面使用情况已正式发布。例如，如果想要对索引器数据源连接、密钥保管库、调试会话或扩充缓存使用用户分配的托管标识，则可以使用正式版 REST API 版本来创建连接，前提是你所使用的功能也已正式发布。

当连接字符串是 Microsoft Entra ID 感知服务或应用程序的唯一资源 ID 时，将指示系统管理标识。用户分配的托管标识是通过“标识”属性指定的。

搜索服务使用 Azure 存储作为索引器数据源，并用作调试会话、扩充缓存和知识存储的数据接收器。对于写回存储的搜索功能，托管标识需要参与者角色分配，如“分配角色”部分中所述。

场景	系统	用户分配
与受支持的 Azure 数据源的索引器连接 ¹	是	是
用于客户管理的密钥的 Azure 密钥保管库	是	是
调试会话（托管在 Azure 存储中）¹	是	否
扩充缓存（托管在 Azure 存储中）^1，²	是	是
知识存储（托管在 Azure 存储中）¹	是	是
连接到 Azure OpenAI 或 Azure AI ³	是	是

¹ 对于搜索和存储之间的连接，网络安全配置会对可使用的托管标识类型进行约束。只有系统托管标识可用于通过受信任的服务异常或资源实例规则与存储建立同区域连接。有关详细信息，请参阅访问受网络保护的存储帐户。

² AI 搜索服务当前无法连接到共享密钥访问已关闭的存储帐户上的表。

³ 与 Azure OpenAI 或 Azure AI 的连接包括：自定义技能、自定义向量器、Azure OpenAI 嵌入技能、Azure OpenAI 向量器、Azure AI Studio 模型目录向量器、Azure AI 视觉多模式嵌入技能、Azure AI 视觉向量器。

创建系统托管标识

启用系统分配的托管标识后，Microsoft Entra ID 将为搜索服务创建一个标识，用于对同一租户和订阅中的其他 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.chinacloudapi.cn/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2024-07-01
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

响应中会返回确认和系统托管标识的对象标识符。

有关详细信息，请参阅创建或更新服务（管理 REST API）。

创建用户分配的托管标识

重要

此方案的部分内容目前以公共预览版提供，使用它需要遵守《补充使用条款》。管理预览版 REST API 为 Azure AI 搜索提供用户分配的托管标识配置。

用户分配的托管标识是 Azure 上的一种资源。如果需要更精细地分配用户，可以创建多个用户分配的托管标识。例如，你可能希望针对不同的应用程序和方案使用单独的标识。

步骤如下：

在 Azure 订阅中，创建用户分配的托管标识。
在搜索服务中，更新服务定义以启用用户分配的托管标识（此步骤为预览版）。
在其他要连接到的 Azure 服务中，为标识创建角色分配。
在 Azure AI 搜索的数据源连接（例如索引器数据源）中，引用连接详细信息中的用户托管标识（如果对该功能的支持已正式发布，则此步骤已正式发布）。

用户分配的托管标识可以限定为订阅、资源组或资源类型。

Azure 门户、管理 REST API 预览版和提供相应功能的 beta SDK 包支持关联用户分配的托管标识。

Azure 门户
REST API

登录到 Azure 门户
选择“创建资源”。
在“搜索服务和市场”搜索栏中，搜索“用户分配的托管标识”，然后选择“创建”。
选择订阅、资源组和区域。为标识提供描述性名称。
选择“创建”，并等待资源完成部署。

使用标识前需要几分钟时间。
在搜索服务页面的“设置”下，选择“标识”。
在“用户分配”选项卡上，选择“添加”。
选择订阅，然后选择在上一步中创建的用户分配的托管资源。

你可以使用预览版管理 REST API 代替门户来分配用户分配的托管标识。使用 API 版本 2021-04-01-preview 或更高版本。本示例使用 2024-06-01-preview。

构建更新搜索服务的请求。

PUT https://management.chinacloudapi.cn/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]": {}
    }
  }
}

设置“标识”属性以指定完全限定的托管标识：
- “类型”是标识的类型。如果要想同时使用两者，则有效值为“SystemAssigned”、“UserAssigned”或“SystemAssigned、UserAssigned”。如果值为“None”，将从搜索服务中清除所有先前分配的标识。
- “userAssignedIdentities”包括用户分配的托管标识的详细信息。此标识必须已存在，你才能在更新服务请求中指定它。

分配角色

获得托管标识后，分配用于确定 Azure 资源的搜索服务权限的角色。

索引器数据连接，以及访问 Azure 密钥保管库中客户管理的密钥都需要读取者权限。
使用 Azure 存储托管调试会话数据、扩充缓存和知识存储中的长期内容存储的 AI 扩充功能需要写入权限。

下面的步骤演示了角色分配的工作流。此示例适用于 Azure OpenAI。有关其他 Azure 资源，请参阅连接到 Azure 存储、连接到 Azure Cosmos DB 或连接到 Azure SQL。

使用 Azure 帐户登录到 Azure 门户，并转到 Azure OpenAI 资源。
在左侧菜单中选择“访问控制”。
依次选择“添加”、“添加角色分配”。
在“工作职能角色”下，选择“认知服务 OpenAI 用户”，然后选择“下一步”。
在“成员”下，选择“托管标识”，然后选择“成员”。
按订阅和资源类型（搜索服务）进行筛选，然后选择搜索服务的托管标识。
选择“查看 + 分配”。

连接字符串示例

为搜索服务定义托管标识并提供角色分配后，可以将出站连接修改为使用其他 Azure 资源的唯一资源 ID。下面是各种方案的连接字符串的一些示例。

可以将正式版 REST API 版本和 Azure SDK 包用于这些连接。

提示

可以在 Azure 门户中创建大部分对象，并指定系统或用户分配的托管标识，然后查看 JSON 定义以获取连接字符串。

Blob 数据源（系统）：

索引器数据源包括“凭据”属性，可以确定如何与数据源建立连接。以下示例显示了一个连接字符串，该字符串指定存储帐户的唯一资源 ID。

Microsoft Entra ID 将使用搜索服务的系统托管标识对请求进行身份验证。请注意，连接字符串不包含容器。在数据源定义中，容器名称是在“容器”属性（未显示）中指定的，而不是在连接字符串中指定的。

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

Blob 数据源（用户）：

也可以在用户分配的托管标识下发出对 Azure 存储的搜索请求。搜索服务用户标识在“标识”属性中指定。

"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 存储的连接字符串。此连接字符串是存储帐户的唯一资源 ID。请注意，该字符串没有在路径中包括容器或表。它们是在嵌入的投影定义中定义的，而不是在连接字符串中定义的。

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

扩充缓存：

索引器创建、使用并记住用于缓存扩充的容器。没有必要在缓存连接字符串中包括容器。可以在门户中搜索服务的“标识”页上找到对象 ID。

"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”可使搜索服务使用托管标识进行连接，并在属性中传递目标函数或应用的应用程序 ID。

{
  "@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 矢量器：

AI 搜索中的 Azure OpenAI 嵌入技能和矢量器以托管嵌入模型的 Azure OpenAI 服务的终结点为目标。终结点在 Azure OpenAI 嵌入技能定义和/或 Azure OpenAI 矢量器定义中进行指定。如果已配置，并且“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 资源位于防火墙后面，请确保有一个入站规则来接受来自你的搜索服务的请求。

对于与 Azure Blob 存储或 Azure Data Lake Storage Gen2 的同区域连接，请使用托管标识和受信任的服务异常。（可选）可以配置资源实例规则来允许请求。
对于所有其他资源和连接，配置 IP 防火墙规则来接受来自搜索的请求。有关详细信息，请参阅索引器访问受 Azure 网络安全功能保护的内容。

通过