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

项目
09/13/2024

重要

本文中的一些 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 CLI 创建和管理 Azure 机器学习工作区。 Azure CLI 提供了一些命令来管理 Azure 资源，这些命令旨在让用户快速使用 Azure（侧重于自动化）。 CLI 的机器学习扩展提供用于处理 Azure 机器学习资源的命令。

先决条件

一个 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 扩展 v1 (azure-cli-ml)，只有部分命令与 Azure 资源管理器通信。具体而言，是用于创建、更新、删除、列出或显示 Azure 资源的命令。提交训练作业等操作直接与 Azure 机器学习工作区通信。如果工作区使用专用终结点进行保护，这足以保护 azure-cli-ml 扩展提供的命令。

将 CLI 连接到 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 <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 -w <workspace-name> -g <resource-group-name>

若要创建使用现有资源的工作区，必须为每个资源提供资源 ID。要获取此 ID，可以在 Azure 门户使用每个资源上的“属性”选项卡，或使用 Azure CLI 运行以下命令。

Azure 存储帐户：az storage account show --name <storage-account-name> --query "id"
Azure Application Insights：az monitor app-insights component show --app <application-insight-name> -g <resource-group-name> --query "id"
Azure 密钥保管库：az keyvault show --name <key-vault-name> --query "ID"
Azure 容器注册表：az acr show --name <acr-name> -g <resource-group-name> --query "id"

返回的资源 ID 具有以下格式："/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/<provider>/<subresource>/<resource-name>"。

获取要用于工作区的资源的 ID 后，请使用基础 az workspace create -w <workspace-name> -g <resource-group-name> 命令，并添加现有资源的参数和 ID。例如，以下命令创建一个使用现有容器注册表的工作区：

az ml workspace create -w <workspace-name>
                       -g <resource-group-name>
                       --container-registry "/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerRegistry/registries/<acr-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 资源管理器。

如果希望仅允许虚拟网络访问工作区，可以在 az ml workspace create 命令中使用以下参数，或者使用 az ml workspace private-endpoint 命令。

az ml workspace create -w <workspace-name>
                       -g <resource-group-name>
                       --pe-name "<pe name>"
                       --pe-auto-approval "<pe-autoapproval>"
                       --pe-resource-group "<pe name>"
                       --pe-vnet-name "<pe name>"
                       --pe-subnet-name "<pe name>"

--pe-name：创建的专用终结点的名称。
--pe-auto-approval：是否应自动批准专用终结点与工作区的连接。
--pe-resource-group：用于创建专用终结点的资源组。必须是包含虚拟网络的同一个组。
--pe-vnet-name：用于创建专用终结点的现有虚拟网络。
--pe-subnet-name：用于创建专用终结点的子网的名称。默认值为 default。

有关如何使用这些命令的详细信息，请参阅 CLI 参考页。

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

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

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

使用 --cmk-keyvault 参数指定包含密钥的 Azure Key Vault，并使用 --resource-cmk-uri 指定保管库中密钥的资源 ID 和 uri。

若要在工作区中限制 Microsoft 收集的数据，可以另外指定 --hbi-workspace 参数。

az ml workspace create -w <workspace-name>
                       -g <resource-group-name>
                       --cmk-keyvault "<cmk keyvault name>"
                       --resource-cmk-uri "<resource cmk uri>"
                       --hbi-workspace

注意

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

注意

Azure Cosmos DB 不用于存储信息，例如模型性能、试验记录的信息或模型部署中记录的信息。有关监视这些项的详细信息，请参阅体系结构和概念一文的监视和日志记录部分。

重要

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

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

使用 CLI 管理工作区

获取工作区信息

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

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

更新工作区

若要更新工作区，请使用以下命令：

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

同步依赖资源的密钥

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

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

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

创建工作区

警告

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

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

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

重要

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

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

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

提示

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 机器学习工作区。

后续步骤

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

若要检查工作区是否存在问题，请参阅如何使用工作区诊断。

若要了解如何将工作区移到新 Azure 订阅，请参阅如何移动工作区。

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