DMatrix 的文本输入格式

这里我们将简要描述 XGBoost 的文本输入格式。然而，对于能够使用受支持的语言环境（如 Python 或 R）的用户，建议使用该生态系统中的数据解析器。例如，sklearn.datasets.load_svmlight_file()。

警告

如上所述，鼓励用户使用第三方数据解析器。XGBoost 中的文本解析器已被弃用。

基本输入格式

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 列

这对于排名任务最有用，其中实例被分组到查询组中。您可以通过在 LIBSVM 文件的每一行中添加qid:xx形式的标记来嵌入每个实例的查询组 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

其中负实例的权重是正实例的一半。