使用 Azure 机器学习 CLI、SDK 和 REST API 训练模型
本文内容
适用范围:Azure CLI ml 扩展 v2(最新版) Python SDK azure-ai-ml v2(最新版)
Azure 机器学习提供了多种提交 ML 训练作业的方法。 在本文中,你将了解如何使用以下方法提交作业:
用于机器学习的 Azure CLI 扩展:ml
扩展,也称为 CLI v2。
用于 Azure 机器学习的 Python SDK v2。
REST API:CLI 和 SDK 所基于的 API。
先决条件
Azure 订阅。 如果没有 Azure 订阅,请在开始前创建一个试用版订阅。 尝试试用版订阅 。
Azure 机器学习工作区。 如果没有,可以使用创建资源以开始使用 一文中的步骤。
若要使用 REST API 信息,需要以下项:
工作区中的服务主体。 管理 REST 请求使用服务主体身份验证 。
服务主体身份验证令牌。 请按照检索服务主体身份验证令牌 中的步骤检索此令牌。
curl 实用工具。 在适用于 Linux 的 Windows 子系统或任何 UNIX 分发版中均已提供了 curl 程序。
提示
在 PowerShell 中,curl
是 Invoke-WebRequest
的别名,并且 curl -d "key=val" -X POST uri
变成了 Invoke-WebRequest -Body "key=val" -Method POST -Uri uri
。
尽管可以从 PowerShell 调用 REST API,但本文中的示例假设你使用的是 Bash。
用于处理 JSON 的 jq 实用工具。 此实用工具用于从 REST API 调用返回的 JSON 文档中提取值。
克隆示例存储库
本文中的代码片段基于 Azure 机器学习示例 GitHub 存储库 中的示例。 若要将存储库克隆到开发环境,请使用以下命令:
git clone --depth 1 https://github.com/Azure/azureml-examples
提示
使用 --depth 1
仅克隆最新提交到存储库的内容,从而减少完成操作所需的时间。
示例作业
本文中的示例使用鸢尾花数据集来训练 MLFlow 模型。
在云中训练
在云中训练时,必须连接到 Azure 机器学习工作区并选择将用于运行训练作业的计算资源。
1.连接到工作区
提示
使用以下选项卡选择要用于训练模型的方法。 选择选项卡会自动将本文中的所有选项卡切换为同一选项卡。你可以随时选择另一个选项卡。
若要连接到工作区,需要提供标识符参数 - 订阅、资源组和工作区名称。 你将在 azure.ai.ml
命名空间的 MLClient
中使用这些详细信息来获取所需 Azure 机器学习工作区的句柄。 若要进行身份验证,请使用默认 Azure 身份验证 。 请查看此示例 ,了解有关如何配置凭据和连接到工作区的更多详细信息。
#import required libraries
from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential
#Enter details of your Azure Machine Learning workspace
subscription_id = '<SUBSCRIPTION_ID>'
resource_group = '<RESOURCE_GROUP>'
workspace = '<AZUREML_WORKSPACE_NAME>'
#connect to the workspace
ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)
使用 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>
本文中的 REST API 示例使用 $SUBSCRIPTION_ID
、$RESOURCE_GROUP
、$LOCATION
和 $WORKSPACE
占位符。 将占位符替换为自己的值,如下所示:
$SUBSCRIPTION_ID
:Azure 订阅 ID。
$RESOURCE_GROUP
:包含你的工作区的 Azure 资源组。
$LOCATION
:工作区所在的 Azure 区域。
$WORKSPACE
:Azure 机器学习工作区的名称。
$COMPUTE_NAME
:Azure 机器学习计算群集的名称。
管理 REST 请求一个服务主体身份验证令牌 。 可使用以下命令检索令牌。 令牌存储在 $TOKEN
环境变量中:
TOKEN=$(az account get-access-token --query accessToken -o tsv)
服务提供商使用 api-version
参数来确保兼容性。 api-version
参数因服务而异。 将 API 版本设置为变量以适应将来的版本:
API_VERSION="2022-05-01"
使用 REST API 进行训练时,必须将数据和训练脚本上传到工作区可以访问的存储帐户。 以下示例获取你的工作区的存储信息,并将其保存到变量中,以便稍后使用:
# Get values for storage account
response=$(curl --location --request GET "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/datastores?api-version=$API_VERSION&isDefault=true" \
--header "Authorization: Bearer $TOKEN")
AZUREML_DEFAULT_DATASTORE=$(echo $response | jq -r '.value[0].name')
AZUREML_DEFAULT_CONTAINER=$(echo $response | jq -r '.value[0].properties.containerName')
export AZURE_STORAGE_ACCOUNT=$(echo $response | jq -r '.value[0].properties.accountName')
2. 创建用于训练的计算资源
Azure 机器学习计算群集是一种完全托管的计算资源,可用于运行训练作业。 在以下示例中,创建了名为 cpu-compute
的计算群集。
from azure.ai.ml.entities import AmlCompute
# specify aml compute name.
cpu_compute_target = "cpu-cluster"
try:
ml_client.compute.get(cpu_compute_target)
except Exception:
print("Creating a new cpu compute target...")
compute = AmlCompute(
name=cpu_compute_target, size="STANDARD_D2_V2", min_instances=0, max_instances=4
)
ml_client.compute.begin_create_or_update(compute).result()
az ml compute create -n cpu-cluster --type amlcompute --min-instances 0 --max-instances 4
curl -X PUT \
"https://management.chinacloudapi.cn/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/computes/$COMPUTE_NAME?api-version=$API_VERSION" \
-H "Authorization:Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"location": "'$LOCATION'",
"properties": {
"computeType": "AmlCompute",
"properties": {
"vmSize": "Standard_D2_V2",
"vmPriority": "Dedicated",
"scaleSettings": {
"maxNodeCount": 4,
"minNodeCount": 0,
"nodeIdleTimeBeforeScaleDown": "PT30M"
}
}
}
}'
提示
尽管几秒钟后会返回响应,但这仅表示已接受创建请求。 可能需要几分钟时间才能完成群集创建。
3.提交训练作业
若要运行此脚本,你将使用 ./sdk/python/jobs/single-step/lightgbm/iris/src/ 下用于执行 main.py Python 脚本的 command
。 该命令通过将其作为 job
提交到 Azure 机器学习来运行。
注意
若要使用无服务器计算 ,请删除此代码中的 compute="cpu-cluster"
。
from azure.ai.ml import command, Input
# define the command
command_job = command(
code="./src",
command="python main.py --iris-csv ${{inputs.iris_csv}} --learning-rate ${{inputs.learning_rate}} --boosting ${{inputs.boosting}}",
environment="AzureML-lightgbm-3.2-ubuntu18.04-py37-cpu@latest",
inputs={
"iris_csv": Input(
type="uri_file",
path="https://azuremlexamples.blob.core.windows.net/datasets/iris.csv",
),
"learning_rate": 0.9,
"boosting": "gbdt",
},
compute="cpu-cluster",
)
# submit the command
returned_job = ml_client.jobs.create_or_update(command_job)
# get a URL for the status of the job
returned_job.services["Studio"].endpoint
在上述示例中,你配置了以下内容:
code
- 用于运行命令的代码所在的路径
command
- 需要运行的命令
environment
- 运行训练脚本所需的环境。 在此示例中,我们使用 Azure 机器学习所提供的名为 AzureML-lightgbm-3.2-ubuntu18.04-py37-cpu
的精选或现成环境。 通过使用 @latest
指令来使用此环境的最新版本。 你还可以通过指定基本 docker 映像并为其指定 conda yaml 来使用自定义环境。
inputs
- 命令的输入字典,采用名称值对的形式。 键是作业上下文中的输入名称,值是输入值。 在 command
中使用 ${{inputs.<input_name>}}
表达式引用输入。 若要将文件或文件夹用作输入,可以使用 Input
类。 有关详细信息,请参阅 SDK 和 CLI v2 表达式 。
有关详细信息,请参阅参考文档 。
提交作业时,会向 Azure 机器学习工作室中的作业状态返回一个 URL。 使用工作室 UI 查看工作进度。 你还可以使用 returned_job.status
检查作业的当前状态。
此示例中使用的 az ml job create
命令需要 YAML 作业定义文件。 此示例中使用的文件内容如下:
注意
若要使用无服务器计算 ,请删除此代码中的 compute: azureml:cpu-cluster"
。
$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
python main.py
--iris-csv ${{inputs.iris_csv}}
--C ${{inputs.C}}
--kernel ${{inputs.kernel}}
--coef0 ${{inputs.coef0}}
inputs:
iris_csv:
type: uri_file
path: wasbs://datasets@azuremlexamples.blob.core.chinacloudapi.cn/iris.csv
C: 0.8
kernel: "rbf"
coef0: 0.1
environment: azureml:AzureML-sklearn-0.24-ubuntu18.04-py37-cpu@latest
compute: azureml:cpu-cluster
display_name: sklearn-iris-example
experiment_name: sklearn-iris-example
description: Train a scikit-learn SVM on the Iris dataset.
上面配置了:
code
- 用于运行命令的代码所在的路径
command
- 需要运行的命令
inputs
- 命令的输入字典,采用名称值对的形式。 键是作业上下文中的输入名称,值是输入值。 在 command
中使用 ${{inputs.<input_name>}}
表达式引用输入。 有关详细信息,请参阅 SDK 和 CLI v2 表达式 。
environment
- 运行训练脚本所需的环境。 在此示例中,我们使用 Azure 机器学习所提供的名为 AzureML-sklearn-0.24-ubuntu18.04-py37-cpu
的精选或现成环境。 通过使用 @latest
指令来使用此环境的最新版本。 你还可以通过指定基本 docker 映像并为其指定 conda yaml 来使用自定义环境。
若要提交作业,请使用以下命令。 训练作业的运行 ID(名称)存储在 $run_id
变量中:
run_id=$(az ml job create -f jobs/single-step/scikit-learn/iris/job.yml --query name -o tsv)
你可以使用存储的运行 ID 返回有关作业的信息。 --web
参数打开 Azure 机器学习工作室 Web UI,你可在其中深入了解作业的详细信息:
az ml job show -n $run_id --web
提交作业时,必须将训练脚本和数据上传到 Azure 机器学习工作区可访问的云存储位置。
使用以下 Azure CLI 命令上传训练脚本。 该命令指定包含训练所需文件的目录,而不是指定单个文件。 若要改用 REST 来上传数据,请参阅放置 Blob 参考:
az storage blob upload-batch -d $AZUREML_DEFAULT_CONTAINER/testjob -s cli/jobs/single-step/scikit-learn/iris/src/ --account-name $AZURE_STORAGE_ACCOUNT
创建对训练数据的版本化参考。 在此示例中,数据已在云中,位于 https://azuremlexamples.blob.core.chinacloudapi.cn/datasets/iris.csv
。 有关引用数据的详细信息,请参阅 Azure 机器学习中的数据 :
DATA_VERSION=$RANDOM
curl --location --request PUT "https://management.chinacloudapi.cn/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/data/iris-data/versions/$DATA_VERSION?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw "{
\"properties\": {
\"description\": \"Iris dataset\",
\"dataType\": \"uri_file\",
\"dataUri\": \"https://azuremlexamples.blob.core.chinacloudapi.cn/datasets/iris.csv\"
}
}"
注册对训练脚本的版本化参考,用于作业。 在此示例中,脚本位置是你在步骤 1 中将数据上传到的默认存储帐户和容器。 将返回带版本训练代码的 ID 并将其存储在 $TRAIN_CODE
变量中:
TRAIN_CODE=$(curl --location --request PUT "https://management.chinacloudapi.cn/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/codes/train-lightgbm/versions/1?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw "{
\"properties\": {
\"description\": \"Train code\",
\"codeUri\": \"https://$AZURE_STORAGE_ACCOUNT.blob.core.chinacloudapi.cn/$AZUREML_DEFAULT_CONTAINER/testjob\"
}
}" | jq -r '.id')
创建群集将用于运行训练脚本的环境。 在此示例中,我们使用 Azure 机器学习所提供的名为 AzureML-lightgbm-3.2-ubuntu18.04-py37-cpu
的精选或现成环境。 以下命令检索环境版本列表,其中最新版本位于集合顶部。 jq
用于检索最新 ([0]
) 版本的 ID,然后将其存储到 $ENVIRONMENT
变量中。
ENVIRONMENT=$(curl --location --request GET "https://management.chinacloudapi.cn/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/environments/AzureML-lightgbm-3.2-ubuntu18.04-py37-cpu/versions?api-version=$API_VERSION" --header "Authorization: Bearer $TOKEN" | jq -r .value[0].id)
最后,提交作业。 以下示例介绍如何提交作业,以及如何参考训练代码 ID、环境 ID、输入数据的 URL 和计算群集的 ID。 作业输出位置将存储在 $JOB_OUTPUT
变量中:
提示
作业名称必须唯一。 在此示例中,uuidgen
用于生成名称的唯一值。
注意
若要使用无服务器计算 ,请删除此代码中的 \"computeId\":
行。
run_id=$(uuidgen)
curl --location --request PUT "https://management.chinacloudapi.cn/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/jobs/$run_id?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw "{
\"properties\": {
\"jobType\": \"Command\",
\"codeId\": \"$TRAIN_CODE\",
\"command\": \"python main.py --iris-csv \$AZURE_ML_INPUT_iris\",
\"environmentId\": \"$ENVIRONMENT\",
\"inputs\": {
\"iris\": {
\"jobInputType\": \"uri_file\",
\"uri\": \"https://azuremlexamples.blob.core.chinacloudapi.cn/datasets/iris.csv\"
}
},
\"experimentName\": \"lightgbm-iris\",
\"computeId\": \"/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/computes/$COMPUTE_NAME\"
}
}"
注册已训练的模型
以下示例介绍如何在 Azure 机器学习工作区中注册模型。
提示
训练作业返回的 name
属性用作模型路径的一部分。
from azure.ai.ml.entities import Model
from azure.ai.ml.constants import AssetTypes
run_model = Model(
path="azureml://jobs/{}/outputs/artifacts/paths/model/".format(returned_job.name),
name="run-model-example",
description="Model created from run.",
type=AssetTypes.MLFLOW_MODEL
)
ml_client.models.create_or_update(run_model)
提示
名称(存储在 $run_id
变量中)用作模型路径的一部分。
az ml model create -n sklearn-iris-example -v 1 -p runs:/$run_id/model --type mlflow_model
提示
名称(存储在 $run_id
变量中)用作模型路径的一部分。
curl --location --request PUT "https://management.chinacloudapi.cn/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/models/sklearn/versions/1?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw "{
\"properties\": {
\"modelType\": \"mlflow_model\",
\"modelUri\":\"runs:/$run_id/model\"
}
}"
后续步骤
训练模型后,了解如何使用在线终结点部署该模型 。
更多示例,请参阅 Azure 机器学习示例 GitHub 存储库。
有关本文中使用的 Azure CLI 命令、Python SDK 类或 REST API 的详细信息,请参阅以下参考文档: