分位数 DMatrix 和外部存储器 DMatrix 可以从数据批次创建。更多...

流式处理协作图

类
结构	XGBoostBatchCSR
	在 XGBoost 数据迭代中使用的 Mini 批次。更多...

类型定义
typedef void *	DataIterHandle
	外部数据迭代器的句柄更多...

typedef void *	DataHolderHandle
	内部数据持有者的句柄。更多...

typedef int	XGBCallbackSetData(DataHolderHandle handle, XGBoostBatchCSR batch)
	设置数据到句柄的回调函数。更多...

typedef int	XGBCallbackDataIterNext(DataIterHandle data_handle, XGBCallbackSetData *set_function, DataHolderHandle set_function_handle)
	数据读取回调函数。迭代器将能够提供数据中的批次子集。更多...

typedef int	XGDMatrixCallbackNext(DataIterHandle iter)
	获取下一批数据的回调函数原型。更多...

typedef 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 有 2 组数据回调函数。第一组目前专门由 JVM 包使用。它使用 XGBoostBatchCSR 接受 CSR 格式输入的批次，并将它们连接成最终的一个大 CSR。相关函数包括：

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

第二种用例是外部存储器支持，用户可以将自定义数据迭代器传递给 XGBoost 以批次加载数据。在这两种情况下，迭代器仅在构建 DMatrix 期间使用，构建完成后可以安全地释放。每种用例在各自的 DMatrix 工厂函数中有简要说明。

工厂函数

用于外部存储器的 XGDMatrixCreateFromCallback
用于分位数 DMatrix 的 XGQuantileDMatrixCreateFromCallback
用于外部存储器分位数 DMatrix 的 XGExtMemQuantileDMatrixCreateFromCallback

调用者可以用来传递数据给 XGBoost 的代理

类型定义文档

◆ DataHolderHandle

typedef void* DataHolderHandle

内部数据持有者的句柄。

◆ DataIterHandle

typedef void* DataIterHandle

外部数据迭代器的句柄

◆ DataIterResetCallback

typedef void DataIterResetCallback(DataIterHandle handle)

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

◆ XGBCallbackDataIterNext

typedef int XGBCallbackDataIterNext( DataIterHandle data_handle, XGBCallbackSetData *set_function, DataHolderHandle set_function_handle)

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

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

参数

data_handle	回调函数的句柄。
set_function	迭代器返回的批次
set_function_handle	要传递给设置函数的句柄。

返回值: 如果到达末尾且未返回批次，则为 0。

◆ XGBCallbackSetData

typedef int XGBCallbackSetData( DataHolderHandle handle, XGBoostBatchCSR batch)

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

参数

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

◆ XGDMatrixCallbackNext

typedef 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：将迭代器句柄、代理句柄和两个方法连同以 JSON 对象编码的其他参数传递给 XGDMatrixCreateFromCallback。
步骤 3：在 next 函数中调用适当的数据设置函数。

参数

	iter	外部数据迭代器的句柄。
	proxy	通过 XGProxyDMatrixCreate 创建的 DMatrix 代理句柄。
	reset	重置迭代器状态的回调函数。
	next	产生下一批数据的回调函数。
	config	用于 DMatrix 构建的 JSON 编码参数。接受的字段包括： missing: 用哪个值表示缺失值 cache_prefix: 缓存文件路径，调用者必须初始化此路径中的所有目录。 nthread (可选): 初始化 DMatrix 使用的线程数。
[out]	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
	)

创建一个由外部存储器支持的分位数 DMatrix。

自: 3.0.0

注意: 这是实验性的，可能会发生变化。

参数

iter	外部数据迭代器的句柄。
proxy	通过 XGProxyDMatrixCreate 创建的 DMatrix 代理句柄。
ref	用于提供分位数信息的参考 DMatrix。
reset	重置迭代器状态的回调函数。
next	产生下一批数据的回调函数。
config	用于 DMatrix 构建的 JSON 编码参数。接受的字段包括： missing: 用哪个值表示缺失值 cache_prefix: 缓存文件路径，调用者必须初始化此路径中的所有目录。 nthread (可选): 初始化 DMatrix 使用的线程数。 max_bin (可选): 构建直方图的最大分箱数。必须与相应的 booster 训练参数一致。 on_host (可选): 数据是否应放置在主机内存上。用于 GPU 输入。 min_cache_page_bytes (可选): 每个内部 GPU 页面的最小字节数。设置为 0 以禁用页面连接。如果未提供参数或设置为 None，则自动配置。 max_quantile_blocks (可选): 对于基于 GPU 的输入，XGBoost 使用多个增长的子流处理传入的批次。此参数设置在 XGBoost 切断子流并创建新子流之前处理的最大批次数。这有助于限制内存使用。默认情况下，XGBoost 会呈指数级增长新子流，直到批次处理完毕。仅用于训练数据集，默认值为 None（无限制）。
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 *	data
	)

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

参数

handle	通过 XGProxyDMatrixCreate 创建的 DMatrix 代理
data	详情请参阅 XGDMatrixCreateFromColumnar。

返回值: 成功时为 0，失败时为 -1

◆ XGProxyDMatrixSetDataCSR()

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

在 DMatrix 代理上设置数据。

参数

handle	通过 XGProxyDMatrixCreate 创建的 DMatrix 代理
indptr	CSR 中行指针的 JSON 编码 array_interface。
indices	CSR 中列索引的 JSON 编码 array_interface。
data	CSR 中值的 JSON 编码 array_interface。
ncol	输入 CSR 矩阵的列数。

返回值: 成功时为 0，失败时为 -1

◆ XGProxyDMatrixSetDataCudaArrayInterface()

int XGProxyDMatrixSetDataCudaArrayInterface	(	DMatrixHandle	handle,
		const char *	data
	)

在 DMatrix 代理上设置数据。

参数

handle	通过 XGProxyDMatrixCreate 创建的 DMatrix 代理
data	以 null 结尾的 JSON 文档字符串表示的 CUDA 数组接口。

返回值: 成功时为 0，失败时为 -1

◆ XGProxyDMatrixSetDataCudaColumnar()

int XGProxyDMatrixSetDataCudaColumnar	(	DMatrixHandle	handle,
		const char *	data
	)

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

参数

handle	通过 XGProxyDMatrixCreate 创建的 DMatrix 代理
data	详情请参阅 XGDMatrixCreateFromColumnar。

返回值: 成功时为 0，失败时为 -1

◆ XGProxyDMatrixSetDataDense()

int XGProxyDMatrixSetDataDense	(	DMatrixHandle	handle,
		char const *	data
	)

在 DMatrix 代理上设置数据。

参数

handle	通过 XGProxyDMatrixCreate 创建的 DMatrix 代理
data	以 null 结尾的 JSON 文档字符串表示的数组接口。

返回值: 成功时为 0，失败时为 -1

示例: external_memory.c.

◆ XGQuantileDMatrixCreateFromCallback()

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

使用数据迭代器创建分位数 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 (可选): 构建直方图的最大分箱数。必须与相应的 booster 训练参数一致。 max_quantile_blocks (可选): 对于基于 GPU 的输入，XGBoost 使用多个增长的子流处理传入的批次。此参数设置在 XGBoost 切断子流并创建新子流之前处理的最大批次数。这有助于限制内存使用。默认情况下，XGBoost 会呈指数级增长新子流，直到批次处理完毕。仅用于训练数据集，默认值为 None（无限制）。
out	创建的分位数 DMatrix。

返回值: 成功时为 0，失败时为 -1