Python 包介绍

本文档对 LightGBM Python 包进行了基本介绍。

其他有用链接列表

安装

安装 LightGBM 的首选方式是使用 pip

pip install lightgbm

请参考 Python-package 文件夹中的详细安装指南。

要验证您的安装，请尝试在 Python 中 import lightgbm

import lightgbm as lgb

数据接口

LightGBM Python 模块可以加载来自以下格式的数据

LibSVM（零基）/ TSV / CSV 格式文本文件
NumPy 二维数组、pandas DataFrame、H2O DataTable 的 Frame（已弃用）、SciPy 稀疏矩阵
LightGBM 二进制文件
LightGBM Sequence 对象

数据存储在 Dataset 对象中。

本页中的许多示例使用了 numpy 的功能。要运行这些示例，请务必在您的会话中导入 numpy。

import numpy as np

将 LibSVM（零基）文本文件或 LightGBM 二进制文件加载到 Dataset 中

train_data = lgb.Dataset('train.svm.bin')

将 numpy 数组加载到 Dataset 中

rng = np.random.default_rng()
data = rng.uniform(size=(500, 10))  # 500 entities, each contains 10 features
label = rng.integers(low=0, high=2, size=(500, ))  # binary target
train_data = lgb.Dataset(data, label=label)

将 scipy.sparse.csr_matrix 数组加载到 Dataset 中

import scipy
csr = scipy.sparse.csr_matrix((dat, (row, col)))
train_data = lgb.Dataset(csr)

从 Sequence 对象加载

我们可以实现 Sequence 接口来读取二进制文件。以下示例展示了使用 h5py 读取 HDF5 文件。

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), label=f['Y'][:])

使用 Sequence 接口的特性

数据采样使用随机访问，因此无需遍历整个数据集
批量读取数据，从而在构建 Dataset 对象时节省内存
支持从多个数据文件创建 Dataset

请参考 Sequence API 文档。

dataset_from_multi_hdf5.py 是一个详细示例。

将 Dataset 保存到 LightGBM 二进制文件将使加载更快

train_data = lgb.Dataset('train.svm.txt')
train_data.save_binary('train.bin')

创建验证数据

validation_data = train_data.create_valid('validation.svm')

或者

validation_data = lgb.Dataset('validation.svm', reference=train_data)

在 LightGBM 中，验证数据应与训练数据对齐。

特定的特征名称和类别特征

train_data = lgb.Dataset(data, label=label, feature_name=['c1', 'c2', 'c3'], categorical_feature=['c3'])

LightGBM 可以直接使用类别特征作为输入。它不需要转换为独热编码，并且比独热编码快得多（约快 8 倍）。

注意：在构建 Dataset 之前，应将类别特征转换为 int 类型。

需要时可以设置权重

rng = np.random.default_rng()
w = rng.uniform(size=(500, ))
train_data = lgb.Dataset(data, label=label, weight=w)

或者

train_data = lgb.Dataset(data, label=label)
rng = np.random.default_rng()
w = rng.uniform(size=(500, ))
train_data.set_weight(w)

并且可以使用 Dataset.set_init_score() 设置初始分数，以及 Dataset.set_group() 为排序任务设置组/查询数据。

内存高效使用

LightGBM 中的 Dataset 对象非常节省内存，只需保存离散的 bin。然而，Numpy/Array/Pandas 对象消耗内存较多。如果担心内存消耗，可以通过以下方式节省内存：

构建 Dataset 时设置 free_raw_data=True（默认为 True）
在 Dataset 构建完成后显式设置 raw_data=None
调用 gc

设置参数

LightGBM 可以使用字典来设置参数。例如

模型参数

param = {'num_leaves': 31, 'objective': 'binary'}
param['metric'] = 'auc'

您还可以指定多个评估指标

param['metric'] = ['auc', 'binary_logloss']

训练

训练模型需要参数列表和数据集

num_round = 10
bst = lgb.train(param, train_data, num_round, valid_sets=[validation_data])

训练后，模型可以保存

bst.save_model('model.txt')

训练好的模型也可以转储为 JSON 格式

json_model = bst.dump_model()

保存的模型可以加载

bst = lgb.Booster(model_file='model.txt')  # init model

交叉验证 (CV)

使用 5 折交叉验证进行训练

lgb.cv(param, train_data, num_round, nfold=5)

提前停止

如果您有验证集，可以使用提前停止来找到最优的 boosting 轮数。提前停止需要 valid_sets 中至少有一个集合。如果多于一个，将使用除训练数据外的所有集合。

bst = lgb.train(param, train_data, num_round, valid_sets=valid_sets, callbacks=[lgb.early_stopping(stopping_rounds=5)])
bst.save_model('model.txt', num_iteration=bst.best_iteration)

模型将一直训练，直到验证分数不再提高。验证分数需要在至少每 stopping_rounds 轮训练中有所提高才能继续训练。

如果通过设置 early_stopping 回调启用提前停止逻辑，表现最佳的迭代轮数索引将保存在 best_iteration 字段中。请注意，train() 将返回最佳迭代的模型。

这适用于需要最小化（如 L2、对数损失等）和最大化（如 NDCG、AUC 等）的指标。请注意，如果指定多个评估指标，所有指标都将用于提前停止。但是，可以通过在 early_stopping 回调构造函数中传递 first_metric_only=True 来更改此行为，使 LightGBM 只检查第一个指标进行提前停止。

预测

训练或加载的模型可以在数据集上进行预测

# 7 entities, each contains 10 features
rng = np.random.default_rng()
data = rng.uniform(size=(7, 10))
ypred = bst.predict(data)

如果在训练期间启用了提前停止，可以使用 bst.best_iteration 获取最佳迭代的预测结果

ypred = bst.predict(data, num_iteration=bst.best_iteration)