安装和使用 Azure 机器学习的 CLI 扩展

重要

本文中的 Azure CLI 命令需要将 azure-cli-ml 或 1.0 扩展用于 Azure 机器学习。 使用 ml 扩展的增强型 2.0 CLI(预览版)现已发布,建议使用它。 这些扩展不兼容,因此 2.0 CLI 命令对于本文中的步骤将不起作用。 但是,机器学习工作区和所有基础资源均可彼此交互,这意味着一个用户可以使用 1.0 CLI 创建工作区,而另一个用户可以使用 2.0 CLI 将作业提交到相同的工作区。

若要查看已安装了哪些扩展,请使用 az extension list。 如果扩展的列表包含 azure-cli-ml,表明你有适用于本文中的步骤的正确扩展。

有关安装和使用不同扩展的详细信息,请参阅以下文章:

Azure 机器学习 CLI 是 Azure CLI(适用于 Azure 平台的跨平台命令行接口)的一个扩展。 此扩展提供用于操作 Azure 机器学习的命令。 通过此扩展可将机器学习活动自动化。 以下列表提供了可以使用 CLI 扩展执行的一些示例操作:

  • 运行试验以创建机器学习模型

  • 注册机器学习模型以供客户使用

  • 打包、部署和跟踪机器学习模型的生命周期

CLI 不能取代 Azure 机器学习 SDK。 它是一个经过优化的补充工具,可以处理高度参数化的、非常适合自动化的任务。

先决条件

  • 若要使用 CLI,必须拥有 Azure 订阅。 如果没有 Azure 订阅,请在开始前创建一个试用帐户。 立即试用 Azure 机器学习的试用版

  • 若要在 本地环境 中使用本文档所述的 CLI 命令,需要安装 Azure CLI

完整参考文档

查找 Azure CLI 的 azure-cli-ml 扩展的完整参考文档

将 CLI 连接到 Azure 订阅

可通过多种方法从 CLI 对 Azure 订阅进行身份验证。 最基本的方法是使用浏览器进行交互式身份验证。 若要以交互方式进行身份验证,请打开命令行或终端,然后使用以下命令:

az login

如果 CLI 可以打开默认的浏览器,则它会打开该浏览器并加载登录页。 否则,需要打开浏览器并按照命令行中的说明操作。 按说明操作时,需要浏览到 https://aka.ms/devicelogin 并输入授权代码。

提示

登录后,你将看到与你的 Azure 帐户关联的订阅列表。 在 isDefault: true 的情况下显示的订阅信息是 Azure CLI 命令的当前已激活的订阅。 此订阅必须与包含 Azure 机器学习工作区的订阅相同。 可以通过访问工作区的概述页从 Azure 门户找到订阅 ID。 还可以使用 SDK 从工作区对象获取订阅 ID。 例如,Workspace.from_config().subscription_id

若要选择另一个订阅,请使用 az account set -s <subscription name or ID> 命令并指定要切换到的订阅名称或 ID。 有关订阅选择的详细信息,请参阅使用多个 Azure 订阅

有关其他身份验证方法,请参阅使用 Azure CLI 登录

安装扩展

首次尝试使用以 az ml 开头的命令时,会自动安装扩展。

更新扩展

若要更新机器学习 CLI 扩展,请使用以下命令:

az extension update -n azure-cli-ml

删除扩展

若要删除 CLI 扩展,请使用以下命令:

az extension remove -n azure-cli-ml

资源管理

以下命令演示如何使用 CLI 来管理 Azure 机器学习所用的资源。

  • 如果没有资源组,请创建一个资源组:

    az group create -n myresourcegroup -l chinaeast
    
  • 创建 Azure 机器学习工作区:

    az ml workspace create -w myworkspace -g myresourcegroup
    

    有关详细信息,请参阅 az ml workspace create

  • 将工作区配置附加到某个文件夹,以启用 CLI 上下文感知。

    az ml folder attach -w myworkspace -g myresourcegroup
    

    此命令创建包含示例 runconfig 和 conda 环境文件的 .azureml 子目录。 此子目录还包含用来与 Azure 机器学习工作区通信的 config.json 文件。

    有关详细信息,请参阅 az ml folder attach

  • 将某个 Azure Blob 容器附加为数据存储。

    az ml datastore attach-blob  -n datastorename -a accountname -c containername
    

    有关详细信息,请参阅 az ml datastore attach-blob

  • 将文件上传到数据存储。

    az ml datastore upload  -n datastorename -p sourcepath
    

    有关详细信息,请参阅 az ml datastore upload

  • 将某个 AKS 群集附加为计算目标。

    az ml computetarget attach aks -n myaks -i myaksresourceid -g myresourcegroup -w myworkspace
    

    有关详细信息,请参阅 az ml computetarget attach aks

