MLflow项目是一种主要基于约定、以可重用和可再现的方式打包数据科学代码的格式。此外，Projects组件还包括一个API和用于运行项目的命令行工具，这使得将项目链接到工作流成为可能。

概述

本质上，MLflow项目只是组织和描述代码的一种惯例，以便让其他数据科学家(或自动化工具)运行代码。每个项目只是一个文件目录，或者一个Git存储库，其中包含您的代码。MLflow可以基于在此目录中放置文件的约定运行一些项目(例如，conda。yaml文件被视为一个Conda环境)，但是您可以通过添加一个MLproject文件(这是一个yaml格式的文本文件)来更详细地描述您的项目。每个项目都可以指定几个属性:
Name
人类可读的项目名称。
Entry Points
可以在项目中运行的命令，以及有关其参数的信息。大多数项目至少包含一个您希望其他用户调用的入口点。有些项目还可以包含多个入口点:例如，您可能有一个包含多个特性化算法的Git存储库。您还可以调用项目中的任何.py或.sh文件作为入口点。但是，如果在MLproject文件中列出入口点，还可以为它们指定参数，包括数据类型和默认值。
Environment
用于执行项目入口点的软件环境。这包括项目代码所需的所有库依赖项。有关MLflow项目支持的软件环境的更多信息，请参见项目环境，包括Conda环境和Docker容器。
您可以使用mlflow run命令行工具或mlflow.projects.run() Python API从Git URI或本地目录运行任何项目。这些api还允许提交项目，以便在Databricks和Kubernetes上远程执行。

默认情况下，MLflow为Git项目使用一个新的临时工作目录。这意味着您通常应该使用绝对路径(而不是相对路径)将任何文件参数传递给MLflow项目。如果项目声明了它的参数，MLflow会自动为path类型的参数设置绝对路径。

指定的项目

默认情况下，任何Git存储库或本地目录都可以被视为一个MLflow项目;您可以调用目录中包含的任何bash或Python脚本作为项目入口点。项目目录部分描述了MLflow如何将目录解释为项目。
要提供对项目属性的额外控制，还可以在项目的存储库或目录中包含MLproject文件。
最后，MLflow项目允许您指定用于执行项目入口点的软件环境。

项目环境

MLflow目前支持的项目环境有:Conda环境、Docker容器环境和系统环境。
Conda environment
Conda环境支持Python包和本地库(例如，CuDNN或Intel MKL)。当MLflow项目指定Conda环境时，将在项目代码运行之前激活该环境。
默认情况下，MLflow使用系统路径来查找和运行conda二进制文件。您可以通过设置MLFLOW_CONDA_HOME环境变量来使用不同的Conda安装;在这种情况下，MLflow尝试在$MLFLOW_CONDA_HOME/bin/conda上运行二进制文件。
通过包含Conda，可以为您的MLflow项目指定Conda环境。或者在您的MLproject文件中包含conda_env条目。有关详细信息，请参见项目目录和指定环境部分。
Docker container environment
Docker容器允许你捕获非python依赖，如Java库。
当你运行一个指定Docker图像的MLflow项目时，MLflow会添加一个新的Docker层，将项目的内容复制到/ MLflow /projects/code目录中。此步骤生成一个新映像。然后MLflow运行新图像并在生成的容器中调用项目入口点。
MLFLOW_TRACKING_URI，在项目执行过程中传播到Docker容器中。此外，项目创建的运行和实验被保存到跟踪URI指定的跟踪服务器中。当针对本地跟踪URI运行时，MLflow将主机系统的跟踪目录(例如，本地mlruns目录)挂载到容器中，以便在项目执行期间记录的指标、参数和工件之后可以访问。
请参阅Dockerized Model Training with MLflow了解一个带有Docker环境的MLflow项目示例。
要指定Docker容器环境，必须在项目中添加MLproject文件。有关在MLproject文件中指定Docker容器环境的信息，请参见指定环境。
System environment
还可以在当前系统环境中直接运行MLflow项目。在项目执行之前，必须在系统上安装项目的所有依赖项。系统环境在运行时提供。它不是MLflow项目目录内容或MLproject文件的一部分。有关在运行项目时使用系统环境的信息，请参见“运行项目”部分中的环境参数说明。

项目目录

