使用 Azure CLI 管理 Azure 机器学习工作区

适用于:Azure CLI ml 扩展 v2(当前版本)

本文介绍如何使用 Azure CLI 创建和管理 Azure 机器学习工作区。 Azure CLI 提供了一些命令来管理 Azure 资源,这些命令旨在让用户快速使用 Azure(侧重于自动化)。 CLI 的机器学习扩展提供用于处理 Azure 机器学习资源的命令。

还可以通过 Azure 门户和 Python SDKAzure PowerShellVS Code 扩展来管理工作区。

先决条件

  • 一个 Azure 订阅。 如果没有 Azure 订阅,请尝试试用版订阅

  • 若要从本地环境使用本文档中的 CLI 命令,需要使用 Azure CLI

限制

  • 创建新的工作区时,可以自动创建工作区所需的服务或使用现有的服务。 如果要使用来自不同于工作区所在的 Azure 订阅的现有服务,则必须在包含这些服务的订阅中注册 Azure 机器学习命名空间。 例如,在订阅 A 中创建一个使用订阅 B 中的存储帐户的工作区时,必须在订阅 B 中注册 Azure 机器学习命名空间,然后才能将此存储帐户用于该工作区。

    Azure 机器学习的资源提供程序是 Microsoft.MachineLearningServices。 有关如何查看它是否已注册以及如何注册的信息,请参阅 Azure 资源提供程序和类型一文。

    重要

    这仅适用于工作区创建期间提供的资源:Azure 存储帐户、Azure 容器注册表、Azure Key Vault 和 Application Insights。

提示

创建工作区时,将创建一个 Azure Application Insights 实例。 如果需要,可以在创建群集后删除 Application Insights 实例。 删除它会限制从工作区收集的信息,并且可能会使问题解决起来更加困难。 如果删除工作区创建的 Application Insights 实例,则无法在不删除和重新创建工作区的情况下重新创建实例。

有关使用此 Application Insights 实例的详细信息,请参阅从机器学习 Web 服务终结点监视和收集数据

保护 CLI 通信

某些 Azure CLI 命令通过 Internet 与 Azure 资源管理器通信。 此通信使用 HTTPS/TLS 1.2 进行保护。

使用 Azure 机器学习 CLI 扩展 v2 ('ml'),所有命令都与 Azure 资源管理器通信。 这包括操作数据(如 YAML 参数和元数据)。 如果 Azure 机器学习工作区是公共的(也就是说,不是在虚拟网络后面),则不需要额外配置。 通信使用 HTTPS/TLS 1.2 进行保护。

如果 Azure 机器学习工作区使用专用终结点和虚拟网络,并且使用的是 CLI v2,请选择以下配置之一来使用:

  • 如果“可以”通过公共 Internet 进行 CLI v2 通信,请对 az ml workspace update 命令使用以下 --public-network-access 参数来启用公用网络访问。 例如,以下命令将更新工作区的公用网络访问:

    az ml workspace update --name myworkspace --public-network-access enabled
    

有关 CLI v2 通信的详细信息,请参阅安装和设置 CLI

将 CLI 连接到 Azure 订阅

可通过多种方法从 CLI 对 Azure 订阅进行身份验证。 最简单的方法是使用浏览器进行交互式身份验证。 若要以交互方式进行身份验证,请打开命令行或终端,然后使用以下命令:

az login

如果 CLI 可以打开默认的浏览器,则它会打开该浏览器并加载登录页。 否则,需要打开浏览器并按照命令行中的说明操作。 按说明操作时,需要浏览到 https://aka.ms/deviceloginchina 并输入授权代码。

提示

登录后,你将看到与你的 Azure 帐户关联的订阅列表。 在 isDefault: true 的情况下显示的订阅信息是 Azure CLI 命令的当前已激活的订阅。 此订阅必须与包含 Azure 机器学习工作区的订阅相同。 可以通过访问工作区的概述页面从 Azure 门户找到订阅 ID。

