预配置 LightGBM 模型对象,以便为给定的输入数据类型、预测类型和参数生成快速单行预测。

lgb.configure_fast_predict(
  model,
  csr = FALSE,
  start_iteration = NULL,
  num_iteration = NULL,
  type = "response",
  params = list()
)

参数

model

LightGBM 模型对象(类 lgb.Booster)。

对象将进行原地修改.

csr

预测函数是否将在稀疏 CSR 输入上调用。如果为 FALSE,则假定预测将在单行常规 R 矩阵上调用。

start_iteration

int 或 None,可选(默认为 None)。要预测的迭代的起始索引。如果为 None 或 <= 0,则从第一次迭代开始。

num_iteration

int 或 None,可选(默认为 None)。预测中迭代次数的限制。如果为 None,如果最佳迭代存在且 start_iteration 为 None 或 <= 0,则使用最佳迭代;否则,使用 start_iteration 开始的所有迭代。如果 <= 0,则使用 start_iteration 开始的所有迭代(无限制)。

type

要输出的预测类型。允许的类型有

  • "response":将根据优化的目标函数(取决于目标函数使用的链接函数)输出预测分数,并在应用任何必要的变换后输出 - 例如,对于 objective="binary",它将输出类别概率。

  • "class":对于分类目标,将输出预测概率最高的类别。对于其他目标,输出与 "response" 相同。请注意,"class" 不是 lgb.configure_fast_predict 支持的类型(有关详细信息,请参阅该函数的文档)。

  • "raw":将输出未变换的数值(来自 boosting 迭代结果的预测总和),给定目标函数就是由此生成 "response" 数值 - 例如,对于 objective="binary",这对应于对数几率 (log-odds)。对于许多目标(如 "regression"),由于未应用变换,输出将与 "response" 相同。

  • "leaf":将输出每个观测值在模型中每棵树上所属的终端节点/叶子的索引,输出为整数,每棵树占一列。

  • "contrib":将返回每个预测的每个特征贡献,包括截距(每个特征生成一列)。

请注意,如果使用自定义目标函数,类型 "class""response" 将不可用,并且将默认使用 "raw" 代替。

如果模型是通过函数 lightgbm 拟合的,并且将 factor 作为标签传递,则通过 params 而非此参数传递预测类型,可能会导致分类目标的 factor level 未正确应用于结果输出。

4.0.0 版本新增

params

附加的命名参数列表。请参阅 文档的“预测参数”部分,了解参数列表和有效值。如果这些参数与此函数的关键字参数值冲突,则 params 中的值优先。

返回值

与输入时传入的 model 相同,不可见地返回,其中存储了所需的配置,可在将来调用 predict.lgb.Booster 时使用。

详情

多次调用此函数并使用不同的参数,可能不会覆盖之前的配置,并可能导致未定义的行为。

在进行与配置类型不同的单行预测后,任何已保存的快速预测配置可能会丢失(类型 "response""class" 除外,它们可以随时相互切换而不会丢失配置)。

在某些情况下,为一种预测类型设置快速预测配置可能会导致预测函数即使在请求的预测类型与配置类型不同时,仍继续使用该配置进行单行预测。

请注意,此函数不接受参数 type="class" - 对于此类情况,可以将 type="response" 传递给此函数,然后将 type="class" 传递给 predict 函数 - 如果在 "response""class" 之间切换,快速配置不会丢失或更改。

配置在反序列化后不保留,因此必须在使用它的每个 R 进程中重新生成(例如,如果通过 readRDS 加载模型对象,之前存在的任何配置都将丢失)。

请求不同的预测类型或将参数传递给 predict.lgb.Booster 将导致它忽略快速预测配置,转而采用慢速路径(但请注意,现有配置可能不会总是被提供不同参数或预测类型所覆盖,因此当对与配置不同的内容进行单行预测时,务必检查输出是否符合预期)。

请注意,如果配置了非默认预测类型(例如叶子索引),那么在调用 predict.lgb.Booster 时也必须传递该类型,以便它使用配置。这也适用于 start_iterationnum_iteration,但在调用 predict 时,params 列表必须为空

关于特征贡献的预测不允许对 CSR 输入使用快速路径,因此,如果同时传递 csr=TRUEtype = "contrib",此函数将产生错误。

示例

# \donttest{
library(lightgbm)
data(mtcars)
X <- as.matrix(mtcars[, -1L])
y <- mtcars[, 1L]
dtrain <- lgb.Dataset(X, label = y, params = list(max_bin = 5L))
params <- list(
  min_data_in_leaf = 2L
  , num_threads = 2L
)
model <- lgb.train(
  params = params
 , data = dtrain
 , obj = "regression"
 , nrounds = 5L
 , verbose = -1L
)
lgb.configure_fast_predict(model)

x_single <- X[11L, , drop = FALSE]
predict(model, x_single)
#> Merc 280C 
#>  19.38465 

# Will not use it if the prediction to be made
# is different from what was configured
predict(model, x_single, type = "leaf")
#>           [,1] [,2] [,3] [,4] [,5]
#> Merc 280C    9    9    9    9    9
# }