安装并使用 CLI (v1)

适用于：Azure CLI ml 扩展 v1

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/deviceloginchina 并输入授权代码。

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

安装扩展

若要安装 CLI (v1) 扩展，请执行以下操作：

az extension add -n azure-cli-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 chinanorth2
  

• 创建 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。

计算实例

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

• 创建新的 computeinstance。

  az ml computetarget create computeinstance -n cpu -s "STANDARD_D3_V2" -v
  

  有关详细信息，请参阅 az ml computetarget create computeinstance。

• 停止 computeinstance。

  az ml computetarget computeinstance stop -n cpu -v
  

  有关详细信息，请参阅 az ml computetarget computeinstance stop。

• 启动 computeinstance。

  az ml computetarget computeinstance start -n cpu -v
  

  有关详细信息，请参阅 az ml computetarget computeinstance start。

• 重启 computeinstance。

  az ml computetarget computeinstance restart -n cpu -v
  

  有关详细信息，请参阅 az ml computetarget computeinstance restart。

• 删除 computeinstance。

  az ml computetarget delete -n cpu -v
  

  有关详细信息，请参阅 az ml computetarget delete computeinstance。

运行试验

• 开始运行试验。 使用此命令时，请针对 -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 类中的公共变量名称之间存在松散的一对一匹配。 在某些情况下，字段可能会映射到构造函数参数，而不是类变量。 例如，environmentVariables 字段映射到 Environment 类中的 environment_variables 变量。

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

ML 管道管理

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

• 创建机器学习管道：

  az ml pipeline create -n mypipeline -y mypipeline.yml
  

  有关详细信息，请参阅 az ml pipeline create。

  有关管道 YAML 文件的详细信息，请参阅在 YAML 中定义机器学习管道。

• 运行管道：

  az ml run submit-pipeline -n myexperiment -y mypipeline.yml
  

  有关详细信息，请参阅 az ml run submit-pipeline。

  有关管道 YAML 文件的详细信息，请参阅在 YAML 中定义机器学习管道。

• 计划管道：

  az ml pipeline create-schedule -n myschedule -e myexperiment -i mypipelineid -y myschedule.yml
  

  有关详细信息，请参阅 az ml pipeline create-schedule。

模型注册、分析和部署

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

• 将模型注册到 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/intelmpi2018.3-ubuntu18.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.7",
                    {
                        "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 服务启用密钥身份验证。 tokenAuthEnabled 和 authEnabled 均不能为 True。 默认值为 True。
tokenAuthEnabled	token_auth_enabled	是否为 Web 服务启用令牌身份验证。 tokenAuthEnabled 和 authEnabled 均不能为 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
    }
}

后续步骤

• 机器学习 CLI 扩展的命令参考。