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

[アーティクル]
09/03/2024

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

次の方法を使用して、Azure Machine Learning ワークスペースを作成および管理することもできます。

前提条件

無料版または有料版の Azure Machine Learning を使用する Azure サブスクリプション。 Azure サブスクリプションをお持ちでない場合は、始める前に無料アカウントを作成してください。
Azure CLI がインストールされている (この記事の Azure CLI コマンドをローカルで実行する場合)。

Azure Cloud Shell で Azure CLI コマンド実行する場合は、何もインストールする必要はありません。ブラウザーは、最新のクラウドバージョンの Azure CLI と Azure Machine Learning 拡張機能にアクセスします。

制限事項

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

Azure Machine Learning のリソースプロバイダーは、Microsoft.MachineLearningServices です。それが登録済みかどうか確認する方法、またはそれを登録する方法については、「Azure リソースプロバイダーと種類」をご覧ください。

重要

この情報は、ワークスペースの作成時に提供されるリソースである、Azure Storage アカウント、Azure Container Registry、Azure Key Vault、Application Insights にのみ適用されます。

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

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

Azure CLI から Azure サブスクリプションをローカルに認証するには、いくつかの方法があります。最も簡単な方法はブラウザーを使用することです。

対話形式で認証するには、コマンドラインまたはターミナルを開き、az login を実行します。 CLI は、既定のブラウザーを開くことができる場合、それを行ってサインインページを読み込みます。それ以外の場合は、コマンドラインの指示に従ってブラウザーで https://aka.ms/devicelogin を開き、デバイスの認証コードを入力します。

ヒント

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

別のサブスクリプションを選択するには、Azure CLI コマンドを使用して az account set -s <subscription> コマンドを実行し、切り替えるサブスクリプション名または ID を指定します。サブスクリプションの選択の詳細については、「複数の Azure サブスクリプションの使用」を参照してください。

その他の認証方法については、「Azure CLI を使用してサインインする」を参照してください。

リソースグループを作成する

Azure Machine Learning ワークスペースは、既存のリソースグループまたは新しいリソースグループ内に作成する必要があります。新しいリソースグループを作成するには、次のコマンドを実行します。 <resource-group-name> をリソースグループ名に置き換え、<location> をこのリソースグループで使用する Azure リージョンに置き換えます。

Note

Azure Machine Learning が使用可能なリージョンを選択する必要があります。詳細については、「リージョン別の利用可能な製品」を参照してください。

az group create --name <resource-group-name> --location <azure-region>

このコマンドへの応答は、次の JSON のようになります。出力値を使用して、作成されたリソースを特定したり、他の Azure 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 ワークスペースでは、関連する依存リソースとして他のさまざまなサービスが必要となります。 Azure CLI を使用してワークスペースを作成するとき、CLI によって新しい関連リソースが作成されるようにすることも、自分で既存のリソースをアタッチすることもできます。

新しいワークスペースを作成して新しい依存サービスを自動的に作成するには、次のコマンドを使用します。

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

既存のリソースを使用する新しいワークスペースを作成するには、次のセクションで説明するように、最初に YAML 構成ファイルでリソースを定義します。その後、次のように Azure CLI ワークスペース作成コマンドで YAML ファイルを参照します。

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

ワークスペース作成コマンドの出力は、次の JSON のようになります。出力値を使用して、作成されたリソースを特定したり、他の Azure CLI コマンドへの入力として渡したりすることができます。

{
  "applicationInsights": "/subscriptions/<subscription-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.insights/components/<application-insight-name>",
  "containerRegistry": "/subscriptions/<subscription-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.containerregistry/registries/<container-registry-name>",
  "creationTime": "2019-08-30T20:24:19.6984254+00:00",
  "description": "",
  "friendlyName": "<workspace-name>",
  "id": "/subscriptions/<subscription-GUID>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-id>",
  "identityPrincipalId": "<GUID>",
  "identityTenantId": "<GUID>",
  "identityType": "SystemAssigned",
  "keyVault": "/subscriptions/<subscription-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.keyvault/vaults/<key-vault-name>",
  "location": "<location>",
  "name": "<workspace-name>",
  "resourceGroup": "<resource-group-name>",
  "storageAccount": "/subscriptions/<subscription-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.storage/storageaccounts/<storage-account-name>",
  "type": "Microsoft.MachineLearningServices/workspaces",
  "workspaceid": "<GUID>"
}

YAML 構成ファイル

新しいワークスペースに既存のリソースを使用するには、YAML 構成ファイルでリソースを定義します。次の例は、YAML ワークスペース構成ファイルを示しています。

$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

