将托管标识与 Azure 机器学习 CLI v1 结合使用

项目
09/13/2024

适用于：Python SDK azureml v1

适用于：Azure CLI ml 扩展 v1

通过托管标识，可以使用访问资源所需的最低权限配置工作区。

以可信方式配置 Azure 机器学习工作区时，务必确保与工作区关联的不同服务具有正确的访问级别。例如，在机器学习工作流期间，工作区需要访问用于 Docker 映像的 Azure 容器注册表 (ACR) 和用于训练数据的存储帐户。

此外，托管标识支持对权限进行精细控制，例如，可以授予或撤消从特定的计算资源对特定 ACR 的访问权限。

本文介绍如何使用托管标识执行以下操作：

为 Azure 机器学习工作区配置和使用 ACR，无需让管理员用户访问 ACR。
访问工作区外部的专有 ACR，以拉取用于训练或推理的基础映像。
创建具有用户分配的托管标识的工作区以访问关联的资源。

先决条件

Azure 机器学习工作区。有关详细信息，请参阅创建工作区资源。
用于机器学习服务的 Azure CLI 扩展

重要

本文中的一些 Azure CLI 命令使用适用于 Azure 机器学习的 azure-cli-ml 或 v1 扩展。对 v1 扩展的支持将于 2025 年 9 月 30 日结束。在该日期之前，你将能够安装和使用 v1 扩展。

建议在 2025 年 9 月 30 日之前转换为 ml 或 v2 扩展。有关 v2 扩展的详细信息，请参阅 Azure ML CLI 扩展和 Python SDK v2。
Azure 机器学习 Python SDK。
若要分配角色，Azure 订阅登录名必须具有托管标识操作员角色或授予所需操作的其他角色（如所有者）。
必须熟悉如何创建和使用托管标识。

配置托管标识

在某些情况下，必须禁止管理员用户对 Azure 容器注册表的访问。例如，可能共享了 ACR，你需要禁止其他用户进行管理访问。或者，订阅级别策略不允许创建启用了管理员用户的 ACR。

重要

使用 Azure 机器学习在 Azure 容器实例 (ACI) 上进行推理时，需要 ACR 上的管理员用户访问权限。如果计划将模型部署到 ACI 进行推理，请不要禁用此功能。

在不启用管理员用户访问权限的情况下创建 ACR 时，将使用托管标识来访问 ACR 以生成和拉取 Docker 映像。

创建工作区时，可以在禁用管理员用户的情况下自带 ACR。或者，让 Azure 机器学习创建工作区 ACR，以后再禁用管理员用户。

自带 ACR

如果订阅策略不允许使用 ACR 管理员用户，则应首先创建无管理员用户的 ACR，然后将其与工作区关联。此外，如果有已禁用管理员用户的现有 ACR，可以将其附加到工作区。

从 Azure CLI 创建 ACR，无需设置 --admin-enabled 参数，或从 Azure 门户创建，无需启用管理员用户。然后，在创建 Azure 机器学习工作区时，指定 ACR 的 Azure 资源 ID。下面的示例演示如何创建使用现有 ACR 的新 Azure 机器学习工作区：

提示

若要获取 --container-registry 参数的值，请使用 az acr show 命令显示 ACR 的信息。 id 字段包含 ACR 的资源 ID。

az ml workspace create -w <workspace name> \
-g <workspace resource group> \
-l <region> \
--container-registry /subscriptions/<subscription id>/resourceGroups/<acr resource group>/providers/Microsoft.ContainerRegistry/registries/<acr name>

让 Azure 机器学习服务创建工作区 ACR

如果没有自带 ACR，Azure 机器学习服务将在执行需要 ACR 的操作时创建一个 ACR。例如，将训练运行提交到机器学习计算、生成环境或部署 web 服务终结点。工作区创建的 ACR 将启用管理员用户，你需要手动禁用管理员用户。

创建新的工作区

az ml workspace show -n <my workspace> -g <my resource group>

执行需要 ACR 的操作。例如，训练模型教程。

获取由群集创建的 ACR 名称：

az ml workspace show -w <my workspace> \
-g <my resource group>
--query containerRegistry