计算群集

  • 创建新的托管计算群集。

    az ml computetarget create amlcompute -n cpu --min-nodes 1 --max-nodes 1 -s STANDARD_D3_V2
    
  • 创建具有托管标识的新托管计算群集

    • 用户分配的托管标识

      az ml computetarget create amlcompute --name cpu-cluster --vm-size Standard_NC6 --max-nodes 5 --assign-identity '/subscriptions/<subcription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user_assigned_identity>'
      
    • 系统分配的托管标识

      az ml computetarget create amlcompute --name cpu-cluster --vm-size Standard_NC6 --max-nodes 5 --assign-identity '[system]'
      
  • 将托管标识添加到现有群集:

    • 用户分配的托管标识

      az ml computetarget amlcompute identity assign --name cpu-cluster '/subscriptions/<subcription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user_assigned_identity>'
      
    • 系统分配的托管标识

      az ml computetarget amlcompute identity assign --name cpu-cluster '[system]'
      

有关详细信息,请参阅 az ml computetarget create amlcompute

备注

Azure 机器学习计算群集只支持一个系统分配的标识或支持多个用户分配的标识,而不能同时支持这二者。

计算实例

管理计算实例。 在下面的所有示例中,计算实例的名称均为“cpu”

运行试验

  • 开始运行试验。 使用此命令时,请为 -c 参数指定 runconfig 文件的名称(如果查看的是文件系统,此名称为 *.runconfig 前面的文本)。

    az ml run submit-script -c sklearn -e testexperiment train.py
    

    提示

    az ml folder attach 命令创建一个 .azureml 子目录,其中包含两个示例 runconfig 文件。

    如果你的某个 Python 脚本以编程方式创建运行配置对象,则你可以使用 RunConfig.save() 将此对象另存为 runconfig 文件。

    可在此 JSON 文件中找到完整的 runconfig 架构。 该架构通过每个对象的 description 键自行记录。 此外,还有可能值的枚举,在末尾还有模板代码片段。

    有关详细信息,请参阅 az ml run submit-script

  • 查看试验列表:

    az ml experiment list
    

    有关详细信息,请参阅 az ml experiment list

HyperDrive 运行

可以结合使用 HyperDrive 与 Azure CLI 以执行参数优化运行。 首先,创建采用以下格式的 HyperDrive 配置文件。 有关超参数优化参数的详细信息,请参阅优化模型的超参数一文。

# hdconfig.yml
sampling: 
    type: random # Supported options: Random, Grid, Bayesian
    parameter_space: # specify a name|expression|values tuple for each parameter.
    - name: --penalty # The name of a script parameter to generate values for.
      expression: choice # supported options: choice, randint, uniform, quniform, loguniform, qloguniform, normal, qnormal, lognormal, qlognormal
      values: [0.5, 1, 1.5] # The list of values, the number of values is dependent on the expression specified.
policy: 
    type: BanditPolicy # Supported options: BanditPolicy, MedianStoppingPolicy, TruncationSelectionPolicy, NoTerminationPolicy
    evaluation_interval: 1 # Policy properties are policy specific. See the above link for policy specific parameter details.
    slack_factor: 0.2
primary_metric_name: Accuracy # The metric used when evaluating the policy
primary_metric_goal: Maximize # Maximize|Minimize
max_total_runs: 8 # The maximum number of runs to generate
max_concurrent_runs: 2 # The number of runs that can run concurrently.
max_duration_minutes: 100 # The maximum length of time to run the experiment before cancelling.

将此文件与运行配置文件一起添加。 然后使用以下命令提交 HyperDrive 运行:

az ml run submit-hyperdrive -e <experiment> -c <runconfig> --hyperdrive-configuration-name <hdconfig> my_train.py

请注意运行配置中的参数部分和 HyperDrive 配置中的参数空间 。这些参数包含要传递给训练脚本的命令行参数。 在每次迭代中,运行配置中的值保持不变,而 HyperDrive 配置中的范围将会更迭。 请不要在这两个文件中指定相同的参数。

数据集管理