若要选择另一个订阅,请使用 az account set -s <subscription name or ID> 命令并指定要切换到的订阅名称或 ID。 有关订阅选择的详细信息,请参阅使用多个 Azure 订阅

有关其他身份验证方法,请参阅使用 Azure CLI 登录

创建资源组

必须在资源组中创建 Azure 机器学习工作区。 可以使用现有资源组,也可以创建新组。 若要创建新的资源组,请使用以下命令。 将 <resource-group-name> 替换为此资源组使用的名称。 将 <location> 替换为此资源组使用的 Azure 区域:

注意

应选择可使用 Azure 机器学习的区域。 有关详细信息,请参阅 各区域的产品可用性

az group create --name <resource-group-name> --location <location>

此命令的响应类似于以下 JSON。 可以使用输出值来查找创建的资源,或将其解析为后续 CLI 步骤的输入以实现自动化。

{
  "id": "/subscriptions/<subscription-GUID>/resourceGroups/<resourcegroupname>",
  "location": "<location>",
  "managedBy": null,
  "name": "<resource-group-name>",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": null
}

要详细了解如何使用资源组,请参阅 az group

创建工作区

部署 Azure 机器学习工作区时,需要各种其他服务作为依赖的相关资源。 使用 CLI 创建工作区时,CLI 可以代表你创建新的关联资源,你也可以附加现有资源。

重要

附加自己的存储帐户时,请确保它满足以下条件:

  • 存储帐户不是高级帐户(Premium_LRS 和 Premium_GRS)
  • Azure Blob 和 Azure 文件功能同时启用
  • 分层命名空间 (ADLS Gen 2) 已禁用。这些要求仅适用于工作区使用的默认存储帐户。

附加 Azure 容器注册表时,必须先为容器注册表启用管理员帐户,然后才能将其用于 Azure 机器学习工作区。

若要创建将在其中自动创建服务的新工作区,请使用以下命令:

az ml workspace create -n <workspace-name> -g <resource-group-name>

重要

附加现有资源时,不必指定所有资源。 可以指定一个或多个资源。 例如,可以指定某个现有存储帐户,工作区会创建其他资源。

工作区创建命令的输出类似于以下 JSON。 可以使用输出值来查找创建的资源,或将其解析为后续 CLI 步骤的输入。

{
  "applicationInsights": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.insights/components/<application-insight-name>",
  "containerRegistry": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.containerregistry/registries/<acr-name>",
  "creationTime": "2019-08-30T20:24:19.6984254+00:00",
  "description": "",
  "friendlyName": "<workspace-name>",
  "id": "/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>",
  "identityPrincipalId": "<GUID>",
  "identityTenantId": "<GUID>",
  "identityType": "SystemAssigned",
  "keyVault": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.keyvault/vaults/<key-vault-name>",
  "location": "<location>",
  "name": "<workspace-name>",
  "resourceGroup": "<resource-group-name>",
  "storageAccount": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.storage/storageaccounts/<storage-account-name>",
  "type": "Microsoft.MachineLearningServices/workspaces",
  "workspaceid": "<GUID>"
}

高级配置

为专用网络连接配置工作区

根据用例和组织要求,可以选择使用专用网络连接来配置 Azure 机器学习。 可以使用 Azure CLI 为工作区资源部署工作区和专用链接终结点。 有关将专用终结点和虚拟网络 (VNet) 与工作区结合使用的详细信息,请参阅虚拟网络隔离和隐私概述。 有关复杂的资源配置,另请参阅基于模板的部署选项,包括 Azure 资源管理器

使用专用链接时,工作区无法使用 Azure 容器注册表来生成 docker 映像。 因此,必须将 image_build_compute 属性设置为 CPU 计算群集名称,以用于生成 Docker 映像环境。 还可以使用 public_network_access 属性指定是否应通过 Internet 访问专用链接工作区。

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-privatelink-prod
location: chinaeast2
display_name: Private Link endpoint workspace-example
description: When using private link, you must set the image_build_compute property to a cluster name to use for Docker image environment building. You can also specify whether the workspace should be accessible over the internet.
image_build_compute: cpu-compute
public_network_access: Disabled
tags:
  purpose: demonstration
