拟合 XGBoost 模型 — xgb.train • xgboost

使用 DMatrix 格式的给定数据（例如，通过 xgb.DMatrix() 生成的数据）拟合 XGBoost 模型。有关 XGBoost 功能的更详细解释，请参阅教程增强树介绍，以及其余的 XGBoost 教程，了解 XGBoost 的特性和用法。

与用户友好、面向交互式使用的函数 xgboost() 相比，xgb.train 是一个较低层级的接口，允许进行更精细的控制并暴露核心库提供的更多功能（例如排序学习目标），但它仅适用于 XGBoost 自己的数据格式（“DMatrices”），而不是常规的 R 对象。

此函数的语法与 Python 包中用于 XGBoost 的同名函数非常相似，建议包开发者使用 xgb.train 而非 xgboost()，因为它将提供更稳定的接口（破坏性更改较少）以及较低的数据验证开销。

如果您从 1.x 系列的先前 XGBoost 版本迁移，另请参阅迁移指南。

用法

xgb.train(
  params = xgb.params(),
  data,
  nrounds,
  evals = list(),
  objective = NULL,
  custom_metric = NULL,
  verbose = 1,
  print_every_n = 1L,
  early_stopping_rounds = NULL,
  maximize = NULL,
  save_period = NULL,
  save_name = "xgboost.model",
  xgb_model = NULL,
  callbacks = list(),
  ...
)

参数

params

控制模型构建过程的 XGBoost 参数列表。有关详细信息，请参阅在线文档和 xgb.params() 的文档。

应作为具有命名条目的列表传递。此列表中未指定的参数将使用其默认值。

可以通过函数 xgb.params() 创建命名参数列表，该函数接受所有有效参数作为函数参数。

data

训练数据集。xgb.train() 只接受 xgb.DMatrix 作为输入。

请注意，有一个函数 xgboost() 旨在接受 R 数据对象作为输入，例如数据框和矩阵。

nrounds

最大提升迭代次数。

evals

用于评估模型性能的 xgb.DMatrix 数据集命名列表。在每次提升迭代期间，将针对每个数据集计算在 eval_metric（在 params 下）或 custom_metric（此处为函数参数）中指定的指标，最终将结果存储在结果对象的 evaluation_log 字段中。

当 verbose>=1 或 xgb.cb.print.evaluation() 回调函数被调用时，性能结果会在训练期间持续打印输出。

例如，指定 evals=list(validation1=mat1, validation2=mat2) 可以跟踪每轮模型在 mat1 和 mat2 上的性能。

objective

自定义目标函数。应接受两个参数：第一个是当前预测值（根据目标/类别数量，可以是数值向量或矩阵），第二个是用于训练的 data DMatrix 对象。

应返回一个包含两个元素 grad 和 hess（按此顺序）的列表，可以是数值向量或数值矩阵，具体取决于目标/类别数量（维度与作为第一个参数传递的预测值相同）。

custom_metric

自定义评估函数。与 objective 类似，应接受两个参数，第一个是预测值，第二个是 data DMatrix。

应返回一个包含两个元素的列表：metric（将为此指标显示的名称，应为字符串/字符），以及 value（函数计算的数值，应为数值标量）。

请注意，即使传递了 custom_metric，目标函数也关联着一个默认指标，该指标将额外进行评估。为了禁用内置指标，可以传递参数 disable_default_eval_metric = TRUE。

verbose

如果为 0，xgboost 将保持静默。如果为 1，将打印性能信息。如果为 2，将打印一些额外信息。请注意，设置 verbose > 0 会自动调用 xgb.cb.print.evaluation(period=1) 回调函数。

print_every_n

当传递 verbose>0 时，根据此处传递的值，评估日志（在 evals 下传递的数据上计算的指标）将每隔 n 次迭代打印一次。第一次和最后一次迭代总是包含在内，无论此 'n' 的值如何。

仅在 evals 下传递数据且传递 verbose>0 时有效。该参数传递给 xgb.cb.print.evaluation() 回调函数。

early_stopping_rounds

在评估数据（在 evals 下传递）上，如果在性能（由目标函数提供的或默认选择的评估指标衡量）没有改善的情况下，将在此参数指定的提升轮次后停止训练。

必须传递 evals 才能使用此功能。设置此参数会添加 xgb.cb.early.stop() 回调函数。

如果为 NULL，则不使用提前停止。

maximize

如果设置了 feval 和 early_stopping_rounds，则也必须设置此参数。当其为 TRUE 时，表示评估得分越大越好。此参数传递给 xgb.cb.early.stop() 回调函数。

save_period

如果不为 NULL，则模型每经过 save_period 轮次后保存到磁盘。0 表示在最后保存。保存由 xgb.cb.save.model() 回调函数处理。

save_name

定期保存的模型文件的名称或路径。

xgb_model

一个先前构建的模型，用于继续训练。可以是 xgb.Booster 类的对象、其原始数据或先前保存的模型文件的名称。

callbacks

用于在提升过程中执行各种任务的回调函数列表。请参阅 xgb.Callback()。根据参数值，会自动创建一些回调函数。用户可以提供现有或自己的回调方法来自定义训练过程。

请注意，某些回调函数可能会尝试在结果模型对象中留下属性，例如评估日志（data.table 对象） - 请注意，这些对象作为 R 属性保留，因此在使用 XGBoost 自己的序列化函数（如 xgb.save()）时不会被保存（但使用 R 序列化函数（如 saveRDS()）时会保留）。

