使用 CLI 和 SDK (v2) 管理 Azure 机器学习环境

项目
08/29/2024

适用范围：Azure CLI ml 扩展 v2（最新版）Python SDK azure-ai-ml v2（最新版）

Azure 机器学习环境定义作业或部署的执行环境，并封装代码的依赖项。 Azure 机器学习使用环境规范在指定的计算目标上创建用于运行训练或评分代码的 Docker 容器。可以从 conda 规范、Docker 映像或 Docker 生成上下文定义环境。

本文介绍如何使用 SDK 和 CLI (V2) 创建和管理 Azure 机器学习环境。

先决条件

在按照本文中的步骤操作之前，请确保满足以下先决条件：

Azure 机器学习工作区。如果没有，请按照快速入门：创建工作区资源一文中的步骤创建一个。
Azure CLI 和 ml 扩展或 Azure 机器学习 Python SDK v2：
- 若要安装 Azure CLI 和扩展，请参阅安装、设置和使用 CLI (v2)。
  
  重要
  
  本文中的 CLI 示例假定你使用的是 Bash（或兼容的）shell。例如，从 Linux 系统或者适用于 Linux 的 Windows 子系统。
- 若要安装 Python SDK v2，请使用以下命令：
```
pip install azure-ai-ml azure-identity
```
  要将 SDK 的现有安装更新到最新版本，请使用以下命令：
```
pip install --upgrade azure-ai-ml azure-identity
```
  有关详细信息，请参阅安装适用于 Azure 机器学习的 Python SDK v2。

提示

在全功能的开发环境中，可以使用 Visual Studio Code 和 Azure 机器学习扩展来管理Azure 机器学习资源和训练机器学习模型。

克隆示例存储库

若要运行训练示例，请首先克隆示例存储库。对于 CLI 示例，请更改为 cli 目录。对于 SDK 示例，请更改为 sdk/python/assets/environment 目录：

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

请注意 --depth 1 仅克隆到存储库的最新提交，这将减少完成操作的时间。

连接到工作区

提示

使用以下选项卡选择要用于处理环境的方法。选择选项卡会自动将本文中的所有选项卡切换为同一选项卡。你可以随时选择另一个选项卡。

Azure CLI
Python SDK

使用 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>

若要连接到工作区，需要提供标识符参数 - 订阅、资源组和工作区名称。你将在 azure.ai.ml 命名空间的 MLClient 中使用这些详细信息来获取所需 Azure 机器学习工作区的句柄。若要进行身份验证，请使用默认 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 机器学习中有两种类型的环境：特选环境和自定义环境。特选环境是包含常用 ML 框架和工具的预定义环境。自定义环境是用户定义的环境，可以通过 az ml environment create 创建。

特选环境由 Azure 机器学习提供，且默认可用。 Azure 机器学习定期使用最新的框架版本更新这些环境，并对其进行维护以消除 bug 并应用安全修补程序。这些环境由缓存的 Docker 映像提供支持，从而降低了作业准备成本和模型部署时间。

可以通过引用特定版本或最新版本的环境，现成地使用这些策展环境进行训练或部署。使用以下语法：azureml://registries/azureml/environment/<curated-environment-name>/versions/<version-number> 或 azureml://registries/azureml/environment/<curated-environment-name>/labels/latest。还可以通过修改支持这些特选环境的 Dockerfile，将其用作你自己的自定义环境的参考。

可以在 Azure 机器学习工作室 UI 中或者通过 az ml environment list 使用 CLI (v2) 来查看可用的特选环境集。

提示

在 CLI 或 SDK 中使用特选环境时，环境名称以 AzureML- 开头，后跟特选环境的名称。使用 Azure 机器学习工作室时，它们没有此前缀。造成这种差异的原因是工作室 UI 在单独的选项卡上显示特选环境和自定义环境，因此不需要前缀。 CLI 和 SDK 没有这种分离，因此使用前缀来区分特选环境和自定义环境。

创建自定义环境

可以从 Docker 映像、Docker 生成上下文和具有 Docker 映像的 conda 规范定义环境。

从 Docker 映像创建环境

若要从 Docker 映像定义环境，请提供托管在注册表（例如 Docker Hub 或 Azure 容器注册表）中的映像的映像 URI。

Azure CLI
Python SDK

以下示例是从 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

以下示例从 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 机器学习维护一组基于 CPU 和 GPU Ubuntu Linux 的基础映像，这些映像包含常用的系统依赖项。例如，GPU 映像包含 Miniconda、OpenMPI、CUDA、cuDNN 和 NCCL。你可以将这些映像用于环境，或者在生成自己的自定义映像时使用其对应的 Dockerfile 作为参考。

有关基础映像集及其对应的 Dockerfile，请参阅 AzureML-Containers 存储库。

