MLflow LightGBM 集成完全指南:模型日志、加载与自动记录(mlflow.lightgbm API 深度解析)

原创2026-09-11 10:52:551,945 阅读
文章标签:人工智能大模型MLOpsLLMOps模型评测可观测性LLM 网关后端

MLflow LightGBM 集成完全指南:模型日志、加载与自动记录(mlflow.lightgbm API 深度解析)

导读

本文基于 MLflow 官方 API 文档 mlflow.lightgbm.rst 及其底层模块 mlflow/lightgbm/init.py 的完整源码,系统讲解 MLflow 对 LightGBM 模型的原生支持。你将掌握:如何通过 save_model / log_model 保存与记录 LightGBM Booster 及 scikit-learn 风格模型,如何用 load_model 从本地或 Run 中加载模型,以及如何通过 autolog 一键自动记录训练参数、迭代指标、特征重要性与模型工件。文中所有参数说明、代码示例与输出均来自当前仓库源码与测试用例,可直接复制运行。

模块概览:两种模型格式与两种 Flavor

mlflow.lightgbm 模块为 LightGBM 模型提供了一套完整的日志(logging)与加载(loading)API。模块 docstring(见 mlflow/lightgbm/init.py)明确了它导出的模型包含两种 flavor:

  • LightGBM (native) 格式:主 flavor,可将模型重新加载回 LightGBM(lightgbm.Booster 实例);
  • mlflow.pyfunc 格式:为通用的 pyfunc 部署工具与批量推理而生成。

在模型类型上,该模块同时支持两类 LightGBM 模型:

模型类型 说明 序列化方式
lightgbm.Booster(原生) lightgbm.train 的直接产物 使用 LightGBM 内建的 Booster.save_model(),产物文件为 model.lgb
scikit-learn API 模型 LGBMClassifier、LGBMRegressor 等 使用 serialization_format 参数指定的格式,产物文件为 model.skops 或 model.pkl

这一判定逻辑体现在源码 save_model 中:isinstance(lgb_model, lgb.Booster) 时为 model.lgb,serialization_format == "skops" 时为 model.skops,否则为 model.pkl。对应的加载逻辑见 _load_model:Booster 通过 lgb.Booster(model_file=...) 加载,sklearn 模型则委托 mlflow.sklearn._load_model_from_local_file 按 flavor 配置中记录的序列化格式还原。

序列化格式:skops / cloudpickle / pickle 的选择

对非 Booster 的 scikit-learn 风格模型,serialization_format 是 save_model 与 log_model 的核心参数(默认值为 "skops")。源码 docstring(mlflow/lightgbm/init.py)给出了三种格式的定位:

  • skops(默认):保证反序列化安全(safe deserialization)。模块内置了一组受信任类型集合 _LIGHTGBM_SKLEARN_SKOPS_TRUSTED_TYPES(见 mlflow/lightgbm/init.py),覆盖 collections.OrderedDict、lightgbm.basic.Booster、lightgbm.sklearn.LGBMClassifier、lightgbm.sklearn.LGBMRegressor,并在保存时自动与用户传入的 skops_trusted_types 合并(mlflow/lightgbm/init.py);
  • cloudpickle:通过识别并打包代码依赖获得更好的跨系统兼容性,但依赖 Python 对象序列化机制,反序列化时可能执行任意代码;
  • pickle:原生 pickle,同样存在任意代码执行风险。

源码 _save_model 中,对非 skops 格式且不在 Databricks 运行时的情况下会打印警告日志,提醒用户 pickle/cloudpickle 的安全风险并推荐 skops。因此生产环境建议:默认使用 skops,仅在需要兼容旧系统或确知模型来源可信时才切换到 cloudpickle / pickle。

保存模型:save_model

save_model 将 LightGBM 模型保存到本地文件系统路径,并自动生成完整的 MLflow 模型目录(含 MLmodel、conda.yaml、python_env.yaml、requirements.txt、模型数据文件等)。

核心参数

