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

项目
08/29/2024

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

还可以使用以下方法来创建并管理 Azure 机器学习工作区：

先决条件

Azure 订阅。如果没有 Azure 订阅，可在开始前创建一个试用帐户。
已安装 Azure CLI（如果要在本地运行本文中的 Azure CLI 命令）。

限制

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

Azure 机器学习的资源提供程序是 Microsoft.MachineLearningServices。有关如何查看是否已注册或需要注册命名空间，请参阅《Azure 资源提供程序和类型》。

重要

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

连接到 Azure 订阅

可使用多种方法通过 CLI 以本地方式向 Azure 订阅进行身份验证。最简单的方法是使用浏览器。

若要以交互方式进行身份验证，请打开命令行或终端，然后运行 az login。如果 CLI 可以打开默认的浏览器，则会打开该浏览器并加载登录页面。否则，请按照命令行说明将浏览器打开到 https://aka.ms/deviceloginchina 并输入设备授权代码。

提示

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

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

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

创建资源组

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

注意

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

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

对此命令的响应类似于以下 JSON。可以使用输出值来定位已创建的资源，或将其作为输入传递给其他 Azure 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 机器学习工作区需要各种其他服务作为依赖的关联资源。使用 Azure CLI 创建工作区时，可以通过 CLI 创建新的关联资源，也可以附加现有资源。

若要创建一个具有自动创建的新依赖服务的新工作区，请运行以下命令：

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

若要创建一个使用现有资源的新工作区，请先在 YAML 配置文件中定义资源，如下一部分所述。然后在 Azure CLI 工作区创建命令中引用 YAML 文件，如下所示：

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

工作区创建命令的输出类似于以下 JSON。可以使用输出值来定位已创建的资源，或将其作为输入传递给其他 Azure CLI 命令。

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

YAML 配置文件

若要将现有资源用于新的工作区，请在 YAML 配置文件中定义资源。以下示例显示了 YAML 工作区配置文件：

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-basicex-prod
location: eastus
display_name: Bring your own dependent resources-example
description: This configuration specifies a workspace configuration with existing dependent resources
storage_account: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Storage/storageAccounts/<STORAGE_ACCOUNT>
container_registry: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerRegistry/registries/<CONTAINER_REGISTRY>
key_vault: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<KEY_VAULT>
application_insights: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.insights/components/<APP_INSIGHTS>
tags:
  purpose: demonstration

不必在配置文件中指定所有关联的依赖资源。可以指定一个或多个资源，而让其他资源自动创建。

必须提供 YAML 文件中现有资源的 ID。可以通过查看 Azure 门户中的资源“属性”或运行以下 Azure CLI 命令来获取这些 ID：

Azure Application Insights：
az monitor app-insights component show --app <application-insight-name> -g <resource-group-name> --query "id"
Azure 容器注册表：
az acr show --name <container-registry-name> -g <resource-group-name> --query "id"
Azure Key Vault：
az keyvault show --name <key-vault-name> --query "id"
Azure 存储帐户：
az storage account show --name <storage-account-name> --query "id"

查询结果类似于以下字符串：
"/subscriptions/<subscription-GUID>/resourceGroups/<resource-group-name>/providers/<provider>/<subresource>/<id>"。

关联的依赖资源

以下注意事项和限制适用于与工作区关联的依赖资源。

Application Insights

提示

创建工作区时，将创建一个 Azure Application Insights 实例。如果需要，可以在创建群集后删除 Application Insights 实例。删除它会限制从工作区收集的信息，并且故障排除可能会更加困难。 如果删除工作区创建的 Application Insights 实例，则重新创建它的唯一方法是删除并重新创建工作区。

若要详细了解如何使用此 Application Insights 实例，请参阅《从机器学习 Web 服务终结点监视和收集数据》。

存储帐户

如果将现有存储帐户用于工作区，则它必须满足以下条件。这些要求仅适用于默认存储帐户。

该帐户不能是 Premium_LRS 或 Premium_GRS。
Azure Blob 和 Azure 文件功能都必须启用。
必须为 Azure Data Lake Storage 禁用分层命名空间。

保护 Azure CLI 通信

所有 Azure 机器学习 V2 az ml 命令都会将操作数据（例如 YAML 参数和元数据）传达给 Azure 资源管理器。某些 Azure CLI 命令通过 Internet 与 Azure 资源管理器通信。

如果 Azure 机器学习工作区是公共的且不在虚拟网络后面，则使用 HTTPS/TLS 1.2 可以保护通信安全。无需进行额外配置。

