mlflow.sklearn

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

Python (原生) pickle 格式: 这是可以重新加载回 scikit-learn 的主要风格。
mlflow.pyfunc: 为通用基于pyfunc的部署工具和批量推理而生成。注意：mlflow.pyfunc 风格仅针对定义了 predict() 的scikit-learn模型添加，因为 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)[源代码]

备注

Autologging 已知与以下包版本兼容：0.24.1 <= scikit-learn <= 1.5.2。当使用此范围之外的包版本时，Autologging 可能不会成功。

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

何时执行自动日志记录？

当你调用时，会执行自动日志记录：

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

记录的信息

参数

通过 estimator.get_params(deep=True) 获得的参数。注意 get_params 是以 deep=True 调用的。这意味着当你拟合一个链式一系列估计器的元估计器时，这些子估计器的参数也会被记录。

训练指标

通过 estimator.score 获得的训练分数。请注意，训练分数是使用传递给 fit() 的参数计算的。
分类器的常见指标：
- precision score
- 召回率
- f1 score
- 准确率分数
如果分类器有 predict_proba 方法，我们还会记录：
- log loss
- roc auc score
回归器的常见指标：
- 均方误差
- 均方根误差
- 平均绝对误差
- r2 score

训练后指标

当用户在模型训练后调用指标API时，MLflow 尝试捕获指标API的结果，并将其记录为与模型关联的运行中的MLflow指标。以下类型的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 指标 API 进行了多次调用，每次后续调用都会在指标键中添加一个“call_index”（从 2 开始）。
MLflow 使用预测输入数据集变量名作为指标键中的“dataset_name”。“预测输入数据集变量”指的是作为关联的 model.predict 或 model.score 调用的第一个参数使用的变量。注意：MLflow 在 outermost 调用帧中捕获“预测输入数据集”实例，并在 outermost 调用帧中获取变量名。如果“预测输入数据集”实例是一个没有定义变量名的中间表达式，数据集名称将设置为“unknown_dataset”。如果多个“预测输入数据集”实例具有相同的变量名，那么后续的实例将在检查的数据集名称后附加一个索引（从2开始）。

限制

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

标签

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

工件

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

元估计器的自动日志记录是如何工作的？

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

参数搜索: 除了记录上述信息外，参数搜索元估计器（GridSearchCV 和 RandomizedSearchCV）的自动记录还会记录每个探索参数集的子运行及其指标，以及最佳模型的工件和参数（如果可用）。

支持的估计器

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

示例

查看更多示例

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']

参数:

log_input_examples – 如果 True，训练数据集中的输入示例将与 scikit-learn 模型工件一起收集并记录在训练过程中。如果 False，则不记录输入示例。注意：输入示例是 MLflow 模型属性，只有在 log_models 也为 True 时才会收集。
log_model_signatures – 如果 True，在训练期间，描述模型输入和输出的 模型签名 将与 scikit-learn 模型工件一起收集并记录。如果 False，则不记录签名。注意：模型签名是 MLflow 模型属性，只有在 log_models 也是 True 时才会收集。
log_models – 如果 True，训练好的模型会被记录为 MLflow 模型工件。如果 False，训练好的模型不会被记录。输入示例和模型签名（MLflow 模型的属性）在 log_models 为 False 时也会被省略。
log_datasets – 如果 True，则在适用的情况下将训练和验证数据集信息记录到 MLflow 跟踪中。如果 False，则不记录数据集信息。
disable – 如果 True，禁用 scikit-learn 自动记录集成。如果 False，启用 scikit-learn 自动记录集成。
exclusive – 如果 True ，自动记录的内容不会记录到用户创建的 fluent 运行中。如果 False ，自动记录的内容会记录到活动的 fluent 运行中，这可能是用户创建的。
disable_for_unsupported_versions – 如果 True，则对未经过此版本 MLflow 客户端测试或不兼容的 scikit-learn 版本禁用自动日志记录。
silent – 如果 True，在 scikit-learn 自动记录期间抑制 MLflow 的所有事件日志和警告。如果 False，在 scikit-learn 自动记录期间显示所有事件和警告。
max_tuning_runs – 为超参数搜索估计器创建的子 MLflow 运行的最大数量。要为搜索中的最佳 k 个结果创建子运行，请将 max_tuning_runs 设置为 k。默认值是跟踪最佳的 5 组搜索参数。如果 max_tuning_runs=None，则为每组搜索参数创建一个子运行。注意：最佳 k 个结果基于 rank_test_score 中的排序。在多指标评估且使用自定义评分器的情况下，将使用第一个评分器的 rank_test_score_<scorer_name> 来选择最佳 k 个结果。要更改用于选择最佳 k 个结果的指标，请更改作为估计器 scoring 参数传递的字典的顺序。
log_post_training_metrics – 如果 True，训练后的指标会被记录。默认为 True。更多详情请参见训练后指标部分。
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)[源代码]

返回:: 通过调用 save_model() 和 log_model() 生成的 MLflow 模型的默认 Conda 环境。

mlflow.sklearn.get_default_pip_requirements(include_cloudpickle=False)[源代码]

返回:: 此flavor生成的MLflow Models的默认pip需求列表。对 save_model() 和 log_model() 的调用会生成一个pip环境，该环境至少包含这些需求。

mlflow.sklearn.load_model(model_uri, dst_path=None)[源代码]

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

参数:

model_uri – MLflow 模型的位置，采用 URI 格式，例如： - /Users/me/path/to/local/model - relative/path/to/local/model - s3://my_bucket/path/to/model - runs:/<mlflow_run_id>/run-relative/path/to/model - models:/<model_name>/<model_version> - models:/<model_name>/<stage> 有关支持的 URI 方案的更多信息，请参阅引用工件。
dst_path – 下载模型工件的本地文件系统路径。此目录必须已经存在。如果未指定，将创建一个本地输出路径。

返回:

一个 scikit-learn 模型。

示例

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, conda_env=None, code_paths=None, serialization_format='cloudpickle', registered_model_name=None, signature: ModelSignature = None, input_example: DataFrame | 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)[源代码]

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

mlflow.sklearn

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

参数:

sk_model – 要保存的 scikit-learn 模型。
artifact_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使用指南 <https://mlflow.org/docs/latest/model/dependencies.html?highlight=code_paths#saving-extra-code-with-an-mlflow-model>`_。
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()，例如：
input_example – 一个或多个有效的模型输入实例。输入示例用作提示，指示应向模型提供哪些数据。它将被转换为Pandas DataFrame，然后使用Pandas的面向分割的格式序列化为json，或者是一个numpy数组，其中示例将通过将其转换为列表来序列化为json。字节被base64编码。当``signature``参数为``None``时，输入示例用于推断模型签名。
await_registration_for – 等待模型版本完成创建并处于 READY 状态的秒数。默认情况下，函数等待五分钟。指定 0 或 None 以跳过等待。
pip_requirements – 可以是 pip 需求字符串的可迭代对象（例如 ["scikit-learn", "-r requirements.txt", "-c constraints.txt"]），或者是本地文件系统上的 pip 需求文件的字符串路径（例如 "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.txt"）。如果提供，这将描述附加的 pip 需求，这些需求会被追加到根据用户当前软件环境自动生成的一组默认 pip 需求中。需求和约束会分别自动解析并写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。需求也会被写入模型的 conda 环境（conda.yaml）文件的 pip 部分。 .. 警告:: 以下参数不能同时指定： - conda_env - pip_requirements - extra_pip_requirements 这个示例展示了如何使用 pip_requirements 和 extra_pip_requirements 指定 pip 需求。
pyfunc_predict_fn – 用于推理的预测函数的名称，该函数与结果 MLflow 模型的 pyfunc 表示一起使用。当前支持的函数有："predict"、"predict_proba"、"predict_log_proba"、"predict_joint_log_proba" 和 "score"。
metadata – 传递给模型并在 MLmodel 文件中存储的自定义元数据字典。

返回:

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

示例

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, "sk_models", signature=signature)

mlflow.sklearn.save_model(sk_model, path, conda_env=None, code_paths=None, mlflow_model=None, serialization_format='cloudpickle', signature: ModelSignature = None, input_example: DataFrame | ndarray | dict | list | csr_matrix | csc_matrix | str | bytes | tuple = None, pip_requirements=None, extra_pip_requirements=None, pyfunc_predict_fn='predict', metadata=None)[源代码]

将 scikit-learn 模型保存到本地文件系统中的路径。生成包含以下风格的 MLflow 模型：

mlflow.sklearn

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

参数:

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使用指南 <https://mlflow.org/docs/latest/model/dependencies.html?highlight=code_paths#saving-extra-code-with-an-mlflow-model>`_。
mlflow_model – mlflow.models.Model 正在添加此风格。
serialization_format – 序列化模型的格式。这应该是 mlflow.sklearn.SUPPORTED_SERIALIZATION_FORMATS 中列出的格式之一。Cloudpickle 格式，mlflow.sklearn.SERIALIZATION_FORMAT_CLOUDPICKLE，通过识别并打包序列化模型中的代码依赖，提供了更好的跨系统兼容性。
signature – 一个 ModelSignature 类的实例，描述了模型的输入和输出。如果没有指定但提供了 input_example，将根据提供的输入示例和模型自动推断签名。要在提供输入示例时禁用自动签名推断，请将 signature 设置为 False。要手动推断模型签名，请在具有有效模型输入（例如省略了目标列的训练数据集）和有效模型输出（例如在训练数据集上进行的模型预测）的数据集上调用 infer_signature()，例如：
input_example – 一个或多个有效的模型输入实例。输入示例用作提示，指示应向模型提供哪些数据。它将被转换为Pandas DataFrame，然后使用Pandas的面向分割的格式序列化为json，或者是一个numpy数组，其中示例将通过将其转换为列表来序列化为json。字节被base64编码。当``signature``参数为``None``时，输入示例用于推断模型签名。
pip_requirements – 可以是 pip 需求字符串的可迭代对象（例如 ["scikit-learn", "-r requirements.txt", "-c constraints.txt"]），或者是本地文件系统上的 pip 需求文件的字符串路径（例如 "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.txt"）。如果提供，这将描述附加的 pip 需求，这些需求会被追加到根据用户当前软件环境自动生成的一组默认 pip 需求中。需求和约束会分别自动解析并写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。需求也会被写入模型的 conda 环境（conda.yaml）文件的 pip 部分。 .. 警告:: 以下参数不能同时指定： - conda_env - pip_requirements - extra_pip_requirements 这个示例展示了如何使用 pip_requirements 和 extra_pip_requirements 指定 pip 需求。
pyfunc_predict_fn – 用于推理的预测函数的名称，该函数与结果 MLflow 模型的 pyfunc 表示一起使用。当前支持的函数有："predict"、"predict_proba"、"predict_log_proba"、"predict_joint_log_proba" 和 "score"。
metadata – 传递给模型并在 MLmodel 文件中存储的自定义元数据字典。

示例

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,
)