参数 类型 / 默认值 说明
lgb_model Booster 或 sklearn 模型 要保存的 LightGBM 模型
path str 本地保存路径
conda_env dict / str / None Conda 环境定义;为 None 时基于 pip requirements 自动推断
code_paths list[str] 与模型一起打包的代码文件/目录路径
mlflow_model Model 要附加此 flavor 的 MLflow Model 对象,缺省时新建
signature ModelSignature 模型输入输出的签名;为 False 时禁用
input_example ModelInputExample 输入示例,用于保存与推断签名
pip_requirements list[str] 显式 pip requirements(会与推断结果合并)
extra_pip_requirements list[str] 追加的 pip requirements
metadata dict 附加到 MLmodel 文件的元数据
serialization_format "skops"(默认) 非 Booster 模型的序列化格式:skops / cloudpickle / pickle
skops_trusted_types list[str] skops 加载时受信任的类型集合
extra_files list[str] 额外复制到模型目录的文件
kwargs dict 透传给 lightgbm.Booster.save_model 的额外参数

官方示例(含输出)

以下示例来自源码 docstring(mlflow/lightgbm/init.py),完整可运行:

from pathlib import Path
from lightgbm import LGBMClassifier
from sklearn import datasets
import mlflow

# Load iris dataset
X, y = datasets.load_iris(return_X_y=True, as_frame=True)

# Initialize our model
model = LGBMClassifier(objective="multiclass", random_state=42)

# Train the model
model.fit(X, y)

# Save the model
path = "model"
mlflow.lightgbm.save_model(
    model,
    path,
    serialization_format="skops",
    skops_trusted_types=[
        "collections.OrderedDict",
        "lightgbm.basic.Booster",
        "lightgbm.sklearn.LGBMClassifier",
    ],
)

# Load model for inference
loaded_model = mlflow.lightgbm.load_model(Path.cwd() / path)
print(loaded_model.predict(X[:5]))

输出:

[0 0 0 0 0]

底层行为要点

  • 环境文件生成:当 conda_env 为 None 时,若 pip_requirements 也为 None,则会调用 mlflow.models.infer_pip_requirements 推断依赖,并与默认依赖(lightgbm,视序列化格式追加 cloudpickle 或 skops,见 get_default_pip_requirements)取并集,最终写出 conda.yaml、requirements.txt、constraints.txt(如有)与 python_env.yaml(mlflow/lightgbm/init.py);
  • 签名与输入示例:未显式传 signature 且提供了 input_example 时,会通过 _infer_signature_from_input_example 基于包装模型自动推断签名(mlflow/lightgbm/init.py);
  • pyfunc 注册:保存时同时调用 pyfunc.add_to_model,注册 loader_module="mlflow.lightgbm",使模型可被 pyfunc 通用推理链路加载(mlflow/lightgbm/init.py)。

记录模型到 Run:log_model

log_model 将模型作为当前 run 的 artifact 记录到 MLflow Tracking,返回包含模型元数据的 ModelInfo 实例。它在参数上与 save_model 基本一致,并额外支持模型注册与 Run 管理相关参数:

  • artifact_path:已废弃,改用 name;
  • registered_model_name:指定后自动创建(如不存在)并注册新版本模型;
  • await_registration_for:等待模型版本变为 READY 的秒数,默认等待五分钟,传 0 或 None 跳过等待;
  • name、params、tags、model_type、step、model_id:模型记录与版本管理相关参数。

官方示例(含输出)

以下示例来自源码 docstring(mlflow/lightgbm/init.py):

from lightgbm import LGBMClassifier
from sklearn import datasets
import mlflow
from mlflow.models import infer_signature

# Load iris dataset
X, y = datasets.load_iris(return_X_y=True, as_frame=True)

# Initialize our model
model = LGBMClassifier(objective="multiclass", random_state=42)

# Train the model
model.fit(X, y)

# Create model signature
predictions = model.predict(X)
signature = infer_signature(X, predictions)

# Log the model
artifact_path = "model"
with mlflow.start_run():
    model_info = mlflow.lightgbm.log_model(model, name=artifact_path, signature=signature)

# Fetch the logged model artifacts
print(f"run_id: {run.info.run_id}")
client = mlflow.MlflowClient()
artifacts = [f.path for f in client.list_artifacts(run.info.run_id, artifact_path)]
print(f"artifacts: {artifacts}")

