xgboost
类 | 类型定义 | 函数
流式传输
DMatrix

分位数 DMatrix 和外部内存 DMatrix 可以通过数据批次创建。更多...

流式处理的协作图

类

结构  XGBoostBatchCSR
 XGBoost 数据迭代中使用的迷你批次。更多...
 

类型定义

typedef void * DataIterHandle
 外部数据迭代器的句柄更多...
 
typedef void * DataHolderHandle
 内部数据持有者的句柄。更多...
 
类型定义 int XGBCallbackSetData(DataHolderHandle handle, XGBoostBatchCSR batch)
 设置数据到句柄的回调。更多...
 
类型定义 int XGBCallbackDataIterNext(DataIterHandle data_handle, XGBCallbackSetData *set_function, DataHolderHandle set_function_handle)
 数据读取回调函数。迭代器将能够提供数据的批次子集。更多...
 
类型定义 int XGDMatrixCallbackNext(DataIterHandle iter)
 获取下一批数据回调函数的原型。更多...
 
类型定义 void DataIterResetCallback(DataIterHandle handle)
 重置外部迭代器回调函数的原型。更多...
 

函数

int XGDMatrixCreateFromDataIter (DataIterHandle data_handle, XGBCallbackDataIterNext *callback, const char *cache_info, float missing, DMatrixHandle *out)
 从数据迭代器创建 DMatrix。更多...
 
int XGProxyDMatrixCreate (DMatrixHandle *out)
 创建一个 DMatrix 代理来设置数据，可以通过 XGDMatrixFree 释放。更多...
 
int XGDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)
 使用数据迭代器创建外部内存 DMatrix。更多...
 
int XGQuantileDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterHandle ref, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)
 使用数据迭代器创建分位数 DMatrix。更多...
 
int XGExtMemQuantileDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterHandle ref, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)
 创建由外部内存支持的分位数 DMatrix。更多...
 
int XGProxyDMatrixSetDataCudaArrayInterface (DMatrixHandle handle, const char *data)
 在 DMatrix 代理上设置数据。更多...
 
int XGProxyDMatrixSetDataColumnar (DMatrixHandle handle, char const *data)
 在 DMatrix 代理上设置列式（表格）数据。更多...
 
int XGProxyDMatrixSetDataCudaColumnar (DMatrixHandle handle, const char *data)
 在 DMatrix 代理上设置基于 CUDA 的列式（表格）数据。更多...
 
int XGProxyDMatrixSetDataDense (DMatrixHandle handle, char const *data)
 在 DMatrix 代理上设置数据。更多...
 
int XGProxyDMatrixSetDataCSR (DMatrixHandle handle, char const *indptr, char const *indices, char const *data, bst_ulong ncol)
 在 DMatrix 代理上设置数据。更多...
 

详细描述

分位数 DMatrix 和外部内存 DMatrix 可以从批量数据创建。

DMatrix 有两组数据回调。第一组目前专门由 JVM 包使用。它使用 ` XGBoostBatchCSR ` 接受 CSR 格式输入的批次，并将它们连接成一个最终的大型 CSR。相关函数是：

另一组由外部数据迭代器使用。它接受外部数据迭代器作为回调。有两种不同的场景，用户可能希望传入回调而不是原始数据。首先是 hist 和基于 GPU 的 hist 树方法使用的分位数 DMatrix。在这种情况下，数据首先通过分位数素描压缩，然后合并。这对于分布式设置特别有用，因为它消除了两次数据复制。第一次是由外部库进行 `concat`，将数据转换为一个 blob 以进行正常 DMatrix 初始化，另一次是由 DMatrix 的内部 CSR 复制。

第二个用例是外部内存支持，用户可以将自定义数据迭代器传递给 XGBoost，以批处理方式加载数据。对于这两种情况，迭代器仅在 DMatrix 构造期间使用，并在构造完成后可以安全释放。在相应的 DMatrix 工厂函数中，每个用例都有简短的说明。

相关函数是

工厂函数

调用者可用于向 XGBoost 传递数据的代理

类型定义文档

◆ DataHolderHandle

类型定义 void* DataHolderHandle

内部数据持有者的句柄。

◆ DataIterHandle

类型定义 void* DataIterHandle

外部数据迭代器的句柄

◆ DataIterResetCallback

类型定义 void DataIterResetCallback(DataIterHandle handle)

重置外部迭代器的回调函数原型。

◆ XGBCallbackDataIterNext

类型定义 int XGBCallbackDataIterNext( DataIterHandle data_handle, XGBCallbackSetData *set_function, DataHolderHandle set_function_handle)

数据读取回调函数。迭代器将能够提供数据中的批次子集。

如果存在数据，该函数将调用 set_function 来设置数据。

参数
data_handle回调的句柄。
set_function迭代器返回的批次
set_function_handle要传递给 set 函数的句柄。
返回
如果已到达末尾且未返回批次，则为 0。

◆ XGBCallbackSetData

类型定义 int XGBCallbackSetData( DataHolderHandle handle, XGBoostBatchCSR batch)

设置数据到句柄的回调函数。