関連付けられている依存リソースをすべて構成ファイルに指定する必要はありません。 1 つ以上のリソースを指定し、他のリソースを自動的に作成することができます。

YAML ファイル内の既存のリソースの ID を指定する必要があります。これらの ID を取得するには、Azure portal でリソースの [プロパティ] を表示するか、次の Azure CLI コマンドを実行します。

Azure Application Insights:
az monitor app-insights component show --app <application-insight-name> -g <resource-group-name> --query "id"
Azure Container Registry:
az acr show --name <container-registry-name> -g <resource-group-name> --query "id"
Azure Key Vault:
az keyvault show --name <key-vault-name> --query "id"
Azure ストレージアカウント:
az storage account show --name <storage-account-name> --query "id"

クエリ結果は次の文字列のようになります。
[https://login.microsoftonline.com/consumers/]("/subscriptions/<subscription-GUID>/resourceGroups/<resource-group-name>/providers/<provider>/<subresource>/<id>")

Azure CLI 通信をセキュリティで保護する

すべての Azure Machine Learning V2 az ml コマンドは、YAML パラメーターやメタデータなどの運用データを Azure Resource Manager とやり取りします。一部の Azure CLI コマンドは、インターネット経由で Azure Resource Manager と通信します。

Azure Machine Learning ワークスペースがパブリックであり、仮想ネットワークの背後にない場合、通信は HTTPS/TLS 1.2 を使用してセキュリティで保護されます。追加の構成は不要です。

Azure Machine Learning ワークスペースでプライベートエンドポイントと仮想ネットワークが使用されている場合、Azure CLI を使用するには、次のいずれかの構成を選択する必要があります。

パブリックインターネット経由で通信するには、--public-network-access パラメーターを Enabled に設定します。
セキュリティ上の理由からパブリックインターネット経由での通信を回避するには、次のセクションで説明するように、プライベートネットワーク接続で Azure Private Link エンドポイントを使用するように Azure Machine Learning を構成します。

プライベートネットワーク接続

ユースケースと組織の要件に応じて、プライベートネットワーク接続を使用してAzure Machine Learning を構成できます。 Azure CLI を使用して、ワークスペースと、ワークスペースリソースの Private Link エンドポイントをデプロイできます。

Azure Container Registry と Azure Machine Learning の両方にプライベートリンクエンドポイントを使用する場合、Container Registry タスクを使用して Docker 環境イメージを作成することはできません。代わりに、Azure Machine Learning コンピューティングクラスターを使用してイメージを作成する必要があります。

YAML ワークスペース構成ファイルで、image_build_compute プロパティにdocker イメージ環境の作成に使用するコンピューティングクラスター名を設定する必要があります。また、public_network_access プロパティを Disabled に設定して、インターネット経由でプライベートリンクワークスペースにアクセスできないように指定することもできます。

次のコードは、プライベートネットワーク接続用のワークスペース構成ファイルの例を示しています。

$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

ワークスペースを作成したら、Azure ネットワーク CLI コマンドを使用して、ワークスペースのプライベートリンクエンドポイントを作成します。

az network private-endpoint create \
    --name <private-endpoint-name> \
    --vnet-name <virtual-network-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 <virtual-network-name> \
    --registration-enabled false

az network private-endpoint dns-zone-group create \
    -g <resource-group-name> \
    --endpoint-name <private-endpoint-name> \
    --name <zone-group-name> \
    --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 <virtual-network-name> \
    --registration-enabled false

az network private-endpoint dns-zone-group add \
    -g <resource-group-name> \
    --endpoint-name <private-endpoint-name> \
    --name <zone-group-name> \
    --private-dns-zone 'privatelink.notebooks.azure.net' \
    --zone-name 'privatelink.notebooks.azure.net'

お使いのワークスペースでプライベートエンドポイントと仮想ネットワークを使用する方法の詳細については、次の記事を参照してください。

リソース管理のプライベートリンク

次のプロセスを使用し、Private Link を使用して Azure 管理グループ内のすべての Azure Resource Manager リソースとの通信をセキュリティで保護できます。

Azure リソースを管理するためのプライベートリンクを作成します。
前のステップで作成したプライベートリンク用のプライベートエンドポイントを作成します。

重要

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

詳細な構成

ワークスペースに適用できる高度な構成が他にもいくつかあります。複雑なリソース構成については、Azure Resource Manager などのテンプレートベースのデプロイオプションも参照してください。

カスタマーマネージドキー

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

Note

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

独自のキーを使用するワークスペースを作成するには、YAML ワークスペース構成ファイルで customer_managed_key パラメーターを使用し、格納される key_vault のリソース ID とコンテナー内のキーの key_uri を指定します。

$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

暗号化に独自のキーを使用するときに作成されるリソースの詳細については、「Azure Machine Learning を使用したデータの暗号化」を参照してください。

Note

追加されたデータ暗号化リソースを管理するには、ID およびアクセス管理を使用し、サブスクリプションに対する共同作成者のアクセス許可を使用して Machine Learning アプリを認可します。

業務への影響が大きいワークスペース

Microsoft がワークスペースで収集するデータを制限するには、YAML 構成ファイルの hbi_workspace プロパティを TRUE に設定することで、ビジネスに大きな影響を与えるワークスペースを指定できます。業務への影響が大きいことを設定できるのは、ワークスペースの作成時のみです。ワークスペースの作成後にこの設定を変更することはできません。

カスタマーマネージドキーと High Business Impact ワークスペースの詳細については、「Azure Machine Learning のエンタープライズセキュリティ」を参照してください。

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

ワークスペースを管理するには、az ml workspace コマンドを使用します。

ワークスペース情報の取得

ワークスペースに関する情報を取得するには、次のコマンドを使用します。

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 -n <workspace-name> -g <resource-group-name> --public-network-access enabled

詳細については、「az ml workspace update」をご覧ください。

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

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

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

sync-keys コマンドの詳細については、「az ml workspace sync-keys」を参照してください。
キーの変更の詳細については、「ストレージアカウントキーの再生成」を参照してください。

ワークスペースの移動

Azure Machine Learning ワークスペースの移動は現在プレビューの段階です。詳細については、「サブスクリプション間で Azure Machine Learning ワークスペースを移動する (プレビュー)」を参照してください。

ワークスペースを削除する

不要になったワークスペースを削除するには、次のコマンドを使用します。

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

Azure Machine Learning の既定の動作では、ワークスペースが "論理的に削除" されます。ワークスペースはすぐに削除されるのではなく、削除対象としてマークされます。詳細については、「論理的な削除」に関する記事をご覧ください。

警告

ワークスペースに対して論理的な削除が有効になっている場合は、削除後に復旧できます。論理的な削除が有効になっていない場合、またはワークスペースを完全に削除するオプションを選択した場合は、復旧できません。詳細については、削除されたワークスペースの復旧に関する記事を参照してください。

ワークスペースを削除しても、ワークスペースで使用されている Application Insights、ストレージアカウント、キーコンテナー、またはコンテナーレジストリは削除されません。ワークスペース、依存リソース、およびリソースグループ内の他のすべての Azure リソースを削除するには、リソースグループを削除します。リソースグループを削除するには、次のコマンドを使用します。

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

詳細については、「az ml workspace delete」を参照してください。

リソースプロバイダーのエラーのトラブルシューティング

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 CLI 拡張機能の詳細については、az ml のドキュメントを参照してください。
ワークスペースの問題を特定して解決するのに役立つ診断の詳細については、「ワークスペース診断を使う方法」を参照してください。
最新のセキュリティ更新プログラムを使用して Azure Machine Learning を最新の状態に保つ方法については、脆弱性の管理に関する記事を参照してください。

次の方法で共有

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

前提条件

制限事項

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

リソースグループを作成する

ワークスペースの作成

YAML 構成ファイル

関連付けられている依存リソース

Application Insights

Container Registry

ストレージアカウント

Azure CLI 通信をセキュリティで保護する

プライベートネットワーク接続

リソース管理のプライベートリンク

詳細な構成

カスタマーマネージドキー

業務への影響が大きいワークスペース

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

ワークスペース情報の取得

ワークスペースの更新

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

ワークスペースの移動

ワークスペースを削除する

リソースプロバイダーのエラーのトラブルシューティング

フィードバック

その他のリソース

次の方法で共有

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

前提条件

制限事項

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

リソース グループを作成する

ワークスペースの作成

YAML 構成ファイル

関連付けられている依存リソース

Application Insights

Container Registry

ストレージ アカウント

Azure CLI 通信をセキュリティで保護する

プライベート ネットワーク接続

リソース管理のプライベート リンク

詳細な構成

カスタマー マネージド キー

業務への影響が大きいワークスペース

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

ワークスペース情報の取得

ワークスペースの更新

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

ワークスペースの移動

ワークスペースを削除する

リソース プロバイダーのエラーのトラブルシューティング

関連リソース

フィードバック

その他のリソース

リソースグループを作成する

ストレージアカウント

プライベートネットワーク接続

リソース管理のプライベートリンク

カスタマーマネージドキー

リソースプロバイダーのエラーのトラブルシューティング