输出(skops 序列化下的典型 artifact 结构):

artifacts: ['model/MLmodel',
            'model/conda.yaml',
            'model/model.skops',
            'model/python_env.yaml',
            'model/requirements.txt']

可以看到,一个被记录的 LightGBM 模型目录包含模型元数据 MLmodel、Conda 环境 conda.yaml、Python 环境 python_env.yaml、依赖清单 requirements.txt 以及序列化后的模型数据文件 model.skops(Booster 场景则为 model.lgb)。该输出与 tests/lightgbm/test_lightgbm_model_export.py 中 _assert_pip_requirements 等断言逻辑相互印证。

加载模型:load_model

load_model 从本地路径或远程 artifact URI 加载 LightGBM 模型,返回 lightgbm.Booster 实例或 scikit-learn 风格模型(取决于保存时的模型类型)。

支持的 URI 形式

源码 docstring(mlflow/lightgbm/init.py)列出的示例:

  • /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(从指定 run 加载)

参数 dst_path 可指定本地下载目录(须已存在),缺省时自动创建本地输出路径。

加载示例

以下示例来自源码 docstring(mlflow/lightgbm/init.py):

from lightgbm import LGBMClassifier
from sklearn import datasets
import mlflow

# Auto log all MLflow entities
mlflow.lightgbm.autolog()

# Load iris dataset
X, y = datasets.load_iris(return_X_y=True, as_frame=True)

# Initialize our model
model = LGBMClassifier(objective="multiclass", random_state=42)

# Train the model
model.fit(X, y)

# Load model for inference
model_uri = f"runs:/{mlflow.last_active_run().info.run_id}/model"
loaded_model = mlflow.lightgbm.load_model(model_uri)
print(loaded_model.predict(X[:5]))

输出:

[0 0 0 0 0]

底层行为要点

加载链路(load_model)为:先将 model_uri 下载到本地(_download_artifact_from_uri),读取 flavor 配置(_get_flavor_configuration),必要时把 code_paths 加入 sys.path(_add_code_from_conf_to_system_path),最后调用 _load_model 还原模型。_load_model 根据 flavor 配置中的 model_class 字段决定走 Booster 路径还是 sklearn 路径(mlflow/lightgbm/init.py)。

PyFunc 推理:_load_pyfunc 与模型包装

为了让模型能接入通用 pyfunc 部署与批量推理,模块实现了 _load_pyfunc(mlflow/lightgbm/init.py),返回 _LGBModelWrapper 包装器。包装器提供:

测试 test_model_save_load 与 test_sklearn_model_save_load(tests/lightgbm/test_lightgbm_model_export.py)验证了:mlflow.lightgbm.load_model 与 pyfunc.load_model 加载的模型,其预测结果与原模型在 np.testing.assert_array_almost_equal 精度下完全一致,确保两条加载路径行为等价。

自动记录:autolog

autolog 是模块中最常用的入口:调用一次后,后续的 lightgbm.train 与 scikit-learn API 训练会自动把各类实体记录到 MLflow。其启用方式是全局的——在训练代码前调用 mlflow.lightgbm.autolog() 即可。

自动记录的内容

源码 docstring(mlflow/lightgbm/init.py)明确列出:

  • 参数:lightgbm.train 中指定的全部参数(通过 mlflow.log_params 逐项记录,便于跨 run 比较,见 mlflow/lightgbm/init.py);
  • 指标:每轮迭代的评估指标(需指定 valid_sets);若设置了 early_stopping_rounds 或 early_stopping 回调,还会记录最佳迭代处的指标;
  • 特征重要性:以 JSON 文件与 PNG 图片两种形式记录 split 与 gain 两类重要性;
  • 训练模型:包括有效输入示例与推断出的输入输出签名。

此外,docs/docs/classic-ml/tracking/autolog/index.mdx 中的官方文档表格确认:LightGBM autolog 捕获"用户指定指标"、"lightgbm.train 参数"、LightGBM 模型(含模型签名、输入示例)与特征重要性工件;若启用了早停,最佳迭代处的指标会作为额外的 step/iteration 记录。

autolog 参数详解

