mlflow.sklearn

该 mlflow.sklearn 模块提供用于记录和加载 scikit-learn 模型的 API。此模块以以下方式导出 scikit-learn 模型：

Python (native) pickle format: 这是可以重新加载回 scikit-learn 的主要 flavor。
mlflow.pyfunc: 为通用的基于 pyfunc 的部署工具和批量推理使用而生成。注意：只有为定义了 predict() 的 scikit-learn 模型才会添加 mlflow.pyfunc flavor，因为 predict() 对于 pyfunc 模型推理是必需的。

mlflow.sklearn.autolog(log_input_examples=False, log_model_signatures=True, log_models=True, log_datasets=True, disable=False, exclusive=False, disable_for_unsupported_versions=False, silent=False, max_tuning_runs=5, log_post_training_metrics=True, serialization_format='cloudpickle', registered_model_name=None, pos_label=None, extra_tags=None)[source]

注意

已知 Autologging 与以下软件包版本兼容： 1.3.1 <= scikit-learn <= 1.7.1. 在此范围之外的包版本中使用 Autologging 可能无法成功。

启用（或禁用）并为 scikit-learn 估计器配置自动记录。

When is autologging performed?

当您调用时，将执行自动记录：

estimator.fit()
estimator.fit_predict()
estimator.fit_transform()

Logged information

Parameters

由 estimator.get_params(deep=True) 获取的参数。注意 get_params 是使用 deep=True 调用的。这意味着当你拟合一个将一系列估计器串联的元估计器时，这些子估计器的参数也会被记录。

Training metrics

通过 estimator.score 获得的训练得分。注意训练得分是使用传递给 fit() 的参数计算的。
分类器的常用指标：
- precision score
- recall score
- f1 score
- accuracy score
如果分类器具有方法 predict_proba，我们会额外记录：
- log loss
- roc auc score
回归器的常见指标：
- mean squared error
- 均方根误差
- mean absolute error
- r2 score

Post training metrics

当用户在模型训练后调用指标 API 时，MLflow 会尝试捕获这些指标 API 的结果，并将其作为 MLflow 指标记录到与模型关联的 Run 中。以下类型的 scikit-learn 指标 API 受支持：

model.score
定义在 sklearn.metrics 模块中的评估指标 API

对于训练后指标的自动记录，指标键格式为：“{metric_name}[-{call_index}]_{dataset_name}”

如果度量函数来自 sklearn.metrics，则 MLflow “metric_name” 为该度量函数的名称。如果度量函数是 model.score，则 “metric_name” 为 “{model_class_name}_score”。
如果对同一个 scikit-learn metric API 进行多次调用，则每次后续调用会在指标键中添加一个“call_index”（从2开始）。
MLflow 使用预测输入数据集变量名作为度量键中的 “dataset_name”。“预测输入数据集变量”是指在关联的 model.predict 或 model.score 调用中作为第一个参数使用的变量。注意：MLflow 在最外层调用帧中捕获“预测输入数据集”实例，并在最外层调用帧中获取变量名。如果“预测输入数据集”实例是一个没有定义变量名的中间表达式，则数据集名称被设置为 “unknown_dataset”。如果多个“预测输入数据集”实例具有相同的变量名，则后续实例将在被检查的数据集名称后附加一个索引（从 2 开始）。

Limitations

MLflow 只能将由模型预测 API 返回的原始预测结果对象（包括 predict / predict_proba / predict_log_proba / transform，但不包括 fit_predict / fit_transform）映射到 MLflow 运行。对于从给定预测结果派生的其他对象（例如通过复制或选择预测结果的子集），MLflow 无法找到运行信息。在派生对象上调用的 scikit-learn 指标 API 不会将指标记录到 MLflow。
必须在从 sklearn.metrics 导入 scikit-learn 指标 API 之前启用 Autologging。在启用 Autologging 之前导入的指标 API 不会将指标记录到 MLflow 运行中。
如果用户定义的评分器不是基于 sklearn.metrics 中的度量 API，则该评分器的训练后度量自动记录无效。

Tags

一个估计器类名（例如 “LinearRegression”）。
一个完全限定的估计器类名 (例如 “sklearn.linear_model._base.LinearRegression”).

