MLflow系列3：MLflow项目

英文链接：https://mlflow.org/docs/latest/projects.html
本文链接：https://www.cnblogs.com/CheeseZH/p/11945432.html

MLflow项目是一种用于以可复用可复现的方式打包数据科学代码的格式。项目的组件包含了API和命令行工具，可以用来在一个工作流中链接多个项目。

简而言之，MLflow项目就是一套框架，用于组织和发布你的代码，使得其他数据科学家或者自动化工具能够运行。每个项目就是一个包含多个文件的目录或者一个Git仓库。MLflow可以根据目录中的文件（比如conda.yaml文件可以看作是Conda环境）来运行项目，你也可以在MLproject文件中指定更详细的信息。

Name

人类可读的项目名称。

Entry Points

项目中可以执行的命令，以及命令的参数信息。大多数项目至少有一个用来调用的入口点，一些项目可能包含多个入口点，比如你有一个Git仓库里边有多种特征提取算法。你也可以调用任意的.py或者.sh文件作为入口点。如果你在MLproject文件中列举了入口点信息，你也需要提供相应的参数信息，包括数据类型和默认值。

Environment

用于执行入口点的软件环境。包括项目代码依赖的所有库。详情参考Project Environments，包括Conda environments和Docker containers。

你可以通过mlflow run命令或者mlflow.projects.run()Python API来运行来自Git URI（需要使用绝对目录）或者本地目录的项目。

默认情况下，一个Git仓库或者一个本地目录都可以被当作一个MLflow项目。项目目录的章节会介绍了MLflow如何把目录解析成一个项目。

为了给一个项目提供额外的信息，你可以在仓库或者目录中提供一个MLproject文件。

MLflow项目允许你指定项目需要的软件环境。

项目环境

目前MLflow支持以下几种项目环境：Conda环境，Docker容器环境，系统环境。

Conda环境

Conda环境支持Python包和本地库（例如CuDNN或Intel MKL）。当一个MLflow项目指定了Conda环境，这个环境会在项目运行前激活（activated）。

默认的，MLflow使用系统路径查找并运行conda。你可以通过环境变量MLFLOW_CONDA_HOME来指定conda环境，这样MLflow就会尝试运行$MLFLOW_CONDA_HOME/bin/conda。

你可以通过conda.yaml文件为项目指定conda环境，将这个文件放在项目根目录或者MLproject的conda_env参数。

Docker容器环境

Docker容器可以让你调用非Python依赖，比如Java库。详情参考Dockerized Model Training with MLflow。

如果指定Docker容器环境，必须向项目中添加MLproject文件。

系统环境

你也可以在当前系统环境下直接运行MLflow项目。前提是你当前系统中安装了项目的所有依赖。使用系统环境的话，不需要在MLproject文件中指定。更多信息查看运行项目的Environment参数。

项目目录

当运行一个没有MLproject文件的MLflow项目目录或者仓库，MLflow使用下面的约定决定项目的属性：

• 项目名称就是目录名称
• 如果有conda.yaml文件，就是用指定的conda环境，否则MLflow会使用一个仅包含Python的conda环境。
• 任何.py和.sh文件都可以作为入口点。
• 默认情况下，入口点没有任何参数。参数可以在运行时通过命令行mlflow run或者Python APImlflow.projects.run()指定参数。语法是--key value。

MLproject文件

MLproject文件是一个遵循YAML语法的文本文件，位于项目根目录，下边是个例子：

name: My Project

conda_env: my_env.yaml
# Can have a docker_env instead of a conda_env, e.g.
# docker_env:
#    image:  mlflow-docker-example

entry_points:
  main:
    parameters:
      data_file: path
      regularization: {type: float, default: 0.1}
    command: "python train.py -r {regularization} {data_file}"
  validate:
    parameters:
      data_file: path
    command: "python validate.py {data_file}"

这个文件可以指定名字，conda或者docker环境，入口点的详细信息。每个入口点都会定义一个运行命令和参数。

