使用 Azure CLI 延伸模組 v1 管理 Azure Machine Learning 工作區

發行項
09/03/2024

重要

本文中的 Azure CLI 命令使用 azure-cli-ml 或 v1 (Azure Machine Learning 的擴充功能)。 v1 擴充功能的支援將於 2025 年 9 月 30 日終止。您將能安裝並使用 v1 擴充功能，直到該日期為止。

建議您在 2025 年 9 月 30 日之前轉換至 ml 或 v2 擴充功能。如需有關 v2 擴充功能的詳細資訊，請參閱 Azure ML CLI 擴充功能和 Python SDK v2。

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

必要條件

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 Registry、Azure Key Vault 和 Application Insights。

提示

當您建立工作區時，會建立 Azure Application Insights 執行個體。建立叢集後，您可以視需要刪除 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 延伸模組 v1 (azure-cli-ml) 時，只有部分命令會與 Azure Resource Manager 通訊。具體為用於建立、更新、刪除、列出或顯示 Azure 資源的命令。提交定型作業等作業則會直接與 Azure Machine Learning 工作區通訊。 若工作區受到私人端點保護，則足以保護 azure-cli-ml 延伸模組所提供的命令。

將 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 入口網站中工作區的概觀頁面上找到訂用帳戶資訊。

若要選取另一個訂用帳戶來用於 Azure CLI 命令，請執行 az account set -s <subscription> 命令，並指定要切換到的訂用帳戶名稱或識別碼。如需訂用帳戶選項的詳細資訊，請參閱使用多個 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 -w <workspace-name> -g <resource-group-name>

若要建立使用現有資源的工作區，您必須提供每個資源的資源識別碼。您可以透過 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>"。

當有想要用於工作區的資源識別碼之後，請使用基底 az workspace create -w <workspace-name> -g <resource-group-name> 命令，並新增現有資源的參數和識別碼。例如，下列命令會建立使用現有容器登錄的工作區：

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 Machine Learning。您可以使用 Azure CLI 來部署工作區資源的工作區和私人連結端點。如需將私人端點和虛擬網路 (VNet) 與工作區搭配使用的詳細資訊，請參閱虛擬網路隔離和隱私權概觀。針對複雜的資源設定，也請參閱以範本為基礎的部署選項，包括 Azure Resource Manager。

如果您要限制工作區存取虛擬網路，請使用下列參數作為 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 Machine Learning 的資料加密。

使用 --cmk-keyvault 參數來指定包含金鑰的 Azure Key Vault，以及使用 --resource-cmk-uri 指定保存庫內金鑰的資源識別碼和 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

注意

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

注意

Azure Cosmos DB 不會用來儲存資訊，例如模型效能、實驗所記錄的資訊，或從模型部署記錄的資訊。如需有關監視這些項目的詳細資訊，請參閱架構和概念文章的監視和記錄一節。

重要

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

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

使用 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 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 (v1) 文件。

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

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

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

共用方式為