MLflow LightGBM 集成完全指南:模型日志、加载与自动记录(mlflow.lightgbm API 深度解析)
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 包装器。包装器提供:
get_raw_model():返回底层原始 LightGBM 模型(mlflow/lightgbm/init.py);predict(dataframe, params=None):接收 DataFrame 输入并返回模型预测结果(mlflow/lightgbm/init.py)。
测试 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)可见其实现方式:
- Patch
lightgbm.Dataset.__init__:在构造数据集时截取前INPUT_EXAMPLE_SAMPLE_ROWS行数据副本,作为后续输入示例与签名推断的数据源(mlflow/lightgbm/init.py); - Patch
lightgbm.train:注入记录每轮评估结果的回调(_autolog_callback),训练结束后批量记录指标、参数,记录best_iteration/stopped_iteration等早停相关指标(mlflow/lightgbm/init.py),绘制并记录 split/gain 特征重要性图与 JSON(mlflow/lightgbm/init.py),最后调用log_model记录模型; - 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。