使用 Azure CLI 管理 Azure Machine Learning 工作區

發行項
03/04/2024

在本文中，您將了解如何使用 Azure CLI 建立及管理 Azure Machine Learning 工作區。 Azure CLI 提供管理 Azure 資源的命令，旨在讓您快速使用 Azure，並強調自動化。 CLI 的這個機器學習延伸模組會提供命令，以便使用 Azure Machine Learning 資源。

您也可以透過 Azure 入口網站和 Python SDK、Azure PowerShell 或 VS Code 延伸模組管理工作區。

必要條件

Azure 訂用帳戶。如果您沒有訂用帳戶，則可試用免費或付費版本的 Azure Machine Learning。
若要從您的本機環境使用本文件中的 CLI 命令，您需要 Azure CLI。

如果您使用 Azure Cloud Shell，CLI 可透過瀏覽器存取，並在雲端運作。

限制

建立新的工作區時，您可以自動建立工作區所需的服務，或使用現有的服務。若要使用有別於工作區的不同 Azure 訂閱的現有服務，您必須在包含這些服務的訂閱中註冊 Azure Machine Learning 命名空間。例如，若要在訂閱 A (使用訂閱 B 的儲存體帳戶) 中建立工作區，則必須先在訂閱 B 中註冊 Azure Machine Learning 命名空間，然後才能在工作區使用儲存體帳戶。

Azure Machine Learning 的資源提供者為 Microsoft.MachineLearningServices。如需如何檢查是否已註冊及如何註冊的相關資訊，請參閱《Azure 資源提供者和類型》一文。

重要

這僅適用於建立工作區期間所提供的資源；Azure 儲存體帳戶、Azure Container Register、Azure Key Vault 和 Application Insights。

提示

當您建立工作區時，會建立 Azure Application Insights 執行個體。建立叢集後，您可以視需要刪除 Application Insights 執行個體。刪除叢集會限制從工作區收集的資訊，且可能會使問題的疑難排解變得較為困難。 若您刪除工作區所建立的 Application Insights 執行個體，即無法在不刪除和重新建立工作區的情況下重新建立該執行個體。

如需關於使用 Application Insights 執行個體的詳細資訊，請參閱監視和收集 Machine Learning Web 服務端點的資料。

保護 CLI 通訊

某些 Azure CLI 命令會透過網際網路與 Azure Resource Manager 通訊。系統使用 HTTPS/TLS 1.2 來確保此通訊安全。

使用 Azure Machine Learning CLI 延伸模組 v2 ('ml') 時，所有命令皆會與 Azure Resource Manager 通訊。其中包含作業資料，例如 YAML 參數和中繼資料。如果您的 Azure Machine Learning 工作區為公用 (即不在虛擬網路後方)，則不需要額外設定。系統使用 HTTPS/TLS 1.2 來確保通訊安全。

如果您的 Azure Machine Learning 工作區使用私人端點和虛擬網路，而且您使用的是 CLI v2，請選擇使用下列其中一種設定：

如果您確定要透過公用網際網路進行 CLI v2 通訊，請對 az ml workspace update 命令使用下列 --public-network-access 參數來啟用公用網路存取。例如，下列命令會更新工作區，以存取公用網路：
```
az ml workspace update --name myworkspace --public-network-access enabled
```
如果您無法接受透過公用網際網路使用 CLI 第 2 版通訊，則可以使用 Azure Private Link 來增加通訊的安全性。使用下列連結，透過 Azure Private Link 來保護與 Azure Resource Manager 的通訊。
1. 使用私人端點保護虛擬網路內的 Azure Machine Learning 工作區。
2. 建立用於管理 Azure 資源的 Private Link。
3. 為在上一個步驟中建立的 Private Link 建立私人端點。
重要

若要設定 Azure Resource Manager 的私人連結，您必須是 Azure 訂用帳戶的訂用帳戶擁有者，以及根管理群組的擁有者或參與者。如需詳細資訊，請參閱建立用於管理 Azure 資源的 Private Link。

如需了解 CLI v2 通訊的詳細資訊，請參閱安裝和設定 CLI。

將 CLI 連接至您的 Azure 訂用帳戶

重要

如果您是使用 Azure Cloud Shell，則可以跳過本節。 Cloud Shell 會使用您登入 Azure 訂閱的帳戶，自動驗證您的身分。