...

未使用。

在之前的 XGBoost 版本中属于此函数的一些参数目前已弃用或已重命名。如果传递了已弃用或已重命名的参数，将（默认情况下）抛出警告并使用其当前等效参数。如果使用 'strict mode' option，此警告将变为错误。

如果传递了既不是当前函数参数，也不是已弃用或已重命名参数的额外参数，则会根据“严格模式”选项抛出警告或错误。

重要提示： ... 将在未来版本中移除，所有当前的弃用警告将变为错误。请仅使用构成函数签名一部分的参数。

返回值

一个 xgb.Booster 类的对象。

详细信息

与 xgboost() 相比，xgb.train() 接口支持高级功能，如 evals、自定义目标和评估指标函数等。区别在于这些功能适用于 xgb.DMatrix 对象，且不遵循典型的 R 惯用法。

如果存在 OpenMP，则自动启用并行化。线程数也可以通过 nthread 参数手动指定。

在 XGBoost 语言绑定中，默认随机种子默认为零，而在 R 中，如果未手动提供参数 seed，它将通过 R 自身的随机数生成器生成一个随机种子，该生成器的种子又可以通过 set.seed 控制。如果传递了 seed，它将覆盖 R 的随机数生成器。

设置某些参数时，会自动创建以下回调函数

当 verbose > 0 且参数 print_every_n 被传递时，xgb.cb.print.evaluation() 会开启并使用该参数。
当 evals 存在时，xgb.cb.evaluation.log() 开启。
xgb.cb.early.stop()：当设置了 early_stopping_rounds 时。
xgb.cb.save.model()：当设置了 save_period > 0 时。

请注意，此函数返回的 xgb.Booster 类型对象与典型的 R 对象行为略有不同（它是一个“altrep”列表类），并且在内部提升器属性（仅限于可 jsonify 的数据）之间进行了区分，这些属性通过 xgb.attr() 访问，并通过 xgb.save() 等序列化函数在接口之间共享；以及 R 特定属性（通常是回调函数的结果），这些属性通过 attributes() 和 attr() 访问，仅在 R 接口中使用，仅在使用 R 的序列化函数（如 saveRDS()）时保留，并且不被 predict.xgb.Booster() 等函数使用。

请注意，会自动添加一个这样的 R 属性：params - 此属性从传递给此函数的 params 参数分配而来，仅用作提升器输入的参考，但在接受提升器对象的其他方法中不使用 - 因此，例如，更改提升器的配置需要调用 xgb.config<- 或 xgb.model.parameters<-，而简单地修改 attributes(model)$params$<...> 将不会产生任何效果。

参考文献

Tianqi Chen and Carlos Guestrin, "XGBoost: A Scalable Tree Boosting System", 22nd SIGKDD Conference on Knowledge Discovery and Data Mining, 2016, https://arxiv.org/abs/1603.02754

另请参阅

xgb.Callback(), predict.xgb.Booster(), xgb.cv()

示例

data(agaricus.train, package = "xgboost")
data(agaricus.test, package = "xgboost")

## Keep the number of threads to 1 for examples
nthread <- 1
data.table::setDTthreads(nthread)

dtrain <- with(
  agaricus.train, xgb.DMatrix(data, label = label, nthread = nthread)
)
dtest <- with(
  agaricus.test, xgb.DMatrix(data, label = label, nthread = nthread)
)
evals <- list(train = dtrain, eval = dtest)

## A simple xgb.train example:
param <- xgb.params(
  max_depth = 2,
  nthread = nthread,
  objective = "binary:logistic",
  eval_metric = "auc"
)
bst <- xgb.train(param, dtrain, nrounds = 2, evals = evals, verbose = 0)

## An xgb.train example where custom objective and evaluation metric are
## used:
logregobj <- function(preds, dtrain) {
   labels <- getinfo(dtrain, "label")
   preds <- 1/(1 + exp(-preds))
   grad <- preds - labels
   hess <- preds * (1 - preds)
   return(list(grad = grad, hess = hess))
}
evalerror <- function(preds, dtrain) {
  labels <- getinfo(dtrain, "label")
  err <- as.numeric(sum(labels != (preds > 0)))/length(labels)
  return(list(metric = "error", value = err))
}

# These functions could be used by passing them as 'objective' and
# 'eval_metric' parameters in the params list:
param <- xgb.params(
  max_depth = 2,
  nthread = nthread,
  objective = logregobj,
  eval_metric = evalerror
)
bst <- xgb.train(param, dtrain, nrounds = 2, evals = evals, verbose = 0)

# ... or as dedicated 'objective' and 'custom_metric' parameters of xgb.train:
bst <- xgb.train(
  within(param, rm("objective", "eval_metric")),
  dtrain, nrounds = 2, evals = evals,
  objective = logregobj, custom_metric = evalerror
)


## An xgb.train example of using variable learning rates at each iteration:
param <- xgb.params(
  max_depth = 2,
  learning_rate = 1,
  nthread = nthread,
  objective = "binary:logistic",
  eval_metric = "auc"
)
my_learning_rates <- list(learning_rate = c(0.5, 0.1))

bst <- xgb.train(
 param,
 dtrain,
 nrounds = 2,
 evals = evals,
 verbose = 0,
 callbacks = list(xgb.cb.reset.parameters(my_learning_rates))
)

## Early stopping:
bst <- xgb.train(
  param, dtrain, nrounds = 25, evals = evals, early_stopping_rounds = 3
)