Artifacts

一个具有 mlflow.sklearn flavor 并包含已拟合估计器的 MLflow 模型（由 mlflow.sklearn.log_model() 记录）。当 scikit-learn 估计器定义了 predict() 时，该模型还包含 mlflow.pyfunc flavor。
对于训练后指标的 API 调用，会记录一个“metric_info.json”工件。它是一个 JSON 对象，其键是 MLflow 训练后指标的名称（有关键的格式，请参见“训练后指标”部分），其值是生成这些指标的相应指标调用命令，例如 accuracy_score(y_true=test_iris_y, y_pred=pred_iris_y, normalize=False)。

How does autologging work for meta estimators?

当一个元估计器（例如 Pipeline、GridSearchCV）调用 fit() 时，它会在内部对其子估计器调用 fit()。Autologging 不会对这些组成的 fit() 调用执行日志记录。

Parameter search: 除了记录上述讨论的信息之外，参数搜索元估计器（GridSearchCV 和 RandomizedSearchCV）的自动记录会为每组探索的参数记录带有指标的子运行，以及最佳模型（如果可用）的工件和参数。

Supported estimators

通过 sklearn.utils.all_estimators 获取的所有估计器（包括元估计器）。
Pipeline
参数搜索估计器 (GridSearchCV 和 RandomizedSearchCV)

示例

See more examples

from pprint import pprint
import numpy as np
from sklearn.linear_model import LinearRegression
import mlflow
from mlflow import MlflowClient


def fetch_logged_data(run_id):
    client = MlflowClient()
    data = client.get_run(run_id).data
    tags = {k: v for k, v in data.tags.items() if not k.startswith("mlflow.")}
    artifacts = [f.path for f in client.list_artifacts(run_id, "model")]
    return data.params, data.metrics, tags, artifacts


# enable autologging
mlflow.sklearn.autolog()

# prepare training data
X = np.array([[1, 1], [1, 2], [2, 2], [2, 3]])
y = np.dot(X, np.array([1, 2])) + 3

# train a model
model = LinearRegression()
with mlflow.start_run() as run:
    model.fit(X, y)

# fetch logged data
params, metrics, tags, artifacts = fetch_logged_data(run.info.run_id)

pprint(params)
# {'copy_X': 'True',
#  'fit_intercept': 'True',
#  'n_jobs': 'None',
#  'normalize': 'False'}

pprint(metrics)
# {'training_score': 1.0,
#  'training_mean_absolute_error': 2.220446049250313e-16,
#  'training_mean_squared_error': 1.9721522630525295e-31,
#  'training_r2_score': 1.0,
#  'training_root_mean_squared_error': 4.440892098500626e-16}

pprint(tags)
# {'estimator_class': 'sklearn.linear_model._base.LinearRegression',
#  'estimator_name': 'LinearRegression'}

pprint(artifacts)
# ['model/MLmodel', 'model/conda.yaml', 'model/model.pkl']

Parameters