此命令返回类似于以下文本的值。只需要文本的最后一部分，即 ACR 实例名称：

/subscriptions/<subscription id>/resourceGroups/<my resource group>/providers/MicrosoftContainerReggistry/registries/<ACR instance name>

更新 ACR 以禁用管理员用户：

az acr update --name <ACR instance name> --admin-enabled false

使用托管标识创建计算以访问用于训练的 Docker 映像

若要访问工作区 ACR，请创建启用了系统分配的托管标识的机器学习计算群集。可以在创建计算时从 Azure 门户或工作室启用该标识，也可以通过以下方法从 Azure CLI 启用。有关详细信息，请参阅将托管标识用于计算群集。

使用 AmlComputeProvisioningConfiguration 创建计算群集时，请使用 identity_type 参数设置托管标识类型。

适用于：Azure CLI ml 扩展 v1

az ml computetarget create amlcompute --name <cluster name> -w <workspace> -g <resource group> --vm-size <vm sku> --assign-identity '[system]'

托管标识在工作区 ACR 上自动被授予 ACRPull 角色，以允许拉取 Docker 映像进行训练。

注意

如果首先创建计算，则必须手动分配 ACRPull 角色，才能创建工作区 ACR。

从专用 ACR 访问基础映像

默认情况下，Azure 机器学习使用来自 Azure 托管的公共存储库中的 Docker 基础映像。然后，在这些映像上生成训练或推理环境。有关详细信息，请参阅什么是 ML 环境？。

若要在企业内部使用自定义基础映像，可以使用托管标识访问专用 ACR。下面是两个用例：

使用基础映像按原样进行训练。
使用自定义映像作为基础生成 Azure 机器学习托管映像。

将 Docker 基础映像拉取到机器学习计算群集按原样进行训练

如前面所述，创建启用了系统分配的托管标识的机器学习计算群集。然后，确定托管标识的主体 ID。

适用于：Azure CLI ml 扩展 v1

az ml computetarget amlcompute identity show --name <cluster name> -w <workspace> -g <resource group>

或者，可以更新计算群集来分配用户分配的托管标识：

适用于：Azure CLI ml 扩展 v1

az ml computetarget amlcompute identity assign --name <cluster name> \
-w $mlws -g $mlrg --identities <my-identity-id>

若要允许计算群集拉取基础映像，请在专用 ACR 上授予托管服务标识 ACRPull 角色

az role assignment create --assignee <principal ID> \
--role acrpull \
--scope "/subscriptions/<subscription ID>/resourceGroups/<private ACR resource group>/providers/Microsoft.ContainerRegistry/registries/<private ACR name>"

最后，在提交训练运行时，请在环境定义中指定基础映像位置。

适用于：Python SDK azureml v1

from azureml.core import Environment
env = Environment(name="private-acr")
env.docker.base_image = "<ACR name>.azurecr.cn/<base image repository>/<base image version>"
env.python.user_managed_dependencies = True

重要

若要确保基础映像直接拉取到计算资源，请设置 user_managed_dependencies = True，并且不要指定 Dockerfile。否则 Azure 机器学习服务将尝试生成新的 Docker 映像并失败，因为只有计算群集才能从 ACR 中拉取基础映像。

从专用 ACR 生成 Azure 机器学习托管环境到基础映像以进行训练或推理

适用于：Azure CLI ml 扩展 v1

在此场景中，Azure 机器学习服务在从专用 ACR 提供的基础映像之上生成训练或推理环境。由于映像生成任务是在工作区 ACR 上使用 ACR 任务来执行的，因此需要执行更多步骤来允许访问。

创建用户分配的托管标识并向该标识授予对专用 ACR 的 ACRPull 访问权限。
向工作区系统分配的托管标识授予上一步中用户分配的托管标识上的托管标识操作员角色。此角色允许工作区将用户分配的托管标识分配给 ACR 任务用于生成托管环境。
1. 获取工作区系统分配的托管标识的主体 ID：
```
az ml workspace show -w <workspace name> -g <resource group> --query identityPrincipalId
```
2. 授予托管标识操作员角色：
```
az role assignment create --assignee <principal ID> --role managedidentityoperator --scope <user-assigned managed identity resource ID>
```
  用户分配的托管标识资源 ID 是用户分配的标识的 Azure 资源 ID，采用 /subscriptions/<subscription ID>/resourceGroups/<resource group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned managed identity name> 格式。

