CLI & SDK (v2) を使用して Azure Machine Learning 環境を管理する

適用対象:Azure CLI ml extension v2 (現行)Python SDK azure-ai-ml v2 (現行)

Azure Machine Learning 環境は、ジョブまたはデプロイの実行環境を定義し、コードの依存関係をカプセル化します。 Azure Machine Learning は、環境仕様を使用して、指定されたコンピューティング ターゲットでトレーニング コードまたはスコアリング コードを実行する Docker コンテナーを作成します。 Conda 仕様、Docker イメージ、または Docker ビルド コンテキストから環境を定義できます。

この記事では、SDK および CLI (v2) を使用して Azure Machine Learning 環境を作成して管理する方法について学習します。

前提条件

この記事の手順に従う前に、次の前提条件が満たされていることをご確認ください。

• Azure Machine Learning ワークスペース。 所有していない場合は、クイック スタート: ワークスペース リソースの作成に関する記事の手順に従って作成してください。

• Azure CLI と ml 拡張機能または Azure Machine Learning Python SDK v2:

  • Azure CLI と拡張機能をインストールするには、「CLI (v2) のインストール、セットアップ、および使用」を参照してください。

    重要

    この記事の CLI の例では、Bash (または互換性のある) シェルを使用していることを前提としています。 たとえば、Linux システムや Linux 用 Windows サブシステムなどです。

  • Python SDK v2 をインストールするには、次のコマンドを使用します。

    pip install azure-ai-ml azure-identity
    

    SDK の既存のインストールを最新バージョンに更新するには、次のコマンドを使用します。

    pip install --upgrade azure-ai-ml azure-identity
    

    詳細については、「Azure Machine Learning 用 Python SDK v2 のインストール」を参照してください。

ヒント

完全な機能を備えた開発環境の場合は、Visual Studio Code と Azure Machine Learning 拡張機能を使用して、Azure Machine Learning リソースを管理し、機械学習モデルをトレーニングします。

examples リポジトリを複製する

トレーニング例を実行するには、最初に examples リポジトリをクローンします。 CLI の例では、cli ディレクトリに移動します。 SDK の例では、sdk/python/assets/environment ディレクトリに移動します。

git clone --depth 1 https://github.com/Azure/azureml-examples

なお、--depth 1 では、リポジトリに対する最新のコミットだけがクローンされるので、操作の完了にかかる時間を短縮できます。

ワークスペースに接続する

ヒント

次のタブを使って、環境の操作に使用する方法を選択します。 タブを選択すると、この記事のすべてのタブが同じタブに自動的に切り替わります。いつでも別のタブを選択できます。

Azure CLI

Azure CLI を使用する場合は、識別子パラメーター (サブスクリプション、リソース グループ、ワークスペース名) が必要です。 コマンドごとにこれらのパラメーターを指定できますが、すべてのコマンドに使用される既定値を設定することもできます。 既定値を設定するには、次のコマンドを使用します。 <subscription ID>、<Azure Machine Learning workspace name>、<resource group> を、構成の値に置き換えます。

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

Python SDK

ワークスペースに接続するには、識別子パラメーター (サブスクリプション、リソース グループ、ワークスペース名) が必要です。 これらの詳細を azure.ai.ml 名前空間の MLClient で使用して、必要な Azure Machine Learning ワークスペースへのハンドルを取得します。 認証には、既定の Azure 認証を使用します。 資格情報を構成してワークスペースに接続する方法の詳細については、こちらの例を参照してください。

# import required libraries
from azure.ai.ml import MLClient
from azure.ai.ml.entities import Environment, BuildContext
from azure.identity import DefaultAzureCredential

# Enter details of your AML workspace
subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"
workspace = "<AML_WORKSPACE_NAME>"

# get a handle to the workspace
ml_client = MLClient(
    DefaultAzureCredential(), subscription_id, resource_group, workspace
)

キュレーションされた環境

Azure Machine Learning には、キュレーションされた環境とカスタム環境という 2 種類の環境があります。 キュレーションされた環境は、一般的な ML フレームワークとツールが含まれた、定義済みの環境です。 カスタム環境は、ユーザー定義の環境であり、az ml environment create を使用して作成できます。

キュレーションされた環境は Azure Machine Learning から提供され、既定で利用できます。 Azure Machine Learning は、これらの環境を最新のフレームワーク バージョンのリリースで定期的に更新し、バグの修正とセキュリティ修正プログラムを行うために保持します。 キャッシュされた Docker イメージによってサポートされるため、ジョブの準備に要するコストとモデルのデプロイに要する時間が短縮されます。

キュレーションされたこれらの環境は、特定のバージョンまたは最新バージョンの環境を参照することで、トレーニングやデプロイにすぐに使用できます。 次の構文を使用します: azureml://registries/azureml/environment/<curated-environment-name>/versions/<version-number> または azureml://registries/azureml/environment/<curated-environment-name>/labels/latest。 また、キュレーションされたこれらの環境をサポートする Dockerfile を変更することで、独自のカスタム環境のリファレンスとして使用することもできます。

