使用 Azure 资源管理器模板创建 Azure 机器学习的工作区

本文介绍了使用 Azure 资源管理器模板创建 Azure 机器学习工作区的几种方法。 使用资源管理器模板,可以轻松地在单个协调的作中创建资源。 模板是一个 JSON 文档,定义部署所需的资源。 它还可以指定部署参数。 参数用于在部署期间提供输入值。

有关详细信息,请参阅 使用 Azure 资源管理器模板部署应用程序

先决条件

限制

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

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

    重要

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

  • 示例模板可能不会一直使用 Azure 机器学习的最新 API 版本。 建议先修改模板以使用最新的 API 版本,然后再使用它。 有关 Azure 机器学习的最新 API 版本的信息,请参阅 Azure 机器学习 REST API 文档中特定作组的页面。

    提示

    每项 Azure 服务都有自己的 API 版本集。 有关特定服务的 API 的信息,请查看 Azure REST API 参考中的服务信息。

    若要更新 API 版本,请查找资源类型的 "apiVersion": "YYYY-MM-DD" 条目,并将其更新为最新版本。 下面是 Azure 机器学习的条目示例:

    "type": "Microsoft.MachineLearningServices/workspaces",
    "apiVersion": "2023-10-01",
    

同一虚拟网络中的多个工作区

该模板不支持在同一虚拟网络中部署多个 Azure 机器学习工作区。 这是因为模板会在部署期间创建新的 DNS 区域。

如果要创建在同一虚拟网络中部署多个工作区的模板,请手动设置它(使用 Azure 门户或 CLI)。 然后使用 Azure 门户生成一个模板

关于资源管理器模板

可以从 Azure 快速入门模板 GitHub 存储库的 microsoft.machineleaerningservices/machine-learning-workspace-vnet 目录获取本文档中使用的资源管理器模板。

此模板创建以下 Azure 服务:

  • Azure 存储帐户
  • Azure Key Vault
  • Application Insights
  • Azure 容器注册表
  • Azure 机器学习工作区

Azure 机器学习工作区使用这些服务来记录和存储数据、机密和 Docker 映像等功能。 该模板还会创建一个包含服务的资源组。

示例模板具有两个必需参数:

  • 指定创建资源的位置的 location

    模板会使用你为大多数资源选择的位置。 例外是 Application Insights,它并非像其他服务那样在所有位置都可用。 如果选择了该服务不可用的位置,将在美国中南部位置创建该服务。

  • workspaceName,它是 Azure 机器学习工作区的友好名称。

    注意

    工作区名称不区分大小写。

    其他服务的名称将随机生成。

提示

尽管与此文档关联的模板创建了容器注册表,但也可以创建新工作区,而无需创建容器注册表。 当你执行需要容器注册表的操作时,会创建容器注册表。 例如,训练或部署模型。

还可以在 Azure 资源管理器模板中引用现有的容器注册表或存储帐户,而不是创建一个新的。 如果这样做,则必须 使用托管标识 或为容器注册表 启用管理员帐户

警告

为工作区创建 Azure 容器注册表后,请勿将其删除。 这样做会使 Azure 机器学习工作区不起作用。

有关模板的详细信息,请参阅以下文章:

部署模板

若要部署模板,需要创建资源组。

如果想要使用图形用户界面,请参阅 Azure 门户 部分。

az group create --name "examplegroup" --location "chinaeast2"

创建资源组后,使用以下命令部署模板:

az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" location="chinaeast2"

默认情况下,模板创建的所有资源都是新的。 但是,还可以通过在模板中包含不同的参数来使用现有资源。 例如,如果要使用现有存储帐户,请将 storageAccountOption 该值设置为该参数 existing并提供 storageAccountName 存储帐户的名称,如以下命令中所示。

重要

如果想要使用现有的 Azure 存储帐户,则它不能是高级帐户(Premium_LRS或Premium_GRS)。 它还不能有分层命名空间(与 Azure Data Lake Storage Gen2 一起使用)。 工作区的默认存储帐户不支持高级存储和分层命名空间。 可以将高级存储或分层命名空间用于非默认存储帐户。