使用方法在工作区连接中指定用户分配的托管标识的外部 ACR 和客户端 ID：

适用于：Python SDK azureml v1

workspace.set_connection(
    name="privateAcr", 
    category="ACR", 
    target = "<acr url>", 
    authType = "RegistryConnection", 
    value={"ResourceId": "<user-assigned managed identity resource id>", "ClientId": "<user-assigned managed identity client ID>"})

完成配置后，可以在生成用于训练或推理的环境时使用专用 ACR 中的基础映像。下面的代码片段演示如何在环境定义中指定基础映像 ACR 和映像名称：

适用于：Python SDK azureml v1

from azureml.core import Environment

env = Environment(name="my-env")
env.docker.base_image = "<acr url>/my-repo/my-image:latest"

或者，可以使用 RegistryIdentity 在环境定义本身中指定托管标识资源 URL 和客户端 ID。如果显式使用注册表标识，则它会替代前面指定的任何工作区连接：

适用于：Python SDK azureml v1

from azureml.core.container_registry import RegistryIdentity

identity = RegistryIdentity()
identity.resource_id= "<user-assigned managed identity resource ID>"
identity.client_id="<user-assigned managed identity client ID>"
env.docker.base_image_registry.registry_identity=identity
env.docker.base_image = "my-acr.azurecr.cn/my-repo/my-image:latest"

使用 Docker 映像进行推理

如前面所述，在没有管理员用户的情况下配置 ACR 后，可以访问 Docker 映像进行推理，无需 Azure Kubernetes service (AKS) 中的管理密钥。创建 AKS 或将其附加到工作区时，会自动为该群集的服务主体分配对工作区 ACR 的 ACRPull 访问权限。

注意

如果自带 AKS 群集，则群集必须已启用服务主体而不是托管标识。

创建具有用户分配的托管标识的工作区

创建工作区时，可以引入你自己的用户分配的托管标识，该标识将用于访问关联的资源：ACR、KeyVault、存储和 App Insights。

重要

使用用户分配的托管标识创建工作区时，必须自行创建关联的资源，并对这些资源授予托管标识角色。使用角色分配 ARM 模板进行分配。

使用 Azure CLI 或 Python SDK 创建工作区。使用 CLI 时，使用 --primary-user-assigned-identity 参数指定 ID。使用 SDK 时，请使用 primary_user_assigned_identity。以下是使用 Azure CLI 和 Python 通过以下参数创建新工作区的示例：

Azure CLI

适用于：Azure CLI ml 扩展 v1

az ml workspace create -w <workspace name> -g <resource group> --primary-user-assigned-identity <managed identity ARM ID>

Python

适用于：Python SDK azureml v1

from azureml.core import Workspace

ws = Workspace.create(name="workspace name", 
    subscription_id="subscription id", 
    resource_group="resource group name",
    primary_user_assigned_identity="managed identity ARM ID")

还可以使用 ARM 模板创建具有用户分配的托管标识的工作区。

对于具有用于加密的客户管理的密钥的工作区，可以传入用户分配的托管标识以从存储向密钥保管库进行身份验证。使用参数 user-assigned-identity-for-cmk-encryption (CLI) 或 user_assigned_identity_for_cmk_encryption (SDK) 来传递托管标识。此托管标识可与工作区主要用户分配的托管标识相同，也可不同。

通过

将托管标识与 Azure 机器学习 CLI v1 结合使用

先决条件

配置托管标识

自带 ACR

让 Azure 机器学习服务创建工作区 ACR

使用托管标识创建计算以访问用于训练的 Docker 映像

从专用 ACR 访问基础映像

将 Docker 基础映像拉取到机器学习计算群集按原样进行训练

从专用 ACR 生成 Azure 机器学习托管环境到基础映像以进行训练或推理

使用 Docker 映像进行推理

创建具有用户分配的托管标识的工作区

后续步骤

其他资源