参数
handle回调的句柄。
batch要设置的数据内容。

◆ XGDMatrixCallbackNext

类型定义 int XGDMatrixCallbackNext(DataIterHandle iter)

获取下一批数据的回调函数原型。

参数
iter用户定义迭代器的处理程序。
返回
成功时为 0，失败时为 -1。

函数文档

◆ XGDMatrixCreateFromCallback()

int XGDMatrixCreateFromCallback ( DataIterHandle  iter,
DMatrixHandle  proxy,
DataIterResetCallback *  reset,
XGDMatrixCallbackNext *  next,
char const *  config,
DMatrixHandle *  out 
)

使用数据迭代器创建外部内存 DMatrix。

关于如何使用第二组回调来支持外部内存数据的简短说明

  • 步骤 0：定义一个具有 `reset` 和 `next` 两个方法的迭代器。
  • 步骤 1：通过 XGProxyDMatrixCreate 创建一个 DMatrix 代理并持有句柄。
  • 步骤 2：将迭代器句柄、代理句柄和两个方法传递给 XGDMatrixCreateFromCallback，以及作为 JSON 对象编码的其他参数。
  • 步骤 3：在 `next` 函数中调用适当的数据设置器。
参数
iter外部数据迭代器的句柄。
proxy由 XGProxyDMatrixCreate 创建的 DMatrix 代理句柄。
reset重置迭代器状态的回调函数。
next产生下一批数据的回调函数。
config用于 DMatrix 构造的 JSON 编码参数。接受的字段有：
  • missing：表示缺失值的值
  • cache_prefix：缓存文件的路径，调用者必须初始化此路径中的所有目录。
  • nthread (可选): 用于初始化 DMatrix 的线程数。
[输出]out创建的外部内存 DMatrix
返回
成功返回 0，失败返回 -1
示例
external_memory.c.

◆ XGDMatrixCreateFromDataIter()

int XGDMatrixCreateFromDataIter ( DataIterHandle  data_handle,
XGBCallbackDataIterNext *  callback,
const char *  cache_info,
float  missing,
DMatrixHandle *  out 
)

从数据迭代器创建 DMatrix。

参数
data_handle数据句柄。
callback获取数据的回调。
cache_info关于缓存文件的附加信息，可以为 null。
missing表示缺失值的值。
out创建的 DMatrix
返回
成功时为 0，失败时为 -1。

◆ XGExtMemQuantileDMatrixCreateFromCallback()

int XGExtMemQuantileDMatrixCreateFromCallback ( DataIterHandle  iter,
DMatrixHandle  proxy,
DataIterHandle  ref,
DataIterResetCallback *  reset,
XGDMatrixCallbackNext *  next,
char const *  config,
DMatrixHandle *  out 
)

创建由外部内存支持的Quantile DMatrix。

自
3.0.0
注意
这是实验性的，可能会有变化。
参数
iter外部数据迭代器的句柄。
proxy由 XGProxyDMatrixCreate 创建的 DMatrix 代理句柄。
ref提供分位数信息的参考 DMatrix。
reset重置迭代器状态的回调函数。
next产生下一批数据的回调函数。
config用于 DMatrix 构造的 JSON 编码参数。接受的字段有：
  • missing：表示缺失值的值
  • cache_prefix：缓存文件的路径，调用者必须初始化此路径中的所有目录。
  • nthread (可选): 用于初始化 DMatrix 的线程数。
  • max_bin (可选)：用于构建直方图的最大分箱数。必须与相应的助推器训练参数一致。
  • on_host (可选)：数据是否应放置在主机内存中。由 GPU 输入使用。
  • min_cache_page_bytes (可选)：每个内部 GPU 页面的最小字节数。设置为 0 以禁用页面连接。如果未提供参数或设置为 None，则自动配置。
  • max_quantile_blocks (可选)：对于基于 GPU 的输入，XGBoost 使用多个不断增长的子流处理传入的批次。此参数设置在 XGBoost 切断子流并创建新子流之前的最大批次数。这有助于限制内存使用。默认情况下，XGBoost 以指数方式增长新子流，直到批次耗尽。仅用于训练数据集，默认值为 None（无限制）。
  • cache_host_ratio (可选)：对于基于 GPU 的输入，XGBoost 可以将缓存分成主机和设备部分，以减少数据传输开销。此参数指定主机缓存相对于整个缓存的大小：`host / (host + device)`。
    参数
    out创建的分位数 DMatrix。
    返回
    成功返回 0，失败返回 -1

◆ XGProxyDMatrixCreate()

int XGProxyDMatrixCreate ( DMatrixHandle *  out)

创建一个 DMatrix 代理来设置数据，可以通过 XGDMatrixFree 释放。

第二组回调函数，用于使用自定义迭代器构建分位数 DMatrix 或外部内存 DMatrix。