az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="chinaeast2" \
      storageAccountOption="existing" \
      storageAccountName="existingstorageaccountname"

部署加密的工作区

以下示例模板演示如何创建具有三个设置的工作区:

  • 为工作区启用高保密性设置。 此配置会创建新 Azure Cosmos DB 实例。
  • 为工作区启用加密。
  • 使用现有的 Azure 密钥保管库检索客户管理的密钥。 使用客户管理的密钥为工作区创建新 Azure Cosmos DB 实例。

重要

创建工作区后,无法更改机密数据、加密、密钥保管库 ID 或密钥标识符的设置。 若要更改这些值,必须创建使用新值的新工作区。

有关详细信息,请参阅客户管理的密钥

重要

在使用此模板之前,订阅必须满足以下要求:

  • 必须具有包含加密密钥的现有 Azure 密钥保管库。
  • 密钥保管库必须位于计划创建 Azure 机器学习工作区的同一区域中。
  • 必须指定密钥保管库的 ID 和加密密钥的 URI。
  • 密钥保管库必须同时启用软删除和清除保护。

有关创建保管库和密钥的信息,请参阅 “配置客户管理的密钥”。

若要获取此模板所需的(密钥保管库 ID)和cmk_keyvault(密钥 URI)参数的值resource_cmk_uri,请执行以下步骤:

  1. 若要获取密钥保管库 ID,请使用以下命令:

    az keyvault show --name <keyvault-name> --query 'id' --output tsv    
    

    此命令会返回类似于 /subscriptions/{subscription-guid}/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<keyvault-name> 的值。

  2. 若要获取客户管理的密钥的 URI 的值,请使用以下命令:

    az keyvault key show --vault-name <keyvault-name> --name <key-name> --query 'key.kid' --output tsv    
    

此命令会返回类似于 https://mykeyvault.vault.azure.cn/keys/mykey/{guid} 的值。

重要

创建工作区后,无法更改机密数据、加密、密钥保管库 ID 或密钥标识符的设置。 若要更改这些值,必须创建使用新值的新工作区。

若要启用客户管理的密钥的使用,在部署模板时设置以下参数:

  • encryption_status 设置为 Enabled
  • cmk_keyvault设置为在前面的步骤中获取的cmk_keyvault值。
  • resource_cmk_uri设置为在前面的步骤中获取的resource_cmk_uri值。
az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="chinaeast2" \
      encryption_status="Enabled" \
      cmk_keyvault="/subscriptions/{subscription-guid}/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<keyvault-name>" \
      resource_cmk_uri="https://mykeyvault.vault.azure.cn/keys/mykey/{guid}" \

使用客户管理的密钥时,Azure 机器学习会创建一个包含 Azure Cosmos DB 实例的辅助资源组。 有关详细信息,请参阅 Azure Cosmos DB 中的静态加密

可以选择性地将 confidential_data 参数设置为 true。 这样做可实现以下行为:

  • 如果尚未在订阅中创建任何群集,请开始加密 Azure 机器学习计算群集的本地暂存磁盘。 如果以前在订阅中创建群集,请开具支持票证,为计算群集启用暂存磁盘加密。

  • 在两次作业之间清理本地暂存磁盘。

  • 使用 Key Vault 将存储帐户、容器注册表和 SSH 帐户的凭据从执行层安全地传递到计算群集。

  • 启用 IP 筛选,以确保除 AzureMachineLearningService 之外的任何外部服务都无法调用基础批处理池。

    重要

    创建工作区后,无法更改机密数据、加密、密钥保管库 ID 或密钥标识符的设置。 若要更改这些值,必须创建使用新值的新工作区。

    有关详细信息,请参阅 静态加密

在虚拟网络后面部署工作区

通过将参数值设置为 vnetOptionnew,可以创建用于虚拟网络后面的工作区的资源。