log_input_examples – 如果 True，训练数据集中的输入示例会在训练期间被收集并与 scikit-learn 模型工件一起记录。如果 False，则不会记录输入示例。注意：输入示例是 MLflow 模型属性，且只有在 log_models 也为 True 时才会被收集。
log_model_signatures – 如果 True， ModelSignatures 描述模型输入和输出，会在训练期间与 scikit-learn 模型工件一起收集并记录。如果 False，则不会记录签名。注意：模型签名是 MLflow 模型属性，只有在 log_models 也为 True 时才会被收集。
log_models – 如果 True，训练好的模型将作为 MLflow 模型工件被记录。如果 False，训练好的模型不会被记录。输入示例和模型签名（它们是 MLflow 模型的属性）在 log_models 为 False 时也会被省略。
log_datasets – 如果 True，则会将训练和验证数据集信息记录到 MLflow Tracking（如果适用）。如果 False，则不记录数据集信息。
disable – 如果 True，则禁用 scikit-learn autologging 集成。如果 False，则启用 scikit-learn autologging 集成。
exclusive – 如果 True，自动记录的内容不会记录到用户创建的 fluent 运行。如果 False，自动记录的内容会记录到活动的 fluent 运行，该运行可能是用户创建的。
disable_for_unsupported_versions – 如果 True，为尚未针对此版本的 MLflow 客户端进行测试或不兼容的 scikit-learn 版本禁用 autologging。
silent – 如果 True，在 scikit-learn autologging 期间抑制 MLflow 的所有事件日志和警告。如果 False，在 scikit-learn autologging 期间显示所有事件和警告。
max_tuning_runs – 为超参数搜索估计器创建的子 MLflow 运行的最大数量。要为搜索中最好的 k 个结果创建子运行，请将 max_tuning_runs 设置为 k。默认值是跟踪最好的 5 个搜索参数集合。如果 max_tuning_runs=None，则为每个搜索参数集合创建一个子运行。注意：最好的 k 个结果是基于 rank_test_score 中的排序。对于使用自定义评分器的多指标评估，将使用第一个评分器的 rank_test_score_ 来选择最好的 k 个结果。要更改用于选择最好的 k 个结果的指标，请更改作为 scoring 参数传递给估计器的 dict 的顺序。
log_post_training_metrics – 如果 True，将记录训练后指标。默认值为 True。有关更多详细信息，请参阅 post training metrics 部分。
serialization_format – 将模型序列化所使用的格式。该格式应为以下之一： mlflow.sklearn.SERIALIZATION_FORMAT_PICKLE 或 mlflow.sklearn.SERIALIZATION_FORMAT_CLOUDPICKLE。
registered_model_name – 如果提供，每次训练模型时，会将模型注册为具有此名称的注册模型的新版本。如果该注册模型尚不存在，则会创建它。
pos_label – 如果提供，将用作正类标签以计算二分类训练指标，例如精确率、召回率、F1 等。此参数仅应为二分类模型设置。如果用于多标签模型，训练指标计算将失败并且训练指标不会被记录。如果用于回归模型，该参数将被忽略。
extra_tags – 一个字典，用于在 autologging 创建的每个托管运行上设置额外标签。

mlflow.sklearn.get_default_conda_env(include_cloudpickle=False)[source]

Returns: 默认的 Conda 环境，用于由调用 save_model() 和 log_model() 生成的 MLflow 模型。

mlflow.sklearn.get_default_pip_requirements(include_cloudpickle=False)[source]

Returns: 该列表列出了由此 flavor 生成的 MLflow Models 的默认 pip 依赖项。对 save_model() 和 log_model() 的调用会生成一个 pip 环境，该环境至少包含这些依赖项。

mlflow.sklearn.load_model(model_uri, dst_path=None)[source]

从本地文件或一次运行中加载 scikit-learn 模型。

Parameters

model_uri –
以 URI 格式表示的 MLflow 模型的位置，例如：
- /Users/me/path/to/local/model
- relative/path/to/local/model
- s3://my_bucket/path/to/model
- runs://run-relative/path/to/model
- models://
- models://
有关支持的 URI 方案的更多信息，请参见 Referencing Artifacts。
dst_path – 要将模型工件下载到的本地文件系统路径。该目录必须已存在。如果未指定，将创建一个本地输出路径。

Returns

一个 scikit-learn 模型。

Example

import mlflow.sklearn

sk_model = mlflow.sklearn.load_model("runs:/96771d893a5e46159d9f3b49bf9013e2/sk_models")

# use Pandas DataFrame to make predictions
pandas_df = ...
predictions = sk_model.predict(pandas_df)

mlflow.sklearn.log_model(sk_model, artifact_path: str | None = None, conda_env=None, code_paths=None, serialization_format='cloudpickle', registered_model_name=None, signature: mlflow.models.signature.ModelSignature = None, input_example: Union[pandas.core.frame.DataFrame, numpy.ndarray, dict, list, csr_matrix, csc_matrix, str, bytes, tuple] = None, await_registration_for=300, pip_requirements=None, extra_pip_requirements=None, pyfunc_predict_fn='predict', metadata=None, params: dict[str, typing.Any] | None = None, tags: dict[str, typing.Any] | None = None, model_type: str | None = None, step: int = 0, model_id: str | None = None, name: str | None = None)[source]