使用可能な一連のキュレーションされた環境は、Azure Machine Learning スタジオの UI で確認することも、az ml environment list で CLI (v2) を使用して確認することもできます。

ヒント

CLI または SDK でキュレーションされた環境を操作する場合、環境名は AzureML- で始まり、その後にキュレーションされた環境の名前が続きます。 Azure Machine Learning スタジオを使用する場合、このプレフィックスはありません。 この違いの理由は、スタジオ UI ではキュレーションされた環境とカスタム環境が別々のタブに表示されるので、プレフィックスは必要ないことです。 CLI と SDK にはこの分離がないため、プレフィックスはキュレーションされた環境とカスタム環境を区別するために使用されます。

カスタム環境を作成する

Docker イメージ、Docker ビルド コンテキスト、および Docker イメージを使用した conda 仕様から環境を定義できます。

Docker イメージから環境を作成する

Docker イメージから環境を定義するには、Docker Hub や Azure Container Registry などのレジストリでホストされているイメージのイメージ URI を指定します。

Azure CLI

Docker イメージから定義された環境の YAML 仕様ファイルの例を以下に示します。 Docker Hub のオフィシャル PyTorch リポジトリにあるイメージは、YAML ファイルの image プロパティを使用して指定されます。

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: docker-image-example
image: pytorch/pytorch:latest
description: Environment created from a Docker image.

環境を作成するには:

az ml environment create --file assets/environment/docker-image.yml

Python SDK

次の例では、Docker イメージから環境を作成します。 Docker Hub の公式の PyTorch リポジトリからのイメージは、image プロパティを使用して指定されます。

env_docker_image = Environment(
    image="pytorch/pytorch:latest",
    name="docker-image-example",
    description="Environment created from a Docker image.",
)
ml_client.environments.create_or_update(env_docker_image)

ヒント

Azure Machine Learning は、共通のシステム依存関係を使用して、CPU と GPU Ubuntu Linux ベースの基本イメージを保持します。 たとえば、GPU イメージには Miniconda、OpenMPI、CUDA、cuDNN、NCCL が含まれています。 ご使用の環境に合わせてこれらのイメージを使用することも、独自のカスタム イメージをビルドするときに、対応する Dockerfile を参考として使用することもできます。

一連の基本イメージと、それに対応する Dockerfile については、AzureML コンテナー リポジトリを参照してください。

Docker ビルド コンテキストから環境を作成する

ビルド済みイメージから環境を定義する代わりに、 Docker ビルド コンテキストから環境を定義することもできます。 これを行うには、ビルド コンテキストとして機能するディレクトリを指定します。 このディレクトリには、Dockerfile (1 MB以下) と、イメージをビルドするために必要なその他のファイルが含まれている必要があります。

Azure CLI

ビルド コンテキストから定義された環境の YAML 仕様ファイルの例を以下に示します。 ビルド コンテキスト フォルダーへのローカル パスが build.path フィールドに指定され、そのビルド コンテキスト フォルダー内の Dockerfile への相対パスが build.dockerfile_path フィールドに指定されます。 YAML ファイルで build.dockerfile_path が省略されている場合、Azure Machine Learning では、ビルド コンテキストのルートで Dockerfile という名前の Dockerfile が検索されます。

この例では、ビルド コンテキストに Dockerfile という名前の Dockerfile と、Python パッケージをインストールするために Dockerfile 内で参照される requirements.txt ファイルが含まれています。

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: docker-context-example
build:
  path: docker-contexts/python-and-pip

環境を作成するには:

az ml environment create --file assets/environment/docker-context.yml

Python SDK

次の例では、ビルド コンテキスト フォルダーのローカル パスが path パラメーターで指定されています。 Azure Machine Learning では、ビルド コンテキストのルートで Dockerfile という名前の Dockerfile が検索されます。

env_docker_context = Environment(
    build=BuildContext(path="docker-contexts/python-and-pip"),
    name="docker-context-example",
    description="Environment created from a Docker context.",
)
ml_client.environments.create_or_update(env_docker_context)

Azure Machine Learning では、環境が作成されるときに、ビルド コンテキストからイメージのビルドが開始されます。 studio UI でビルドの状態を監視し、ビルド ログを確認できます。

Conda 仕様から環境を作成する

Conda 環境の依存関係を含む標準の conda YAML 構成ファイルを使用して環境を定義できます。 この標準形式の詳細については、環境の手動作成に関するセクションを参照してください。

この環境では、Docker 基本イメージも指定する必要があります。 Azure Machine Learning では、提供されている Docker イメージを基盤にして conda 環境が構築されます。 Python の一部の依存関係を Docker イメージにインストールした場合、それらのパッケージは実行環境に存在しないため、実行時エラーが発生します。 既定では、指定した依存関係を含む Conda 環境が Azure Machine Learning で構築され、その環境でジョブが実行されます。基本イメージにインストールされている Python ライブラリは使用されません。

Azure CLI