重要

对于容器注册表,仅支持高级版 SKU。

重要

Application Insights 不支持在虚拟网络后面部署。

仅将工作区部署在专用终结点之后

如果关联的资源不在虚拟网络后面,则可以将 privateEndpointType 参数设置为 AutoAprovalManualApproval,以便在专用终结点后面部署工作区。 此设置可用于新工作区和现有工作区。 更新现有工作区时,请使用现有工作区中的信息配置模板参数。

az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="chinaeast2" \
      privateEndpointType="AutoApproval"

使用新的虚拟网络

若要在新虚拟网络后面部署资源,请将 vnetOption 设置为 new,并为该资源提供虚拟网络设置。 以下示例演示如何部署工作区,以及如何在新虚拟网络后面部署存储帐户资源。

az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="chinaeast2" \
      vnetOption="new" \
      vnetName="examplevnet" \
      storageAccountBehindVNet="true"
      privateEndpointType="AutoApproval"

或者,可以在虚拟网络后面部署多个或所有依赖资源:

az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="chinaeast2" \
      vnetOption="new" \
      vnetName="examplevnet" \
      storageAccountBehindVNet="true" \
      keyVaultBehindVNet="true" \
      containerRegistryBehindVNet="true" \
      containerRegistryOption="new" \
      containerRegistrySku="Premium"
      privateEndpointType="AutoApproval"

使用现有虚拟网络和现有资源

若要部署具有现有资源的工作区,必须将参数和子网参数设置为 vnetOptionexisting。 但是,在部署之前,需要在虚拟网络中为每个资源创建服务终结点。 与新的虚拟网络部署一样,可以将一个或多个资源放在虚拟网络后面。

重要

子网应具有 Microsoft.Storage 服务终结点。

重要

子网不支持专用终结点。 禁用专用终结点以启用子网。

  1. 为资源启用服务端点:

    az network vnet subnet update --resource-group "examplegroup" --vnet-name "examplevnet" --name "examplesubnet" --service-endpoints "Microsoft.Storage"
    az network vnet subnet update --resource-group "examplegroup" --vnet-name "examplevnet" --name "examplesubnet" --service-endpoints "Microsoft.KeyVault"
    az network vnet subnet update --resource-group "examplegroup" --vnet-name "examplevnet" --name "examplesubnet" --service-endpoints "Microsoft.ContainerRegistry"
    
  2. 部署工作区:

    az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="chinaeast2" \
      vnetOption="existing" \
      vnetName="examplevnet" \
      vnetResourceGroupName="examplegroup" \
      storageAccountBehindVNet="true" \
      keyVaultBehindVNet="true" \
      containerRegistryBehindVNet="true" \
      containerRegistryOption="new" \
      containerRegistrySku="Premium" \
      subnetName="examplesubnet" \
      subnetOption="existing"
      privateEndpointType="AutoApproval"
    

使用 Azure 门户

  1. 完成 从自定义模板部署资源中的步骤。 访问 “自定义部署 ”窗格时,选择 “快速入门模板”。

  2. 快速入门模板 列表中,选择 快速入门/microsoft.machinelearningservices/machine-learning-workspace-vnet。 最后,选择 “选择模板”。

  3. “自定义部署 ”页上,提供以下必需信息以及部署方案所需的任何其他参数。

    • 订阅:选择要用于资源的 Azure 订阅。
    • 资源组:选择或创建包含服务的资源组。
    • 区域:选择要在其中创建资源的 Azure 区域。
    • 工作区名称:输入 Azure 机器学习工作区的名称。 工作区名称的长度必须为 3 到 33 个字符。 它只能包含字母数字字符和 - 字符。
    • 位置:选择部署元数据的位置。 此位置可以与区域位置相同,也可以是不同的。
    • Vnet 名称:输入虚拟网络名称。
  4. 选择“查看 + 创建”。

  5. 选择 创建

有关详细信息,请参阅从自定义模板部署资源