您可藉由數種方式透過 CLI 向您的 Azure 訂用帳戶進行驗證。最簡單的方式是使用瀏覽器，以互動方式進行驗證。若要以互動方式進行驗證，請開啟命令列或終端機，並使用下列命令：

az login

如果 CLI 可以開啟預設瀏覽器，它會執行這項操作，並載入登入頁面。否則，您需要開啟瀏覽器，並遵循命令列上的指示。這些指示需要瀏覽至 https://aka.ms/devicelogin，並輸入授權碼。

提示

登入之後，您會看到一份與您的 Azure 帳戶相關聯的訂閱清單。具有 isDefault: true 的訂用帳戶資訊是目前針對 Azure CLI 命令啟用的訂用帳戶。此訂用帳戶必須是包含 Azure Machine Learning 工作區的相同訂用帳戶。您可從 Azure 入口網站瀏覽工作區的概觀頁面來尋找訂用帳戶識別碼。

若要選取另一個訂用帳戶，請使用 az account set -s <subscription name or ID> 命令並指定訂用帳戶名稱或識別碼以進行切換。如需訂用帳戶選取的詳細資訊，請參閱使用多個 Azure 訂用帳戶。

如需其他驗證方法，請參閱使用 Azure CLI 登入。

建立資源群組

Azure Machine Learning 工作區必須在資源群組內建立。您可以使用現有的資源群組或建立一個新的群組。若要「建立新的資源群組」，請使用下列命令。將 <resource-group-name> 取代成要用於此資源群組的名稱。將 <location> 取代成要用於此資源群組的 Azure 區域：

注意

建議選取可使用 Azure Machine Learning 的區域。如需資訊，請參閱依區域提供的產品。

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 Machine Learning 工作區時，需要不同的其他服務做為相依相關聯的資源。當您使用 CLI 建立工作區時，CLI 可以代表您建立新的相關聯資源，或者您可以附加現有的資源。

重要

附加您自己的儲存體帳戶時，請確定其符合下列準則：

儲存體帳戶不是進階帳戶 (Premium_LRS and Premium_GRS)
已啟用 Azure Blob 和 Azure 檔案功能
階層命名空間 (ADLS Gen 2) 已停用。這些需求僅適用於工作區所使用的預設儲存體帳戶。

附加 Azure 容器登錄時，您必須啟用管理帳戶，才能搭配 Azure Machine Learning 工作區使用。

使用新資源建立
導入現有資源

若要建立會在其中自動建立服務的新工作區，請使用下列命令：

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

若要建立新的工作區，同時使用 CLI 來導入現有相關聯的資源，您必須先定義您的工作區在設定檔中的設定方式。

$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

然後，您可以在工作區建立 CLI 命令過程中參考此設定檔。

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

如果附加現有資源，您必須提供資源的識別碼。您可以在 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 Key Vault：az keyvault show --name <key-vault-name> --query "ID"
Azure Container Registry：az acr show --name <acr-name> -g <resource-group-name> --query "id"

資源識別碼值看起來會如下列文字所示："/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/<provider>/<subresource>/<resource-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 Machine Learning。您可以使用 Azure CLI 來部署工作區資源的工作區和私人連結端點。如需將私人端點和虛擬網路 (VNet) 與工作區搭配使用的詳細資訊，請參閱虛擬網路隔離和隱私權概觀。針對複雜的資源設定，也請參閱以範本為基礎的部署選項，包括 Azure Resource Manager。

使用私人連結時，您的工作區無法使用 Azure Container Registry 來建置 Docker 映像。因此，您必須將 image_build_compute 屬性設定為 CPU 計算叢集名稱，以用於 Docker 映射環境建置。您也可以使用 public_network_access 屬性，指定是否應該可透過網際網路存取私人連結工作區。

$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

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.azureml.ms
az network private-dns zone create \
    -g <resource-group-name> \
    --name 'privatelink.api.azureml.ms'

az network private-dns link vnet create \
    -g <resource-group-name> \
    --zone-name 'privatelink.api.azureml.ms' \
    --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.azureml.ms' \
    --zone-name 'privatelink.api.azureml.ms'

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

