Python 包介绍

本文档提供了 xgboost Python 包的基本概述。Python 包由三种不同的接口组成，包括原生接口、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 数组的支持下提供帮助。
CPA: 在cupy数组的帮助下提供支持。
SciCSR: 在 scripy 稀疏 CSR 的帮助下提供支持。转换为 scipy CSR 可能是也可能是不可能的。如果转换失败，则引发类型错误。
FF: 如果需要，我们可以期待在不久的将来获得它的支持。
empty: 待填写。

表格标题

X 表示预测矩阵。
元信息：标签、权重等。
多标签：多目标的二维标签。
其他：我们未在此明确列出的任何内容，包括 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
列表	NPA	NPA	NPA	NPA	NPA	T
元组	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
datatable.Frame	T	FF		NPA	FF
datatable.Table	T	FF		NPA	FF
modin.DataFrame	NPA	FF	NPA	NPA	FF
modin.Series	NPA	FF	NPA	NPA	FF
pyarrow.Table	NPA	NPA	NPA	NPA	NPA	NPA
__array__	NPA	F	NPA	NPA	H
其他	SciCSR	F		F	F

设置参数

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

助推器参数

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 进行了一些预配置，包括设置缓存和其他参数。

早停

如果你有一个验证集，你可以使用早停法来找到最佳的提升轮数。早停法至少需要一个在 evals 中的集合。如果有多个，它将使用最后一个。

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

模型将训练直到验证分数停止提高。验证错误需要至少每 early_stopping_rounds 减少一次以继续训练。

如果发生提前停止，模型将有两个额外的字段：bst.best_score，bst.best_iteration。注意，xgboost.train() 将返回最后一个迭代的模型，而不是最佳模型。

这适用于最小化的指标（如 RMSE、对数损失等）和最大化的指标（如 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: xgb.Booster = reg.get_booster()