Python 包介绍

本文档提供了 xgboost Python 包的基本演练。Python 包由 3 种不同的接口组成，包括原生接口、scikit-learn 接口和 dask 接口。有关 dask 接口的介绍，请参阅 使用 Dask 的分布式 XGBoost。

其他有用链接列表

目录

安装 XGBoost

要安装 XGBoost，请按照 安装指南 中的说明进行操作。

要验证您的安装，请在 Python 中运行以下代码

import xgboost as xgb

数据接口

XGBoost Python 模块能够加载多种不同类型的数据格式，包括 CPU 和 GPU 数据结构。有关支持的数据类型的完整列表，请参考 XGBoost 各类函数支持的数据结构。有关文本输入格式的详细说明，请访问 DMatrix 的文本输入格式。

输入数据存储在 DMatrix 对象中。对于 sklearn 估计器接口，根据选择的算法和输入，会创建一个 DMatrix 或 QuantileDMatrix 对象，详情请参阅 sklearn API 参考。这里我们将使用 DMatrix 来演示一些基本的输入类型。

  • 将 NumPy 数组加载到 DMatrix 中

    data = np.random.rand(5, 10)  # 5 entities, each contains 10 features
label = np.random.randint(2, size=5)  # binary target
dtrain = xgb.DMatrix(data, label=label)

  • 将 scipy.sparse 数组加载到 DMatrix 中

    csr = scipy.sparse.csr_matrix((dat, (row, col)))
dtrain = xgb.DMatrix(csr)

  • 将 Pandas 数据帧加载到 DMatrix 中

    data = pandas.DataFrame(np.arange(12).reshape((4,3)), columns=['a', 'b', 'c'])
label = pandas.DataFrame(np.random.randint(2, size=4))
dtrain = xgb.DMatrix(data, label=label)

  • 将 DMatrix 保存到 XGBoost 二进制文件会使加载更快

    dtrain = xgb.DMatrix('train.svm.txt?format=libsvm')
dtrain.save_binary('train.buffer')

  • 在 DMatrix 构造函数中，缺失值可以被默认值替换

    dtrain = xgb.DMatrix(data, label=label, missing=np.NaN)

  • 需要时可以设置权重

    w = np.random.rand(5, 1)
dtrain = xgb.DMatrix(data, label=label, missing=np.NaN, weight=w)

执行排序任务时，权重数量应等于组数。

  • 将 LIBSVM 文本文件或 XGBoost 二进制文件加载到 DMatrix 中

    dtrain = xgb.DMatrix('train.svm.txt?format=libsvm')
dtest = xgb.DMatrix('test.svm.buffer')

    XGBoost 中的解析器功能有限。使用 Python 接口时，建议使用 sklearn 的 load_svmlight_file 或其他类似工具，而非 XGBoost 内置的解析器。

  • 将 CSV 文件加载到 DMatrix 中

    # label_column specifies the index of the column containing the true label
dtrain = xgb.DMatrix('train.csv?format=csv&label_column=0')
dtest = xgb.DMatrix('test.csv?format=csv&label_column=0')

    XGBoost 中的解析器功能有限。使用 Python 接口时，建议使用 pandas 的 read_csv 或其他类似工具，而非 XGBoost 内置的解析器。

XGBoost 各类函数支持的数据结构

标记

  • T：支持。

  • F：不支持。

  • NE：用例的无效类型。例如，pd.Series 不能作为多目标标签。

  • NPA：借助 numpy 数组支持。

  • AT：借助 arrow table 支持。

  • CPA：借助 cupy 数组支持。

  • SciCSR：借助 scripy 稀疏 CSR 支持。转换为 scipy CSR 可能可行也可能不可行。如果转换失败，将引发类型错误。

  • FF：如果请求，我们期待在近期支持它。

  • empty：待填充。

表头

  • X 表示预测变量矩阵。

  • 元信息：标签、权重等。

  • 多标签：用于多目标的 2 维标签。

  • 其他：我们未在此明确列出的任何其他内容，包括 lil、dia、bsr 等格式。XGBoost 将尝试将其转换为 scipy csr。

支持矩阵

名称

DMatrix X

QuantileDMatrix X

Sklearn X

元信息

原地预测

多标签

numpy.ndarray

T

T

T

T

T

T

scipy.sparse.csr

T

T

T

NE

T

F

scipy.sparse.csc

T

F

T

NE

F

F

scipy.sparse.coo

SciCSR

F

SciCSR

NE

F

F

uri

T

F

F

F

NE

F

list

NPA

NPA

NPA

NPA

NPA

T

tuple

NPA

NPA

NPA

NPA

NPA

T

pandas.DataFrame