az network private-dns link vnet create \
    -g <resource-group-name> \
    --zone-name 'privatelink.notebooks.azure.net' \
    --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.azure.net' \
    --zone-name 'privatelink.notebooks.azure.net'

客戶自控金鑰和高業務影響工作區

根據預設，工作區的中繼資料會儲存在 Microsoft 所維護的 Azure Cosmos DB 執行個體中。此資料會使用 Microsoft 受控金鑰進行加密。您也可以提供自己的金鑰，而不使用 Microsoft 管理的金鑰。此方法會在您的 Azure 訂閱中，建立一組額外的資源儲存資料。

若要深入了解當您攜帶自己的金鑰來加密時所建立的資源，請參閱 Azure Machine Learning 的資料加密。

使用 customer_managed_key 參數，並包含 key_vault 和 key_uri 參數，以指定保存庫內金鑰的資源識別碼和 URI。

若要限制 Microsoft 在您的工作區上收集的資料，您可以另外指定 hbi_workspace 屬性。

$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

然後，您可以在工作區建立 CLI 命令過程中參考此設定檔。

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

注意

使用訂用帳戶的參與者權限，對 Machine Learning 應用程式 (在 [身分識別和存取管理] 中) 進行授權。

注意

Azure Cosmos DB 不會用來儲存資訊，例如模型效能、實驗所記錄的資訊，或從模型部署記錄的資訊。

重要

只有在建立工作區時，才能選取 [高業務影響]。建立工作區之後，就無法變更此設定。

如需有關客戶自控金鑰和高業務影響工作區的詳細資訊，請參閱 Azure Machine Learning 的企業安全性。

使用 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 工作區 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 Machine Learning 的預設行為是虛刪除工作區。這表示工作區不會立即刪除，而是標示為要刪除。如需詳細資訊，請參閱虛刪除。

疑難排解

資源提供者錯誤

建立 Azure Machine Learning 工作區或工作區所使用的資源時，您可能會收到類似下列訊息的錯誤：

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

大部分資源提供者都會自動註冊，但並非全部。如果您收到此訊息，則需要註冊先前提及的提供者。

下表包含 Azure Machine Learning 所需的資源提供者清單：

資源提供者	需要的原因
Microsoft.MachineLearningServices	建立 Azure Machine Learning 工作區。
Microsoft.Storage	Azure 儲存體帳戶用來做為工作區的預設儲存體。
Microsoft.ContainerRegistry	工作區會使用 Azure Container Registry 來建置 Docker 映像。
Microsoft.KeyVault	工作區會使用 Azure Key Vault 來儲存秘密。
Microsoft.Notebooks	Azure Machine Learning 計算執行個體上的整合式筆記本。
Microsoft.ContainerService	若您打算將已定型的模型部署至 Azure Kubernetes Service。

若您打算搭配 Azure Machine Learning 使用客戶自控金鑰，則必須註冊下列服務提供者：

資源提供者	需要的原因
Microsoft.DocumentDB	記錄工作區中繼資料的 Azure CosmosDB 執行個體。
Microsoft.Search	Azure 搜尋可為工作區提供索引編製功能。

如果您打算搭配 Azure Machine Learning 使用受控虛擬網路，則必須註冊 Microsoft.Network 資源提供者。建立受控虛擬網路的私人端點時，工作區會使用此資源提供者。

如需有關註冊資源提供者的詳細資訊，請參閱解決資源提供者註冊的錯誤。

移動工作區

警告

不支援將 Azure Machine Learning 工作區移至不同的訂用帳戶，或將擁有的訂用帳戶移至新租用戶。這麼做可能會導致錯誤。

刪除 Azure Container Registry

Azure Machine Learning 工作區會使用 Azure Container Registry (ACR) 進行某些作業。它會在第一次需要 ACR 執行個體時自動建立一個。

警告

為工作區建立 Azure Container Registry 之後，請勿將其刪除。這樣做將會造成您的 Azure Machine Learning 工作區中斷。

下一步

如需 Azure CLI 機器學習延伸模組的詳細資訊，請參閱 az ml 文件。

如要檢查工作區是否發生問題，請參閱如何使用工作區診斷。

若要了解如何將工作區移至新的 Azure 訂用帳戶，請參閱如何移動工作區。

若要了解如何使用最新的安全性更新讓 Azure Machine Learning 保持最新狀態的相關資訊，請參閱弱點管理。