以下命令演示如何在 Azure 机器学习中处理数据集:

  • 注册数据集:

    az ml dataset register -f mydataset.json
    

    如需用于定义数据集的 JSON 文件的格式信息,请使用 az ml dataset register --show-template

    有关详细信息,请参阅 az ml dataset register

  • 列出工作区中的所有数据集:

    az ml dataset list
    

    有关详细信息,请参阅 az ml dataset list

  • 获取数据集的详细信息:

    az ml dataset show -n dataset-name
    

    有关详细信息,请参阅 az ml dataset show

  • 取消注册数据集:

    az ml dataset unregister -n dataset-name
    

    有关详细信息,请参阅 az ml dataset unregister

环境管理

以下命令演示如何为工作区创建、注册和列出 Azure 机器学习环境

  • 为环境创建基架文件:

    az ml environment scaffold -n myenv -d myenvdirectory
    

    有关详细信息,请参阅 az ml environment scaffold

  • 注册环境:

    az ml environment register -d myenvdirectory
    

    有关详细信息,请参阅 az ml environment register

  • 列出已注册的环境:

    az ml environment list
    

    有关详细信息,请参阅 az ml environment list

  • 下载已注册的环境:

    az ml environment download -n myenv -d downloaddirectory
    

    有关详细信息,请参阅 az ml environment download

环境配置架构

如果使用 az ml environment scaffold 命令,它将生成一个模板 azureml_environment.json 文件,可以通过 CLI 修改该文件并使用它来创建自定义环境配置。 顶层对象松散地映射到 Python SDK 中的 Environment 类。

{
    "name": "testenv",
    "version": null,
    "environmentVariables": {
        "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
    },
    "python": {
        "userManagedDependencies": false,
        "interpreterPath": "python",
        "condaDependenciesFile": null,
        "baseCondaEnvironment": null
    },
    "docker": {
        "enabled": false,
        "baseImage": "mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:20210615.v1",
        "baseDockerfile": null,
        "sharedVolumes": true,
        "shmSize": "2g",
        "arguments": [],
        "baseImageRegistry": {
            "address": null,
            "username": null,
            "password": null
        }
    },
    "spark": {
        "repositories": [],
        "packages": [],
        "precachePackages": true
    },
    "databricks": {
        "mavenLibraries": [],
        "pypiLibraries": [],
        "rcranLibraries": [],
        "jarLibraries": [],
        "eggLibraries": []
    },
    "inferencingStackVersion": null
}

下表详细介绍了 JSON 文件中的每个顶层字段、其类型和说明。 如果某个对象类型已链接到 Python SDK 中的类,则在每个 JSON 字段与 Python 类中的公共变量名称之间存在松散的 1:1 匹配。 在某些情况下,字段可能会映射到构造函数参数,而不是类变量。 例如,environmentVariables 字段映射到 Environment 类中的 environment_variables 变量。

JSON 字段 类型 说明
name string 环境的名称。 名称不能以 MicrosoftAzureML 开头。
version string 环境的版本。
environmentVariables {string: string} 环境变量名称和值的哈希映射。
python PythonSection 定义要在目标计算资源上使用的 Python 环境和解释器。
docker DockerSection 定义根据环境规范对生成的 Docker 映像进行自定义时使用的设置。
spark SparkSection 此节配置 Spark 设置。 仅当 framework 设置为 PySpark 时才使用它。
databricks DatabricksSection 配置 Databricks 库依赖项。
inferencingStackVersion string 指定添加到映像的推理堆栈版本。 若要避免添加推理堆栈,请将此字段保留为 null。 有效值:latest。

ML 管道管理

以下命令演示如何使用机器学习管道:

模型注册、分析和部署

以下命令演示如何注册已训练的模型,然后将其部署为生产服务:

  • 将模型注册到 Azure 机器学习:

    az ml model register -n mymodel -p sklearn_regression_model.pkl
    

    有关详细信息,请参阅 az ml model register

  • (可选) 分析模型以获取部署的最佳 CPU 和内存值。

    az ml model profile -n myprofile -m mymodel:1 --ic inferenceconfig.json -d "{\"data\": [[1,2,3,4,5,6,7,8,9,10],[10,9,8,7,6,5,4,3,2,1]]}" -t myprofileresult.json
    

    有关详细信息,请参阅 az ml model profile

  • 将模型部署到 AKS

    az ml model deploy -n myservice -m mymodel:1 --ic inferenceconfig.json --dc deploymentconfig.json --ct akscomputetarget
    

    有关推理配置文件架构的详细信息,请参阅推理配置架构

    有关部署配置文件架构的详细信息,请参阅部署配置架构

    有关详细信息,请参阅 az ml model deploy

推理配置架构

inferenceconfig.json 文档中的条目映射到 InferenceConfig 类的参数。 下表描述了 JSON 文档中的实体与方法参数之间的映射:

JSON 实体 方法参数 说明
entryScript entry_script 包含要为映像运行的代码的本地文件路径。
sourceDirectory source_directory 可选。 包含用于创建图像的所有文件的文件夹路径,这样就可以方便地访问此文件夹或子文件夹中的任何文件。 可从本地计算机上传整个文件夹,作为 WebService 的依赖项。 注意:entry_script、conda_file 和 extra_docker_file_steps 路径是 source_directory 路径的相对路径。
environment environment 可选。 Azure 机器学习环境

可以在推理配置文件中包含 Azure 机器学习环境的完整规范。 如果工作区中不存在此环境,Azure 机器学习将创建它。 否则,Azure 机器学习将更新环境(如必要)。 以下 JSON 是一个示例:

{
    "entryScript": "score.py",
    "environment": {
        "docker": {
            "arguments": [],
            "baseDockerfile": null,
            "baseImage": "mcr.microsoft.com/azureml/base:intelmpi2018.3-ubuntu16.04",
            "enabled": false,
            "sharedVolumes": true,
            "shmSize": null
        },
        "environmentVariables": {
            "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
        },
        "name": "my-deploy-env",
        "python": {
            "baseCondaEnvironment": null,
            "condaDependencies": {
                "channels": [
                    "conda-forge"
                ],
                "dependencies": [
                    "python=3.6.2",
                    {
                        "pip": [
                            "azureml-defaults",
                            "azureml-telemetry",
                            "scikit-learn==0.22.1",
                            "inference-schema[numpy-support]"
                        ]
                    }
                ],
                "name": "project_environment"
            },
            "condaDependenciesFile": null,
            "interpreterPath": "python",
            "userManagedDependencies": false
        },
        "version": "1"
    }
}

你还可以在单独的 CLI 参数中使用现有的 Azure 机器学习环境,并从推理配置文件中删除环境键。 使用 -e 代表环境名称,而使用 --ev 代表环境版本。 如果你未指定 --ev,系统将使用最新版本。 下面是该推理配置文件的一个示例:

{
    "entryScript": "score.py",
    "sourceDirectory": null
}

以下命令演示了如何使用以前的推理配置文件(名为 myInferenceConfig.json)来部署模型。

它还使用现有 Azure 机器学习环境(名为 AzureML-Minimal)的最新版本。

az ml model deploy -m mymodel:1 --ic myInferenceConfig.json -e AzureML-Minimal --dc deploymentconfig.json

部署配置架构

本地部署配置架构

deploymentconfig.json 文档中的条目对应于 LocalWebservice.deploy_configuration 的参数。 下表描述了 JSON 文档中的实体与方法参数之间的映射:

JSON 实体 方法参数 说明
computeType 不可用 计算目标。 对于本地目标,值必须是 local
port port 用于公开服务的 HTTP 终结点的本地端口。

此 JSON 是用于 CLI 的部署配置示例:

{
    "computeType": "local",
    "port": 32267
}

将此 JSON 保存为名为 deploymentconfig.json 的文件。

Azure 容器实例部署配置架构

deploymentconfig.json 文档中的条目映射到 AciWebservice.deploy_configuration 的参数。 下表描述了 JSON 文档中的实体与方法参数之间的映射:

JSON 实体 方法参数 说明
computeType 不可用 计算目标。 对于 ACI,此值必须为 ACI
containerResourceRequirements 不可用 CPU 和内存实体的容器。
  cpu cpu_cores 要分配的 CPU 核心数。 默认值为 0.1
  memoryInGB memory_gb 为此 Web 服务分配的内存量 (GB)。 默认值为 0.5
location location 要将此 Webservice 部署到的 Azure 区域。 如果未指定,将使用工作区位置。 有关可用区域的详细信息,请参阅:ACI 区域
authEnabled auth_enabled 是否为此 Webservice 启用身份验证。 默认为 False
sslEnabled ssl_enabled 是否为此 Webservice 启用 SSL。 默认为 False。
appInsightsEnabled enable_app_insights 是否为此 Webservice 启用 AppInsights。 默认为 False
sslCertificate ssl_cert_pem_file 如果启用 SSL,则需要证书文件
sslKey ssl_key_pem_file 如果启用 SSL,则需要密钥文件
cname ssl_cname 如果启用 SSL,则需要 CNAME
dnsNameLabel dns_name_label 评分终结点的 DNS 名称标签。 如果未指定,则将为评分终结点生成唯一的 DNS 名称标签。

以下 JSON 是用于 CLI 的部署配置示例:

{
    "computeType": "aci",
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    },
    "authEnabled": true,
    "sslEnabled": false,
    "appInsightsEnabled": false
}

Azure Kubernetes 服务部署配置架构

deploymentconfig.json 文档中的条目对应于 AksWebservice.deploy_configuration 的参数。 下表描述了 JSON 文档中的实体与方法参数之间的映射:

JSON 实体 方法参数 说明
computeType 不可用 计算目标。 对于 AKS,此值必须为 aks
autoScaler 不可用 包含自动缩放的配置元素。 请参阅自动缩放程序表。
  autoscaleEnabled autoscale_enabled 是否为 Web 服务启用自动缩放。 如果 numReplicas = 0,则为 True;否则为 False
  minReplicas autoscale_min_replicas 自动缩放此 Web 服务时可使用的容器的最小数目。 默认值为 1
  maxReplicas autoscale_max_replicas 自动缩放此 Web 服务时可使用的容器的最大数目。 默认值为 10
  refreshPeriodInSeconds autoscale_refresh_seconds 自动缩放程序尝试缩放此 Web 服务的频率。 默认值为 1
  targetUtilization autoscale_target_utilization 自动缩放程序应尝试维持的此 Web 服务的目标利用率(以低于 100 的百分比表示)。 默认值为 70
dataCollection 不可用 包含数据集合的配置元素。
  storageEnabled collect_model_data 是否为 Web 服务启用模型数据收集。 默认值为 False
authEnabled auth_enabled 是否为 Web 服务启用密钥身份验证。 tokenAuthEnabledauthEnabled 均不能为 True。 默认值为 True
tokenAuthEnabled token_auth_enabled 是否为 Web 服务启用令牌身份验证。 tokenAuthEnabledauthEnabled 均不能为 True。 默认值为 False
containerResourceRequirements 不可用 CPU 和内存实体的容器。
  cpu cpu_cores 要分配给此 Web 服务的 CPU 核心数。 默认值为 0.1
  memoryInGB memory_gb 为此 Web 服务分配的内存量 (GB)。 默认值为 0.5
appInsightsEnabled enable_app_insights 是否为 Web 服务启用 Application Insights 日志记录。 默认值为 False
scoringTimeoutMs scoring_timeout_ms 对 Web 服务调用的评分强制执行的超时时间。 默认值为 60000
maxConcurrentRequestsPerContainer replica_max_concurrent_requests 此 Web 服务每个节点的最大并发请求数。 默认值为 1
maxQueueWaitMs max_request_wait_time 在返回 503 错误之前,请求在队列中停留的最长时间(毫秒)。 默认值为 500
numReplicas num_replicas 要分配给此 Web 服务的容器数量。 没有默认值。 如果未设置此参数,则默认启用自动缩放程序。
keys 不可用 包含密钥的配置元素。
  primaryKey primary_key 要用于此 Web 服务的主要身份验证密钥
  secondaryKey secondary_key 要用于此 Web 服务的辅助身份验证密钥
gpuCores gpu_cores 为此 Webservice 分配的 GPU 内核(每个容器的副本)数。 默认值为 1。 仅支持整数值。
livenessProbeRequirements 不可用 包含运行情况探测要求的配置元素。
  periodSeconds period_seconds 执行运行情况探测的频率(秒)。 默认值为 10 秒。 最小值为 1。
  initialDelaySeconds initial_delay_seconds 启动容器后,启动运行情况探测前的秒数。 默认值为 310
  timeoutSeconds timeout_seconds 运行情况探测超时前等待的秒数。默认值为 2 秒。 最小值为 1
  successThreshold success_threshold 运行情况探测失败后,将其视为成功所需的最小连续成功次数。 默认值为 1。 最小值为 1。
  failureThreshold failure_threshold 当 Pod 启动而运行情况探测失败时,Kubernetes 将尝试 failureThreshold 次才会放弃。 默认值为 3。 最小值为 1。
namespace namespace 将 Web 服务部署到的 Kubernetes 命名空间。 最多 63 个字符,可使用小写字母数字字符(“a”-“z”,“0”-“9”)和连字符(“-”)。 第一个和最后一个字符不能为连字符。

以下 JSON 是用于 CLI 的部署配置示例:

{
    "computeType": "aks",
    "autoScaler":
    {
        "autoscaleEnabled": true,
        "minReplicas": 1,
        "maxReplicas": 3,
        "refreshPeriodInSeconds": 1,
        "targetUtilization": 70
    },
    "dataCollection":
    {
        "storageEnabled": true
    },
    "authEnabled": true,
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    }
}

后续步骤