参数 默认值 说明
log_input_examples False 为 True 时收集训练数据输入示例并随模型工件记录(仅当 log_models 为 True 时生效)
log_model_signatures True 是否记录描述模型输入输出的 ModelSignature(仅当 log_models 为 True 时生效)
log_models True 是否将训练好的模型记录为 MLflow 模型工件;为 False 时输入示例与签名也一并省略
log_datasets True 是否记录训练/验证数据集信息到 MLflow Tracking
disable False True 时禁用本集成
exclusive False True 时自动记录的内容不写入用户创建的 fluent run
disable_for_unsupported_versions False True 时对未经测试或兼容的 LightGBM 版本禁用 autolog
silent False True 时抑制 MLflow 在 autolog 期间的日志与警告
registered_model_name None 指定后每次训练完成将模型注册为该注册模型的新版本
extra_tags None 附加到 autolog 创建的每个托管 run 上的额外标签字典

autolog 官方示例(含输出)

以下示例来自源码 docstring(mlflow/lightgbm/init.py):

import mlflow
from lightgbm import LGBMClassifier
from sklearn import datasets


def print_auto_logged_info(run):
    tags = {k: v for k, v in run.data.tags.items() if not k.startswith("mlflow.")}
    artifacts = [
        f.path for f in mlflow.MlflowClient().list_artifacts(run.info.run_id, "model")
    ]
    feature_importances = [
        f.path
        for f in mlflow.MlflowClient().list_artifacts(run.info.run_id)
        if f.path != "model"
    ]
    print(f"run_id: {run.info.run_id}")
    print(f"artifacts: {artifacts}")
    print(f"feature_importances: {feature_importances}")
    print(f"params: {run.data.params}")
    print(f"metrics: {run.data.metrics}")
    print(f"tags: {tags}")


# Load iris dataset
X, y = datasets.load_iris(return_X_y=True, as_frame=True)

# Initialize our model
model = LGBMClassifier(objective="multiclass", random_state=42)

# Auto log all MLflow entities
mlflow.lightgbm.autolog()

# Train the model
with mlflow.start_run() as run:
    model.fit(X, y)

# fetch the auto logged parameters and metrics
print_auto_logged_info(mlflow.get_run(run_id=run.info.run_id))

输出(run_id 为随机值):

run_id: e08dd59d57a74971b68cf78a724dfaf6
artifacts: ['model/MLmodel',
            'model/conda.yaml',
            'model/model.pkl',
            'model/python_env.yaml',
            'model/requirements.txt']
feature_importances: ['feature_importance_gain.json',
                      'feature_importance_gain.png',
                      'feature_importance_split.json',
                      'feature_importance_split.png']
params: {'boosting_type': 'gbdt',
         'categorical_feature': 'auto',
         'colsample_bytree': '1.0',
         ...
         'verbose_eval': 'warn'}
metrics: {}
tags: {}

注意:sklearn 模型默认按 model.pkl 记录(此示例输出为早期版本默认),而当前版本默认 serialization_format="skops",产物为 model.skops;特征重要性工件固定为 4 个:feature_importance_gain.json / .png 与 feature_importance_split.json / .png。

autolog 底层机制

从源码(mlflow/lightgbm/init.py)可见其实现方式:

  1. Patch lightgbm.Dataset.__init__:在构造数据集时截取前 INPUT_EXAMPLE_SAMPLE_ROWS 行数据副本,作为后续输入示例与签名推断的数据源(mlflow/lightgbm/init.py);
  2. Patch lightgbm.train:注入记录每轮评估结果的回调(_autolog_callback),训练结束后批量记录指标、参数,记录 best_iteration / stopped_iteration 等早停相关指标(mlflow/lightgbm/init.py),绘制并记录 split/gain 特征重要性图与 JSON(mlflow/lightgbm/init.py),最后调用 log_model 记录模型;
  3. Patch lightgbm.sklearn.train:关闭其自身模型记录(避免重复),sklearn 估计器的模型记录改由 mlflow.sklearn._autolog 统一处理,从而以 LGBMClassifier / LGBMRegressor 等原生类保存模型(mlflow/lightgbm/init.py)。