DMatrix 代理只是对实际用户数据的临时引用（包装器）。例如，如果通过 XGProxyDMatrixSetDataDense 方法将密集矩阵（如 numpy 数组）传递给代理 DMatrix，则代理 DMatrix 仅持有引用，并且在下一次迭代开始之前（由 XGBoost 调用 XGDMatrixCallbackNext 发出信号）不能释放输入数组。它被称为 `ProxyDMatrix`，因为它重用了 XGBoost 中 DMatrix 类的接口，但它只是一个中间接口，供 XGDMatrixCreateFromCallback 和相关构造函数使用各种用户输入类型。

用户输入 -> 代理 DMatrix (包装器) -> 实际 DMatrix
参数
out创建的代理 DMatrix。
返回
成功时为 0，失败时为 -1。
示例
external_memory.c.

◆ XGProxyDMatrixSetDataColumnar()

int XGProxyDMatrixSetDataColumnar ( DMatrixHandle  handle,
char const *  数据 
)

在DMatrix代理上设置列状（表状）数据。

参数
handle由 XGProxyDMatrixCreate 创建的 DMatrix 代理
数据详情请参阅 XGDMatrixCreateFromColumnar。
返回
成功返回 0，失败返回 -1

◆ XGProxyDMatrixSetDataCSR()

int XGProxyDMatrixSetDataCSR ( DMatrixHandle  handle,
char const *  indptr,
char const *  indices,
char const *  数据,
bst_ulong  ncol 
)

在DMatrix代理上设置数据。

参数
handle由 XGProxyDMatrixCreate 创建的 DMatrix 代理
indptrJSON 编码的 array_interface 到 CSR 中的行指针。
indicesJSON编码的CSR中列索引的array_interface。
数据JSON 编码的 array_interface 到 CSR 中的值。
ncol输入 CSR 矩阵的列数。
返回
成功返回 0，失败返回 -1

◆ XGProxyDMatrixSetDataCudaArrayInterface()

int XGProxyDMatrixSetDataCudaArrayInterface ( DMatrixHandle  handle,
const char *  数据 
)

在DMatrix代理上设置数据。

参数
handle由 XGProxyDMatrixCreate 创建的 DMatrix 代理
数据CUDA 数组接口的以空字符结尾的 JSON 文档字符串表示。
返回
成功返回 0，失败返回 -1

◆ XGProxyDMatrixSetDataCudaColumnar()

int XGProxyDMatrixSetDataCudaColumnar ( DMatrixHandle  handle,
const char *  数据 
)

在 DMatrix 代理上设置基于 CUDA 的列式（表格）数据。

参数
handle由 XGProxyDMatrixCreate 创建的 DMatrix 代理
数据详情请参阅 XGDMatrixCreateFromColumnar。
返回
成功返回 0，失败返回 -1

◆ XGProxyDMatrixSetDataDense()

int XGProxyDMatrixSetDataDense ( DMatrixHandle  handle,
char const *  数据 
)

在DMatrix代理上设置数据。

参数
handle由 XGProxyDMatrixCreate 创建的 DMatrix 代理
数据以空字符结尾的 JSON 文档字符串表示的数组接口。
返回
成功返回 0，失败返回 -1
示例
external_memory.c.

◆ XGQuantileDMatrixCreateFromCallback()

int XGQuantileDMatrixCreateFromCallback ( DataIterHandle  iter,
DMatrixHandle  proxy,
DataIterHandle  ref,
DataIterResetCallback *  reset,
XGDMatrixCallbackNext *  next,
char const *  config,
DMatrixHandle *  out 
)

使用数据迭代器创建Quantile DMatrix。

关于如何使用第二组回调用于 (GPU) Hist 树方法的简短说明

  • 步骤 0：定义一个具有 `reset` 和 `next` 两个方法的迭代器。
  • 步骤 1：通过 XGProxyDMatrixCreate 创建一个 DMatrix 代理并持有句柄。
  • 步骤 2：将迭代器句柄、代理句柄和两个方法传递给 XGQuantileDMatrixCreateFromCallback。
  • 步骤 3：在 `next` 函数中调用适当的数据设置器。

请参阅 test_iterative_dmatrix.cu 或 Python 接口以获取示例。

参数
iter外部数据迭代器的句柄。
proxy由 XGProxyDMatrixCreate 创建的 DMatrix 代理句柄。
ref提供分位数信息的参考 DMatrix。
reset重置迭代器状态的回调函数。
next产生下一批数据的回调函数。
config用于 DMatrix 构造的 JSON 编码参数。接受的字段有：
  • missing：表示缺失值的值
  • nthread (可选): 用于初始化 DMatrix 的线程数。
  • max_bin (可选)：用于构建直方图的最大分箱数。必须与相应的助推器训练参数一致。
  • max_quantile_blocks (可选)：对于基于 GPU 的输入，XGBoost 使用多个不断增长的子流处理传入的批次。此参数设置在 XGBoost 切断子流并创建新子流之前的最大批次数。这有助于限制内存使用。默认情况下，XGBoost 以指数方式增长新子流，直到批次耗尽。仅用于训练数据集，默认值为 None（无限制）。
out创建的分位数 DMatrix。
返回
成功返回 0，失败返回 -1
生成于 2025 年 10 月 17 日星期五 23:27:08，由 doxygen 1.9.1 为 xgboost 生成