az ml workspace create -g <resource-group-name> --file privatelink.yml

创建工作区后,使用 Azure 网络 CLI 命令为工作区创建专用链接终结点。

az network private-endpoint create \
    --name <private-endpoint-name> \
    --vnet-name <vnet-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id "/subscriptions/<subscription>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>" \
    --group-id amlworkspace \
    --connection-name workspace -l <location>

若要为工作区创建专用 DNS 区域条目,请使用以下命令:

# Add privatelink.api.ml.azure.cn
az network private-dns zone create \
    -g <resource-group-name> \
    --name 'privatelink.api.ml.azure.cn'

az network private-dns link vnet create \
    -g <resource-group-name> \
    --zone-name 'privatelink.api.ml.azure.cn' \
    --name <link-name> \
    --virtual-network <vnet-name> \
    --registration-enabled false

az network private-endpoint dns-zone-group create \
    -g <resource-group-name> \
    --endpoint-name <private-endpoint-name> \
    --name myzonegroup \
    --private-dns-zone 'privatelink.api.ml.azure.cn' \
    --zone-name 'privatelink.api.ml.azure.cn'

# Add privatelink.notebooks.chinacloudapi.cn
az network private-dns zone create \
    -g <resource-group-name> \
    --name 'privatelink.notebooks.chinacloudapi.cn'

az network private-dns link vnet create \
    -g <resource-group-name> \
    --zone-name 'privatelink.notebooks.chinacloudapi.cn' \
    --name <link-name> \
    --virtual-network <vnet-name> \
    --registration-enabled false

az network private-endpoint dns-zone-group add \
    -g <resource-group-name> \
    --endpoint-name <private-endpoint-name> \
    --name myzonegroup \
    --private-dns-zone 'privatelink.notebooks.chinacloudapi.cn' \
    --zone-name 'privatelink.notebooks.chinacloudapi.cn'

客户管理的密钥和极大影响业务的工作区

默认情况下,工作区的元数据存储在 Azure 维护的 Azure Cosmos DB 实例中。 该数据是使用 Azure 管理的密钥加密的。 也可以提供自己的密钥,而不使用 Azure 管理的密钥。 这样可以在 Azure 订阅中创建一组额外的资源来存储数据。

若要详细了解在引入自己的密钥进行加密时创建的资源,请参阅使用 Azure 机器学习进行数据加密

使用 customer_managed_key 参数并包含 key_vaultkey_uri 参数来指定保管库中密钥的资源 ID 和 uri。

若要限制 Azure 在你的工作区中收集的数据,可以另外指定 hbi_workspace 属性。

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-cmkexample-prod
location: chinaeast2
display_name: Customer managed key encryption-example
description: This configurations shows how to create a workspace that uses customer-managed keys for encryption.
customer_managed_key: 
  key_vault: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<KEY_VAULT>
  key_uri: https://<KEY_VAULT>.vault.azure.cn/keys/<KEY_NAME>/<KEY_VERSION>
tags:
  purpose: demonstration

然后,可以在工作区创建 CLI 命令中引用此配置文件。

az ml workspace create -g <resource-group-name> --file cmk.yml

注意

授予机器学习应用(在标识和访问管理中)对订阅的参与者权限,以管理数据加密和其他资源。

注意

Azure Cosmos DB 不用于存储信息,例如模型性能、试验记录的信息或模型部署中记录的信息。

重要

只能在创建工作区时选择高业务影响。 在创建工作区后,不能更改此设置。

有关客户管理的密钥和极大影响业务的工作区的详细信息,请参阅 Azure 机器学习的企业安全性

使用 CLI 管理工作区

获取工作区信息