将 scikit-learn 模型记录为当前运行的 MLflow 工件。生成一个包含以下 flavors 的 MLflow 模型：

mlflow.sklearn

mlflow.pyfunc. 注意：该 flavor 仅包含用于定义 predict() 的 scikit-learn 模型，因为 predict() 是 pyfunc 模型推理所必需的。

Parameters

sk_model – 要保存的 scikit-learn 模型。
artifact_path – 已弃用。请改用 name。
conda_env –
要么是 Conda 环境的字典表示，要么是指向 conda 环境 yaml 文件的路径。如果提供，则描述了该模型应在其上运行的环境。至少，它应指定包含在 get_default_conda_env() 中的依赖项。如果 None，则会将一个带有由 mlflow.models.infer_pip_requirements() 推断出的 pip 依赖的 conda 环境添加到模型中。如果依赖推断失败，则回退使用 get_default_pip_requirements。来自 conda_env 的 pip 依赖会被写入一个 pip requirements.txt 文件，完整的 conda 环境则写入 conda.yaml。以下是一个示例的 conda 环境的字典表示：
```
{
    "name": "mlflow-env",
    "channels": ["conda-forge"],
    "dependencies": [
        "python=3.8.15",
        {
            "pip": [
                "scikit-learn==x.y.z"
            ],
        },
    ],
}
```
code_paths –
本地文件系统中指向 Python 文件依赖（或包含文件依赖的目录）路径的列表。这些文件在模型加载时会被预先添加到系统路径中。如果为某个模型声明了依赖文件且多个文件之间存在导入依赖关系，那么这些文件应从一个共同的根路径声明相对导入，以避免在加载模型时发生导入错误。

有关 code_paths 功能、推荐的使用模式和限制的详细说明，请参阅 code_paths usage guide。
serialization_format – 将模型序列化的格式。该格式应为 mlflow.sklearn.SUPPORTED_SERIALIZATION_FORMATS 列出的格式之一。Cloudpickle 格式，mlflow.sklearn.SERIALIZATION_FORMAT_CLOUDPICKLE，通过识别并打包与序列化模型相关的代码依赖，提供更好的跨系统兼容性。
registered_model_name – 如果提供，将在 registered_model_name 下创建一个模型版本，并在不存在同名的注册模型时创建该注册模型。
signature –
一个 ModelSignature 类的实例，用于描述模型的输入和输出。如果未指定但提供了 input_example，则会根据提供的输入示例和模型自动推断签名。要在提供输入示例时禁用自动签名推断，请将 signature 设置为 False。要手动推断模型签名，请在具有有效模型输入，例如省略了目标列的训练数据集，以及有效模型输出，例如在训练数据集上生成的模型预测的数据集上调用 infer_signature()，例如：
```
from mlflow.models import infer_signature

train = df.drop_column("target_label")
predictions = ...  # 计算模型预测
signature = infer_signature(train, predictions)
```
input_example – 一个或多个有效模型输入实例。输入示例用于提示应向模型提供何种数据。它将被转换为一个 Pandas DataFrame，然后使用 Pandas 的 split-oriented 格式序列化为 json，或者转换为一个 numpy array，其中示例将通过将其转换为列表的方式序列化为 json。字节使用 base64 编码。当 signature 参数为 None 时，输入示例用于推断模型签名。
await_registration_for – 等待模型版本完成创建并处于 READY 状态的秒数。默认情况下，函数等待五分钟。指定 0 或 None 可跳过等待。
pip_requirements – 要么是 pip 依赖字符串的可迭代对象（例如 ["scikit-learn", "-r requirements.txt", "-c constraints.txt"]）要么是本地文件系统上 pip requirements 文件的字符串路径（例如 "requirements.txt"）。如果提供，它描述了该模型应在其中运行的环境。如果 None，默认的依赖列表将由 mlflow.models.infer_pip_requirements() 从当前软件环境中推断得到。如果依赖推断失败，则回退使用 get_default_pip_requirements。依赖和约束会分别自动解析并写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。依赖还会写入模型的 conda 环境（conda.yaml）文件的 pip 部分。
extra_pip_requirements –
要么是一个 pip 需求字符串的可迭代对象（例如 ["pandas", "-r requirements.txt", "-c constraints.txt"]），要么是本地文件系统上 pip requirements 文件的字符串路径（例如 "requirements.txt"）。如果提供，该参数描述了附加的 pip 依赖，这些依赖会被追加到基于用户当前软件环境自动生成的默认 pip 依赖集合中。requirements 和 constraints 会被自动解析并分别写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。依赖项也会被写入模型的 conda 环境（conda.yaml）文件的 pip 部分。
警告

