将记录从 SDK v1 迁移到 SDK v2

项目
08/29/2024

Azure 机器学习将 MLflow 跟踪用于试验的指标日志记录和项目存储，无论试验是通过 Azure 机器学习 Python SDK、Azure 机器学习 CLI 还是 Azure 机器学习工作室创建的。建议使用 MLflow 来跟踪试验。

如果要从 SDK v1 迁移到 SDK v2，请使用本部分中的信息来了解 SDK v1 记录 API 的 MLflow 等效项。

为什么使用 MLflow？

MLflow 每月下载量超过 1300 万次，已成为端到端 MLOps 的标准平台，各种规模的团队通过它都能够跟踪、共享、打包和部署任何模型以进行批量或实时推理。 Azure 机器学习与 MLflow 集成，可支持训练代码实现真正的可移植性，并与其他平台无缝集成，因为它不包含任何特定于 Azure 机器学习的指令。

准备迁移到 MLflow

要使用 MLflow 跟踪，需要安装 Mlflow SDK 包 mlflow 和适用于 MLflow azureml-mlflow 的 Azure 机器学习插件。所有 Azure 机器学习环境已提供这些包，但如果创建自己的环境，则需包含这些包。

pip install mlflow azureml-mlflow

连接到工作区

用户使用 Azure 机器学习可在工作区上运行或远程运行的训练作业中执行跟踪（跟踪在 Azure 机器学习外部运行的试验）。如果执行远程跟踪，则需指示要将 MLflow 连接到的工作区。

Azure 机器学习计算
远程计算

在 Azure 机器学习计算中运行时，已连接到工作区。

配置跟踪 URI

获取工作区的跟踪 URI：
- Azure CLI
- Python
- 工作室
- 手动
适用于：Azure CLI ml 扩展 v2（当前）
1. 登录并配置工作区：
```
az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location> 
```
2. 可以使用 az ml workspace 命令获取跟踪 URI：
```
az ml workspace show --query mlflow_tracking_uri
```
适用于：Python SDK azure-ai-ml v2（当前版本）

可以使用适用于 Python 的 Azure 机器学习 SDK v2 获取 Azure ML MLflow 跟踪 URI。确保在使用的计算中安装了库 azure-ai-ml。以下示例获取与工作区关联的唯一 MLFLow 跟踪 URI。
1. 使用 MLClient 登录到工作区。要执行此操作，更简单方法是使用工作区配置文件：
```
from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential

ml_client = MLClient.from_config(credential=DefaultAzureCredential())
```
  提示
  
  可以通过以下方式下载工作区配置文件：
  
  导航到 Azure ML 工作室
  
  单击页面右上角 -> 下载配置文件。
  
  将文件 config.json 保存到正在使用的同一目录中。
2. 或者，也可以使用订阅 ID、资源组名称和工作区名称来获取：
```
from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential

#Enter details of your AzureML workspace
subscription_id = '<SUBSCRIPTION_ID>'
resource_group = '<RESOURCE_GROUP>'
workspace_name = '<WORKSPACE_NAME>'

ml_client = MLClient(credential=DefaultAzureCredential(),
                        subscription_id=subscription_id, 
                        resource_group_name=resource_group,
                        workspace_name=workspace_name)
```
  重要
  
  DefaultAzureCredential 将尝试从可用上下文中拉取凭据。如果想要以其他方式指定凭据，例如以交互式方式使用 Web 浏览器，则可以使用 InteractiveBrowserCredential 或 azure.identity 包中提供的任何其他方法。
3. 获取 Azure 机器学习跟踪 URI：
```
mlflow_tracking_uri = ml_client.workspaces.get(ml_client.workspace_name).mlflow_tracking_uri
```
使用 Azure 机器学习门户获取跟踪 URI：
1. 打开 Azure 机器学习工作室并使用你的凭据登录。
2. 在右上角，单击工作区的名称以显示“目录 + 订阅 + 工作区”边栏选项卡。
3. 单击“在 Azure 门户中查看所有属性”。
4. 可以在“概要”部分中找到“MLflow 跟踪 URI”属性。
Azure 机器学习跟踪 URI 可以使用订阅 ID、资源部署区域、资源组名称和工作区名称来生成。以下代码示例显示了如何：

警告

如果在启用了专用链接的工作区中工作，MLflow 终结点还将使用专用链接与 Azure 机器学习通信。因此，跟踪 URI 看起来会有所不同，如此处所示。在这些情况下，需要使用 Azure ML SDK 或 CLI v2 获取跟踪 URI。
```
region = "<LOCATION>"
subscription_id = '<SUBSCRIPTION_ID>'
resource_group = '<RESOURCE_GROUP>'
workspace_name = '<AML_WORKSPACE_NAME>'

mlflow_tracking_uri = f"azureml://{region}.api.azureml.ms/mlflow/v1.0/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.MachineLearningServices/workspaces/{workspace_name}"
```
配置跟踪 URI：
- 使用 MLflow SDK
- 使用环境变量
然后，set_tracking_uri() 方法将 MLflow 跟踪 URI 指向该 URI。
```
import mlflow

mlflow.set_tracking_uri(mlflow_tracking_uri)
```
可以在计算中设置 MLflow 环境变量 MLFLOW_TRACKING_URI，从而将与该计算中的 MLflow 的任何交互默认指向 Azure 机器学习。
```
MLFLOW_TRACKING_URI=$(az ml workspace show --query mlflow_tracking_uri | sed 's/"//g') 
```
提示

使用共享环境（如 Azure Databricks 群集、Azure Synapse Analytics 群集或类似环境）时，可以在群集级别设置环境变量 MLFLOW_TRACKING_URI 以自动配置 MLflow 跟踪 URI，以指向群集中运行的基于所有会话的 Azure 机器学习，而不是指向群集中运行的基于每会话的 Azure 机器学习。

配置身份验证

配置跟踪后，还需要配置需要对关联工作区进行身份验证的方式。默认情况下，适用于 MLflow 的 Azure 机器学习插件将通过打开默认浏览器提示输入凭据来执行交互式身份验证。有关在 Azure 机器学习工作区中为 MLflow 配置身份验证的更多方法，请参阅为 Azure 机器学习配置 MLflow：配置身份验证。

如果交互式作业有用户连接到会话，你可以依赖交互式身份验证，因此无需进一步操作。

警告

在系统提示输入凭据时，交互式浏览器身份验证将阻止代码执行。此方法不适用于无人参与的环境（如训练作业）中的身份验证。建议配置不同的身份验证模式。

对于需要无人参与执行的方案，则必须配置服务主体，以便与 Azure 机器学习通信。

MLflow SDK
使用环境变量

import os

os.environ["AZURE_TENANT_ID"] = "<AZURE_TENANT_ID>"
os.environ["AZURE_CLIENT_ID"] = "<AZURE_CLIENT_ID>"
os.environ["AZURE_CLIENT_SECRET"] = "<AZURE_CLIENT_SECRET>"

export AZURE_TENANT_ID="<AZURE_TENANT_ID>"
export AZURE_CLIENT_ID="<AZURE_CLIENT_ID>"
export AZURE_CLIENT_SECRET="<AZURE_CLIENT_SECRET>"

提示

使用共享环境时，建议在计算中配置这些环境变量。最佳做法是在 Azure 密钥保管库实例中将这些环境变量作为机密进行管理。

例如，在 Azure Databricks 中，可以在群集配置的环境变量中使用机密，如下所示：AZURE_CLIENT_SECRET={{secrets/<scope-name>/<secret-name>}}。有关在 Azure Databricks 中实现此方法的详细信息，请参阅引用环境变量中的机密或参考适用于你平台的文档。

实验和运行

SDK v1

from azureml.core import Experiment

# create an Azure Machine Learning experiment and start a run
experiment = Experiment(ws, "create-experiment-sdk-v1")
azureml_run = experiment.start_logging()

使用 MLflow 的 SDK v2

# Set the MLflow experiment and start a run
mlflow.set_experiment("logging-with-mlflow")
mlflow_run = mlflow.start_run()

记录 API 比较

记录整数或浮点数指标

SDK v1

azureml_run.log("sample_int_metric", 1)

使用 MLflow 的 SDK v2

mlflow.log_metric("sample_int_metric", 1)

记录布尔指标

SDK v1

azureml_run.log("sample_boolean_metric", True)

使用 MLflow 的 SDK v2

mlflow.log_metric("sample_boolean_metric", 1)

记录字符串指标

SDK v1

azureml_run.log("sample_string_metric", "a_metric")

使用 MLflow 的 SDK v2

mlflow.log_text("sample_string_text", "string.txt")

字符串将记录为项目，而不是记录为指标。在 Azure 机器学习工作室中，该值会显示在“输出 + 日志”选项卡中。

将图像记录到 PNG 或 JPEG 文件

SDK v1

azureml_run.log_image("sample_image", path="Azure.png")

使用 MLflow 的 SDK v2

mlflow.log_artifact("Azure.png")

图像会记录为项目，并将显示在 Azure 机器学习工作室中的“图像”选项卡中。

记录 matplotlib.pyplot

SDK v1

import matplotlib.pyplot as plt

plt.plot([1, 2, 3])
azureml_run.log_image("sample_pyplot", plot=plt)

使用 MLflow 的 SDK v2

import matplotlib.pyplot as plt

plt.plot([1, 2, 3])
fig, ax = plt.subplots()
ax.plot([0, 1], [2, 3])
mlflow.log_figure(fig, "sample_pyplot.png")

图像会记录为项目，并将显示在 Azure 机器学习工作室中的“图像”选项卡中。

记录指标列表

SDK v1

list_to_log = [1, 2, 3, 2, 1, 2, 3, 2, 1]
azureml_run.log_list('sample_list', list_to_log)

使用 MLflow 的 SDK v2

list_to_log = [1, 2, 3, 2, 1, 2, 3, 2, 1]
from mlflow.entities import Metric
from mlflow.tracking import MlflowClient
import time

metrics = [Metric(key="sample_list", value=val, timestamp=int(time.time() * 1000), step=0) for val in list_to_log]
MlflowClient().log_batch(mlflow_run.info.run_id, metrics=metrics)

指标显示在 Azure 机器学习工作室中的“指标”选项卡中。
不支持文本值。

记录一行指标

SDK v1

azureml_run.log_row("sample_table", col1=5, col2=10)

使用 MLflow 的 SDK v2

metrics = {"sample_table.col1": 5, "sample_table.col2": 10}
mlflow.log_metrics(metrics)

在 Azure 机器学习工作室中，指标不会呈现为表。
不支持文本值。
记录为项目，而不是指标。

记录表

SDK v1

table = {
"col1" : [1, 2, 3],
"col2" : [4, 5, 6]
}
azureml_run.log_table("table", table)

使用 MLflow 的 SDK v2

# Add a metric for each column prefixed by metric name. Similar to log_row
row1 = {"table.col1": 5, "table.col2": 10}
# To be done for each row in the table
mlflow.log_metrics(row1)

# Using mlflow.log_artifact
import json

with open("table.json", 'w') as f:
json.dump(table, f)
mlflow.log_artifact("table.json")

记录每个列的指标。
在 Azure 机器学习工作室中，指标不会呈现为表。
不支持文本值。
记录为项目，而不是指标。

记录准确度表

SDK v1

ACCURACY_TABLE = '{"schema_type": "accuracy_table", "schema_version": "v1", "data": {"probability_tables": ' +\
        '[[[114311, 385689, 0, 0], [0, 0, 385689, 114311]], [[67998, 432002, 0, 0], [0, 0, ' + \
        '432002, 67998]]], "percentile_tables": [[[114311, 385689, 0, 0], [1, 0, 385689, ' + \
        '114310]], [[67998, 432002, 0, 0], [1, 0, 432002, 67997]]], "class_labels": ["0", "1"], ' + \
        '"probability_thresholds": [0.52], "percentile_thresholds": [0.09]}}'

azureml_run.log_accuracy_table('v1_accuracy_table', ACCURACY_TABLE)

使用 MLflow 的 SDK v2

ACCURACY_TABLE = '{"schema_type": "accuracy_table", "schema_version": "v1", "data": {"probability_tables": ' +\
        '[[[114311, 385689, 0, 0], [0, 0, 385689, 114311]], [[67998, 432002, 0, 0], [0, 0, ' + \
        '432002, 67998]]], "percentile_tables": [[[114311, 385689, 0, 0], [1, 0, 385689, ' + \
        '114310]], [[67998, 432002, 0, 0], [1, 0, 432002, 67997]]], "class_labels": ["0", "1"], ' + \
        '"probability_thresholds": [0.52], "percentile_thresholds": [0.09]}}'

mlflow.log_dict(ACCURACY_TABLE, 'mlflow_accuracy_table.json')

在 Azure 机器学习工作室中，指标不会呈现为准确度表。
记录为项目，而不是指标。
mlflow.log_dict 方法是实验性方法。

记录混淆矩阵

SDK v1

CONF_MATRIX = '{"schema_type": "confusion_matrix", "schema_version": "v1", "data": {"class_labels": ' + \
    '["0", "1", "2", "3"], "matrix": [[3, 0, 1, 0], [0, 1, 0, 1], [0, 0, 1, 0], [0, 0, 0, 1]]}}'

azureml_run.log_confusion_matrix('v1_confusion_matrix', json.loads(CONF_MATRIX))

使用 MLflow 的 SDK v2

CONF_MATRIX = '{"schema_type": "confusion_matrix", "schema_version": "v1", "data": {"class_labels": ' + \
    '["0", "1", "2", "3"], "matrix": [[3, 0, 1, 0], [0, 1, 0, 1], [0, 0, 1, 0], [0, 0, 0, 1]]}}'

mlflow.log_dict(CONF_MATRIX, 'mlflow_confusion_matrix.json')

在 Azure 机器学习工作室中，指标不会呈现为混淆矩阵。
记录为项目，而不是指标。
mlflow.log_dict 方法是实验性方法。

记录预测

SDK v1

PREDICTIONS = '{"schema_type": "predictions", "schema_version": "v1", "data": {"bin_averages": [0.25,' + \
    ' 0.75], "bin_errors": [0.013, 0.042], "bin_counts": [56, 34], "bin_edges": [0.0, 0.5, 1.0]}}'

azureml_run.log_predictions('test_predictions', json.loads(PREDICTIONS))

使用 MLflow 的 SDK v2

PREDICTIONS = '{"schema_type": "predictions", "schema_version": "v1", "data": {"bin_averages": [0.25,' + \
    ' 0.75], "bin_errors": [0.013, 0.042], "bin_counts": [56, 34], "bin_edges": [0.0, 0.5, 1.0]}}'

mlflow.log_dict(PREDICTIONS, 'mlflow_predictions.json')

在 Azure 机器学习工作室中，指标不会呈现为混淆矩阵。
记录为项目，而不是指标。
mlflow.log_dict 方法是实验性方法。

记录残差

SDK v1

RESIDUALS = '{"schema_type": "residuals", "schema_version": "v1", "data": {"bin_edges": [100, 200, 300], ' + \
'"bin_counts": [0.88, 20, 30, 50.99]}}'

azureml_run.log_residuals('test_residuals', json.loads(RESIDUALS))

使用 MLflow 的 SDK v2

RESIDUALS = '{"schema_type": "residuals", "schema_version": "v1", "data": {"bin_edges": [100, 200, 300], ' + \
'"bin_counts": [0.88, 20, 30, 50.99]}}'

mlflow.log_dict(RESIDUALS, 'mlflow_residuals.json')

在 Azure 机器学习工作室中，指标不会呈现为混淆矩阵。
记录为项目，而不是指标。
mlflow.log_dict 方法是实验性方法。

查看运行信息和数据

可以使用 mLflow 运行 (mlflow.entities.Run) 对象的属性 data 和 info 来访问运行信息。

提示

可以使用 MLflow 查询 Azure 机器学习中的试验和运行跟踪信息，MLflow 可提供全面的搜索 API 来轻松查询和搜索试验和运行，并快速比较结果。有关此维度的 MLflow 中所有功能的详细信息，请参阅使用 MLflow 查询并比较试验和运行

以下示例展示了如何检索已完成的运行：

from mlflow.tracking import MlflowClient

# Use MlFlow to retrieve the run that was just completed
client = MlflowClient()
finished_mlflow_run = MlflowClient().get_run("<RUN_ID>")

以下示例展示了如何查看 metrics、tags 和 params：

metrics = finished_mlflow_run.data.metrics
tags = finished_mlflow_run.data.tags
params = finished_mlflow_run.data.params

注意

metrics 将仅具有给定指标的最近记录值。例如，如果按顺序依次将 1、2、3 和 4 的值记录到名为 sample_metric 的指标，则 metrics 字典中将仅存在 4。若要获取为特定命名指标记录的所有指标，请使用 MlFlowClient.get_metric_history：

with mlflow.start_run() as multiple_metrics_run:
    mlflow.log_metric("sample_metric", 1)
    mlflow.log_metric("sample_metric", 2)
    mlflow.log_metric("sample_metric", 3)
    mlflow.log_metric("sample_metric", 4)

print(client.get_run(multiple_metrics_run.info.run_id).data.metrics)
print(client.get_metric_history(multiple_metrics_run.info.run_id, "sample_metric"))

有关详细信息，请参阅 MlFlowClient 参考。

info 字段提供有关运行的常规信息，例如开始时间、运行 ID、实验 ID 等：

run_start_time = finished_mlflow_run.info.start_time
run_experiment_id = finished_mlflow_run.info.experiment_id
run_id = finished_mlflow_run.info.run_id

查看运行项目

若要查看运行的项目，请使用 MlFlowClient.list_artifacts：

client.list_artifacts(finished_mlflow_run.info.run_id)

要下载项目，请使用 mlflow.artifacts.download_artifacts：

mlflow.artifacts.download_artifacts(run_id=finished_mlflow_run.info.run_id, artifact_path="Azure.png")

通过

将记录从 SDK v1 迁移到 SDK v2

为什么使用 MLflow？

准备迁移到 MLflow

连接到工作区

实验和运行

记录 API 比较

记录整数或浮点数指标

记录布尔指标

记录字符串指标

将图像记录到 PNG 或 JPEG 文件

记录 matplotlib.pyplot

记录指标列表

记录一行指标

记录表

记录准确度表

记录混淆矩阵

记录预测

记录残差

查看运行信息和数据

查看运行项目

后续步骤

其他资源