Booster

Booster 类是 XGBoost 的梯度提升模型。更多...

Booster 的协作图

模块
	预测
	这些函数用于运行预测和解释算法。
	序列化
	根据用例，有多种方法可以序列化 Booster 对象。

函数
int	XGBoosterCreate (const DMatrixHandle dmats[], bst_ulong len, BoosterHandle *out)
	创建一个 XGBoost 学习器（助推器）更多...
int	XGBoosterFree (BoosterHandle handle)
	删除助推器。更多...
int	XGBoosterReset (BoosterHandle handle)
	重置助推器对象以释放训练中使用的缓存数据。更多...
int	XGBoosterSlice (BoosterHandle handle, int begin_layer, int end_layer, int step, BoosterHandle *out)
	使用提升索引对模型进行切片。切片 m:n 表示获取在提升轮次 m、(m+1)、(m+2)、...、(n-1) 期间拟合的所有树。更多...
int	XGBoosterBoostedRounds (BoosterHandle handle, int *out)
	从梯度助推器中获取提升轮次的数量。当 process_type 为 update 时，此数字可能因删除的树而减少。更多...
int	XGBoosterSetParam (BoosterHandle handle, const char *name, const char *value)
	设置参数 更多...
int	XGBoosterGetNumFeature (BoosterHandle handle, bst_ulong *out)
	获取特征数量 更多...
int	XGBoosterUpdateOneIter (BoosterHandle handle, int iter, DMatrixHandle dtrain)
	使用 dtrain 更新模型一轮 更多...
int	XGBoosterBoostOneIter (BoosterHandle handle, DMatrixHandle dtrain, float *grad, float *hess, bst_ulong len)
int	XGBoosterTrainOneIter (BoosterHandle handle, DMatrixHandle dtrain, int iter, char const *grad, char const *hess)
	使用梯度和 Hessian 更新模型。这用于使用自定义目标函数进行训练。更多...
int	XGBoosterEvalOneIter (BoosterHandle handle, int iter, DMatrixHandle dmats[], const char *evnames[], bst_ulong len, const char **out_result)
	获取 xgboost 的评估统计信息 更多...
int	XGBoosterDumpModel (BoosterHandle handle, const char *fmap, int with_stats, bst_ulong *out_len, const char ***out_dump_array)
	转储模型，返回表示模型转储的字符串数组 更多...
int	XGBoosterDumpModelEx (BoosterHandle handle, const char *fmap, int with_stats, const char *format, bst_ulong *out_len, const char ***out_dump_array)
	转储模型，返回表示模型转储的字符串数组 更多...
int	XGBoosterDumpModelWithFeatures (BoosterHandle handle, int fnum, const char **fname, const char **ftype, int with_stats, bst_ulong *out_len, const char ***out_models)
	转储模型，返回表示模型转储的字符串数组 更多...
int	XGBoosterDumpModelExWithFeatures (BoosterHandle handle, int fnum, const char **fname, const char **ftype, int with_stats, const char *format, bst_ulong *out_len, const char ***out_models)
	转储模型，返回表示模型转储的字符串数组 更多...
int	XGBoosterGetAttr (BoosterHandle handle, const char *key, const char **out, int *success)
	从助推器中获取字符串属性。更多...
int	XGBoosterSetAttr (BoosterHandle handle, const char *key, const char *value)
	设置或删除字符串属性。更多...
int	XGBoosterGetAttrNames (BoosterHandle handle, bst_ulong *out_len, const char ***out)
	从助推器中获取所有属性的名称。更多...
int	XGBoosterSetStrFeatureInfo (BoosterHandle handle, const char *field, const char **features, const bst_ulong size)
	在助推器中设置字符串编码的特征信息，类似于 DMatrix 中的特征信息。更多...
int	XGBoosterGetStrFeatureInfo (BoosterHandle handle, const char *field, bst_ulong *len, const char ***out_features)
	从助推器中获取字符串编码的特征信息，类似于 DMatrix 中的特征信息。更多...
int	XGBoosterFeatureScore (BoosterHandle handle, const char *config, bst_ulong *out_n_features, char const ***out_features, bst_ulong *out_dim, bst_ulong const **out_shape, float const **out_scores)
	计算树模型的特征分数。当用于线性模型时，仅定义了 `weight` 重要性类型，并且对于多类模型，输出分数是形状为 [n_features, n_classes] 的行主矩阵。对于树模型，out_n_feature 始终等于 out_n_scores，并且具有多种重要性类型定义。更多...

详细描述

Booster 类是 XGBoost 的梯度提升模型。

在训练期间，助推器对象有许多缓存以提高性能。除了梯度和预测之外，它还包括像叶分区这样的运行时缓冲区。这些缓冲区与 Booster 对象一起保留，直到调用 XGBoosterReset() 或通过 XGBoosterFree() 删除助推器。

函数文档

XGBoosterBoostedRounds()

int XGBoosterBoostedRounds	(	BoosterHandle	handle,
		int *	out
	)

从梯度助推器中获取提升轮次的数量。当 process_type 为 update 时，此数字可能因删除的树而减少。

参数

handle	助推器句柄。
out	指向输出整数的指针。

返回

成功返回 0，失败返回 -1

XGBoosterBoostOneIter()

int XGBoosterBoostOneIter	(	BoosterHandle	handle,
		DMatrixHandle	dtrain,
		float *	grad,
		float *	hess,
		bst_ulong	长度
	)

已废弃

自 2.1.0 起

XGBoosterCreate()

int XGBoosterCreate	(	const DMatrixHandle	dmats[],
		bst_ulong	长度,
		BoosterHandle *	out
	)

创建一个XGBoost学习器（booster）

参数

dmats	设置为由助推器缓存的矩阵。
长度	dmats 的长度
out	结果助推器的句柄

返回

成功返回 0，失败返回 -1

示例

c-api-demo.c、external_memory.c 和 inference.c。

XGBoosterDumpModel()

int XGBoosterDumpModel	(	BoosterHandle	handle,
		const char *	fmap,
		int	with_stats,
		bst_ulong *	out_len,
		const char ***	out_dump_array
	)

转储模型，返回表示模型转储的字符串数组

参数

handle	handle
fmap	fmap 的名称可以是空字符串
with_stats	是否转储统计信息
out_len	输出数组的长度
out_dump_array	指向保存每个模型转储的指针

返回

成功返回 0，失败返回 -1

XGBoosterDumpModelEx()

int XGBoosterDumpModelEx	(	BoosterHandle	handle,
		const char *	fmap,
		int	with_stats,
		const char *	format,
		bst_ulong *	out_len,
		const char ***	out_dump_array
	)

转储模型，返回表示模型转储的字符串数组

参数

handle	handle
fmap	fmap 的名称可以是空字符串
with_stats	是否转储统计信息
format	转储模型的格式
out_len	输出数组的长度
out_dump_array	指向保存每个模型转储的指针

返回

成功返回 0，失败返回 -1

XGBoosterDumpModelExWithFeatures()

int XGBoosterDumpModelExWithFeatures	(	BoosterHandle	handle,
		int	fnum,
		const char **	fname,
		const char **	ftype,
		int	with_stats,
		const char *	format,
		bst_ulong *	out_len,
		const char ***	out_models
	)

转储模型，返回表示模型转储的字符串数组

参数

handle	handle
fnum	特征数量
fname	特征名称
ftype	特征类型
with_stats	是否转储统计信息
format	转储模型的格式
out_len	输出数组的长度
out_models	指向保存每个模型转储的指针

返回

成功返回 0，失败返回 -1

XGBoosterDumpModelWithFeatures()

int XGBoosterDumpModelWithFeatures	(	BoosterHandle	handle,
		int	fnum,
		const char **	fname,
		const char **	ftype,
		int	with_stats,
		bst_ulong *	out_len,
		const char ***	out_models
	)

转储模型，返回表示模型转储的字符串数组

参数

handle	handle
fnum	特征数量
fname	特征名称
ftype	特征类型
with_stats	是否转储统计信息
out_len	输出数组的长度
out_models	指向保存每个模型转储的指针

返回

成功返回 0，失败返回 -1

XGBoosterEvalOneIter()

int XGBoosterEvalOneIter	(	BoosterHandle	handle,
		int	iter,
		DMatrixHandle	dmats[],
		const char *	evnames[],
		bst_ulong	长度,
		const char **	out_result
	)

获取xgboost的评估统计数据

参数

handle	handle
iter	当前迭代轮次
dmats	指向要评估的数据的指针
evnames	指向每个数据名称的指针
长度	dmats 的长度
out_result	包含评估统计信息的字符串

返回

成功返回 0，失败返回 -1

示例

c-api-demo.c 和 external_memory.c。

XGBoosterFeatureScore()

int XGBoosterFeatureScore	(	BoosterHandle	handle,
		const char *	config,
		bst_ulong *	out_n_features,
		char const ***	out_features,
		bst_ulong *	out_dim,
		bst_ulong const **	out_shape,
		float const **	out_scores
	)

计算树模型的特征分数。当用于线性模型时，仅定义了 `weight` 重要性类型，并且对于多类模型，输出分数是形状为 [n_features, n_classes] 的行主矩阵。对于树模型，out_n_feature 始终等于 out_n_scores，并且具有多种重要性类型定义。

参数

handle	助推器的一个实例
config	用于计算分数（编码为 JSON）的参数。接受的 JSON 键是 importance_type: 一个 JSON 字符串，可能的值如下： 'weight'：特征在所有树中用于分割数据的次数。 'gain'：特征用于分割的平均增益。 'cover'：特征用于分割的平均覆盖度。 'total_gain'：特征用于分割的总增益。 'total_cover'：特征用于分割的总覆盖度。 feature_map: 可选的 JSON 字符串，包含特征映射文件的 URI 或路径。 feature_names: 可选的 JSON 数组，包含每个特征的字符串名称。
out_n_features	输出特征名称的长度。
out_features	一个字符串数组作为特征名称，与输出分数的顺序相同。
out_dim	输出特征分数的维度。
out_shape	输出特征分数的形状，长度为 out_dim。
out_scores	一个浮点数组作为特征分数，形状为 out_shape。

返回

成功返回 0，失败返回 -1

XGBoosterFree()

int XGBoosterFree

(

BoosterHandle

handle

)

删除增强器。

参数

handle

要释放的句柄。

返回

成功返回 0，失败返回 -1

示例

c-api-demo.c、external_memory.c 和 inference.c。

XGBoosterGetAttr()

int XGBoosterGetAttr	(	BoosterHandle	handle,
		const char *	key,
		const char **	out,
		int *	success
	)

从 Booster 获取字符串属性。

参数

handle	handle
key	属性的键。
out	结果属性，如果属性不存在，则可以为 NULL。
success	结果是否包含在 out 中。

返回

成功返回 0，失败返回 -1

XGBoosterGetAttrNames()

int XGBoosterGetAttrNames	(	BoosterHandle	handle,
		bst_ulong *	out_len,
		const char ***	out
	)

获取Booster中所有属性的名称。

参数

handle	handle
out_len	用于保存输出长度的参数
out	指向保存输出属性字符串的指针

返回

成功返回 0，失败返回 -1

XGBoosterGetNumFeature()

int XGBoosterGetNumFeature	(	BoosterHandle	handle,
		bst_ulong *	out
	)

获取特征数量

参数

handle	助推器句柄。
out	特征数量

返回

成功返回 0，失败返回 -1

示例

c-api-demo.c.

XGBoosterGetStrFeatureInfo()

int XGBoosterGetStrFeatureInfo	(	BoosterHandle	handle,
		const char *	field,
		bst_ulong *	长度,
		const char ***	out_features
	)

从 Booster 获取字符串编码的特征信息，类似于 DMatrix 中的特征信息。

接受的字段有

• feature_name
• feature_type

调用者负责在下一次调用任何 XGBoost API 函数之前复制数据。

参数

handle	助推器的一个实例
field	字段名称
长度	输出指针 features 的大小（返回的字符串数量）。
out_features	指向字符串数组的指针的地址。结果存储在线程本地内存中。

返回

成功返回 0，失败返回 -1

XGBoosterReset()

int XGBoosterReset

(

BoosterHandle

handle

)

重置booster对象以释放用于训练的数据缓存。

自

3.0.0

返回

成功返回 0，失败返回 -1

XGBoosterSetAttr()

int XGBoosterSetAttr	(	BoosterHandle	handle,
		const char *	key,
		const char *	value
	)

设置或删除字符串属性。

参数

handle	handle
key	属性的键。
value	要保存的值。如果为 nullptr，则属性将被删除。

返回

成功返回 0，失败返回 -1

XGBoosterSetParam()

int XGBoosterSetParam	(	BoosterHandle	handle,
		const char *	name,
		const char *	value
	)

设置参数

参数

handle	handle
name	参数名称
value	参数值

返回

成功返回 0，失败返回 -1

示例

c-api-demo.c 和 external_memory.c。

XGBoosterSetStrFeatureInfo()

int XGBoosterSetStrFeatureInfo	(	BoosterHandle	handle,
		const char *	field,
		const char **	features,
		const bst_ulong	size
	)

在 Booster 中设置字符串编码的特征信息，类似于 DMatrix 中的特征信息。

接受的字段有

• feature_name
• feature_type

参数

handle	助推器的一个实例
field	字段名称
features	指向字符串数组的指针。
size	features 指针的大小（传入的字符串数量）。

返回

成功返回 0，失败返回 -1

XGBoosterSlice()

int XGBoosterSlice	(	BoosterHandle	handle,
		int	begin_layer,
		int	end_layer,
		int	step,
		BoosterHandle *	out
	)

使用提升索引对模型进行切片。切片 m:n 表示获取在提升轮次 m、(m+1)、(m+2)、...、(n-1) 期间拟合的所有树。

参数

handle	要切片的助推器。
begin_layer	切片的开始
end_layer	切片的结束；end_layer=0 等效于 end_layer=num_boost_round
step	切片的步长
out	切片后的助推器。

返回

成功时为 0，失败时为 -1，索引越界时为 -2。

XGBoosterTrainOneIter()

int XGBoosterTrainOneIter	(	BoosterHandle	handle,
		DMatrixHandle	dtrain,
		int	iter,
		char const *	grad,
		char const *	hess
	)

使用梯度和Hessian更新模型。这用于使用自定义目标函数进行训练。

自

2.0.0

参数

handle	handle
dtrain	训练数据。
iter	当前迭代轮次。当使用训练继续时，计数应重新开始。
grad	梯度的 Json 编码 __(cuda)_array_interface__。
hess	Hessian 的 Json 编码 __(cuda)_array_interface__。

返回

成功返回 0，失败返回 -1

XGBoosterUpdateOneIter()

int XGBoosterUpdateOneIter	(	BoosterHandle	handle,
		int	iter,
		DMatrixHandle	dtrain
	)

使用dtrain更新模型一个回合

参数

handle	handle
iter	当前迭代轮次
dtrain	训练数据

返回

成功返回 0，失败返回 -1

示例

c-api-demo.c、external_memory.c 和 inference.c。