conda 仕様から定義された環境の YAML 仕様ファイルの例を以下に示します。 ここでは、Azure Machine Learning 環境 YAML ファイルから conda ファイルへの相対パスが、conda_file プロパティを使用して指定されています。 また、別のファイルで定義するのではなく、conda_file プロパティを使用して conda 仕様をインラインで定義することもできます。

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: docker-image-plus-conda-example
image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04
conda_file: conda-yamls/pydata.yml
description: Environment created from a Docker image plus Conda environment.

環境を作成するには:

az ml environment create --file assets/environment/docker-image-plus-conda.yaml

Python SDK

conda ファイルへの相対パスは、conda_file パラメーターを使用して指定されます。

env_docker_conda = Environment(
    image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    conda_file="conda-yamls/pydata.yml",
    name="docker-image-plus-conda-example",
    description="Environment created from a Docker image plus Conda environment.",
)
ml_client.environments.create_or_update(env_docker_conda)

環境がジョブまたはデプロイで使用されている場合、Azure Machine Learning ではこの環境仕様から最終的な Docker イメージがビルドされます。 また、スタジオ UI で環境のビルドを手動でトリガーすることもできます。

環境を管理する

SDK と CLI (v2) では、Azure Machine Learning 環境資産のライフサイクルを管理することもできます。

List

ワークスペース内のすべての環境を一覧表示します。

Azure CLI

az ml environment list

Python SDK

envs = ml_client.environments.list()
for env in envs:
    print(env.name)

指定された名前のすべての環境バージョンを一覧表示します。

Azure CLI

az ml environment list --name docker-image-example

Python SDK

envs = ml_client.environments.list(name="docker-image-example")
for env in envs:
    print(env.version)

表示

特定の環境の詳細を取得します。

Azure CLI

az ml environment show --name docker-image-example --version 1

Python SDK

env = ml_client.environments.get(name="docker-image-example", version="1")
print(env)

更新

特定の環境の変更可能なプロパティを更新します。

Azure CLI

az ml environment update --name docker-image-example --version 1 --set description="This is an updated description."

Python SDK

env.description="This is an updated description."
ml_client.environments.create_or_update(environment=env)

重要

環境については、description と tags のみを更新できます。 その他のすべてのプロパティは変更できません。これらのプロパティを変更する必要がある場合は、新しいバージョンの環境を作成する必要があります。

アーカイブ

環境をアーカイブすると、既定でリスト クエリ (az ml environment list) から非表示になります。 アーカイブされた環境は、ワークフローで参照し、使用し続けることができます。 環境コンテナーのすべてのバージョンまたは特定のバージョンのみをアーカイブできます。

バージョンを指定しない場合、特定の名前のすべてのバージョンの環境がアーカイブされます。 アーカイブされた環境コンテナーの下に新しい環境バージョンを作成すると、その新しいバージョンも自動的にアーカイブ済みとして設定されます。

環境のすべてのバージョンをアーカイブする:

Azure CLI

az ml environment archive --name docker-image-example

Python SDK

ml_client.environments.archive(name="docker-image-example")

特定の環境バージョンをアーカイブする:

Azure CLI

az ml environment archive --name docker-image-example --version 1

Python SDK

ml_client.environments.archive(name="docker-image-example", version="1")

トレーニングに環境を使用する

Azure CLI

トレーニング ジョブにカスタム環境を使用するには、ジョブ YAML 構成の environment フィールドを指定します。 environment: azureml:<environment-name>:<environment-version> または environment: azureml:<environment-name>@latest を使用して既存の登録済みの Azure Machine Learning 環境を参照するか (環境の最新バージョンを参照する場合)、インラインで環境仕様を定義するかのいずれかを行うことができます。 環境をインラインで定義する場合は、name と version フィールドを指定しないでください。これらの環境は "未登録" の環境として扱われ、環境資産レジストリでは追跡されません。

Python SDK

トレーニング ジョブに環境を使用するには、コマンドの environment プロパティを指定します。

ジョブの送信例については、https://github.com/Azure/azureml-examples/tree/main/sdk/python/jobs の例を参照してください。

トレーニング ジョブを送信するときに、新しい環境のビルドに数分かかる場合があります。 その期間は、必要な依存関係のサイズによって異なります。 環境はサービスによってキャッシュされます。 そのため、環境定義が変更されていない限り、完全なセットアップの時間が発生するのは一度だけです。

---

ジョブでの環境の使用方法の詳細については、「モデルをトレーニングする」を参照してください。

モデル デプロイに環境を使用する

Azure CLI

オンラインとバッチの両方のスコアリング用に、モデルのデプロイに環境を使用することもできます。 これを行うには、デプロイ YAML 構成で environment フィールドを指定します。

デプロイでの環境の使用方法について詳しくは、「オンライン エンドポイントを使用して機械学習モデルをデプロイおよびスコア付けする」をご覧ください。

Python SDK

モデルのデプロイに環境を使用することもできます。 詳細については、機械学習モデルのデプロイとスコアリングに関するページを参照してください。

次のステップ

• モデルをトレーニングする (ジョブを作成する)
• オンライン エンドポイントを使用して機械学習モデルをデプロイおよびスコア付けする
• 環境 YAML スキーマ リファレンス