NPA

NPA

NPA

NPA

NPA

NPA

pandas.Series

NPA

NPA

NPA

NPA

NPA

NE

cudf.DataFrame

T

T

T

T

T

T

cudf.Series

T

T

T

T

FF

NE

cupy.ndarray

T

T

T

T

T

T

torch.Tensor

T

T

T

T

T

T

dlpack

CPA

CPA

CPA

FF

FF

modin.DataFrame

NPA

FF

NPA

NPA

FF

modin.Series

NPA

FF

NPA

NPA

FF

pyarrow.Table

T

T

T

T

T

T

polars.DataFrame

AT

AT

AT

AT

AT

AT

polars.LazyFrame (警告)

AT

AT

AT

AT

AT

AT

polars.Series

AT

AT

AT

AT

AT

NE

__array__

NPA

F

NPA

NPA

H

其他

SciCSR

F

F

F

polars LazyFrame.collect 支持多种配置，包括查询引擎的选择和类型强制转换。XGBoost 仅使用默认参数。请在将其传递给 XGBoost 之前运行 collect 以获取 DataFrame，从而更好地控制行为。

设置参数

XGBoost 可以使用列表对或字典来设置 参数。例如

  • Booster 参数

    param = {'max_depth': 2, 'eta': 1, 'objective': 'binary:logistic'}
param['nthread'] = 4
param['eval_metric'] = 'auc'

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

    param['eval_metric'] = ['auc', 'ams@0']

# alternatively:
# plst = param.items()
# plst += [('eval_metric', 'ams@0')]

  • 指定验证集以观察性能

    evallist = [(dtrain, 'train'), (dtest, 'eval')]

训练

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

num_round = 10
bst = xgb.train(param, dtrain, num_round, evallist)

训练后，模型可以保存。

bst.save_model('0001.model')

模型及其特征映射也可以转储到文本文件。

# dump model
bst.dump_model('dump.raw.txt')
# dump model with feature map
bst.dump_model('dump.raw.txt', 'featmap.txt')

已保存的模型可以按如下方式加载

bst = xgb.Booster({'nthread': 4})  # init model
bst.load_model('model.bin')  # load model data

xgboost.Booster 中的 update 和 boost 等方法仅用于内部使用。包装函数 xgboost.train 执行一些预配置，包括设置缓存和一些其他参数。

早停

如果您有验证集，可以使用早停来找到最优的 boosting 轮数。早停至少需要 evals 中有一个集合。如果多于一个，它将使用最后一个。

train(..., evals=evals, early_stopping_rounds=10)

模型将训练直到验证分数不再提高。验证错误需要每 early_stopping_rounds 轮至少下降一次才能继续训练。

如果发生早停，模型将有两个额外的字段：bst.best_score, bst.best_iteration。请注意，xgboost.train() 将返回最后一轮的模型，而不是最优的模型。

这适用于需要最小化的指标（RMSE, log loss 等）和需要最大化的指标（MAP, NDCG, AUC）。请注意，如果您指定了多个评估指标，param['eval_metric'] 中的最后一个指标将用于早停。

预测

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

# 7 entities, each contains 10 features
data = np.random.rand(7, 10)
dtest = xgb.DMatrix(data)
ypred = bst.predict(dtest)

如果训练期间启用了早停，您可以使用 bst.best_iteration 从最优迭代获取预测结果。

ypred = bst.predict(dtest, iteration_range=(0, bst.best_iteration + 1))

绘图

您可以使用绘图模块来绘制重要性图和输出树。

要绘制重要性图，请使用 xgboost.plot_importance()。此函数需要安装 matplotlib。

xgb.plot_importance(bst)

要通过 matplotlib 绘制输出树，请使用 xgboost.plot_tree()，并指定目标树的序号。此函数需要 graphviz 和 matplotlib。

xgb.plot_tree(bst, num_trees=2)

使用 IPython 时，可以使用 xgboost.to_graphviz() 函数，该函数将目标树转换为 graphviz 实例。graphviz 实例会在 IPython 中自动渲染。

xgb.to_graphviz(bst, num_trees=2)

Scikit-Learn 接口

XGBoost 为一些预定义的模型（包括回归、分类和排序）提供了易于使用的 scikit-learn 接口。更多信息请参阅 使用 Scikit-Learn 估计器接口。

# Use "hist" for training the model.
reg = xgb.XGBRegressor(tree_method="hist", device="cuda")
# Fit the model using predictor X and response y.
reg.fit(X, y)
# Save model into JSON format.
reg.save_model("regressor.json")

用户在需要时仍然可以访问底层的 booster 模型

booster: xgb.Booster = reg.get_booster()