从 Docker 生成上下文创建环境

如果不从预生成的映像定义环境，也可以从 Docker 生成上下文定义环境。为此，请指定充当生成上下文的目录。此目录应包含 Dockerfile（不大于 1MB）以及用于生成映像的任何其他文件。

Azure CLI
Python SDK

以下示例是从生成上下文定义的环境的 YAML 规范文件。生成上下文文件夹的本地路径在 build.path 字段中指定，该生成上下文文件夹中 Dockerfile 的相对路径在 build.dockerfile_path 字段中指定。如果在 YAML 文件中省略了 build.dockerfile_path，Azure 机器学习会在生成上下文的根目录中查找名为 Dockerfile 的 Dockerfile。

在此示例中，生成上下文包含名为 Dockerfile 的 Dockerfile 和一个 requirements.txt 文件，该文件在 Dockerfile 中引用以安装 Python 包。

$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

在以下示例中，在 path 参数中指定了生成上下文文件夹的本地路径。 Azure 机器学习会在生成上下文根目录查找名为 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 机器学习开始从生成上下文生成映像。可以在工作室 UI 中监视生成状态和查看生成日志。

从 conda 规范创建环境

可以使用包含 conda 环境依赖项的标准 conda YAML 配置文件来定义环境。有关此标准格式的信息，请参阅手动创建环境。

此外，必须为此环境指定基础 Docker 映像。 Azure 机器学习会在提供的 Docker 映像之上生成 conda 环境。如果在 Docker 映像中安装了某些 Python 依赖项，则执行环境中不会存在这些包，并会因此导致运行时失败。默认情况下，Azure 机器学习使用你指定的依赖项构建一个 Conda 环境，并会在该环境中运行作业，而不是使用你在基础映像上安装的任何 Python 库。

Azure CLI
Python SDK

以下示例是从 conda 规范定义的环境的 YAML 规范文件。此处通过 conda_file 属性指定了从 Azure 机器学习环境 YAML 文件到 conda 文件的相对路径。或者，可以使用 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

使用 conda_file 参数指定 conda 文件的相对路径。

env_docker_conda = Environment(
    image="mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.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 机器学习会从此环境规范生成最终的 Docker 映像。也可以在工作室 UI 中手动触发环境的生成。

管理环境

通过 SDK 和 CLI (v2) 还可管理 Azure 机器学习环境资产的生命周期。

列出

列出工作区中的所有环境：

Azure CLI
Python SDK

az ml environment list

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

列出给定名称下的所有环境版本：

Azure CLI
Python SDK

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

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

显示

获取特定环境的详细信息：

Azure CLI
Python SDK

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

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

更新

更新特定环境的可变属性：

Azure CLI
Python SDK

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

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

重要

对于环境，只能更新 description 和 tags。所有其他属性都是不可变的；如果需要更改其中的任何属性，应创建一个新版本的环境。

存档

默认情况下，将环境存档会使其从列表查询 (az ml environment list) 中隐藏。你仍然可以继续在工作流中引用和使用已存档的环境。你可以存档环境的所有版本，也可只存档特定版本。

如果未指定版本，则会存档该给定名称下环境的所有版本。如果在已存档环境容器下创建新的环境版本，该新版本也将自动设置为已存档。

存档环境的所有版本：

Azure CLI
Python SDK

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

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

存档特定环境版本：

Azure CLI
Python SDK

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

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

若要将自定义环境用于训练作业，请指定作业 YAML 配置的 environment 字段。可以通过 environment: azureml:<environment-name>:<environment-version> 或 environment: azureml:<environment-name>@latest 引用现有的已注册 Azure 机器学习环境（以引用最新版本的环境），或以内联方式定义环境规范。如果以内联方式定义环境，请不要指定 name 和 version 字段，因为这些环境被视为“未注册”环境，不会在环境资产注册表中进行跟踪。

提交训练作业时，生成新环境可能需要几分钟时间。具体的持续时间取决于所需依赖项的大小。环境由服务缓存。因此，只要环境定义保持不变，完整安装就只会发生一次。

有关如何在作业中使用环境的详细信息，请参阅训练模型。

使用环境进行模型部署

Azure CLI
Python SDK

还可以将环境用于模型部署，以进行联机评分和批量评分。为此，请在部署 YAML 配置中指定 environment 字段。

有关如何在部署中使用环境的详细信息，请参阅使用联机终结点部署机器学习模型并为其评分。

通过

使用 CLI 和 SDK (v2) 管理 Azure 机器学习环境

先决条件

克隆示例存储库

连接到工作区

特选环境

创建自定义环境

从 Docker 映像创建环境

从 Docker 生成上下文创建环境

从 conda 规范创建环境

管理环境

列出

显示

更新

存档

使用环境进行训练

使用环境进行模型部署

后续步骤

其他资源