若要获取有关工作区的信息,请使用以下命令:

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

有关详细信息,请参阅 az ml workspace show 文档。

更新工作区

若要更新工作区,请使用以下命令:

az ml workspace update -n <workspace-name> -g <resource-group-name>

有关详细信息,请参阅 az ml workspace update 文档。

同步依赖资源的密钥

如果更改工作区使用的资源之一的访问密钥,则工作区需要大约一个小时才能与新密钥同步。 若要强制工作区立即同步新密钥,请使用以下命令:

az ml workspace sync-keys -n <workspace-name> -g <resource-group-name>

有关更改密钥的详细信息,请参阅重新生成存储访问密钥

有关 sync-keys 命令详细信息,请参阅 az ml workspace sync-keys

创建工作区

警告

如果为工作区启用了软删除,则可以在删除后恢复它。 如果未启用软删除,或者选择永久删除工作区的选项,则无法恢复该工作区。 有关详细信息,请参阅恢复已删除的工作区

若要删除不再需要的工作区,请使用以下命令:

az ml workspace delete -n <workspace-name> -g <resource-group-name>

重要

删除某个工作区不会删除该工作区使用的 Application Insights、存储帐户、密钥保管库或容器注册表。

也可以删除资源组,这会删除该资源组中的工作区和所有其他 Azure 资源。 若要删除资源组,请使用以下命令:

az group delete -g <resource-group-name>

有关详细信息,请参阅 az ml workspace delete 文档。

提示

Azure 机器学习的默认行为是软删除工作区。 这意味着不会立即删除工作区,而是将其标记为要删除。 有关详细信息,请参阅软删除

疑难解答

资源提供程序错误

创建 Azure 机器学习工作区或工作区使用的资源时,可能会收到类似于以下消息的错误:

  • No registered resource provider found for location {location}
  • The subscription is not registered to use namespace {resource-provider-namespace}

大多数资源提供程序会自动注册,但并非全部。 如果收到此消息,则需要注册所提到的提供程序。

下表包含 Azure 机器学习所需的资源提供程序的列表:

资源提供程序 为什么需要它
Microsoft.MachineLearningServices 创建 Azure 机器学习工作区。
Microsoft.Storage Azure 存储帐户用作该工作区的默认存储。
Microsoft.ContainerRegistry Azure 容器注册表被工作区用来生成 Docker 映像。
Microsoft.KeyVault 该工作区使用 Azure Key Vault 来存储机密。
Microsoft.Notebooks Azure 机器学习计算实例上集成的笔记本。
Microsoft.ContainerService 如果计划将训练后的模型部署到 Azure Kubernetes 服务。

如果计划将客户管理的密钥与 Azure 机器学习一起使用,则必须注册以下服务提供程序:

资源提供程序 为什么需要它
Microsoft.DocumentDB 用于记录工作区元数据的 Azure CosmosDB 实例。
Microsoft.Search Azure 搜索为工作区提供索引编制功能。

如果打算将托管虚拟网络与 Azure 机器学习配合使用,必须注册 Microsoft.Network 资源提供程序。 为托管虚拟网络创建专用终结点时,工作区会使用此资源提供程序。

有关注册资源提供程序的信息,请参阅解决资源提供程序注册错误

移动工作区

警告

不支持将 Azure 机器学习工作区移动到另一个订阅,或将拥有的订阅移到新租户。 这样做可能会导致错误。

删除 Azure 容器注册表

Azure 机器学习工作区使用 Azure 容器注册表 (ACR) 执行某些操作。 首次需要 ACR 实例时,它会自动创建一个。

警告

为工作区创建 Azure 容器注册表后,请不要将其删除。 删除该注册表将损坏 Azure 机器学习工作区。

后续步骤

有关适用于机器学习的 Azure CLI 扩展的详细信息,请参阅 az ml 文档。

有关如何使用最新的安全更新使 Azure 机器学习保持最新状态的信息,请参阅漏洞管理