DMatrix 的文本输入格式

在此，我们将简要介绍 XGBoost 的文本输入格式。但是，对于可以使用 Python 或 R 等受支持语言环境的用户，建议使用该生态系统中的数据解析器。例如，sklearn.datasets.load_svmlight_file()。

基本输入格式

XGBoost 当前支持两种文本格式用于摄取数据：LIBSVM 和 CSV。本文档的其余部分将描述 LIBSVM 格式。（有关 CSV 格式的描述，请参见 这篇维基百科文章。）请注意，XGBoost 不理解文件扩展名，也不尝试猜测文件格式，因为 LIBSVM 或 CSV 的文件扩展名没有普遍一致的约定。相反，它采用 URI 格式来指定精确的输入文件类型。例如，如果您提供一个 csv 文件 ./data.train.csv 作为输入，XGBoost 将盲目地使用默认的 LIBSVM 解析器来处理它并产生解析错误。相反，用户需要提供一个 URI，其形式为 train.csv?format=csv 或 train.csv?format=libsvm。对于外部内存输入，URI 应类似于 train.csv?format=csv#dtrain.cache。另请参见数据接口和使用 XGBoost 外部内存版本。

对于训练或预测，XGBoost 接受一个实例文件，其格式如下：

train.txt
1 101:1.2 102:0.03
0 1:2.1 10001:300 10002:400
0 0:1.3 1:0.3
1 0:0.01 1:0.3
0 0:0.2 1:0.3

每行代表一个实例，第一行中的“1”是实例标签，“101”和“102”是特征索引，“1.2”和“0.03”是特征值。在二分类情况下，“1”用于表示正样本，“0”用于表示负样本。我们也支持使用 [0,1] 之间的概率值作为标签，以表示实例为正的概率。

附加信息的辅助文件

注意：以下所有信息仅适用于单节点版本的软件包。如果您想使用多个节点进行分布式训练，请跳至将附加信息嵌入到 LIBSVM 文件中一节。

组输入格式

对于排序任务，XGBoost 支持组输入格式。在排序任务中，实例在实际场景中被分类为查询组。例如，在学习对网页进行排序的场景中，网页实例按其查询进行分组。XGBoost 需要一个指示组信息的文件。例如，如果实例文件是上面显示的train.txt，则组文件应命名为train.txt.group并具有以下格式：

train.txt.group
2
3

这意味着数据集包含 5 个实例，前两个实例属于一个组，其余三个属于另一个组。组文件中的数字实际上按顺序指示了实例文件中每个组中的实例数量。在配置时，您不必指定组文件的路径。如果实例文件名为xxx，XGBoost 将检查同一目录下是否存在名为xxx.group的文件。

实例权重文件

训练数据中的实例可以分配权重，以区分它们之间的相对重要性。例如，如果我们为示例中的train.txt文件提供一个实例权重文件，如下所示：

train.txt.weight
1
0.5
0.5
1
0.5

这意味着在训练时，XGBoost 将更多地强调第一个和第四个实例（即正例）。配置类似于配置组信息。如果实例文件名为xxx，XGBoost 将在同一目录下查找名为xxx.weight的文件。如果该文件存在，则将提取实例权重并在训练时使用。

注意

二进制缓冲区格式和实例权重

如果您选择将训练数据保存为二进制缓冲区（使用save_binary()），请记住生成的二进制缓冲区文件将包含实例权重。要更新权重，请使用set_weight()函数。

初始边距文件

XGBoost 支持为每个实例提供一个初始边距预测。例如，如果我们使用逻辑回归对train.txt文件进行初始预测，我们可以创建以下文件：

train.txt.base_margin
-0.4
1.0
3.4

XGBoost 将把这些值作为初始边距预测并在此基础上进行提升。关于 base_margin 的一个重要注意事项是，它应该是变换前的边距预测值，因此如果您正在进行逻辑损失，则需要放入逻辑变换之前的值。如果您正在使用 XGBoost 预测器，请使用pred_margin=1来输出边距值。

在 LIBSVM 文件中嵌入附加信息

本节适用于单节点和多节点设置。

查询 ID 列

这对于排序任务最为有用，其中实例被分组到查询组中。您可以通过在每行中添加一个形式为qid:xx的标记，在 LIBSVM 文件中为每个实例嵌入查询组 ID。

train.txt
1 qid:1 101:1.2 102:0.03
0 qid:1 1:2.1 10001:300 10002:400
0 qid:2 0:1.3 1:0.3
1 qid:2 0:0.01 1:0.3
0 qid:3 0:0.2 1:0.3
1 qid:3 3:-0.1 10:-0.3
0 qid:3 6:0.2 10:0.15

请记住以下限制：

  • 您不允许为部分实例指定查询 ID，而为其他实例不指定。要么每行都分配了查询 ID，要么都没有。

  • 行必须按查询 ID 升序排序。因此，例如，您的某一行不能比其后任何一行拥有更大的查询 ID。

实例权重

您可以通过在每个实例标签后附加相应的权重，形式为[label]:[weight]，在 LIBSVM 文件中指定实例权重，如下例所示：

train.txt
1:1.0 101:1.2 102:0.03
0:0.5 1:2.1 10001:300 10002:400
0:0.5 0:1.3 1:0.3
1:1.0 0:0.01 1:0.3
0:0.5 0:0.2 1:0.3

其中负样本被赋予正样本一半的权重。