指定环境

Conda environment
Include a top-level conda_env entry in the MLproject file. The value of this entry must be a relative path to a Conda environment YAML file within the MLflow project’s directory. In the following example:

MLproject文件不能同时指定conda环境和Docker环境。

Conda环境

在MLproject文件的顶层通过conda_env来指定。conda_env的值必须是MLflow项目目录中的指定conda环境的YAML文件的相对目录。例如：

conda_env: files/config/conda_environment.yaml

conda_env会被解析成<MLFLOW_PROJECT_DIRECTORY>/files/config/conda_environment.yaml，其中<MLFLOW_PROJECT_DIRECTORY>表示项目的根目录。

Docker容器环境

Include a top-level docker_env entry in the MLproject file. The value of this entry must be the name of a Docker image that is accessible on the system executing the project; this image name may include a registry path and tags. Here are a couple of examples.

Example 1: Image without a registry path

在MLproject文件的顶层通过docker_env来指定。docker_env的值必须是该项目可以访问到的Docker镜像，以下是几个例子。

例1: 无注册路径的镜像

docker_env:
  image: mlflow-docker-example-environment

默认Tag是latest，首先从当前系统中查找镜像mlflow-docker-example-environment，如果本地没有找到，就会尝试到DockerHub上拉取。

例2: 有注册路径的镜像

docker_env:
  image: 012345678910.dkr.ecr.us-west-2.amazonaws.com/mlflow-docker-example-environment:7.0

命令语法

参考Python format string syntax

指定参数

# 简单指定
parameter_name: data_type

# Short syntax
parameter_name: {type: data_type, default: value}  

# Long syntax
parameter_name:     
  type: data_type
  default: value

参数类型

• string
• float
• path
• uri

MLflow提供了两种运行项目的方式：mlflow run命令行工具，mlflow.projects.run() Python API。这两种方式都包括以下参数：

• Project URI
• Project Version
• Entry Point
• Parameters
• Deployment Mode
• Environment

例如mlflow run git@github.com:mlflow/mlflow-example.git -P alpha=0.5

在Databricks上运行MLflow项目

在Kubernetes上运行MLflow项目(experimental)

• 项目中添加MLproject文件
• 将主程序指定为main入口点
• 将参数设置为默认参数
• 执行mlflow run .

结合使用mlflow.tracking和mlflow.projects.run()能够构建一个多步骤工作流，每个步骤可以是单独的项目或者一个项目中的入口点。每次调用mlflow.projects.run()都会返回一个run对象，你可以使用mlflow.tracking来知道这个run什么时候结束以及它的输出产品。这些产品可以通过路径或者URI参数传递到下一个步骤。你可以通过一个Python程序协调所有工作流，查看每个步骤的结果。下边是个使用多步骤工作流的场景：

模块化你的数据科学代码

不同的用户可以发布数据特征抽取，训练，验证等可复用的步骤，这样其他用户或者团队就可以在他们的工作流中使用。因为MLflow支持Git版本，另一个团队可以锁定他们的工作令使用指定版本的项目，或者根据他们自己的计划升级。

超参数调优

使用mlflow.projects.run()你可以并行启动多个runs，无论是在本地机器还是在Databricks这种云平台。你的主程序就可以实时查看每个run的指标，以此为依据取消runs或者启动新的runs或者选择最好的run。

交叉验证

Sometimes you want to run the same training code on different random splits of training and validation data. With MLflow Projects, you can package the project in a way that allows this, for example, by taking a random seed for the train/validation split as a parameter, or by calling another project first that can split the input data.
For an example of how to construct such a multistep workflow, see the MLflow Multistep Workflow Example project.

有时候你希望同样的训练代码在不同的训练集和验证集上运行。使用MLflow项目，你可以做到这点，比如随机切分训练集／验证集，或者通过调用另一个项目来切分输入数据。

详情参考MLflow Multistep Workflow Example。