Azure CLI を使用して Azure Machine Learning ワークスペースを管理する

[アーティクル]
06/16/2023

この記事では、Azure CLI を使用して Azure Machine Learning ワークスペースを作成および管理する方法について説明します。 Azure CLI には、Azure リソースを管理するためのコマンドが用意されています。また、オートメーションに重点を置くことで、Azure で迅速に作業できるように設計されています。 CLI の機械学習拡張機能には、Azure Machine Learning リソースを操作するためのコマンドが用意されています。

ワークスペースは、Azure portal および Python SDK、Azure PowerShell、または VS Code 拡張機能経由で管理することもできます。

前提条件

Azure サブスクリプション。お持ちでない場合は、無料版または有料版の Azure Machine Learning をお試しください。
ご使用のローカル環境からこのドキュメントの CLI コマンドを使用するには、Azure CLI が必要です。

Azure Cloud Shell を使用する場合は、ブラウザーを使用してクラウド内に存在する CLI にアクセスします。

制限事項

新しいワークスペースを作成する場合は、ワークスペースに必要なサービスを自動的に作成するか、既存のサービスを使用することができます。ワークスペースとは異なる Azure サブスクリプションの既存のサービスを使用する場合は、それらのサービスを含むサブスクリプションに Azure Machine Learning 名前空間を登録する必要があります。たとえば、サブスクリプション B のストレージアカウントを使用するサブスクリプション A でワークスペースを作成する場合、ワークスペースでストレージアカウントを使用するには、Azure Machine Learning 名前空間がサブスクリプション B に登録されている必要があります。

Azure Machine Learning のリソースプロバイダーは、Microsoft.MachineLearningServices です。登録されているかどうかを確認する方法や、登録方法については、記事「Azure リソースプロバイダーと種類」を参照してください。

重要

これは、ワークスペースの作成時に提供されるリソースである、Azure Storage アカウント、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 v2 通信に問題がある場合は、Azure Private Link を使用して通信のセキュリティを向上させることができます。次のリンクを使用して、Azure Private Link を使うことにより、Azure Resource Manager との通信をセキュリティ保護します。
1. プライベートエンドポイントを使って、仮想ネットワーク内の Azure Machine Learning ワークスペースをセキュリティ保護します。
2. Azure リソースを管理するためのプライベートリンクを作成します。
3. 前のステップで作成したプライベートリンク用のプライベートエンドポイントを作成します。
重要

Azure Resource Manager 用のプライベートリンクを構成するには、Azure サブスクリプションの "サブスクリプション所有者" であり、ルート管理グループの "所有者" または "共同作成者" である必要があります。詳しくは、Azure リソースを管理するためのプライベートリンクの作成に関する記事をご覧ください。

CLI v2 の詳細については、「CLI のインストールと設定」を参照してください。

Azure サブスクリプションへの CLI の接続

重要

Azure Cloud Shell を使用している場合は、このセクションを省略できます。 Cloud Shell では、Azure サブスクリプションにログインするアカウントを使用して自動的に認証が行われます。

CLI から Azure サブスクリプションを認証するには、いくつかの方法があります。最も簡単な方法は、ブラウザーを使用して対話形式で認証することです。対話形式で認証するには、コマンドラインまたはターミナルを開き、次のコマンドを使用します。

az login

CLI で既定のブラウザーを開くことができる場合、開いたブラウザにサインインページが読み込まれます。それ以外の場合は、ブラウザーを開き、コマンドラインの指示に従う必要があります。この手順では、https://aka.ms/devicelogin にアクセスして認証コードを入力する必要があります。

ヒント

ログインすると、ご使用のアカウントに関連付けられているサブスクリプションの一覧が表示されます。 isDefault: true が示されているサブスクリプション情報が、Azure CLI コマンドに対して現在アクティブになっているサブスクリプションです。このサブスクリプションは、Azure Machine Learning ワークスペースが含まれているものと同じである必要があります。 Azure portal で自分のワークスペースの概要ページに移動することで、サブスクリプション ID を確認できます。

別のサブスクリプションを選択するには、az account set -s <subscription name or ID> コマンドを使用して、切り替えるサブスクリプション名または 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 アカウント (Premium_LRS と Premium_GRS) "ではない"
Azure Blob と Azure File の両方の機能が有効になっている
階層型名前空間 (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

既存のリソースをアタッチするには、そのリソースの ID を指定する必要があります。この ID を取得するには、Azure portal 内で各リソースの [プロパティ] タブを使用するか、Azure CLI を使って次のコマンドを実行します。

Azure Storage アカウント: 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"

リソース ID の値は次のテキストのようになります: "/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/<provider>/<subresource>/<resource-name>"。

重要

既存のリソースをアタッチする場合、必ずしもすべてを指定する必要はありません。 1 つ以上を指定できます。たとえば、既存のストレージアカウントを指定すると、ワークスペースによって他のリソースが作成されます。

ワークスペース作成コマンドの出力は、次の 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'

カスタマーマネージドキーと High Business Impact ワークスペース

ワークスペースのメタデータは、既定で Microsoft が管理する Azure Cosmos DB インスタンスに格納されます。このデータは Microsoft のマネージドキーで暗号化されます。 Microsoft のマネージドキーを使用する代わりに、独自のキーを指定することもできます。これにより、データ格納目的で、Azure サブスクリプションで追加のリソースセットが作成されます。

暗号化用の独自のキーを持ち込むときに作成されるリソースの詳細については、Azure Machine Learning を使用したデータの暗号化に関するページをご覧ください。

customer_managed_key パラメーターと、それに含まれる key_vault パラメーターおよび key_uri パラメーターを使って、コンテナー内のキーのリソース ID と 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 アプリ (ID とアクセスの管理) を承認します。

注意

Azure Cosmos DB は、モデルのパフォーマンス、実験によってログに記録された情報、またはモデルデプロイからログに記録された情報などの情報を格納するために使用されることはありません。

重要

業務への影響が大きいは、ワークスペースの作成時にのみ選択できます。ワークスペースの作成後にこの設定を変更することはできません。

カスタマーマネージドキーと High Business Impact ワークスペースの詳細については、「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」のドキュメントをご覧ください。

依存リソースのキーの同期

ワークスペースに使用されているいずれかのリソースのアクセスキーを変更すると、ワークスペースが新しいキーと同期されるまでに約 1 時間かかります。ワークスペースで新しいキーを直ちに同期させるには、次のコマンドを使用します。

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

キーの変更の詳細については、「ストレージアカウントキーの再生成」を参照してください。

sync-keys コマンドの詳細については、az ml workspace 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 Storage アカウントは、ワークスペースの既定のストレージとして使用されます。
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 Search では、ワークスペースのインデックス作成機能を提供します。

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 を最新の状態に保つ方法については、脆弱性の管理に関する記事を参照してください。