xgboost
模块 | 函数
增强器

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

Booster 的协作图

模块

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

函数

int XGBoosterCreate (const DMatrixHandle dmats[], bst_ulong len, BoosterHandle *out)
 创建一个 XGBoost 学习器 (booster) 更多...
 
int XGBoosterFree (BoosterHandle handle)
 删除 booster。 更多...
 
int XGBoosterReset (BoosterHandle handle)
 重置 booster 对象，释放训练中使用的数据缓存。 更多...
 
int XGBoosterSlice (BoosterHandle handle, int begin_layer, int end_layer, int step, BoosterHandle *out)
 使用 boosting 索引对模型进行切片。切片 m:n 表示选取在 boosting 轮次 m, (m+1), (m+2), ..., (n-1) 期间拟合的所有树。 更多...
 
int XGBoosterBoostedRounds (BoosterHandle handle, int *out)
 获取梯度增强器的 boosting 轮次数。当 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)
 从 Booster 获取字符串属性。 更多...
 
int XGBoosterSetAttr (BoosterHandle handle, const char *key, const char *value)
 设置或删除字符串属性。 更多...
 
int XGBoosterGetAttrNames (BoosterHandle handle, bst_ulong *out_len, const char ***out)
 从 Booster 获取所有属性名称。 更多...
 
int XGBoosterSetStrFeatureInfo (BoosterHandle handle, const char *field, const char **features, const bst_ulong size)
 在 Booster 中设置字符串编码的特征信息，类似于 DMatrix 中的特征信息。 更多...
 
int XGBoosterGetStrFeatureInfo (BoosterHandle handle, const char *field, bst_ulong *len, const char ***out_features)
 从 Booster 获取字符串编码的特征信息，类似于 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 对象有许多缓存用于提高性能。除了梯度和预测，它还包括运行时缓冲区，如叶子分区。这些缓冲区与 Booster 对象一起存在，直到调用 XGBoosterReset() 或通过 XGBoosterFree() 删除 booster。

函数文档

◆ XGBoosterBoostedRounds()

int XGBoosterBoostedRounds ( BoosterHandle  handle,
int *  out 
)

获取梯度增强器的 boosting 轮次数。当 process_type 为 update 时，由于树被移除，此数值可能会下降。

参数
handlebooster 的句柄。
out指向输出整数的指针。
返回值
成功时返回 0，失败时返回 -1

◆ XGBoosterBoostOneIter()

int XGBoosterBoostOneIter ( BoosterHandle  handle,
DMatrixHandle  dtrain,
float *  grad,
float *  hess,
bst_ulong  len 
)
已废弃
自 2.1.0 版本起

◆ XGBoosterCreate()

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

创建一个 XGBoost 学习器 (booster)

参数
dmats设置为由 booster 缓存的矩阵。
lendmats 的长度
out结果 booster 的句柄
返回值
成功时返回 0，失败时返回 -1
示例
c-api-demo.c, external_memory.c, and inference.c。

◆ XGBoosterDumpModel()

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

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

参数
handlehandle
fmapfmap 名称可以为空字符串
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 
)

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

参数
handlehandle
fmapfmap 名称可以为空字符串
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 
)

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

参数
handlehandle
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 
)

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

参数
handlehandle
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  len,
const char **  out_result 
)

获取 xgboost 的评估统计信息

参数
handlehandle
iter当前迭代轮次
dmats指向待评估数据的指针
evnames指向每个数据名称的指针
lendmats 的长度
out_result包含评估统计信息的字符串
返回值
成功时返回 0，失败时返回 -1
示例
c-api-demo.c, and 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，并有多种重要性类型定义。

参数
handleBooster 的一个实例
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)

删除 booster。

参数
handle待释放的句柄。
返回值
成功时返回 0，失败时返回 -1
示例
c-api-demo.c, external_memory.c, and inference.c。

◆ XGBoosterGetAttr()

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

从 Booster 获取字符串属性。

参数
handlehandle
key属性的键。
out结果属性，如果属性不存在则可以为 NULL。
success结果是否包含在 out 中。
返回值
成功时返回 0，失败时返回 -1

◆ XGBoosterGetAttrNames()

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

从 Booster 获取所有属性名称。

参数
handlehandle
out_len用于存储输出长度的参数
out指向存储输出属性字符串的指针
返回值
成功时返回 0，失败时返回 -1

◆ XGBoosterGetNumFeature()

int XGBoosterGetNumFeature ( BoosterHandle  handle,
bst_ulong *  out 
)

获取特征数量

参数
handlebooster 的句柄。
out特征数量
返回值
成功时返回 0，失败时返回 -1
示例
c-api-demo.c.

◆ XGBoosterGetStrFeatureInfo()

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

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

接受的字段有

  • feature_name
  • feature_type

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

参数
handleBooster 的一个实例
field字段名称
len输出指针 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 
)

设置或删除字符串属性。

参数
handlehandle
key属性的键。
value要保存的值。如果为 nullptr，则属性将被删除。
返回值
成功时返回 0，失败时返回 -1

◆ XGBoosterSetParam()

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

设置参数

参数
handlehandle
name参数名称
value参数值
返回值
成功时返回 0，失败时返回 -1
示例
c-api-demo.c, and external_memory.c。

◆ XGBoosterSetStrFeatureInfo()

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

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

接受的字段有

  • feature_name
  • feature_type
参数
handleBooster 的一个实例
field字段名称
features指向字符串数组的指针。
sizefeatures 指针的大小（传入的字符串数量）。
返回值
成功时返回 0，失败时返回 -1

◆ XGBoosterSlice()

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

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

参数
handle待切片的 Booster。
begin_layer切片的起始
end_layer切片的结束；end_layer=0 等同于 end_layer=num_boost_round
step切片的步长
out切片后的 booster。
返回值
成功时返回 0，失败时返回 -1，索引超出范围时返回 -2。

◆ XGBoosterTrainOneIter()

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

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

始于
2.0.0
参数
handlehandle
dtrain训练数据。
iter当前迭代轮次。使用训练继续时，计数应重新开始。
grad梯度的 Json 编码 __(cuda)_array_interface__。
hessHessian 的 Json 编码 __(cuda)_array_interface__。
返回值
成功时返回 0，失败时返回 -1

◆ XGBoosterUpdateOneIter()

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

使用 dtrain 更新模型一个轮次

参数
handlehandle
iter当前迭代轮次
dtrain训练数据
返回值
成功时返回 0，失败时返回 -1
示例
c-api-demo.c, external_memory.c, and inference.c。
生成于 2025年5月26日 星期一 21:34:52，由 doxygen 1.9.1 为 xgboost 生成