MLflow 配方

MLflow Recipes（以前称为 MLflow Pipelines）是一个框架，使数据科学家能够快速开发高质量的模型并将其部署到生产中。与临时 ML 工作流程相比，MLflow Recipes 提供了几个主要优势：

• 快速开始：预定义模板 用于常见的机器学习任务，例如 回归建模，使数据科学家能够快速开始并专注于构建优秀的模型，消除了传统上需要大量样板代码来整理数据集、工程特征、训练和调整模型以及打包模型以进行生产部署的需求。

• 迭代更快：智能配方执行引擎通过缓存过程中的每一步结果，并在更改时重新运行最小步骤集，从而加速模型开发。

• 轻松部署到生产环境：模块化、与 git 集成的 配方结构 通过确保所有模型代码、数据和配置易于审查和部署，极大地简化了从开发到生产的交接过程。

快速入门

先决条件

MLflow Recipes 作为 MLflow Python 库 的扩展提供。您可以如下安装 MLflow Recipes：

• 本地: 从 PyPI 安装 MLflow: pip install mlflow。注意，MLflow 配方需要 Make，这可能在某些 Windows 系统上未预装。Windows 用户在使用 MLflow 配方之前必须安装 Make。有关在 Windows 上安装 Make 的更多信息，请参见 https://gnuwin32.sourceforge.net/install.html。

• Databricks：通过在 Databricks Notebook 中运行 %pip install mlflow 来安装 MLflow Recipes，或者通过遵循 这里 的 PyPI 库安装说明并在指定 mlflow 包字符串的情况下在 Databricks 集群上安装 MLflow Recipes。

  备注

  Databricks Runtime 版本 11.0 或更高是安装 MLflow Recipes 在 Databricks 上的必要条件。

纽约市出租车费用预测示例

纽约市出租车费用预测示例 使用 |MLflow Recipes 回归模板| 在 纽约市出租车（TLC）行程记录数据集 上开发和评分模型。您可以通过 安装 MLflow Recipes 并运行 Jupyter 示例回归笔记本 在本地运行该示例。您可以通过 使用 Databricks Repos 克隆示例仓库 并在 Databricks 示例回归笔记本 上运行来在 Databricks 上运行该示例。

要为您的用例构建和评分模型，我们建议使用 MLflow Recipes Regression Template。更多信息，请参阅 |Regression Template 参考指南|。

分类问题示例

分类问题示例 使用 MLflow Recipes Classification Template 在 Wine Quality Dataset 上开发和评分模型。您可以通过 安装 MLflow Recipes 并运行 Jupyter 示例分类笔记本 在本地运行示例。您可以通过 使用 Databricks Repos 克隆示例仓库 并在 Databricks 示例分类笔记本 上运行，在 Databricks 上运行示例。

要为您的用例构建和评分模型，我们推荐使用 MLflow Recipes Classification Template。更多信息，请参阅 |Classification Template 参考指南|。

关键概念

• 步骤：一个步骤代表一个单独的机器学习操作，例如数据摄取、拟合估计器、根据测试数据评估模型，或部署模型进行实时评分。每个步骤接受一组定义良好的输入，并根据用户定义的配置和代码生成定义良好的输出。

• 配方: 配方是用于解决机器学习问题或执行MLOps任务（如开发回归模型或对生产数据进行批量模型评分）的有序 步骤 组合。MLflow Recipes 提供了 API 和一个 CLI 用于运行配方并检查其结果。

• 模板：配方模板是一个包含 标准化、模块化布局 的 git 仓库，其中包含了 配方 的所有可自定义代码和配置。配置以 YAML 格式定义，便于通过 recipe.yaml 文件和 配置文件 YAML 文件 进行审查。每个模板还定义了其需求、数据科学笔记本和测试。MLflow 配方包括针对各种模型开发和 MLOps 任务的 预定义模板。

• 配置文件：配置文件包含用户特定或环境特定的 配方 配置，例如数据科学家在开发中调整的特定超参数集，或用于存储生产就绪模型的 MLflow 模型注册表 URI 和凭据。每个配置文件在 配方模板 中表示为一个 YAML 文件（例如 local.yaml 和 databricks.yaml）。

• 步骤卡片：步骤卡片显示运行 步骤 所产生的结果，包括数据集概况、模型性能和可解释性图表、在调优过程中找到的最佳模型参数概览等。步骤卡片及其对应的数据集和模型信息也会记录到 MLflow 跟踪中。

用法

模型开发工作流程

使用 MLflow Recipes 的一般模型开发工作流程如下：