此外,_patch_metric_names 会把 LightGBM 中形如 ndcg@3 的指标名中的 @ 替换为 _at_(如 ndcg_at_3),以符合 MLflow 指标命名规范,并在替换发生时输出一条 info 日志说明(mlflow/lightgbm/init.py)。

数据集自动记录

当 autolog(log_datasets=True) 时,训练集与验证集信息会被记录到 MLflow Tracking。_log_lightgbm_dataset(mlflow/lightgbm/init.py)支持以下数据源类型:

  • pandas.DataFrame → mlflow.data.from_pandas;
  • 稀疏矩阵(scipy.sparse)→ 转为稠密数组后使用 mlflow.data.from_numpy;
  • numpy.ndarray → mlflow.data.from_numpy(同时携带标签);
  • Polars DataFrame → mlflow.data.from_polars;
  • 其他未识别类型会记录警告并跳过。

每个数据集以 InputTag(key="mlflow.dataset.context") 标记上下文(train 或 eval),验证集存在 valid_names 时使用对应名称标记。

端到端实战示例

仓库中的 examples/lightgbm/lightgbm_native/train.py 提供了完整的原生 Booster 训练 + autolog 示例:

import argparse
import lightgbm as lgb
from sklearn import datasets
from sklearn.metrics import accuracy_score, log_loss
from sklearn.model_selection import train_test_split
import mlflow
import mlflow.lightgbm

# parse command-line arguments(--learning-rate / --colsample-bytree / --subsample)
args = parse_args()

# prepare train and test data
iris = datasets.load_iris()
X, y = iris.data, iris.target
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# enable auto logging
mlflow.lightgbm.autolog()

train_set = lgb.Dataset(X_train, label=y_train)

with mlflow.start_run():
    params = {
        "objective": "multiclass",
        "num_class": 3,
        "learning_rate": args.learning_rate,
        "metric": "multi_logloss",
        "colsample_bytree": args.colsample_bytree,
        "subsample": args.subsample,
        "seed": 42,
    }
    model = lgb.train(
        params, train_set, num_boost_round=10, valid_sets=[train_set], valid_names=["train"]
    )

    # evaluate model and log custom metrics
    y_proba = model.predict(X_test)
    y_pred = y_proba.argmax(axis=1)
    loss = log_loss(y_test, y_proba)
    acc = accuracy_score(y_test, y_pred)
    mlflow.log_metrics({"log_loss": loss, "accuracy": acc})

运行方式(examples/lightgbm/lightgbm_native/README.md):

python train.py --colsample-bytree 0.8 --subsample 0.9

也可以尝试不同超参数组合:

python train.py --learning-rate 0.4 --colsample-bytree 0.7 --subsample 0.8

训练完成后通过以下命令启动 MLflow UI 查看实验与 run 对比:

mlflow server

或以 MLflow 项目方式运行:

mlflow run . -P learning_rate=0.2 -P colsample_bytree=0.8 -P subsample=0.9

该示例展示了完整工作流:启用 autolog 自动记录训练参数与每轮 multi_logloss 指标,再通过 mlflow.log_metrics 补充自定义评估指标(log_loss、accuracy),实现"自动记录 + 手动补充"的混合记录模式。

总结

mlflow.lightgbm 模块将 LightGBM 的模型生命周期管理完整纳入 MLflow 生态:

  • 保存与记录:save_model / log_model 同时支持原生 Booster(model.lgb)与 scikit-learn 风格模型(model.skops / model.pkl),默认安全序列化格式 skops;
  • 加载与推理:load_model 支持本地路径、runs:/ URI 与对象存储 URI,_load_pyfunc 让模型无缝接入 pyfunc 部署与批量推理;
  • 自动记录:autolog 一行开启后自动记录训练参数、每轮与最佳迭代指标、split/gain 特征重要性(JSON + PNG)、模型签名与输入示例,并可选记录数据集信息与自动注册模型版本。

配套的完整测试见 tests/lightgbm/test_lightgbm_model_export.py 与 tests/lightgbm/test_lightgbm_autolog.py,可直接作为行为契约参考;API 文档源头为 mlflow.lightgbm.rst,自动记录的框架级说明见 docs/docs/classic-ml/tracking/autolog/index.mdx。

登录后查看全文
mlflow