LightGBM Python API 完全指南数据接口、训练引擎与 scikit-learn/Dask 生态全解析【免费下载链接】LightGBMA fast, distributed, high performance gradient boosting (GBT, GBDT, GBRT, GBM or MART) framework based on decision tree algorithms, used for ranking, classification and many other machine learning tasks.项目地址: https://gitcode.com/GitHub_Trending/li/LightGBM本指南以 docs/Python-API.rst 的 API 索引为骨架系统梳理 LightGBM Python 包的完整公开接口——从Dataset/Booster数据结构、train/cv训练引擎到 scikit-learn 风格模型、Dask 分布式接口、回调与可视化工具。读完你既能掌握原生 API 的底层调用逻辑也能直接上手高层封装并在源码层python-package/lightgbm确认每个接口的真实签名与默认值。一、LightGBM Python API 全景LightGBM 的 Python 包将所有公开符号统一从顶层lightgbm命名空间导出其完整清单定义在 python-package/lightgbm/init.py 的__all__中。按功能可划分为六大类分类公开 API实现模块数据结构Dataset、Booster、CVBooster、EvalResult、Sequencebasic.py、engine.py训练引擎train、cvengine.pyscikit-learn APILGBMModel、LGBMClassifier、LGBMRegressor、LGBMRankersklearn.pyDask API3.2.0 起DaskLGBMClassifier、DaskLGBMRegressor、DaskLGBMRankerdask.py回调early_stopping、log_evaluation、record_evaluation、reset_parametercallback.py可视化plot_importance、plot_split_value_histogram、plot_metric、plot_tree、create_tree_digraphplotting.py工具register_loggerbasic.py从源码结构看__init__.py通过三个try/except ImportError块分别对 sklearn、plotting、dask 子模块做可选导入python-package/lightgbm/init.py这意味着即使缺失scikit-learn、matplotlib或dask等可选依赖包的其余功能仍可正常加载——这是理解后续各 API 使用前置条件的重要线索。另外lightgbm.__version__直接读取包目录下的VERSION.txt文件python-package/lightgbm/init.py项目根目录的 VERSION.txt 即当前版本号来源。二、数据结构 API训练数据的底层抽象2.1 Dataset——LightGBM 的数据核心Dataset是 LightGBM Python 训练体系中一切数据的载体。其类文档明确指出basic.pyLightGBM does not train on raw data. It discretizes continuous features into histogram bins, tries to combine categorical features, and automatically handles missing and infinite values.即 LightGBM 并不直接消费原始数据而是在构造Dataset时完成三项关键预处理连续特征离散化为直方图分箱histogram bins、类别特征自动合并、缺失值与无穷值的自动处理。Dataset持有的是预处理后的另一种数据表示。Dataset.__init__的完整签名basic.py如下Dataset( data, # 必填 labelNone, # 标签 referenceNone, # 验证集引用训练集 weightNone, # 每个样本的权重须非负 groupNone, # 学习排序任务的 query/group 信息 init_scoreNone, # 初始分数可嵌套列表用于多分类 feature_nameauto, # 特征名DataFrame 输入时自动取列名 categorical_featureauto, # 类别特征DataFrame 的 unordered categorical 列自动识别 paramsNone, # 其他 Dataset 参数 free_raw_dataTrue, # 构造完内部 Dataset 后是否释放原始数据 positionNone, # 无偏学习排序任务中的位置信息 )data支持的数据源非常广泛字符串/pathlib.Path路径文本文件 CSV/TSV/LibSVM或 LightGBM Dataset 二进制文件、numpy 数组、pandas DataFrame、scipy.sparse 稀疏矩阵、Sequence及Sequence/numpy 数组的列表、pyarrow Table4.2.0 起、polars DataFrame4.7.0 起。label、weight、group、init_score、position同样各自兼容 numpy/pandas/pyarrow/polars 格式。类别特征的处理约束文档明确列出实操需特别注意类别值会被强制转换为 int32因此所有取值须小于 2147483647过大的取值会显著增加内存占用建议使用从 0 开始的连续整数所有负值会被视为缺失值输出结果不能对类别特征施加单调约束类别特征中的浮点数会向 0 取整。构造示例import lightgbm as lgb import pandas as pd df pd.DataFrame({ age: [23, 45, 12, 67], city: pd.Categorical([A, B, A, C]), # unordered categorical → 自动识别 }) label [0, 1, 1, 0] train_data lgb.Dataset( datadf, labellabel, categorical_featureauto, # city 列会被自动识别为类别特征 free_raw_dataTrue, )从实现看Dataset持有_handleC 层句柄与_predictor内部_InnerPredictor并通过train_set.construct()延迟构造底层对象——这一构造动作发生在Booster创建或显式调用construct()时basic.py。此外Dataset还实现了subset()、create_valid()、save_binary()、set_label()/get_label()、get_data()、get_params()等常用方法支持采样_create_sample_indices基于bin_construct_sample_cnt参数决定采样数量见 basic.py。2.2 Booster——模型的底层实体Booster是 LightGBM 模型的 Python 包装四种构造方式basic.pyBooster(paramsNone, train_setNone, model_fileNone, model_strNone)paramsBooster 参数字典train_set训练数据集传入即进入训练模式此时会先调用train_set.construct()并自动调用set_network()初始化分布式网络见 basic.pymodel_file从模型文件加载model_str从模型字符串加载。从实现细节看当train_set非空时basic.py若params中给出machines则假定用户要做分布式训练LightGBM 会自动推导num_machines机器数量、设置默认local_listen_port12400与listen_time_out120秒并建立 socket 网络。训练完成后Booster的best_iteration与best_score属性会记录最优轮次与对应分数。Booster核心方法包括update()单轮训练、predict()预测支持pred_early_stop、num_threads等参数、save_model()/model_to_string()、dump_model()、feature_importance()、eval()/eval_train()/eval_valid()、shrinkage()等。需要注意若train()返回时keep_training_boosterFalse返回对象会被转换为_InnerPredictor此时eval系列方法不可用详见下文 train 一节。2.3 EvalResult——结构化的评估结果EvalResult是一个NamedTuplebasic.py在 4.7.0 之前评估结果以普通元组形式返回如今以具名字段呈现EvalResult( dataset_name: str, # 数据集标识如 valid_0 metric_name: str, # 指标名如 rmse metric_value: float, # 指标值 maximize: bool, # 是否越大越好AUC 为 Truebinary error 为 False metric_std_dev: Optional[float] None, # 跨 fold 的指标标准差cv 聚合时使用 )其is_cv_result()方法通过metric_std_dev is not None判断结果是否来自cv()聚合basic.py。为保证向后兼容__len__()与__iter__()仍按旧元组行为工作非 cv 结果为 4 个字段cv 结果为 5 个字段。2.4 Sequence——流式数据访问接口Sequence是抽象基类3.3.0 起引入定义了一套通用的数据访问协议basic.py用于以流式、低内存方式喂入大规模数据。它要求子类实现__len__()返回总行数__getitem__(idx)支持三种索引——整数随机访问单行用于采样、切片范围访问用于批量读取构造 Dataset、整数列表仅在使用Dataset.subset()时需要可选属性batch_size类属性默认 4096即每批读取 4K 行。import numbers import numpy as np import lightgbm as lgb class MySequence(lgb.Sequence): batch_size 4096 def __init__(self, data): self.data data def __getitem__(self, idx): if isinstance(idx, numbers.Integral): return self.data[idx] elif isinstance(idx, slice): return np.stack([self.data[i] for i in range(idx.start, idx.stop)]) elif isinstance(idx, list): return np.array([self.data[i] for i in idx]) raise TypeError(fSequence index must be integer, slice or list, got {type(idx).__name__}) def __len__(self): return len(self.data) ds lgb.Dataset(MySequence(large_data), labellabels)其设计动机在类文档中写得很清楚随机访问使数据采样无需遍历全部数据范围访问使构造 Dataset 时无需一次性读入全部数据从而降低内存占用basic.py。这正是 LightGBM 支撑超大数据集的关键机制之一配合Dataset.subset()可在子集上构造训练数据而无需重读全量。三、训练 APItrain 与 cv3.1 train——核心训练入口train()位于 engine.py签名如下train( params, # dict训练参数优先级高于具名参数 train_set, # Dataset训练数据 num_boost_round100, # 提升迭代轮数 valid_setsNone, # list of Dataset训练过程中评估的数据 valid_namesNone, # list of strvalid_sets 的名称 fevalNone, # 自定义评估函数或函数列表 init_modelNone, # 模型文件路径或 Booster用于继续训练 keep_training_boosterFalse, # 是否保留可继续训练的 Booster callbacksNone, # 每轮迭代应用的回调函数列表 ) - Boosterfeval自定义评估函数的约定engine.py每个评估函数接收(preds, eval_data)两个参数返回(metric_name, metric_value, maximize)或这类元组的列表。其中preds在多分类任务下是形状为[n_samples, n_classes]的二维数组若使用了自定义目标函数preds返回的是变换前的原始边际raw margin而非二分类正类概率。若要忽略与 objective 对应的默认指标可在params中设置metricNone。init_model继续训练接受模型文件名或Booster实例用于继续训练已有模型。keep_training_booster的权衡engine.py为False默认时返回的 Booster 会被转换为_InnerPredictor因此无法再调用eval、eval_train、eval_valid方法当模型非常大、model_to_string内部转换导致内存错误时应设为True——此时返回的 Booster 仍可继续训练且_InnerPredictor依然可作为下次训练的init_model。自定义目标函数engine.py可将可调用对象直接传给params[objective]。该函数接收(preds, train_data)返回(grad, hess)——即损失函数关于预测值的一阶导梯度与二阶导Hessian。多分类任务下preds、grad、hess均为[n_samples, n_classes]的二维数组。从实现流程看engine.pytrain()会先对params做深拷贝处理objective为 callable 的情形将其替换为none并单独持有fobj再通过_choose_num_iterations协调num_boost_round与params[num_iterations]的关系engine.py并检查num_boost_round 0。此外early_stopping_round可以直接写进全局params生效。一个完整示例import lightgbm as lgb import numpy as np from sklearn.datasets import load_breast_cancer from sklearn.model_selection import train_test_split X, y load_breast_cancer(return_X_yTrue) X_train, X_valid, y_train, y_valid train_test_split(X, y, test_size0.2, random_state42) train_data lgb.Dataset(X_train, labely_train) valid_data lgb.Dataset(X_valid, labely_valid, referencetrain_data) params { objective: binary, metric: binary_logloss, learning_rate: 0.05, num_leaves: 31, verbose: -1, } booster lgb.train( paramsparams, train_settrain_data, num_boost_round200, valid_sets[valid_data], valid_names[valid], callbacks[ lgb.log_evaluation(period50), lgb.early_stopping(stopping_rounds20), ], ) print(best_iteration:, booster.best_iteration) print(best_score:, booster.best_score)3.2 cv——交叉验证cv()同样定义在 engine.pycv( params, train_set, num_boost_round100, foldsNone, # (train_idx, test_idx) 迭代器或 sklearn splitter优先级最高 nfold5, # 折数 stratifiedTrue, # 是否分层采样 shuffleTrue, # 切分前是否打乱 metricsNone, # 评估指标 fevalNone, # 自定义评估函数 init_modelNone, # 继续训练 fpreprocNone, # 每折数据预处理函数 seed0, # 随机种子 callbacksNone, eval_train_metricFalse, # 是否同时评估训练集 return_cvboosterFalse, # 是否返回 CVBooster 而非聚合指标 ) - Dict[str, Union[List[float], CVBooster]]folds参数优先于其他切分参数可传生成器/迭代器yield 每折的 train/test 索引也可传 scikit-learn 的 splitter 类对象需有split方法。返回值为字典默认返回各指标的mean/stdv列表键形如valid-rmse-mean、valid-rmse-stdv当return_cvboosterTrue时cvbooster键对应一个CVBooster实例。CVBoosterengine.py是cv()返回的多个折 Booster 的容器提供boost()每折继续训练一轮、predict()对每折预测并合并等方法可配合save_model/load_model复用。cv_result lgb.cv( paramsparams, train_settrain_data, num_boost_round200, nfold5, stratifiedTrue, seed42, callbacks[lgb.log_evaluation(period100)], ) print(rmse mean:, cv_result[valid-binary_logloss-mean][-1]) print(rmse stdv:, cv_result[valid-binary_logloss-stdv][-1])四、scikit-learn API与 sklearn 生态无缝衔接4.1 LGBMModel 与三个具体模型sklearn.py 中LGBMModel实现了 scikit-learn 风格接口fit/predict/predict_proba等而LGBMClassifier、LGBMRegressor、LGBMRanker分别继承自_LGBMClassifierBase、_LGBMRegressorBase与LGBMModel对应分类、回归、学习排序三大任务。LGBMModel.__init__的核心参数与默认值参数默认值说明boosting_typegbdtgbdt传统 GBDT、dart带 Dropout 的 MART、rf随机森林num_leaves31基学习器最大叶子数max_depth-1最大树深0表示不限制设为正值时建议同时令num_leaves 2^max_depthlearning_rate0.1学习率可在fit中通过reset_parameter回调调整n_estimators100要拟合的树的数量subsample_for_bin200000用于构造直方图分箱的样本数objectiveNone默认回归为regression、分类为binary/multiclass、排序为lambdarank也可传自定义目标函数class_weightNone{类别: 权重}字典或balancedmin_split_gain0.0分裂最小增益min_child_weight1e-3叶子最小二阶导之和min_child_samples20叶子最少样本数subsample/subsample_freq1.0/0行采样比例与频率0 表示不采样colsample_bytree1.0列采样比例reg_alpha/reg_lambda0.0/0.0L1 / L2 正则random_stateNone随机种子n_jobsNone并行线程数importance_typesplit特征重要性类型split分裂次数或gain信息增益用法示例from lightgbm import LGBMClassifier clf LGBMClassifier( n_estimators100, learning_rate0.1, num_leaves31, max_depth-1, objectivebinary, class_weightbalanced, n_jobs-1, ) clf.fit(X_train, y_train, eval_set[(X_valid, y_valid)], eval_metric[auc, binary_logloss], callbacks[lgb.early_stopping(20, verboseFalse)]) preds clf.predict(X_valid) proba clf.predict_proba(X_valid) print(feature importance (gain):, clf.feature_importances_)LGBMClassifier额外提供predict_proba、classes_等分类专属能力LGBMRanker通过group参数每组的样本数列表指定 query 分组用于学习排序任务。所有 sklearn 模型的fit均可接收eval_set、eval_metric、callbacks与原生 API 的行为保持一致。4.2 从 sklearn API 到原生 API 的桥接从实现结构看LGBMModel内部将 sklearn 风格参数映射为原生params字典后最终仍然调用train()完成训练见 sklearn.py 及fit中调用lgb.train(...)的逻辑。这意味着无论使用哪一层 API底层都是同一套原生训练引擎与 C 库只是参数组织方式不同——这是理解 sklearn 参数与原生参数一一对应关系如n_estimators↔num_iterations的根源。五、Dask API分布式训练开箱即用自 3.2.0 起LightGBM 提供 Dask 分布式接口dask.pyDaskLGBMClassifierdask.py继承LGBMClassifier与_DaskLGBMModelDaskLGBMRegressordask.py继承LGBMRegressorDaskLGBMRankerdask.py继承LGBMRanker。这些类接受 Dask DataFrame / Array 作为输入训练时通过_train_partdask.py把数据按分区分发到各 worker并自动分配网络端口_assign_open_ports_to_workersdask.py建立集群内通信预测则由_predict_partdask.py完成分区级推理。其分布式拓扑示意参见 docs/_static/images/dask-initial-setup.svg 与 docs/_static/images/dask-concat.svg。import dask.dataframe as dd from dask.distributed import Client from lightgbm import DaskLGBMClassifier client Client() # 启动本地分布式集群 ddf dd.from_pandas(pd.DataFrame(X), npartitions4) dseries dd.from_pandas(pd.Series(y), npartitions4) model DaskLGBMClassifier(n_estimators100) model.fit(ddf, dseries) preds model.predict(ddf)对应回归与排序任务可分别使用DaskLGBMRegressor、DaskLGBMRanker分布式场景下的用法与 sklearn API 保持一致仅输入变为 Dask 集合。Dask 接口的详细使用示例见 examples/python-guide/dask含binary-classification.py、regression.py、ranking.py、prediction.py、multiclass-classification.py等完整脚本。六、Callbacks训练过程的自定义钩子回调函数会在每一轮迭代后被调用用于控制训练节奏与记录信息。全部实现在 callback.py。6.1 early_stoppingearly_stopping(stopping_rounds, first_metric_onlyFalse, verboseTrue, min_delta0.0)触发早停的条件是验证分数至少每stopping_rounds轮须改善一次改善幅度不低于min_delta否则停止训练最佳轮次记录在模型的best_iteration属性中。要求至少提供一个验证集与一个评估指标多指标时默认检查全部设first_metric_onlyTrue可只检查第一个指标callback.py。min_delta4.0.0 起最小改善阈值可传单个 float所有指标共用或与指标总数等长的列表。注意使用boosting_typedart时该回调无效不会执行早停callback.py。日志输出默认走标准输出可通过register_logger()注册自定义 logger 接管。6.2 log_evaluationlog_evaluation(period1, show_stdvTrue)每period轮打印一次评估结果show_stdvTrue时在 cv 场景下同时显示标准差。period0表示不输出。6.3 record_evaluationrecord_evaluation(eval_result: Dict[str, Dict[str, List[Any]]])把每轮评估结果记录到传入的嵌套字典中外层键为数据集名内层键为指标名值为逐轮指标列表用于训练结束后绘制指标曲线或做其他分析。eval_result {} booster lgb.train( params, train_data, num_boost_round100, valid_sets[valid_data], callbacks[lgb.record_evaluation(eval_result)], ) # eval_result[valid][binary_logloss] 即为逐轮 loss 列表6.4 reset_parameterreset_parameter(**kwargs) # 每个参数可传定值或 callable在训练过程中动态调整参数例如学习率衰减def lr_decay(epoch): return 0.1 * (0.99 ** epoch) lgb.train( params, train_data, callbacks[lgb.reset_parameter(learning_ratelr_decay)], )参数值既可以是常量也可以是接收当前迭代轮数并返回新值的 callable。此外 callback.py 还定义了EarlyStopException在早停触发时抛出供上层捕获。七、Plotting训练结果的可视化绘图功能集中在 plotting.py依赖matplotlib树形图依赖graphviz。函数用途plot_importance(booster, importance_typesplit, max_num_featuresNone, figsizeNone, ...)绘制特征重要性条形图importance_type支持split默认分裂次数与gain信息增益见 plotting.pyplot_split_value_histogram(booster, feature, binsNone, figsizeNone, ...)绘制指定特征在全部树中的分裂值直方图plot_metric(booster, metricNone, dataset_namesNone, ...)绘制训练/验证过程中各指标随迭代轮数的变化曲线plot_tree(booster, tree_index0, figsizeNone, ...)以 matplotlib 方式渲染单棵树create_tree_digraph(booster, tree_index0, ...)返回 graphviz 的Digraph对象适合交互式与矢量输出import lightgbm as lgb import matplotlib.pyplot as plt # 特征重要性gain 视角 lgb.plot_importance(booster, importance_typegain, max_num_features10, figsize(8, 6)) plt.show() # 训练曲线先记录再绘图 lgb.plot_metric(booster, metricbinary_logloss) plt.show() # 树结构graphviz 矢量图 graph lgb.create_tree_digraph(booster, tree_index0) graph.render(tree_0, formatpng)配合record_evaluation记录的结果plot_metric是诊断过拟合与早停时机最常用的工具。八、register_logger自定义日志接管register_logger(logger) # logger 需提供 debug/info/warning/error 等方法register_logger用于将 LightGBM 的日志输出重定向到自定义 logger 对象如 Python 标准库logging.Logger同时保留 C 层原生日志的回调路径实现见 basic.py内部通过_log_callback把_LIB.LGBM_RegisterLogCallback注册的 C 日志转发到 Python logger。典型用法import logging import lightgbm as lgb logging.basicConfig(levellogging.INFO) lgb.register_logger(logging.getLogger(my_app))配合early_stopping(verboseTrue)与log_evaluation使用可将训练日志统一收编进应用自身的日志体系。九、快速上手清单与选用建议根据任务形态选择 API 层的速查表场景推荐 API理由原生控制、细粒度参数与回调Datasettrain/cv完整暴露全部原生参数支持feval/自定义 objective/init_model继续训练与 scikit-learn 生态Pipeline、GridSearchCV集成LGBMClassifier/LGBMRegressor/LGBMRanker标准 sklearn 接口参数名经过 sklearn 风格封装超大数据集的低内存流式读取SequenceDataset随机访问采样 批量范围读取避免全量载入内存分布式 / 大规模并行训练DaskLGBM*基于 Dask 集群自动分发数据与通信训练过程控制early_stopping/reset_parameter/log_evaluation/record_evaluation早停、学习率衰减、日志与指标记录结果可视化plot_importance/plot_tree/plot_metric/create_tree_digraph/plot_split_value_histogram特征重要性、树结构与训练曲线几条经过源码确认的实战要点Dataset构造即预处理分箱、类别合并、缺失值处理都在construct()时完成reference参数确保验证集复用训练集的分箱方式类别特征会被强制转 int32请使用从 0 开始的连续整数负值视为缺失train()返回的 Booster 默认不可再eval大模型训练可设keep_training_boosterTruedart 模式下early_stopping不生效需要同时评估训练集时可给cv()传eval_train_metricTrue需要保存各折模型时用return_cvboosterTrue获取CVBooster。更多端到端示例可直接参考仓库中的 examples/python-guide如 simple_example.py、sklearn_example.py、advanced_example.py对应的 Python 接口测试覆盖见 tests/python_package_testtest_basic.py、test_engine.py、test_sklearn.py、test_dask.py等可据此验证本文所述各接口的实际行为。【免费下载链接】LightGBMA fast, distributed, high performance gradient boosting (GBT, GBDT, GBRT, GBM or MART) framework based on decision tree algorithms, used for ranking, classification and many other machine learning tasks.项目地址: https://gitcode.com/GitHub_Trending/li/LightGBM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LightGBM Python API 完全指南：数据接口、训练引擎与 scikit-learn/Dask 生态全解析
LightGBM Python API 完全指南数据接口、训练引擎与 scikit-learn/Dask 生态全解析【免费下载链接】LightGBMA fast, distributed, high performance gradient boosting (GBT, GBDT, GBRT, GBM or MART) framework based on decision tree algorithms, used for ranking, classification and many other machine learning tasks.项目地址: https://gitcode.com/GitHub_Trending/li/LightGBM本指南以 docs/Python-API.rst 的 API 索引为骨架系统梳理 LightGBM Python 包的完整公开接口——从Dataset/Booster数据结构、train/cv训练引擎到 scikit-learn 风格模型、Dask 分布式接口、回调与可视化工具。读完你既能掌握原生 API 的底层调用逻辑也能直接上手高层封装并在源码层python-package/lightgbm确认每个接口的真实签名与默认值。一、LightGBM Python API 全景LightGBM 的 Python 包将所有公开符号统一从顶层lightgbm命名空间导出其完整清单定义在 python-package/lightgbm/init.py 的__all__中。按功能可划分为六大类分类公开 API实现模块数据结构Dataset、Booster、CVBooster、EvalResult、Sequencebasic.py、engine.py训练引擎train、cvengine.pyscikit-learn APILGBMModel、LGBMClassifier、LGBMRegressor、LGBMRankersklearn.pyDask API3.2.0 起DaskLGBMClassifier、DaskLGBMRegressor、DaskLGBMRankerdask.py回调early_stopping、log_evaluation、record_evaluation、reset_parametercallback.py可视化plot_importance、plot_split_value_histogram、plot_metric、plot_tree、create_tree_digraphplotting.py工具register_loggerbasic.py从源码结构看__init__.py通过三个try/except ImportError块分别对 sklearn、plotting、dask 子模块做可选导入python-package/lightgbm/init.py这意味着即使缺失scikit-learn、matplotlib或dask等可选依赖包的其余功能仍可正常加载——这是理解后续各 API 使用前置条件的重要线索。另外lightgbm.__version__直接读取包目录下的VERSION.txt文件python-package/lightgbm/init.py项目根目录的 VERSION.txt 即当前版本号来源。二、数据结构 API训练数据的底层抽象2.1 Dataset——LightGBM 的数据核心Dataset是 LightGBM Python 训练体系中一切数据的载体。其类文档明确指出basic.pyLightGBM does not train on raw data. It discretizes continuous features into histogram bins, tries to combine categorical features, and automatically handles missing and infinite values.即 LightGBM 并不直接消费原始数据而是在构造Dataset时完成三项关键预处理连续特征离散化为直方图分箱histogram bins、类别特征自动合并、缺失值与无穷值的自动处理。Dataset持有的是预处理后的另一种数据表示。Dataset.__init__的完整签名basic.py如下Dataset( data, # 必填 labelNone, # 标签 referenceNone, # 验证集引用训练集 weightNone, # 每个样本的权重须非负 groupNone, # 学习排序任务的 query/group 信息 init_scoreNone, # 初始分数可嵌套列表用于多分类 feature_nameauto, # 特征名DataFrame 输入时自动取列名 categorical_featureauto, # 类别特征DataFrame 的 unordered categorical 列自动识别 paramsNone, # 其他 Dataset 参数 free_raw_dataTrue, # 构造完内部 Dataset 后是否释放原始数据 positionNone, # 无偏学习排序任务中的位置信息 )data支持的数据源非常广泛字符串/pathlib.Path路径文本文件 CSV/TSV/LibSVM或 LightGBM Dataset 二进制文件、numpy 数组、pandas DataFrame、scipy.sparse 稀疏矩阵、Sequence及Sequence/numpy 数组的列表、pyarrow Table4.2.0 起、polars DataFrame4.7.0 起。label、weight、group、init_score、position同样各自兼容 numpy/pandas/pyarrow/polars 格式。类别特征的处理约束文档明确列出实操需特别注意类别值会被强制转换为 int32因此所有取值须小于 2147483647过大的取值会显著增加内存占用建议使用从 0 开始的连续整数所有负值会被视为缺失值输出结果不能对类别特征施加单调约束类别特征中的浮点数会向 0 取整。构造示例import lightgbm as lgb import pandas as pd df pd.DataFrame({ age: [23, 45, 12, 67], city: pd.Categorical([A, B, A, C]), # unordered categorical → 自动识别 }) label [0, 1, 1, 0] train_data lgb.Dataset( datadf, labellabel, categorical_featureauto, # city 列会被自动识别为类别特征 free_raw_dataTrue, )从实现看Dataset持有_handleC 层句柄与_predictor内部_InnerPredictor并通过train_set.construct()延迟构造底层对象——这一构造动作发生在Booster创建或显式调用construct()时basic.py。此外Dataset还实现了subset()、create_valid()、save_binary()、set_label()/get_label()、get_data()、get_params()等常用方法支持采样_create_sample_indices基于bin_construct_sample_cnt参数决定采样数量见 basic.py。2.2 Booster——模型的底层实体Booster是 LightGBM 模型的 Python 包装四种构造方式basic.pyBooster(paramsNone, train_setNone, model_fileNone, model_strNone)paramsBooster 参数字典train_set训练数据集传入即进入训练模式此时会先调用train_set.construct()并自动调用set_network()初始化分布式网络见 basic.pymodel_file从模型文件加载model_str从模型字符串加载。从实现细节看当train_set非空时basic.py若params中给出machines则假定用户要做分布式训练LightGBM 会自动推导num_machines机器数量、设置默认local_listen_port12400与listen_time_out120秒并建立 socket 网络。训练完成后Booster的best_iteration与best_score属性会记录最优轮次与对应分数。Booster核心方法包括update()单轮训练、predict()预测支持pred_early_stop、num_threads等参数、save_model()/model_to_string()、dump_model()、feature_importance()、eval()/eval_train()/eval_valid()、shrinkage()等。需要注意若train()返回时keep_training_boosterFalse返回对象会被转换为_InnerPredictor此时eval系列方法不可用详见下文 train 一节。2.3 EvalResult——结构化的评估结果EvalResult是一个NamedTuplebasic.py在 4.7.0 之前评估结果以普通元组形式返回如今以具名字段呈现EvalResult( dataset_name: str, # 数据集标识如 valid_0 metric_name: str, # 指标名如 rmse metric_value: float, # 指标值 maximize: bool, # 是否越大越好AUC 为 Truebinary error 为 False metric_std_dev: Optional[float] None, # 跨 fold 的指标标准差cv 聚合时使用 )其is_cv_result()方法通过metric_std_dev is not None判断结果是否来自cv()聚合basic.py。为保证向后兼容__len__()与__iter__()仍按旧元组行为工作非 cv 结果为 4 个字段cv 结果为 5 个字段。2.4 Sequence——流式数据访问接口Sequence是抽象基类3.3.0 起引入定义了一套通用的数据访问协议basic.py用于以流式、低内存方式喂入大规模数据。它要求子类实现__len__()返回总行数__getitem__(idx)支持三种索引——整数随机访问单行用于采样、切片范围访问用于批量读取构造 Dataset、整数列表仅在使用Dataset.subset()时需要可选属性batch_size类属性默认 4096即每批读取 4K 行。import numbers import numpy as np import lightgbm as lgb class MySequence(lgb.Sequence): batch_size 4096 def __init__(self, data): self.data data def __getitem__(self, idx): if isinstance(idx, numbers.Integral): return self.data[idx] elif isinstance(idx, slice): return np.stack([self.data[i] for i in range(idx.start, idx.stop)]) elif isinstance(idx, list): return np.array([self.data[i] for i in idx]) raise TypeError(fSequence index must be integer, slice or list, got {type(idx).__name__}) def __len__(self): return len(self.data) ds lgb.Dataset(MySequence(large_data), labellabels)其设计动机在类文档中写得很清楚随机访问使数据采样无需遍历全部数据范围访问使构造 Dataset 时无需一次性读入全部数据从而降低内存占用basic.py。这正是 LightGBM 支撑超大数据集的关键机制之一配合Dataset.subset()可在子集上构造训练数据而无需重读全量。三、训练 APItrain 与 cv3.1 train——核心训练入口train()位于 engine.py签名如下train( params, # dict训练参数优先级高于具名参数 train_set, # Dataset训练数据 num_boost_round100, # 提升迭代轮数 valid_setsNone, # list of Dataset训练过程中评估的数据 valid_namesNone, # list of strvalid_sets 的名称 fevalNone, # 自定义评估函数或函数列表 init_modelNone, # 模型文件路径或 Booster用于继续训练 keep_training_boosterFalse, # 是否保留可继续训练的 Booster callbacksNone, # 每轮迭代应用的回调函数列表 ) - Boosterfeval自定义评估函数的约定engine.py每个评估函数接收(preds, eval_data)两个参数返回(metric_name, metric_value, maximize)或这类元组的列表。其中preds在多分类任务下是形状为[n_samples, n_classes]的二维数组若使用了自定义目标函数preds返回的是变换前的原始边际raw margin而非二分类正类概率。若要忽略与 objective 对应的默认指标可在params中设置metricNone。init_model继续训练接受模型文件名或Booster实例用于继续训练已有模型。keep_training_booster的权衡engine.py为False默认时返回的 Booster 会被转换为_InnerPredictor因此无法再调用eval、eval_train、eval_valid方法当模型非常大、model_to_string内部转换导致内存错误时应设为True——此时返回的 Booster 仍可继续训练且_InnerPredictor依然可作为下次训练的init_model。自定义目标函数engine.py可将可调用对象直接传给params[objective]。该函数接收(preds, train_data)返回(grad, hess)——即损失函数关于预测值的一阶导梯度与二阶导Hessian。多分类任务下preds、grad、hess均为[n_samples, n_classes]的二维数组。从实现流程看engine.pytrain()会先对params做深拷贝处理objective为 callable 的情形将其替换为none并单独持有fobj再通过_choose_num_iterations协调num_boost_round与params[num_iterations]的关系engine.py并检查num_boost_round 0。此外early_stopping_round可以直接写进全局params生效。一个完整示例import lightgbm as lgb import numpy as np from sklearn.datasets import load_breast_cancer from sklearn.model_selection import train_test_split X, y load_breast_cancer(return_X_yTrue) X_train, X_valid, y_train, y_valid train_test_split(X, y, test_size0.2, random_state42) train_data lgb.Dataset(X_train, labely_train) valid_data lgb.Dataset(X_valid, labely_valid, referencetrain_data) params { objective: binary, metric: binary_logloss, learning_rate: 0.05, num_leaves: 31, verbose: -1, } booster lgb.train( paramsparams, train_settrain_data, num_boost_round200, valid_sets[valid_data], valid_names[valid], callbacks[ lgb.log_evaluation(period50), lgb.early_stopping(stopping_rounds20), ], ) print(best_iteration:, booster.best_iteration) print(best_score:, booster.best_score)3.2 cv——交叉验证cv()同样定义在 engine.pycv( params, train_set, num_boost_round100, foldsNone, # (train_idx, test_idx) 迭代器或 sklearn splitter优先级最高 nfold5, # 折数 stratifiedTrue, # 是否分层采样 shuffleTrue, # 切分前是否打乱 metricsNone, # 评估指标 fevalNone, # 自定义评估函数 init_modelNone, # 继续训练 fpreprocNone, # 每折数据预处理函数 seed0, # 随机种子 callbacksNone, eval_train_metricFalse, # 是否同时评估训练集 return_cvboosterFalse, # 是否返回 CVBooster 而非聚合指标 ) - Dict[str, Union[List[float], CVBooster]]folds参数优先于其他切分参数可传生成器/迭代器yield 每折的 train/test 索引也可传 scikit-learn 的 splitter 类对象需有split方法。返回值为字典默认返回各指标的mean/stdv列表键形如valid-rmse-mean、valid-rmse-stdv当return_cvboosterTrue时cvbooster键对应一个CVBooster实例。CVBoosterengine.py是cv()返回的多个折 Booster 的容器提供boost()每折继续训练一轮、predict()对每折预测并合并等方法可配合save_model/load_model复用。cv_result lgb.cv( paramsparams, train_settrain_data, num_boost_round200, nfold5, stratifiedTrue, seed42, callbacks[lgb.log_evaluation(period100)], ) print(rmse mean:, cv_result[valid-binary_logloss-mean][-1]) print(rmse stdv:, cv_result[valid-binary_logloss-stdv][-1])四、scikit-learn API与 sklearn 生态无缝衔接4.1 LGBMModel 与三个具体模型sklearn.py 中LGBMModel实现了 scikit-learn 风格接口fit/predict/predict_proba等而LGBMClassifier、LGBMRegressor、LGBMRanker分别继承自_LGBMClassifierBase、_LGBMRegressorBase与LGBMModel对应分类、回归、学习排序三大任务。LGBMModel.__init__的核心参数与默认值参数默认值说明boosting_typegbdtgbdt传统 GBDT、dart带 Dropout 的 MART、rf随机森林num_leaves31基学习器最大叶子数max_depth-1最大树深0表示不限制设为正值时建议同时令num_leaves 2^max_depthlearning_rate0.1学习率可在fit中通过reset_parameter回调调整n_estimators100要拟合的树的数量subsample_for_bin200000用于构造直方图分箱的样本数objectiveNone默认回归为regression、分类为binary/multiclass、排序为lambdarank也可传自定义目标函数class_weightNone{类别: 权重}字典或balancedmin_split_gain0.0分裂最小增益min_child_weight1e-3叶子最小二阶导之和min_child_samples20叶子最少样本数subsample/subsample_freq1.0/0行采样比例与频率0 表示不采样colsample_bytree1.0列采样比例reg_alpha/reg_lambda0.0/0.0L1 / L2 正则random_stateNone随机种子n_jobsNone并行线程数importance_typesplit特征重要性类型split分裂次数或gain信息增益用法示例from lightgbm import LGBMClassifier clf LGBMClassifier( n_estimators100, learning_rate0.1, num_leaves31, max_depth-1, objectivebinary, class_weightbalanced, n_jobs-1, ) clf.fit(X_train, y_train, eval_set[(X_valid, y_valid)], eval_metric[auc, binary_logloss], callbacks[lgb.early_stopping(20, verboseFalse)]) preds clf.predict(X_valid) proba clf.predict_proba(X_valid) print(feature importance (gain):, clf.feature_importances_)LGBMClassifier额外提供predict_proba、classes_等分类专属能力LGBMRanker通过group参数每组的样本数列表指定 query 分组用于学习排序任务。所有 sklearn 模型的fit均可接收eval_set、eval_metric、callbacks与原生 API 的行为保持一致。4.2 从 sklearn API 到原生 API 的桥接从实现结构看LGBMModel内部将 sklearn 风格参数映射为原生params字典后最终仍然调用train()完成训练见 sklearn.py 及fit中调用lgb.train(...)的逻辑。这意味着无论使用哪一层 API底层都是同一套原生训练引擎与 C 库只是参数组织方式不同——这是理解 sklearn 参数与原生参数一一对应关系如n_estimators↔num_iterations的根源。五、Dask API分布式训练开箱即用自 3.2.0 起LightGBM 提供 Dask 分布式接口dask.pyDaskLGBMClassifierdask.py继承LGBMClassifier与_DaskLGBMModelDaskLGBMRegressordask.py继承LGBMRegressorDaskLGBMRankerdask.py继承LGBMRanker。这些类接受 Dask DataFrame / Array 作为输入训练时通过_train_partdask.py把数据按分区分发到各 worker并自动分配网络端口_assign_open_ports_to_workersdask.py建立集群内通信预测则由_predict_partdask.py完成分区级推理。其分布式拓扑示意参见 docs/_static/images/dask-initial-setup.svg 与 docs/_static/images/dask-concat.svg。import dask.dataframe as dd from dask.distributed import Client from lightgbm import DaskLGBMClassifier client Client() # 启动本地分布式集群 ddf dd.from_pandas(pd.DataFrame(X), npartitions4) dseries dd.from_pandas(pd.Series(y), npartitions4) model DaskLGBMClassifier(n_estimators100) model.fit(ddf, dseries) preds model.predict(ddf)对应回归与排序任务可分别使用DaskLGBMRegressor、DaskLGBMRanker分布式场景下的用法与 sklearn API 保持一致仅输入变为 Dask 集合。Dask 接口的详细使用示例见 examples/python-guide/dask含binary-classification.py、regression.py、ranking.py、prediction.py、multiclass-classification.py等完整脚本。六、Callbacks训练过程的自定义钩子回调函数会在每一轮迭代后被调用用于控制训练节奏与记录信息。全部实现在 callback.py。6.1 early_stoppingearly_stopping(stopping_rounds, first_metric_onlyFalse, verboseTrue, min_delta0.0)触发早停的条件是验证分数至少每stopping_rounds轮须改善一次改善幅度不低于min_delta否则停止训练最佳轮次记录在模型的best_iteration属性中。要求至少提供一个验证集与一个评估指标多指标时默认检查全部设first_metric_onlyTrue可只检查第一个指标callback.py。min_delta4.0.0 起最小改善阈值可传单个 float所有指标共用或与指标总数等长的列表。注意使用boosting_typedart时该回调无效不会执行早停callback.py。日志输出默认走标准输出可通过register_logger()注册自定义 logger 接管。6.2 log_evaluationlog_evaluation(period1, show_stdvTrue)每period轮打印一次评估结果show_stdvTrue时在 cv 场景下同时显示标准差。period0表示不输出。6.3 record_evaluationrecord_evaluation(eval_result: Dict[str, Dict[str, List[Any]]])把每轮评估结果记录到传入的嵌套字典中外层键为数据集名内层键为指标名值为逐轮指标列表用于训练结束后绘制指标曲线或做其他分析。eval_result {} booster lgb.train( params, train_data, num_boost_round100, valid_sets[valid_data], callbacks[lgb.record_evaluation(eval_result)], ) # eval_result[valid][binary_logloss] 即为逐轮 loss 列表6.4 reset_parameterreset_parameter(**kwargs) # 每个参数可传定值或 callable在训练过程中动态调整参数例如学习率衰减def lr_decay(epoch): return 0.1 * (0.99 ** epoch) lgb.train( params, train_data, callbacks[lgb.reset_parameter(learning_ratelr_decay)], )参数值既可以是常量也可以是接收当前迭代轮数并返回新值的 callable。此外 callback.py 还定义了EarlyStopException在早停触发时抛出供上层捕获。七、Plotting训练结果的可视化绘图功能集中在 plotting.py依赖matplotlib树形图依赖graphviz。函数用途plot_importance(booster, importance_typesplit, max_num_featuresNone, figsizeNone, ...)绘制特征重要性条形图importance_type支持split默认分裂次数与gain信息增益见 plotting.pyplot_split_value_histogram(booster, feature, binsNone, figsizeNone, ...)绘制指定特征在全部树中的分裂值直方图plot_metric(booster, metricNone, dataset_namesNone, ...)绘制训练/验证过程中各指标随迭代轮数的变化曲线plot_tree(booster, tree_index0, figsizeNone, ...)以 matplotlib 方式渲染单棵树create_tree_digraph(booster, tree_index0, ...)返回 graphviz 的Digraph对象适合交互式与矢量输出import lightgbm as lgb import matplotlib.pyplot as plt # 特征重要性gain 视角 lgb.plot_importance(booster, importance_typegain, max_num_features10, figsize(8, 6)) plt.show() # 训练曲线先记录再绘图 lgb.plot_metric(booster, metricbinary_logloss) plt.show() # 树结构graphviz 矢量图 graph lgb.create_tree_digraph(booster, tree_index0) graph.render(tree_0, formatpng)配合record_evaluation记录的结果plot_metric是诊断过拟合与早停时机最常用的工具。八、register_logger自定义日志接管register_logger(logger) # logger 需提供 debug/info/warning/error 等方法register_logger用于将 LightGBM 的日志输出重定向到自定义 logger 对象如 Python 标准库logging.Logger同时保留 C 层原生日志的回调路径实现见 basic.py内部通过_log_callback把_LIB.LGBM_RegisterLogCallback注册的 C 日志转发到 Python logger。典型用法import logging import lightgbm as lgb logging.basicConfig(levellogging.INFO) lgb.register_logger(logging.getLogger(my_app))配合early_stopping(verboseTrue)与log_evaluation使用可将训练日志统一收编进应用自身的日志体系。九、快速上手清单与选用建议根据任务形态选择 API 层的速查表场景推荐 API理由原生控制、细粒度参数与回调Datasettrain/cv完整暴露全部原生参数支持feval/自定义 objective/init_model继续训练与 scikit-learn 生态Pipeline、GridSearchCV集成LGBMClassifier/LGBMRegressor/LGBMRanker标准 sklearn 接口参数名经过 sklearn 风格封装超大数据集的低内存流式读取SequenceDataset随机访问采样 批量范围读取避免全量载入内存分布式 / 大规模并行训练DaskLGBM*基于 Dask 集群自动分发数据与通信训练过程控制early_stopping/reset_parameter/log_evaluation/record_evaluation早停、学习率衰减、日志与指标记录结果可视化plot_importance/plot_tree/plot_metric/create_tree_digraph/plot_split_value_histogram特征重要性、树结构与训练曲线几条经过源码确认的实战要点Dataset构造即预处理分箱、类别合并、缺失值处理都在construct()时完成reference参数确保验证集复用训练集的分箱方式类别特征会被强制转 int32请使用从 0 开始的连续整数负值视为缺失train()返回的 Booster 默认不可再eval大模型训练可设keep_training_boosterTruedart 模式下early_stopping不生效需要同时评估训练集时可给cv()传eval_train_metricTrue需要保存各折模型时用return_cvboosterTrue获取CVBooster。更多端到端示例可直接参考仓库中的 examples/python-guide如 simple_example.py、sklearn_example.py、advanced_example.py对应的 Python 接口测试覆盖见 tests/python_package_testtest_basic.py、test_engine.py、test_sklearn.py、test_dask.py等可据此验证本文所述各接口的实际行为。【免费下载链接】LightGBMA fast, distributed, high performance gradient boosting (GBT, GBDT, GBRT, GBM or MART) framework based on decision tree algorithms, used for ranking, classification and many other machine learning tasks.项目地址: https://gitcode.com/GitHub_Trending/li/LightGBM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考