以下参数不能同时指定：
- conda_env
- pip_requirements
- extra_pip_requirements
This example 演示了如何使用 pip_requirements 和 extra_pip_requirements 指定 pip 依赖。
pyfunc_predict_fn – 用于在生成的 MLflow Model 的 pyfunc 表示上进行推断时使用的预测函数的名称。当前支持的函数有："predict", "predict_proba", "predict_log_proba", "predict_joint_log_proba", 和 "score"。
metadata – 传递给模型并存储在 MLmodel 文件中的自定义元数据字典。
params – 一个用于与模型一同记录的参数字典。
tags – 一个要与模型一起记录的标签字典。
model_type – 模型的类型。
step – 在该步记录模型输出和指标
model_id – 模型的 ID。
name – 模型名称。

Returns

一个 ModelInfo 实例，包含已记录模型的元数据。

Example

import mlflow
import mlflow.sklearn
from mlflow.models import infer_signature
from sklearn.datasets import load_iris
from sklearn import tree

with mlflow.start_run():
    # load dataset and train model
    iris = load_iris()
    sk_model = tree.DecisionTreeClassifier()
    sk_model = sk_model.fit(iris.data, iris.target)

    # log model params
    mlflow.log_param("criterion", sk_model.criterion)
    mlflow.log_param("splitter", sk_model.splitter)
    signature = infer_signature(iris.data, sk_model.predict(iris.data))

    # log model
    mlflow.sklearn.log_model(sk_model, name="sk_models", signature=signature)

mlflow.sklearn.save_model(sk_model, path, conda_env=None, code_paths=None, mlflow_model=None, serialization_format='cloudpickle', signature: mlflow.models.signature.ModelSignature = None, input_example: Union[pandas.core.frame.DataFrame, numpy.ndarray, dict, list, csr_matrix, csc_matrix, str, bytes, tuple] = None, pip_requirements=None, extra_pip_requirements=None, pyfunc_predict_fn='predict', metadata=None)[source]

将 scikit-learn 模型保存到本地文件系统的某个路径。生成一个包含以下 flavors 的 MLflow Model：

mlflow.sklearn

mlflow.pyfunc。注意：此 flavor 仅包含针对定义了 predict() 的 scikit-learn 模型，因为 predict() 对于 pyfunc 模型的推理是必需的。

Parameters

sk_model – 要保存的 scikit-learn 模型。
path – 模型要保存的本地路径。
conda_env –
可以是 Conda 环境的字典表示，或指向 conda 环境 yaml 文件的路径。如果提供，它描述了应该在何种环境中运行此模型。至少，它应指定包含在 get_default_conda_env() 中的依赖项。如果 None，则会将通过 mlflow.models.infer_pip_requirements() 推断出的 pip 依赖添加到模型的 conda 环境中。如果依赖推断失败，则回退使用 get_default_pip_requirements。来自 conda_env 的 pip 依赖将被写入 pip requirements.txt 文件，完整的 conda 环境将被写入 conda.yaml。以下是一个示例的 conda 环境字典表示：
```
{
    "name": "mlflow-env",
    "channels": ["conda-forge"],
    "dependencies": [
        "python=3.8.15",
        {
            "pip": [
                "scikit-learn==x.y.z"
            ],
        },
    ],
}
```
code_paths –
本地文件系统中指向 Python 文件依赖（或包含文件依赖的目录）路径的列表。这些文件在模型加载时会被预先添加到系统路径中。如果为某个模型声明了依赖文件且多个文件之间存在导入依赖关系，那么这些文件应从一个共同的根路径声明相对导入，以避免在加载模型时发生导入错误。