如果 Azure 机器学习工作区使用专用终结点和虚拟网络，则必须选择以下配置之一来使用 Azure CLI：

若要通过公共 Internet 进行通信，请将 --public-network-access 参数设置为 Enabled。
为了避免出于安全原因通过公共 Internet 进行通信，请将 Azure 机器学习配置为使用通过 Azure 专用链接终结点完成的专用网络连接，如下一部分所述。

专用网络连接

根据用例和组织要求，可以将 Azure 机器学习配置为使用专用网络连接。可以使用 Azure CLI 为工作区资源部署工作区和专用链接终结点。

如果对 Azure 容器注册表和 Azure 机器学习都使用专用链接终结点，则无法使用容器注册表任务来生成 Docker 环境映像，而必须使用 Azure 机器学习计算群集来生成映像。

在 YAML 工作区配置文件中，必须将 image_build_compute 属性设置为一个用于生成 Docker 映像环境的计算群集名称。还可通过将 public_network_access 属性设置为 Disabled 来指定专用链接工作区不可通过 Internet 进行访问。

以下代码显示了专用网络连接的示例工作区配置文件。

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-privatelink-prod
location: eastus
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

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

az network private-endpoint create \
    --name <private-endpoint-name> \
    --vnet-name <virtual-network-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 <virtual-network-name> \
    --registration-enabled false

az network private-endpoint dns-zone-group create \
    -g <resource-group-name> \
    --endpoint-name <private-endpoint-name> \
    --name <zone-group-name> \
    --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 <virtual-network-name> \
    --registration-enabled false

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

有关将专用终结点和虚拟网络与工作区结合使用的详细信息，请参阅以下文章：

高级配置

可以将其他几种高级配置应用于工作区。有关复杂的资源配置，另请参阅基于模板的部署选项，包括 Azure 资源管理器。

客户管理的密钥

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

注意

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

若要创建使用你自己的密钥的工作区，请使用 YAML 工作区配置文件中的 customer_managed_key 参数，并指定保管库内密钥的包含 key_vault 的资源 ID 和 key_uri。

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-cmkexample-prod
location: eastus
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.net/keys/<KEY_NAME>/<KEY_VERSION>
tags:
  purpose: demonstration

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

注意

若要管理添加的数据加密资源，请使用“标识和访问管理”为机器学习应用授予对你的订阅的“参与者”权限。

重大业务影响工作区

若要限制 Microsoft 在你的工作区上收集的数据，可以通过将 YAML 配置文件中的 hbi_workspace 属性设置为 TRUE 来指定重大业务影响工作区。只有在创建工作区时才可以设置重大业务影响。在创建工作区后，不能更改此设置。

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

使用 Azure CLI 管理工作区

可以使用 az ml workspace 命令来管理工作区。

获取工作区信息

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

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 -n <workspace-name> -g <resource-group-name> --public-network-access enabled

有关详细信息，请参阅 az ml workspace update。

同步依赖资源的密钥

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

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

有关 sync-keys 命令的详细信息，请参阅 az ml workspace sync-keys。
有关更改密钥的详细信息，请参阅重新生成存储访问密钥。

移动工作区

移动 Azure 机器学习工作区的功能目前为预览版。有关详细信息，请参阅在订阅之间移动 Azure 机器学习工作区（预览版）。

创建工作区

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

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

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

警告

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

删除某个工作区不会删除该工作区使用的 Application Insights、存储帐户、密钥保管库或容器注册表。若要删除工作区、依赖资源以及资源组中的所有其他 Azure 资源，可以删除资源组。若要删除资源组，请使用以下命令：

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

有关详细信息，请参阅 az ml workspace delete。

排查资源提供程序错误

创建 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 CLI 扩展的详细信息，请参阅 az ml 文档。
有关可识别并帮助解决工作区问题的诊断的信息，请参阅如何使用工作区诊断。
有关如何使用最新的安全更新使 Azure 机器学习保持最新状态的信息，请参阅漏洞管理。

通过

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

先决条件

限制

连接到 Azure 订阅

创建资源组

创建工作区

YAML 配置文件

关联的依赖资源

Application Insights

存储帐户

保护 Azure CLI 通信

专用网络连接

高级配置

客户管理的密钥

重大业务影响工作区

使用 Azure CLI 管理工作区

获取工作区信息

更新工作区

同步依赖资源的密钥

移动工作区

创建工作区

排查资源提供程序错误

相关资源

其他资源