疑难解答

资源提供程序错误

创建 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 Cosmos DB 实例记录工作区的元数据。
Microsoft.Search Azure 搜索为工作区提供索引编制功能。

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

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

Key Vault 访问策略和资源管理器模板

如果使用资源管理器模板创建工作区和关联的资源(包括 Key Vault),可能会多次失败。 例如,在持续集成和部署管道中多次使用具有相同参数的模板可能会导致失败。

通过模板运行的大多数资源创建操作都是幂等的,但每次应用模板时,Key Vault 都会清除其访问策略。 移除访问策略会导致任何正在使用密钥保管库的工作区在访问密钥保管库时出现问题。 例如,停止和创建 Azure 笔记本虚拟机的操作可能会失败。

若要避免此问题,我们建议运用以下方法之一:

  • 不要使用相同参数多次部署模板。 或者在使用模板重新创建现有资源之前删除现有资源。

  • 检查 Key Vault 访问策略,并使用这些策略设置 accessPolicies 模板的属性。 若要查看访问策略,请使用以下 Azure CLI 命令:

    az keyvault show --name mykeyvault --resource-group myresourcegroup --query properties.accessPolicies
    

    若要详细了解如何使用模板的 accessPolicies 部分,请参阅 AccessPolicyEntry 对象参考

  • 检查 Key Vault 资源是否已存在。 如果这样做,请不要使用模板重新创建它。 例如,若要使用现有的 Key Vault 而不是创建新的 Key Vault,请对模板进行以下更改:

    • 添加接受现有 Key Vault 资源的 ID 的参数:

      "keyVaultId":{
        "type": "string",
        "metadata": {
          "description": "Specify the existing Key Vault ID."
        }
      }
      
    • 删除创建 Key Vault 资源的部分:

      {
        "type": "Microsoft.KeyVault/vaults",
        "apiVersion": "2018-02-14",
        "name": "[variables('keyVaultName')]",
        "location": "[parameters('location')]",
        "properties": {
          "tenantId": "[variables('tenantId')]",
          "sku": {
            "name": "standard",
            "family": "A"
          },
          "accessPolicies": [
          ]
        }
      },
      
    • 请从工作区的"[resourceId('Microsoft.KeyVault/vaults', variables('keyVaultName'))]",部分中删除dependsOn行。 此外, 更改 keyVault 条目的 properties 工作区部分以引用 keyVaultId 参数:

      {
        "type": "Microsoft.MachineLearningServices/workspaces",
        "apiVersion": "2019-11-01",
        "name": "[parameters('workspaceName')]",
        "location": "[parameters('location')]",
        "dependsOn": [
          "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]",
          "[resourceId('Microsoft.Insights/components', variables('applicationInsightsName'))]"
        ],
        "identity": {
          "type": "systemAssigned"
        },
        "sku": {
          "tier": "[parameters('sku')]",
          "name": "[parameters('sku')]"
        },
        "properties": {
          "friendlyName": "[parameters('workspaceName')]",
          "keyVault": "[parameters('keyVaultId')]",
          "applicationInsights": "[resourceId('Microsoft.Insights/components',variables('applicationInsightsName'))]",
          "storageAccount": "[resourceId('Microsoft.Storage/storageAccounts/',variables('storageAccountName'))]"
        }
      }
      

    进行这些更改后,可以在运行模板时指定现有 Key Vault 资源的 ID。 然后,该模板通过将工作区的 keyVault 属性设置为密钥保管库的 ID 来重用密钥保管库。

    若要获取密钥保管库的 ID,可以引用原始模板作业的输出或使用 Azure CLI。 以下命令演示如何使用 Azure CLI 获取密钥保管库资源 ID:

    az keyvault show --name mykeyvault --resource-group myresourcegroup --query id
    

    此命令返回如下所示的值:

    /subscriptions/{subscription-guid}/resourceGroups/myresourcegroup/providers/Microsoft.KeyVault/vaults/mykeyvault