LightGBM Python 包入门指南:从数据接口到训练、调参与预测的完整实践 📅 发布时间:2026/9/13 14:52:42 👁 浏览次数: LightGBM Python 包入门指南从数据接口到训练、调参与预测的完整实践【免费下载链接】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本文是基于 LightGBM 仓库 docs/Python-Intro.rst 编写的 Python 包实战指南系统讲解 Python 生态下 LightGBM 的核心用法数据如何装载进Dataset、参数如何配置、模型如何训练与预测以及早停、交叉验证、内存优化等实战要点。读完本文你将掌握一套可直接复制运行的最小工作流并理解其背后的源码级实现原理能够独立完成从原始数据到可部署模型的完整链路。安装与验证官方推荐通过 pip 安装 LightGBMpip install lightgbm更详细的构建与安装说明可参考 python-package。安装完成后在 Python 中导入即可验证环境是否就绪import lightgbm as lgb仓库内的可执行示例位于 examples/python-guide运行这些示例还需要scikit-learn、pandas、matplotlib仅绘图示例和scipy仅逻辑回归示例pip install scikit-learn pandas matplotlib scipy -U python simple_example.py数据接口Dataset 是一切训练的起点LightGBM 不会直接在原始数据上训练。从源码 python-package/lightgbm/basic.py 中的Dataset类文档可以看到LightGBM 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. This class handles that preprocessing, and holds that alternative representation of the input data.也就是说Dataset负责完成连续特征分箱直方图化、类别特征合并、缺失值与无穷值处理等全部预处理并持有数据的内部表示训练过程中真正使用的是这份内部表示而不是原始内存对象。支持的数据源Dataset构造函数basic.py中_LGBM_TrainDataType类型定义python-package/lightgbm/basic.py支持以下输入形式LibSVM零基索引/ TSV / CSV 格式的文本文件NumPy 2D 数组、SciPy 稀疏矩阵pandas DataFrame、polars DataFrame、pyarrow TableLightGBM 二进制文件LightGBMSequence对象可传入单个或多个下面逐一给出最小可运行示例。本文示例依赖numpy请先导入import numpy as np从 LibSVM 文本文件或 LightGBM 二进制文件加载train_data lgb.Dataset(train.svm.bin)当data参数是字符串或pathlib.Path时它被解释为文本文件CSV/TSV/LibSVM或 LightGBM Dataset 二进制文件的路径见 python-package/lightgbm/basic.py。从 NumPy 数组加载rng np.random.default_rng() data rng.uniform(size(500, 10)) # 500 个样本每个样本 10 个特征 label rng.integers(low0, high2, size(500, )) # 二分类标签 train_data lgb.Dataset(data, labellabel)从 SciPy 稀疏矩阵加载import scipy csr scipy.sparse.csr_matrix((dat, (row, col))) train_data lgb.Dataset(csr)稀疏矩阵适用于高维稀疏场景如 CTR 预估可以显著降低内存占用。用 Sequence 接口读取超大文件HDF5 示例对于无法一次性载入内存的大规模数据可以自定义实现lgb.Sequence接口。该抽象基类定义在 python-package/lightgbm/basic.py要求子类实现两个抽象方法__getitem__(self, idx)支持整数索引随机访问单行、切片批量读取多行和列表索引__len__(self)返回总行数同时提供类属性batch_size 4096默认每批读取 4K 行可在子类中覆盖。以下示例用h5py包装 HDF5 数据集与 examples/python-guide/dataset_from_multi_hdf5.py 中的HDFSequence实现一致import h5py class HDFSequence(lgb.Sequence): def __init__(self, hdf_dataset, batch_size): self.data hdf_dataset self.batch_size batch_size def __getitem__(self, idx): return self.data[idx] def __len__(self): return len(self.data) f h5py.File(train.hdf5, r) train_data lgb.Dataset(HDFSequence(f[X], 8192), labelf[Y][:])使用Sequence接口有三个核心收益随机访问式采样数据采样不必遍历整个数据集只需按索引取行批量读取、按需加载构造Dataset时按批读取避免一次性把全部数据读入内存支持多数据文件可以把多个Sequence如多个 HDF5 文件组合起来构造一个Dataset。dataset_from_multi_hdf5.py还演示了如何把多个 HDF5 文件组合成Dataset将多个HDFSequence放入列表传入lgb.Dataset并通过params{bin_construct_sample_cnt: 200000, max_bin: 255}控制分箱采样数量与最大分箱数。该示例对 HDF5 的 chunk 大小做了针对性优化——由于采样是随机访问chunk 过大时一次 I/O 会读入整块数据因此 chunk 应与batch_size匹配且数据按行主序存储以减少拷贝。Sequence的完整 API 文档见 docs/Python-API.rst 的 Data Structure API 一节。保存为二进制文件加速加载将Dataset保存为 LightGBM 二进制文件后续加载会显著更快train_data lgb.Dataset(train.svm.txt) train_data.save_binary(train.bin)创建验证集验证集必须与训练集对齐特征顺序、分箱方式一致。有两种方式validation_data train_data.create_valid(validation.svm)或显式传入referencevalidation_data lgb.Dataset(validation.svm, referencetrain_data)源码层面reference的作用是让验证集复用训练集的分箱与预处理信息从而保证评估口径一致。特征名与类别特征train_data lgb.Dataset(data, labellabel, feature_name[c1, c2, c3], categorical_feature[c3])LightGBM 支持直接使用类别特征输入无需做 one-hot 编码官方文档明确说明其速度约为 one-hot 方案的 8 倍。构造Dataset前需将类别特征转换为int类型。从Dataset的 docstringpython-package/lightgbm/basic.py可进一步了解类别特征的底层规则所有类别值会被转换为 int32因此需小于 int32 最大值2147483647过大的取值会消耗更多内存建议使用从 0 开始的连续整数负数会被当作缺失值处理浮点型类别值会向 0 取整类别特征不支持单调约束。categorical_feature支持按索引整数列表或按名称字符串列表需同时指定feature_name指定当输入为 pandas DataFrame 且参数为auto时会自动识别 pandas 的无序类别列。advanced_example.py中categorical_feature[21]即为按索引指定的实战用法。样本权重、初始分数与排序分组权重既可以在构造时传入也可以在构造后设置rng np.random.default_rng() w rng.uniform(size(500, )) train_data lgb.Dataset(data, labellabel, weightw)train_data lgb.Dataset(data, labellabel) rng np.random.default_rng() w rng.uniform(size(500, )) train_data.set_weight(w)此外还可使用Dataset.set_init_score()设置初始分数如继续训练或迁移学习的先验预测以及Dataset.set_group()为排序任务learning-to-rank设置 group/query 数据。group的语义是每个查询下的文档数量例如 100 个文档、group[10, 20, 40, 10, 10, 10]表示 6 个查询组前 10 条记录属于第一组、第 11-30 条属于第二组依此类推见 python-package/lightgbm/basic.py。内存高效用法Dataset只保存离散化后的分箱数据内存效率很高但 NumPy / pandas 原始对象本身占用较大。若关注内存占用可按以下顺序操作构造Dataset时设置free_raw_dataTrue默认即为True构造内部 Dataset 后立即释放原始数据构造完成后显式将raw_data置为None调用gc触发垃圾回收。需要说明的是advanced_example.py中刻意设置free_raw_dataFalse是为了演示复用原始数据构造新的 Dataset的场景——这属于需要保留原始数据的特例。设置参数LightGBM 使用 Python 字典配置参数完整参数清单见 docs/Parameters.rst。示例param {num_leaves: 31, objective: binary} param[metric] aucmetric也支持列表形式同时指定多个评估指标param[metric] [auc, binary_logloss]仓库示例中更完整的参数配置见 examples/python-guide/simple_example.pyparams { boosting_type: gbdt, objective: regression, metric: {l2, l1}, num_leaves: 31, learning_rate: 0.05, feature_fraction: 0.9, bagging_fraction: 0.8, bagging_freq: 5, verbose: 0, }其中feature_fraction控制每轮迭代随机采样的特征比例缓解过拟合、加速训练bagging_fraction与bagging_freq控制 bagging 采样的比例与频率。更系统的调参思路可参考 docs/Parameters-Tuning.rst。训练模型训练只需参数列表与数据集num_round 10 bst lgb.train(param, train_data, num_round, valid_sets[validation_data])训练完成后可以保存模型文本格式bst.save_model(model.txt)也可以导出为 JSON 格式以便程序化解析advanced_example.py中还演示了将 JSON 写入文件的完整做法json_model bst.dump_model()加载已保存的模型bst lgb.Booster(model_filemodel.txt) # init model交叉验证无需手动划分数据直接进行 5 折交叉验证lgb.cv(param, train_data, num_round, nfold5)cv返回每一轮的评估结果可用于判断迭代轮数对泛化性能的影响。早停找到最优迭代轮数配合验证集使用早停可以自动确定最优的 boosting 轮数。早停要求valid_sets中至少有一个验证集若传入多个则除训练数据外的全部验证集都会参与早停判断bst lgb.train(param, train_data, num_round, valid_setsvalid_sets, callbacks[lgb.early_stopping(stopping_rounds5)]) bst.save_model(model.txt, num_iterationbst.best_iteration)工作机理与关键细节模型会一直训练到验证分数不再改善为止验证分数必须至少每stopping_rounds轮改善一次否则停止最优迭代轮次记录在bst.best_iteration字段中且开启早停后train()返回的模型本身就来自最优迭代早停对最小化类指标L2、log loss 等和最大化类指标NDCG、AUC 等均适用若同时指定多个评估指标默认所有指标都会参与早停判断若只想依据第一个指标判断可向early_stopping构造函数传入first_metric_onlyTrue。simple_example.py展示了早停配合gbm.predict(X_test, num_iterationgbm.best_iteration)的完整回归流程。预测训练好或加载好的模型可以直接对数据预测# 7 个样本每个样本 10 个特征 rng np.random.default_rng() data rng.uniform(size(7, 10)) ypred bst.predict(data)训练期间启用了早停时可用bst.best_iteration锁定最优迭代进行预测ypred bst.predict(data, num_iterationbst.best_iteration)advanced_example.py还演示了预测相关的其他细节从文件加载模型后只能以最优迭代或保存时指定的迭代预测而通过pickle序列化的模型可以指定任意迭代次数预测。此外该示例还展示了gbm.feature_name()、gbm.feature_importance()获取特征名与特征重要度以及通过init_model参数接受模型文件路径或Booster对象实现继续训练。进阶sklearn 接口与 Dask 分布式训练除原生train/cvAPI 外Python 包还提供与 scikit-learn 完全兼容的封装见 docs/Python-API.rst 的 Scikit-learn API 一节LGBMModel、LGBMClassifier、LGBMRegressor、LGBMRanker。示例 examples/python-guide/sklearn_example.py 演示了其典型用法gbm lgb.LGBMRegressor(num_leaves31, learning_rate0.05, n_estimators20) gbm.fit(X_train, y_train, eval_X(X_test,), eval_y(y_test,), eval_metricl1, callbacks[lgb.early_stopping(5)]) y_pred gbm.predict(X_test, num_iterationgbm.best_iteration_)sklearn 接口天然支持自定义评估函数签名f(y_true, y_pred) - (name, value, is_higher_better)、GridSearchCV网格搜索以及feature_importances_属性。对大规模分布式训练可以进一步使用 Dask API自 3.2.0 版本起提供DaskLGBMClassifier、DaskLGBMRegressor、DaskLGBMRanker对应示例见 examples/python-guide/dask。完整的 API 目录Data Structure API、Training API、Scikit-learn API、Dask API、Callbacks、Plotting、Utilities均可参考 docs/Python-API.rst。总结一条完整的 Python 工作流把上述内容串起来一个典型流程如下装载数据从文本文件、NumPy/SciPy、DataFrame 或Sequence构造lgb.Dataset需要时指定feature_name、categorical_feature、weight划分验证用create_valid或reference创建与训练集对齐的验证集配置参数用字典设置objective、metric、num_leaves、learning_rate等见 docs/Parameters.rst训练与早停lgb.train(..., callbacks[lgb.early_stopping(...)])用best_iteration保存最优模型评估与部署bst.predict()预测save_model/dump_model持久化lgb.Booster(model_file...)重新加载。至此你已经掌握了 LightGBM Python 包从数据接口到预测部署的全链路能力。仓库中的 examples/python-guide 提供了可直接运行的完整示例基础流程simple_example.py、进阶技巧advanced_example.py、sklearn 接口sklearn_example.py、多 HDF5 文件dataset_from_multi_hdf5.py、Dask 分布式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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考