当运行不包含MLproject文件的MLflow项目目录或存储库时，MLflow使用以下约定来确定项目的属性:

  • 项目的名称是目录的名称。
  • Conda环境以Conda格式指定。yaml,如果存在。如果没有conda。当运行项目时，MLflow使用一个只包含Python(特别是Conda可用的最新Python)的Conda环境。
  • 项目中的任何.py和.sh文件都可以作为入口点。MLflow使用Python执行扩展名为.py的入口点，使用bash执行扩展名为.sh的入口点。有关在运行时指定项目入口点的详细信息，请参见运行项目。
  • 默认情况下，当不包含MLproject文件时，入口点没有任何参数。参数可以在运行时通过mlflow run CLI或mlflow.projects.run() Python API提供。使用—key值语法将运行时参数传递到命令行上的入口点。有关运行项目和使用运行时参数的详细信息，请参见运行项目。

    MLproject文件

    通过将MLproject文件(YAML语法中的文本文件)添加到项目的根目录，您可以获得对MLflow项目的更多控制。下面是一个MLproject文件的示例: ```bash 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}”

  1. 该文件可以指定一个名称和一个Conda或Docker环境，以及关于每个入口点的更详细的信息。具体来说，每个入口点定义要运行的命令和传递给该命令的参数(包括数据类型)。
  2. <a name="rubBp"></a>
  3. #### 指定一个环境
  4. 本节介绍如何在MLproject文件中指定Conda和Docker容器环境。MLproject文件不能同时指定Conda环境和Docker环境。<br />Conda environment<br />在MLproject文件中包含一个顶级conda_env条目。这个条目的值必须是Conda环境YAML文件在MLflow项目目录中的相对路径。在以下示例中:
  5. ```bash
  6. conda_env: files/config/conda_environment.yaml

conda_env指向位于/files/config/conda_environment.yaml的环境文件。其中是MLflow项目根目录的路径。
Docker container environment
在MLproject文件中包含一个顶级docker_env条目。该条目的值必须是在执行该项目的系统上可以访问的Docker镜像的名称;此图像名称可能包括注册表路径和标记。这里有几个例子。
例1:没有注册表路径的镜像

  1. docker_env:
  2.   image: mlflow-docker-example-environment

在这个例子中，docker_env引用名为mlflow-docker-example-environment和默认标签latest的Docker映像。由于没有指定注册表路径，Docker在运行MLflow项目的系统上搜索此映像。如果没有找到该映像，Docker将尝试从DockerHub中提取它。
例2:挂载卷并指定环境变量
你也可以指定要挂载在docker镜像中的本地卷(就像你通常使用docker的-v选项那样)，以及附加的环境变量(就像docker的-e选项那样)。环境变量可以从主机系统的环境变量中复制，也可以指定为Docker环境的新变量。环境字段应该是一个列表。这个列表中的元素可以是两个字符串(用于定义新变量)的列表，也可以是单个字符串(用于从主机系统复制变量)的列表。例如:

  1. docker_env:
  2.   image: mlflow-docker-example-environment
  3.   volumes: ["/local/path:/container/mount/path"]
  4.   environment: [["NEW_ENV_VAR", "new_var_value"], "VAR_TO_COPY_FROM_HOST_ENVIRONMENT"]

在这个例子中，我们的docker容器将挂载一个额外的本地卷，以及两个额外的环境变量:一个是新定义的，另一个是从主机系统中复制的。
示例3:远程注册表中的映像

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

在这个例子中，docker_env在Docker注册表中引用名为mlflow-docker-example-environment和标记7.0的Docker映像，路径为012345678910.dkr.ecr.us- west2.amazonaws.com，它对应于一个Amazon ECR注册表。当MLflow项目运行时，Docker会尝试从指定的注册表中提取映像。执行MLflow项目的系统必须具有从指定注册中心提取此映像的凭据。

命令语法

当在MLproject文件中指定入口点时，该命令可以是Python格式字符串语法中的任何字符串。在入口点的parameters字段中声明的所有参数都被传递到这个字符串中进行替换。如果您使用没有在parameters字段中列出的附加参数调用项目，那么MLflow将使用—key value语法传递它们，因此您可以使用MLproject文件来声明参数子集的类型和默认值。
在替换命令中的参数之前，MLflow使用Python shlex对它们进行转义。函数，因此您不需要担心在命令字段中添加引号。

指定参数

MLflow允许为每个参数指定数据类型和默认值。你可以这样指定数据类型:

  1. parameter_name: data_type

在你的YAML文件中，或者使用以下语法之一添加一个默认值(在YAML中是等价的):

  1. parameter_name: {type: data_type, default: value}  # Short syntax
  3. parameter_name:     # Long syntax
  4.   type: data_type
  5.   default: value