有关 code_paths 功能、推荐的使用模式和限制的详细说明，请参阅 code_paths usage guide。
mlflow_model – mlflow.models.Model 此 flavor 正在被添加到。
serialization_format – 用于序列化模型的格式。该格式应为列在 mlflow.sklearn.SUPPORTED_SERIALIZATION_FORMATS 中的某一种。Cloudpickle 格式，mlflow.sklearn.SERIALIZATION_FORMAT_CLOUDPICKLE，通过识别并与序列化模型一起打包代码依赖项，提供更好的跨系统兼容性。
signature –
一个 ModelSignature 类的实例，用于描述模型的输入和输出。如果未指定但提供了 input_example，则会根据提供的输入示例和模型自动推断签名。要在提供输入示例时禁用自动签名推断，请将 signature 设置为 False。要手动推断模型签名，请在具有有效模型输入，例如省略了目标列的训练数据集，以及有效模型输出，例如在训练数据集上生成的模型预测的数据集上调用 infer_signature()，例如：
```
from mlflow.models import infer_signature

train = df.drop_column("target_label")
predictions = ...  # 计算模型预测
signature = infer_signature(train, predictions)
```
input_example – 一个或多个有效模型输入实例。输入示例用于提示应向模型提供何种数据。它将被转换为一个 Pandas DataFrame，然后使用 Pandas 的 split-oriented 格式序列化为 json，或者转换为一个 numpy array，其中示例将通过将其转换为列表的方式序列化为 json。字节使用 base64 编码。当 signature 参数为 None 时，输入示例用于推断模型签名。
pip_requirements – 要么是一个可迭代的 pip 需求字符串（例如 ["scikit-learn", "-r requirements.txt", "-c constraints.txt"]）要么是本地文件系统上 pip requirements 文件的字符串路径（例如 "requirements.txt"）。如果提供，它描述了运行该模型所需的环境。如果 None，默认的依赖列表将由 mlflow.models.infer_pip_requirements() 从当前软件环境推断出来。如果依赖推断失败，则回退使用 get_default_pip_requirements。需求和约束会分别自动解析并写入 requirements.txt 和 constraints.txt 文件中，并作为模型的一部分存储。需求也会写入模型的 conda 环境（conda.yaml）文件的 pip 部分。
extra_pip_requirements –
要么是一个 pip 需求字符串的可迭代对象（例如 ["pandas", "-r requirements.txt", "-c constraints.txt"]），要么是本地文件系统上 pip requirements 文件的字符串路径（例如 "requirements.txt"）。如果提供，该参数描述了附加的 pip 依赖，这些依赖会被追加到基于用户当前软件环境自动生成的默认 pip 依赖集合中。requirements 和 constraints 会被自动解析并分别写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。依赖项也会被写入模型的 conda 环境（conda.yaml）文件的 pip 部分。
警告

以下参数不能同时指定：
- conda_env
- pip_requirements
- extra_pip_requirements
This example 演示了如何使用 pip_requirements 和 extra_pip_requirements 指定 pip 依赖。
pyfunc_predict_fn – 用于对结果的 MLflow Model 的 pyfunc 表示进行推理时使用的预测函数的名称。当前支持的函数有： "predict", "predict_proba", "predict_log_proba", "predict_joint_log_proba", and "score".
metadata – 传递给模型并存储在 MLmodel 文件中的自定义元数据字典。

Example

import mlflow.sklearn
from sklearn.datasets import load_iris
from sklearn import tree

iris = load_iris()
sk_model = tree.DecisionTreeClassifier()
sk_model = sk_model.fit(iris.data, iris.target)

# Save the model in cloudpickle format
# set path to location for persistence
sk_path_dir_1 = ...
mlflow.sklearn.save_model(
    sk_model,
    sk_path_dir_1,
    serialization_format=mlflow.sklearn.SERIALIZATION_FORMAT_CLOUDPICKLE,
)

# save the model in pickle format
# set path to location for persistence
sk_path_dir_2 = ...
mlflow.sklearn.save_model(
    sk_model,
    sk_path_dir_2,
    serialization_format=mlflow.sklearn.SERIALIZATION_FORMAT_PICKLE,
)