使用 MLflow 运行管理训练代码

项目
05/11/2024

本文介绍用于管理机器学习训练的 MLflow 运行。它还包括有关如何跨试验管理和比较运行的指导。

一个 MLflow 运行对应于模型代码的单次执行。每个运行都记录以下信息：

源：启动了此运行的笔记本的名称，或者此运行的项目名称和入口点。
- 版本：如果笔记本存储在 Databricks Git 文件夹中或从 MLflow 项目运行，则为 Git 提交哈希。否则为笔记本修订版。
- 开始与结束时间：运行的开始时间和结束时间。
- 参数：保存为键值对的模型参数。键和值都是字符串。
- 指标：保存为键值对的模型评估指标。值为数字。每个指标都可以在整个运行过程中更新（例如，用于跟踪模型的损失函数如何聚合），而 MLflow 会记录指标的历史记录并将其可视化。
- 标记：运行保存为键值对的元数据。可以在运行过程中和运行完成后更新标记。键和值都是字符串。
- 项目：任意格式的输出文件。例如，可以将图像、模型（例如，pickle 格式的 scikit-learn 模型）和数据文件（例如，Parquet 文件）记录为项目。

所有 MLflow 运行都会记录到活动试验中。如果尚未将某个试验显式设置为活动试验，则会将运行记录到笔记本试验。

查看运行

可以从运行的父试验页访问运行，或直接从创建运行的笔记本访问运行。

从试验页的运行表中，单击运行的开始时间。

在笔记本的“试验运行”边栏中，单击运行的日期和时间旁边的外部链接图标。

运行屏幕显示了用于运行的参数、运行所生成的指标以及任何标记或注释。若要显示此运行的“注释”、“参数”、“指标”或“标记”，请单击标签左侧的。

你还可以在此屏幕中访问从运行中保存的项目。

查看运行

用于预测的代码片段

如果从运行中记录模型，则该模型显示在本页的“项目”部分。若要显示代码片段，以便说明如何加载并使用模型来对 Spark 和 pandas DataFrames 进行预测，请单击模型名称。

预测代码片段

查看用于运行的笔记本或 Git 项目

若要查看创建了运行的笔记本的版本，请执行以下操作：

在试验页上，单击“源”列中的链接。
在运行页上，单击“源”旁边的链接。
在笔记本的“试验运行”边栏中，单击试该验运行框中的“笔记本”图标。

与该运行关联的笔记本版本会在主窗口中显示，并有一个高亮条显示运行日期和时间。

如果已从 Git 项目以远程方式启动了运行，则请单击“Git 提交”字段中的链接，以打开运行中所用项目的特定版本。 “源”字段中的链接可打开用于运行的 Git 项目的主分支。

向运行中添加标记

标签是键值对，你可以创建这些键值对，并在以后使用这些键值对来搜索运行。

在运行页面中，单击（如果尚未打开）。此时将显示标记表。
单击“名称”和“值”字段，然后键入标签的键和值。
单击“添加”。

编辑或删除运行的标记

若要编辑或删除现有标记，请使用“操作”列中的图标。

标记操作

重现运行的软件环境

通过单击“重现运行”可重现运行所需的确切软件环境。以下对话框随即出现：

“重现运行”对话框

单击“确认”使用默认设置时：

笔记本将克隆到对话框中显示的位置。
如果原始群集仍存在，则克隆的笔记本将附加到原始群集并启动该群集。
如果原始群集不再存在，则会创建并启动与原始群集配置相同（包括任何已安装的库）的新群集。笔记本将附加到新群集。

可为克隆的笔记本选择不同的位置，并检查群集配置和已安装的库：

若要选择其他文件夹保存克隆的笔记本，请单击“编辑文件夹”。
若要查看群集规格，请单击“查看规格”。若要仅克隆笔记本而不克隆群集，请取消选中此选项。
若要查看原始群集上安装的库，请单击“查看库”。如果无需考虑安装的库是否与原始群集上的库相同，请取消选中此选项。

管理运行

重命名运行

若要重命名运行，请单击运行页右上角的，然后选择“重命名”。

筛选运行

可基于参数或指标值搜索运行。你还可以按标记搜索运行。

若要搜索与包含参数和指标值的表达式匹配的运行，请在搜索字段中输入查询并单击“搜索”。查询的部分语法示例如下：

metrics.r2 > 0.3

params.elasticNetParam = 0.5

params.elasticNetParam = 0.5 AND metrics.avg_areaUnderROC > 0.3
要按标记搜索运行，请按以下格式输入标记：tags.<key>="<value>"。字符串值必须用引号引起来，如下所示。

tags.estimator_name="RandomForestRegressor"

tags.color="blue" AND tags.size=5

键和值都可以包含空格。如果键包含空格，则必须将其括在反引号中，如下所示。
```
tags.`my custom tag` = "my value"
```

还可根据运行状态（“活动”或“已删除”）以及模型版本是否与运行关联来筛选运行。为此，请分别在“状态”和“创建时间”下拉菜单中做出选择。

筛选运行

下载运行

选择一个或多个运行。

单击“下载 CSV”。包含以下字段的 CSV 文件下载：

Run ID,Name,Source Type,Source Name,User,Status,<parameter1>,<parameter2>,...,<metric1>,<metric2>,...

删除运行

可以通过以下步骤使用 Databricks 机器学习 UI 删除运行：

在试验中，通过单击运行左侧的复选框来选择一个或多个运行。
单击 “删除” 。
如果运行为父运行，则确定是否也要删除后代运行。默认情况下选择此选项。
单击“删除”进行确认。删除的运行保存 30 天。若要显示删除的运行，请选择“状态”字段中的“已删除”。

基于创建时间批量删除运行

可以使用 Python 批量删除在某个 UNIX 时间戳处或之前创建的试验的运行。使用 Databricks Runtime 14.1 或更高版本，可以调用 mlflow.delete_runs API 来删除运行并返回已删除的运行数。

以下是 mlflow.delete_runs 参数：

experiment_id：包含要删除的运行的试验 ID。
max_timestamp_millis：自删除运行的 UNIX 纪元以来的最大创建时间戳（以毫秒为单位）。仅删除在此时间戳或之前创建的运行。
max_runs：可选。一个正整数，表示要删除的最大运行数。 max_runs 允许的最大值为 10000。如果未指定，则 max_runs 默认为 10000。

import mlflow

# Replace <experiment_id>, <max_timestamp_ms>, and <max_runs> with your values.
runs_deleted = mlflow.delete_runs(
  experiment_id=<experiment_id>,
  max_timestamp_millis=<max_timestamp_ms>,
  max_runs=<max_runs>
)
# Example:
runs_deleted = mlflow.delete_runs(
  experiment_id="4183847697906956",
  max_timestamp_millis=1711990504000,
  max_runs=10
)

使用 Databricks Runtime 13.3 LTS 或更早版本，可以在 Azure Databricks Notebook 中运行以下客户端代码。

from typing import Optional

def delete_runs(experiment_id: str,
                max_timestamp_millis: int,
                max_runs: Optional[int] = None) -> int:
    """
    Bulk delete runs in an experiment that were created prior to or at the specified timestamp.
    Deletes at most max_runs per request.

    :param experiment_id: The ID of the experiment containing the runs to delete.
    :param max_timestamp_millis: The maximum creation timestamp in milliseconds
                                  since the UNIX epoch for deleting runs. Only runs
                                  created prior to or at this timestamp are deleted.
    :param max_runs: Optional. A positive integer indicating the maximum number
                      of runs to delete. The maximum allowed value for max_runs
                      is 10000. If not specified, max_runs defaults to 10000.
    :return: The number of runs deleted.
    """
    from mlflow.utils.databricks_utils import get_databricks_host_creds
    from mlflow.utils.request_utils import augmented_raise_for_status
    from mlflow.utils.rest_utils import http_request

    json_body = {"experiment_id": experiment_id, "max_timestamp_millis": max_timestamp_millis}
    if max_runs is not None:
        json_body["max_runs"] = max_runs
    response = http_request(
        host_creds=get_databricks_host_creds(),
        endpoint="/api/2.0/mlflow/databricks/runs/delete-runs",
        method="POST",
        json=json_body,
    )
    augmented_raise_for_status(response)
    return response.json()["runs_deleted"]

有关基于创建时间删除运行的参数和返回值规范，请参阅 Azure Databricks 试验 API 文档。

还原运行

可以使用 Databricks 机器学习 UI 还原以前删除的运行。

在“试验”页上的“状态”字段中选择“已删除”以显示已删除的运行。
通过单击运行左侧的复选框来选择一个或多个运行。
请单击“还原”。
单击“还原”进行确认。要显示已还原的运行，请在“状态”字段中选择“活动”。

基于删除时间批量还原运行

还可以使用 Python 批量还原在某个 UNIX 时间戳或之后删除的试验的运行。使用 Databricks Runtime 14.1 或更高版本，可以调用 mlflow.restore_runs API 来还原运行并返回已还原的运行数。

以下是 mlflow.restore_runs 参数：

experiment_id：包含要还原的运行的试验 ID。
min_timestamp_millis：自还原运行的 UNIX 纪元以来的最小删除时间戳（以毫秒为单位）。仅还原在此时间戳或之后删除的运行。
max_runs：可选。一个正整数，表示要还原的最大运行数。 max_runs 允许的最大值为 10000。如果未指定，则 max_runs 默认为 10000。

import mlflow

# Replace <experiment_id>, <min_timestamp_ms>, and <max_runs> with your values.
runs_restored = mlflow.restore_runs(
  experiment_id=<experiment_id>,
  min_timestamp_millis=<min_timestamp_ms>,
  max_runs=<max_runs>
)
# Example:
runs_restored = mlflow.restore_runs(
  experiment_id="4183847697906956",
  min_timestamp_millis=1711990504000,
  max_runs=10
)

使用 Databricks Runtime 13.3 LTS 或更早版本，可以在 Azure Databricks Notebook 中运行以下客户端代码。

from typing import Optional

def restore_runs(experiment_id: str,
                 min_timestamp_millis: int,
                 max_runs: Optional[int] = None) -> int:
    """
    Bulk restore runs in an experiment that were deleted at or after the specified timestamp.
    Restores at most max_runs per request.

    :param experiment_id: The ID of the experiment containing the runs to restore.
    :param min_timestamp_millis: The minimum deletion timestamp in milliseconds
                                 since the UNIX epoch for restoring runs. Only runs
                                 deleted at or after this timestamp are restored.
    :param max_runs: Optional. A positive integer indicating the maximum number
                     of runs to restore. The maximum allowed value for max_runs
                     is 10000. If not specified, max_runs defaults to 10000.
    :return: The number of runs restored.
    """
    from mlflow.utils.databricks_utils import get_databricks_host_creds
    from mlflow.utils.request_utils import augmented_raise_for_status
    from mlflow.utils.rest_utils import http_request
    json_body = {"experiment_id": experiment_id, "min_timestamp_millis": min_timestamp_millis}
    if max_runs is not None:
        json_body["max_runs"] = max_runs
    response = http_request(
        host_creds=get_databricks_host_creds(),
        endpoint="/api/2.0/mlflow/databricks/runs/restore-runs",
        method="POST",
        json=json_body,
    )
    augmented_raise_for_status(response)
    return response.json()["runs_restored"]

有关基于删除时间还原运行的参数和返回值规范，请参阅 Azure Databricks 试验 API 文档。

比较运行

可以比较单个试验或多个试验中的运行。 “比较运行”页以图形和表格格式显示有关所选运行的信息。还可以创建运行结果的可视化效果，以及运行信息、运行参数和指标的表。

若要创建可视化效果，请执行以下操作：

选择绘图类型（“平行坐标图”、“散点图”或“等高线图”）。
1. 对于“平行坐标图”，请选择要绘制的参数和指标。在此处，可以确定所选参数和指标之间的关系，这有助于更好地定义模型的超参数优化空间。
2. 对于“散点图”或“等高线图”，请选择要在每个轴上显示的参数或指标。

“参数”和“指标”表显示所有选定运行中的运行参数和指标。这些表中的列由紧靠其上的“运行详细信息”表标识。为方便起见，可以通过切换仅显示差异按钮来隐藏所有选定运行中相同的参数和指标。

比较运行页表

比较单个试验中的运行

在试验页上，通过单击运行左侧的复选框来选择两个或更多个运行，或者通过选中列顶部的框来选择所有运行。
单击“比较”。此时将出现“比较 <N> 个运行”屏幕。

比较多个试验中的运行

在试验页上，通过单击试验名称左侧的框来选择要比较的试验。
单击“比较 (n) 个”（n 是选择的试验数）。此时将出现一个屏幕，其中显示了所选试验中的所有运行。
通过单击运行左侧的复选框来选择两个或更多个运行，或者通过选中列顶部的框来选择所有运行。
单击“比较”。此时将出现“比较 <N> 个运行”屏幕。

在工作区之间复制运行

若要将 MLflow 运行导入或导出 Databricks 工作区，可以使用社区驱动的开放源代码项目 MLflow Export-Import。

通过

使用 MLflow 运行管理训练代码

查看运行

用于预测的代码片段

查看用于运行的笔记本或 Git 项目

向运行中添加标记

编辑或删除运行的标记

重现运行的软件环境

管理运行

重命名运行

筛选运行

下载运行

删除运行

基于创建时间批量删除运行

还原运行

基于删除时间批量还原运行

比较运行

比较单个试验中的运行

比较多个试验中的运行

在工作区之间复制运行

其他资源