MLflow支持四种参数类型，其中一些是特殊处理的(例如，将数据下载到本地文件)。任何未声明的参数都被视为字符串。参数类型有:
string
字符串
float
一个实数。MLflow验证参数是否为数字。
path
本地文件系统的路径。MLflow将任何相对路径参数转换为绝对路径。MLflow还将任何作为分布式存储uri传递的路径(s3://， dbfs://， gs://等)下载到本地文件。对于只能读取本地文件的程序，请使用此类型。
uri
用于本地或分布式存储系统中的数据的URI。MLflow将相对路径转换为绝对路径，就像路径类型一样。对于那些知道如何从分布式存储读取数据的程序(例如使用Spark的程序)，可以使用这种类型。

运行项目

MLflow提供了两种运行项目的方式:MLflow run命令行工具，或MLflow .projects.run() Python API。这两个工具都有以下参数:
Project URI
本地文件系统上的目录或Git存储库路径，指定为URI形式的https://(使用HTTPS)或user@host:path(通过SSH使用Git)。要对位于项目的子目录中的MLproject文件运行，请在URI参数的末尾添加“#”，然后是从项目的根目录到包含所需项目的子目录的相对路径。
Project Version
对于基于Git的项目，在Git存储库中提交哈希或分支名称。
Entry Point
入口点的名称，默认为main。您可以使用MLproject文件中命名的任何入口点，或者项目中的任何.py或.sh文件，这些文件作为项目根目录的路径给出(例如，src/test.py)。
Parameters
键-值参数。如果需要，将验证和转换声明类型的任何参数。
Deployment Mode

  • 命令行和API都允许您在Databricks环境中远程启动项目。包括设置虚拟机类型等集群参数。当然，您还可以使用本地版本的mlflow run命令在您选择的任何其他计算基础设施上运行项目(例如，向标准作业队列系统提交执行mlflow运行的脚本)。
  • 还可以使用mlflow run CLI在Kubernetes集群上远程启动项目(请参阅在Kubernetes上运行mlflow项目(实验性))。

Environment
默认情况下，MLflow项目在项目目录或MLproject文件指定的环境中运行(请参阅指定项目环境)。您可以忽略项目的指定环境，并通过提供—no-conda标志在当前系统环境中运行项目。
例如，本教程创建并发布一个MLflow项目来训练线性模型。该项目也发表在GitHub的https://github.com/mlflow/mlflow-example上。要运行这个项目:

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

还有一些其他选项可以禁用Conda环境的创建，如果您想快速地在现有的shell环境中测试项目，这些选项非常有用。

在Databricks上运行MLflow项目

您可以在数据块上远程运行MLflow项目。要使用此特性，您必须拥有enterprise Databricks帐户(不支持Community Edition)，并且必须设置了Databricks CLI。在Databricks文档(Azure Databricks, AWS上的Databricks)中找到详细的说明。

在Kubernetes上运行MLflow项目(实验性)

你可以在Kubernetes上使用Docker环境运行MLflow项目。以下部分提供了该特性的概述，包括一个简单的项目执行指南和示例。
要查看这个特性的实际应用，您还可以参考Docker示例，其中包括所需的Kubernetes后端配置(kubernetes_backend.json)和Kubernetes作业规范(kubernetes_job_template.yaml)文件。

它是如何运作的

当你在Kubernetes上运行一个MLflow项目时，MLflow会构造一个新的包含项目内容的Docker映像;这个映像继承自该项目的Docker环境。然后，MLflow将新的项目图像推送到指定的Docker注册表，并在指定的Kubernetes集群上启动Kubernetes作业。这个Kubernetes作业下载项目映像并启动一个相应的Docker容器。最后，容器调用项目的入口点、日志参数、标记、度量和工件到MLflow跟踪服务器。

运行手册

您可以通过以下步骤在Kubernetes上运行您的MLflow项目:

  1. 向您的MLflow项目添加Docker环境(如果不存在的话)。有关参考，请参见指定环境。
  2. 创建一个后端配置JSON文件，包含以下条目:
    • kube-context是MLflow将在其中运行作业的Kubernetes上下文。如果没有提供，MLflow将使用当前上下文。如果没有上下文可用，MLflow将假定它运行在Kubernetes集群中，并使用Kubernetes服务帐户运行当前pod (‘ in-cluster ‘配置)。
    • repository- URI docker存储库的URI, docker的镜像将在这里上传(推送)。Kubernetes集群必须能够访问这个存储库才能运行MLflow项目。
    • kube-job-template-path Kubernetes作业的YAML配置文件路径——Kubernetes作业规范。MLflow读取作业规范并替换某些字段，以方便作业执行和监视;MLflow不修改原始模板文件。有关编写与MLflow一起使用的Kubernetes作业规范模板的更多信息，请参见作业模板一节。

使用实例Kubernetes后端配置

  1. {
  2.   "kube-context": "docker-for-desktop",
  3.   "repository-uri": "username/mlflow-kubernetes-example",
  4.   "kube-job-template-path": "/Users/username/path/to/kubernetes_job_template.yaml"
  5. }
  1. 如有必要，获取访问项目Docker和Kubernetes资源的凭证，包括:
    • 在MLproject文件中指定的Docker环境映像。
    • 后端配置文件中的repository-uri引用Docker存储库。
    • 后端配置文件中kube-context引用的Kubernetes上下文。

MLflow希望在运行项目之前可以通过docker和kubectl命令行访问这些资源。

  1. 使用MLflow项目CLI或Python API运行项目，指定项目URI和后端配置文件的路径。例如:
    1. mlflow run <project_uri> --backend kubernetes --backend-config examples/docker/kubernetes_config.json
    其中是一个Git存储库URI或文件夹。

    工作模板

    MLflow通过创建Kubernetes作业资源在Kubernetes上执行项目。MLflow通过读取用户指定的作业规范来为MLflow项目创建一个Kubernetes作业。当MLflow读取作业规范时，它会格式化以下字段:
  • metadata.name替换为包含MLflow项目名称和项目执行时间的字符串
  • spec.template.spec.container[0].name用MLflow项目的名称替换
  • spec.template.spec.container[0].image替换为项目执行过程中创建的Docker image的URI。这个URI包含Docker映像的摘要哈希。
  • spec.template.spec.container[0].command替换执行MLflow项目时指定的项目入口点命令。

下面的示例显示了一个简单的Kubernetes作业规范，该规范与MLflow项目执行兼容。替换后的字段使用括号内的文本表示。
Kubernetes的工作规范

  1. apiVersion: batch/v1
  2. kind: Job
  3. metadata:
  4.   name: "{replaced with MLflow Project name}"
  5.   namespace: mlflow
  6. spec:
  7.   ttlSecondsAfterFinished: 100
  8.   backoffLimit: 0
  9.   template:
  10.     spec:
  11.       containers:
  12.       - name: "{replaced with MLflow Project name}"
  13.         image: "{replaced with URI of Docker image created during Project execution}"
  14.         command: ["{replaced with MLflow Project entry point command}"]
  15.         env: ["{appended with MLFLOW_TRACKING_URI, MLFLOW_RUN_ID and MLFLOW_EXPERIMENT_ID}"]
  16.       resources:
  17.         limits:
  18.           memory: 512Mi
  19.         requests:
  20.           memory: 256Mi
  21.       restartPolicy: Never

container.name, container.image和 container.command字段仅在作业规范中定义的第一个容器中被替换。此外，MLFLOW_TRACKING_URI、MLFLOW_RUN_ID和MLFLOW_EXPERIMENT_ID被追加到container.env中。使用KUBE_MLFLOW_TRACKING_URI将不同的跟踪URI从标准的MLFLOW_TRACKING_URI传递给作业容器。所有后续的容器定义都不需要修改即可应用。

快速迭代

如果您想快速开发一个项目，我们建议创建一个MLproject文件，将您的主程序指定为主要入口点，并使用mlflow run ..为了避免重复写入参数，您可以在您的MLproject文件中添加默认参数。

建立多步工作流

mlflow.projects.run() API与mlflow.tracking相结合。使得用单独的项目(或同一项目中的入口点)作为单个步骤构建多步骤工作流成为可能。每次调用mlflow.projects.run()都会返回一个可以用于mlflow.tracking的run对象以确定运行何时结束并获取其输出工件。然后，可以将这些构件传递到采用路径或uri参数的另一个步骤。您可以在单个Python程序中协调所有工作流，该程序查看每个步骤的结果，并使用自定义代码决定下一步提交什么。一些多步骤工作流的示例使用案例包括:
Modularizing Your Data Science Code
不同的用户可以发布数据特性化、培训、验证等的可重用步骤，其他用户或团队可以在他们的工作流中运行这些步骤。由于MLflow支持Git版本控制，其他团队可以将他们的工作流锁定在项目的特定版本上，或者根据自己的日程升级到新的版本。
Hyperparameter Tuning
使用mlflow.projects.run()，您可以在本地机器上或在像Databricks这样的云平台上并行启动多个运行。然后，驱动程序可以实时检查每次运行的指标，以取消运行，启动新的指标，或选择在目标指标上运行的最佳性能。
Cross-validation
有时您希望在训练和验证数据的不同随机分割上运行相同的训练代码。使用MLflow项目，您可以以一种允许这样做的方式打包项目，例如，将火车/验证分割的随机种子作为参数，或者首先调用另一个可以分割输入数据的项目。
有关如何构造这样一个多步骤工作流的示例，请参见MLflow多步骤工作流示例项目。