1. 克隆一个与您希望解决的机器学习问题相对应的 配方模板 git 仓库。按照模板的 README 文件获取模板特定的说明。

   • [本地] 将 MLflow Recipes Regression Template 克隆到本地目录中。

   git clone https://github.com/mlflow/recipes-regression-template
   

   • [Databricks] 使用 Databricks Repos 克隆 MLflow Recipes Regression Template git 仓库。

     

2. 编辑 recipe.yaml 和 profiles/*.yaml 中标记为 FIXME::REQUIRED 注释的必填字段。一旦所有必填字段都填写了适当的值，配方就可以运行了。如果是第一次执行此步骤，您可以继续到步骤3。否则，继续编辑 YAML 配置文件以及 steps/*.py 文件，根据需要填写标记为 FIXME::OPTIONAL 的区域，以根据您的 ML 问题定制配方步骤，从而提高模型性能。

   

3. 通过选择一个期望的配置文件来运行配方。配置文件用于快速切换特定于环境的配方设置，例如摄取数据的位置。当配方运行完成后，您可以检查运行结果。MLflow Recipes 创建并显示一个带有最后执行的 步骤 结果的交互式 步骤卡片。每个 配方模板 还包括一个 Databricks Notebook 和一个 Jupyter Notebook，用于运行配方并检查其结果。

   运行 MLflow Recipes Regression Template 的示例 API 和 CLI 工作流程以及检查结果。请注意，配方必须在相应的 git 仓库内运行。

   import os
   from mlflow.recipes import Recipe
   from mlflow.pyfunc import PyFuncModel
   
   os.chdir("~/recipes-regression-template")
   regression_recipe = Recipe(profile="local")
   # Run the full recipe
   regression_recipe.run()
   # Inspect the model training results
   regression_recipe.inspect(step="train")
   # Load the trained model
   regression_model_recipe: PyFuncModel = regression_recipe.get_artifact("model")
   

   git clone https://github.com/mlflow/recipes-regression-template
   cd recipes-regression-template
   # Run the full recipe
   mlflow recipes run --profile local
   # Inspect the model training results
   mlflow recipes inspect --step train --profile local
   # Inspect the resulting model performance evaluations
   mlflow recipes inspect --step evaluate --profile local
   

   

   通过运行 MLflow Recipes Regression Template 的 evaluate 步骤生成的示例步骤卡片。步骤卡片结果表明，训练的模型通过了所有性能验证，并准备好与 MLflow 模型注册表 进行注册。

   

   一个MLflow运行视图页面的示例，显示了从Recipe步骤中记录的工件。

   

   从 MLflow Recipes Regression Template 中包含的 Databricks Notebook 运行的示例配方。

   备注

   数据分析通常在“分位数”模式下查看效果最佳。要启用此模式，在Facet数据分析中，找到``显示图表``，点击下方的选择器，然后选择``分位数``。

4. 迭代步骤2和3：对单个步骤进行更改，并通过运行该步骤并观察其产生的结果来测试它们。使用 Recipe.inspect() 来可视化整个Recipe依赖图和每个步骤产生的工件。使用 Recipe.get_artifact() 在笔记本中进一步检查单个步骤的输出。

   MLflow Recipes 智能地缓存每个 Recipe Step 的结果，确保只有在输入、代码或配置发生变化，或者依赖步骤发生此类变化时，步骤才会执行。一旦你对更改的结果感到满意，请将它们提交到 Recipe Repository 的分支中，以确保可重复性，并与团队共享或审查这些更改。

   

   示例 Recipe.inspect() 输出，显示了配方步骤的依赖关系图以及每个步骤产生的工件。

   备注

   在测试暂存或生产环境中的更改之前，建议您将更改提交到 配方仓库 的分支中，以确保可重复性。

   备注

   默认情况下，MLflow Recipes 会缓存每个 Recipe Step 的结果在本地文件系统的 home 文件夹下的 .mlflow 子目录中。可以使用 MLFLOW_RECIPES_EXECUTION_DIRECTORY 环境变量来指定缓存结果的替代位置。

开发环境

我们建议使用以下环境配置之一来使用 MLflow Recipes 开发模型：

[Databricks]

• 在 Databricks Repos 中编辑 YAML 配置和 Python 文件。为每个你希望修改的文件模块打开单独的浏览器标签。例如，一个用于配方配置文件 recipe.yaml，一个用于配置文件 profile/databricks.yaml，一个用于驱动笔记本 notebooks/databricks.py，以及一个用于当前开发步骤（例如训练） steps/train.py。

• 使用 notebooks/databricks.py 作为驱动程序来运行配方步骤并检查其输出。

• 固定工作区浏览器以方便文件导航。

[本地使用 Jupyter Notebook]

• 使用 notebooks/jupyter.ipynb 作为驱动程序来运行配方步骤并检查其输出。

• 使用您选择的编辑器相应地编辑 recipe.yaml、steps/*.py 和 profiles/*.yaml。

• 要运行整个配方，可以运行 notebooks/jupyter.ipynb 或在命令行中调用 ``mlflow recipes run –profile local``（首先将当前工作目录更改为项目根目录）。

[使用IDE（VSCode）在本地编辑并运行在Databricks上]

• 使用 VSCode 和 Jupyter 插件在本地机器上编辑文件。

• 使用 dbx 将它们同步到 Databricks Repos ，如下所示。

• 在 Databricks 上，使用 notebooks/databricks.py 笔记本作为驱动程序来运行配方步骤并检查其输出。

在本地机器上高效编辑食谱并将其更改同步到 Databricks Repos 的示例工作流程

# Install the Databricks CLI, which is used to remotely access your Databricks Workspace
pip install databricks-cli
# Configure remote access to your Databricks Workspace
databricks configure
# Install dbx, which is used to automatically sync changes to and from Databricks Repos
pip install dbx
# Clone the MLflow Recipes Regression Template
git clone https://github.com/mlflow/recipes-regression-template
# Enter the MLflow Recipes Regression Template directory and configure dbx within it
cd recipes-regression-template
dbx configure
# Use dbx to enable syncing from the repository directory to Databricks Repos
dbx sync repo -d recipes-regression-template
# Iteratively make changes to files in the repository directory and observe that they
# are automatically synced to Databricks Repos

配方模板

MLflow Recipes 目前提供以下预定义模板，可以轻松定制以开发和部署高质量、生产就绪的模型，以满足您的使用案例：

• MLflow Recipes 回归模板: MLflow Recipes 回归模板旨在用于开发和评分回归模型。更多信息，请参阅 |回归模板参考指南|。

• MLflow Recipes 分类模板: MLflow Recipes 分类模板旨在用于开发和评分分类模型。更多信息，请参阅 |分类模板参考指南|。

针对各种机器学习问题和MLOps任务的额外配方正在积极开发中。

详细参考指南

模板结构

配方模板是具有标准化、模块化布局的 git 仓库。以下示例概述了配方仓库的结构。它改编自 |MLflow Recipes 回归模板|。

├── recipe.yaml
├── requirements.txt
├── steps
│   ├── ingest.py
│   ├── split.py
│   ├── transform.py
│   ├── train.py
│   ├── custom_metrics.py
├── profiles
│   ├── local.yaml
│   ├── databricks.yaml
├── tests
│   ├── ingest_test.py
│   ├── ...
│   ├── train_test.py
│   ├── ...

食谱模板布局的主要组成部分，这些部分在所有食谱中都是通用的，包括：

• recipe.yaml: 主配方配置文件，以声明方式定义每个配方步骤的属性和行为，例如用于训练模型的输入数据集或用于将模型提升到生产的性能标准。有关参考，请参阅 MLflow Recipes Regression Template 中的 recipe.yaml 配置文件。

• requirements.txt: 一个 pip 需求文件，指定了运行配方所需的必须安装的包。

• steps: 一个包含Python代码模块的目录，这些模块被用于配方步骤。例如，MLflow Recipes Regression Template 在 steps/train.py 中定义了训练模型时使用的估计器类型和参数，并在 steps/custom_metrics.py 中定义了自定义指标计算。

• profiles: 一个包含 配置文件 自定义的目录，用于 recipe.yaml 中定义的配置。例如，MLflow Recipes Regression Template 定义了一个 |本地配置文件|，用于 |自定义本地模型开发使用的数据集| 和 |指定本地 MLflow Tracking 存储以记录模型内容|。MLflow Recipes Regression Template 还定义了一个 |Databricks 配置文件|，用于在 Databricks 上的开发。

• tests: 包含用于配方步骤的Python测试代码的目录。例如，MLflow Recipes Regression Template 为 steps/transform.py 和 steps/train.py 模块中定义的转换器和估计器实现了测试。

下面是一个从 MLflow Recipes Regression Template 改编的 recipe.yaml 配置文件示例。recipe.yaml 是包含所有配方步骤聚合配置的配方主配置文件；支持使用 Jinja2 模板语法的基于 Profile 的替换和覆盖。

recipe: "regression/v1"
target_col: "fare_amount"
primary_metrics: "root_mean_squared_error"
steps:
  ingest: {{INGEST_CONFIG}}
  split:
    split_ratios: {{SPLIT_RATIOS|default([0.75, 0.125, 0.125])}}
  transform:
    using: custom
    transformer_method: transformer_fn
  train:
    using: custom
    estimator_method: estimator_fn
  evaluate:
    validation_criteria:
      - metric: root_mean_squared_error
        threshold: 10
      - metric: weighted_mean_squared_error
        threshold: 20
  register:
    allow_non_validated_model: false
custom_metrics:
  - name: weighted_mean_squared_error
    function: weighted_mean_squared_error
    greater_is_better: False

使用配置文件

配置文件是针对配方主文件 recipe.yaml 中定义的配置进行自定义的集合。配置文件在配方仓库的 profiles 目录 中定义为 YAML 文件。在运行配方或检查其结果时，所需的配置文件作为 API 或 CLI 参数指定。

使用不同配置文件自定义运行配方的示例API和CLI工作流程

import os
from mlflow.recipes import Recipe

os.chdir("~/recipes-regression-template")
# Run the regression recipe to train and evaluate the performance of an ElasticNet regressor
regression_recipe_local_elasticnet = Recipe(profile="local-elasticnet")
regression_recipe_local_elasticnet.run()
# Run the recipe again to train and evaluate the performance of an SGD regressor
regression_recipe_local_sgd = Recipe(profile="local-sgd")
regression_recipe_local_sgd.run()
# After finding the best model type and updating the 'shared-workspace' profile accordingly,
# run the recipe again to retrain the best model in a workspace where teammates can view it
regression_recipe_shared = Recipe(profile="shared-workspace")
regression_recipe_shared.run()

git clone https://github.com/mlflow/recipes-regression-template
cd recipes-regression-template
# Run the regression recipe to train and evaluate the performance of an ElasticNet regressor
mlflow recipes run --profile local-elasticnet
# Run the recipe again to train and evaluate the performance of an SGD regressor
mlflow recipes run --profile local-sgd
# After finding the best model type and updating the 'shared-workspace' profile accordingly,
# run the recipe again to retrain the best model in a workspace where teammates can view it
mlflow recipes run --profile shared-workspace

支持以下配置文件自定义：

• 覆盖

  • 如果 recipe.yaml 配置文件定义了一个带有默认值的 Jinja2 模板属性，一个配置文件可以通过使用 YAML 字典语法将该属性映射到一个不同的值来覆盖该默认值。请注意，覆盖的值可能具有任意嵌套的类型（例如列表、字典、字典列表等）。

    示例 recipe.yaml 配置文件，定义了一个可覆盖的 RMSE_THRESHOLD 属性，用于验证模型性能，默认值为 10

    steps:
      evaluate:
        validation_criteria:
          - metric: root_mean_squared_error
            # The maximum RMSE value on the test dataset that a model can have
            # to be eligible for production deployment
            threshold: {{RMSE_THRESHOLD|default(10)}}
    

    示例 prod.yaml 配置文件，该文件使用自定义值覆盖 RMSE_THRESHOLD，以更积极地验证生产模型的质量

    RMSE_THRESHOLD: 5.2
    

• 替换

  • 如果 recipe.yaml 配置文件定义了一个没有默认值的 Jinja2 模板属性，则必须使用 YAML 字典语法将该属性映射到一个特定值。请注意，替代值可能具有任意嵌套类型（例如列表、字典、字典列表等）。

    示例 recipe.yaml 配置文件，定义了一个 DATASET_INFO 变量，其值必须由选定的配方配置文件指定。

    # Specifies the dataset to use for model training
    ingest: {{INGEST_CONFIG}}
    

    示例 dev.yaml 配置文件，为 DATASET_INFO 提供了一个对应于开发用小型数据集的值

    INGEST_CONFIG:
        location: ./data/taxi-small.parquet
        format: parquet
    

• 添加

  • 如果 recipe.yaml 配置文件没有定义某个特定属性，一个配置文件可能会定义它。这个功能对于提供可选配置的值很有帮助，如果未指定，配方将忽略这些配置。

    示例 local.yaml 配置文件，指定了一个基于 sqlite 的 MLflow 跟踪 存储，用于笔记本电脑上的本地测试

    experiment:
      tracking_uri: "sqlite:///metadata/mlflow/mlruns.db"
      name: "sklearn_regression_experiment"
      artifact_location: "./metadata/mlflow/mlartifacts"
    

警告

如果 recipe.yaml 配置文件定义了一个不能被覆盖或替换的属性（即因为其值没有使用 Jinja2 模板语法指定），则配置文件中不得定义该属性。在配置文件中定义此类属性会产生错误。