企业官网建设流程全解析

XGBoost R 包索引约定完全指南：base-0 与 base-1 的转换机制

【免费下载链接】xgboostScalable, Portable and Distributed Gradient Boosting (GBDT, GBRT or GBM) Library, for Python, R, Java, Scala, C and more. Runs on single machine, Hadoop, Spark, Dask, Flink and DataFlow项目地址: https://gitcode.com/gh_mirrors/xg/xgboost

在 XGBoost 的 R 接口中，迭代轮数（boosting rounds）、树编号、分类特征的类别（categories）、特征编号等"可索引元素"遵循一套与 Python/C++ 略有不同的索引约定：底层 C++ 核心使用base-0（从 0 开始）索引，而 R 接口为了让用户获得更地道的 R 使用体验，在对外 API 上采用了base-1（从 1 开始）索引，并在内部完成双向转换。本文以 XGBoost 官方 R 文档 Handling of indexable elements 为骨架，结合 R 包源码（R-package/R 与 R-package/src/xgboost_R.cc），逐项拆解这套约定，帮助你在使用predict、xgb.slice.DMatrix、xgb.slice.Booster、xgb.cb.early.stop等函数时避免"差一错误"（off-by-one），并为开发新的 R 接口函数提供规范参考。

为什么存在两套索引体系

XGBoost 的核心是一个用 C++ 编写的库，它对"可索引元素"（包括模型中的 boosting 轮次/迭代/树、类别、分类特征的 levels 等）采用base-0 索引，并且认为区间/序列是左闭右开的——例如区间(0, 3)包含编号为 0、1、2 的前三个元素。这种约定可以从核心库的 C API 设计（include/xgboost/c_api.h）以及 R 包对 C 函数的封装调用中看出。

Python 接口天然沿用这一逻辑，因为 Python 的索引本身就是 base-0、左闭右开的。但 R 完全不同：

• base-1 索引：第一个元素编号为 1；
• 区间双闭：要表示"前三个元素"，写作(1, 3)，即元素 1、2、3。

为了让 R 用户获得地道的体验，XGBoost 的 R 接口在用户可见层面遵循 R 惯例，但在内部必须把所有这些数字转换回 C 接口使用的格式。问题的难点在于：模型是可序列化的，并且可以在不同接口之间加载——一个在 R 中训练的模型，可能被保存后在 Python 或 Scala 中读取，而不同接口的索引逻辑不同，因此转换规则必须清晰、一致、可复现。

以下是 R 接口所做的全部索引调整清单，也是本文的目录：

DMatrix 的行切片：在 C 层完成 base-0 转换

xgb.DMatrix的行切片是唯一一个转换发生在 C 层包装函数中的场景，其余所有转换都在 R 侧完成后才传给 C。

R 侧入口有两个等价形式：

dsub <- xgb.slice.DMatrix(dtrain, 1:42) # 等价于： dsub <- dtrain[1:42, ]

其实现位于 R-package/R/xgb.DMatrix.R：

xgb.slice.DMatrix <- function(object, idxset, allow_groups = FALSE) { if (!inherits(object, "xgb.DMatrix")) { stop("object must be xgb.DMatrix") } ret <- .Call(XGDMatrixSliceDMatrix_R, object, idxset, allow_groups) # ... 同步切片与行数相关的元数据（label、weight 等） } `[.xgb.DMatrix` <- function(object, idxset, colset = NULL) { xgb.slice.DMatrix(object, idxset) }

传入的idxset是一个整数数组，用户按 base-1 提供（例如1:42表示取前 42 行）。真正的 base-0 转换在 C 层包装函数XGDMatrixSliceDMatrix_R中完成，见 R-package/src/xgboost_R.cc，它对每个索引减 1 后再调用核心库的XGDMatrixSliceDMatrixEx。

切片后与行数等长的元数据（如label、weight、base_margin、qid等）会被同步切片；而group和qid这类分组信息不会被继承到子对象中（见 xgb.slice.DMatrix 的实现细节），需要用户自行处理。

Booster 的轮次切片：模拟 R 的seq语义

xgb.slice.Booster从一个已训练的 booster 中抽取指定轮次子集，生成一个新 booster。它的语义与 R 的seq(start, end, step)完全一致：base-1、双闭。

model <- xgb.train(data = dm, params = xgb.params(nthread = 1), nrounds = 5) model_slice <- xgb.slice.Booster(model, 1, 3) # 取第 1~3 轮

实现见 R-package/R/xgb.Booster.R：

xgb.slice.Booster <- function(model, start, end = xgb.get.num.boosted.rounds(model), step = 1L) { # 模拟 R 的 seq：当 step 不能恰好到达 end 时，截断 end if (end > start && step > 1) { d <- (end - start + 1) / step if (d != floor(d)) { end <- start + step * ceiling(d) - 1 } } return( .Call( XGBoosterSlice_R, xgb.get.handle(model), start - 1, # 左端减 1，转为 base-0 end, step ) ) }

这里的转换逻辑是：

1. 左端总是减 1（start - 1），把 base-1 的起点转成 base-0；
2. 右端是否调整取决于 step：当step > 1且序列无法恰好落在end上时，先按 Rseq的截断规则把end收缩到实际会取到的最后一个元素，再传给 C——因为核心库的区间是左闭右开，而 R 的seq是双闭，需要在"step 恰好整除"与"step 不能整除"两种情形下分别处理。

此外，R 接口还提供了[运算符重载（xgb.Booster.R）：

`[.xgb.Booster` <- function(x, i) { if (missing(i)) { return(xgb.slice.Booster(x, 1, 0)) # 全部轮次 } if (length(i) == 1) { return(xgb.slice.Booster(x, i, i)) # 单轮 } steps <- diff(i) if (any(steps < 0)) { stop("Can only slice booster with ascending sequences.") } if (length(unique(steps)) > 1) { stop("Can only slice booster with fixed-step sequences.") } return(xgb.slice.Booster(x, i[1L], i[length(i)], steps[1L])) }

即model[1:3]等价于xgb.slice.Booster(model, 1, 3)。注意索引序列必须是递增且等步长的，否则会报错。

切片底层调用核心库的XGBoosterSlice（xgboost_R.cc），相关的行为在测试 R-package/tests/testthat/test_booster_slicing.R 中有完整覆盖。

predict的iterationrange：只需调整左端

predict.xgb.Booster的参数iterationrange用于指定用模型的哪些轮次做预测，其语义同样模仿 R 的seq。由于它没有步长参数（只有 start 和 end），所以只需要把左端减 1 即可完成 base-0 转换。

# 使用前 20 轮做预测（第 1~20 轮） pred <- predict(bst, test$data, iterationrange = c(1, 20)) # 仅使用第 1 轮 pred1 <- predict(bst, test$data, iterationrange = c(1, 1))

实现见 R-package/R/xgb.Booster.R：

if (!is.null(iterationrange)) { if (is.character(iterationrange)) { stopifnot(iterationrange == "all") iterationrange <- c(0, 0) # "all"：全部轮次 } else { iterationrange[1] <- iterationrange[1] - 1 # base-0 indexing } } else { ## 未指定时：优先停在 best iteration；否则用全部轮次 best_iteration <- xgb.best_iteration(object) if (is.null(best_iteration)) { iterationrange <- c(0, 0) } else { iterationrange <- c(0, as.integer(best_iteration) + 1L) } }

值得注意的细节：当用户不传iterationrange时，R 接口读取 C 层存储的best_iteration（base-0），并用best_iteration + 1作为右开的端点传给 C（因为核心库区间左闭右开），从而保证预测恰好停在最优轮次。iterationrange只接受NULL、"all"或长度为 2 的数值向量；它对gblinearbooster 不生效，因为gblinear不保留 boosting 历史（见 predict.xgb.Booster 的文档）。

best_iteration：C 层属性保持 base-0，R 属性调整为 base-1

best_iteration（最优迭代轮次）是"双轨制"存储的：

• C 层 booster 属性（可通过xgb.attr(bst, "best_iteration")访问）使用base-0索引。由于 C 层属性在接口间共享、且被预测方法使用，为了兼容性它必须保持 base-0。predict等函数只查看这一份 C 层属性。
• R 属性（挂在 R 对象上的 attribute）如果存在，会被调整为base-1，以符合 R 惯例。

这一约定在早停回调 R-package/R/callbacks.R 中体现得最清楚。相关注释明确说明："best_iteration存储在 R 属性下时遵循 base-1 索引，因此它比 C 层的best_iteration大 1"。具体实现中：

# 回调内部：R 环境中的 best_iteration 是 base-1 best_iteration <- xgb.attr(model, 'best_iteration') if (NROW(best_iteration)) env$best_iteration <- as.numeric(best_iteration) + 1 # C(base-0) -> R(base-1) ... # 保存到 C 层属性时再减回来 best_iteration = env$best_iteration - 1, # convert to 0-based index

当save_best = TRUE时，回调还会用XGBoosterSliceAndReplace_R（xgboost_R.cc）把模型截断到最优轮次。需要留意的是：xgb.attr(bst, "best_iteration")读到的始终是C 层属性（base-0）——例如模型最优在"第 10 轮（R 计数）"，则读出的 C 层值为 9；而xgb.cv结果或 R 属性中的best_iteration则是 base-1 的 10。两者相差 1，使用时务必区分数据来源。

打印指标与模型快照：纯 R 侧的 base-1

除了best_iteration之外，其他涉及迭代轮数引用的场景（例如回调打印评估指标、保存模型快照时标注轮次）都遵循base-1 索引。这些引用完全在 R 代码中实现，因为 C 层函数并不处理这类逻辑——例如评估日志回调xgb.cb.evaluation.log、打印回调xgb.cb.print.evaluation中的iteration计数都是从 1 开始的（见 R-package/R/callbacks.R 与xgb.cv返回对象中的迭代记录）。

叶子/节点编号：保持 base-0

当使用predict(bst, newdata, predleaf = TRUE)预测每棵树的叶子索引时，返回的终端叶子/节点编号是 base-0，与 C 接口原始返回一致，不做任何转换。predleaf的结果是一个nsamples × ntrees的矩阵（多分类/多目标时列按group1的所有叶子、group2的所有叶子依次排列，见 predict.xgb.Booster 的返回值文档）。

这意味着 R 用户看到第一个叶子是 0，而不是 1。如果你要用叶子编号做特征工程（例如配合 xgb.create.features.R），需要自行适配 base-0 的叶子编号。

绘图中的树编号：DiagrammeR 路径用 base-1

在xgb.plot.tree等绘图功能中，树编号遵循 base-1 索引。但有一个重要前提：只有通过 R 接口自身的 DiagrammeR 对象处理路径生成的图才采用 base-1；当使用 C 层的 GraphVizdot格式生成器时（即直接调用xgb.dump生成dot文本），编号并不做 base-1 调整。

特征编号：重要性、JSON、树转表与 SHAP 均为 base-0

特征编号（feature numbers）在特征重要性、JSON 导出、树转表（trees-to-tables）以及 SHAP 输出中一律使用 base-0 索引：

• xgb.importance.R 返回的特征重要性表，其Feature列在无特征名时会以f0、f1…… 形式出现，对应 base-0 编号；
• xgb.model.dt.tree.R 输出的树结构表中，Feature列同样采用 base-0 编号（如f0表示第 0 个特征）；
• SHAP 相关输出（xgb.plot.shap.R）的列顺序对应 base-0 特征索引。

这与predcontrib返回的[nrows, nfeats+1]矩阵的列序一致（最后一列是 baseline）。

分类特征与分类标签：两处最容易踩坑的 base-0 约定

factor 类型自动转 base-0

R 中分类特征以factor类型表示，其内部编码是base-1。当分类特征以 Rfactor类型传入xgb.DMatrix时，转换会自动完成。核心实现在.process.df.for.dmatrix（R-package/R/xgb.DMatrix.R）：

lst <- lapply(df, function(col) { is_factor <- is.factor(col) col <- as.numeric(col) if (is_factor) { col <- col - 1 # factor 的 base-1 编码转成 base-0 } return(col) })

同时，如果未显式指定feature_types，data.frame 的列类型会自动推断：factor列 →"c"（categorical），integer列 →"int"，logical列 →"i"，numeric列 →"float"。

但请注意两个关键点：

1. 如果用户想手动以已编码整数的方式提供分类特征，这些整数必须已经是 base-0 编码（即从 0 开始）。通过feature_types = c("c", ...)手动声明分类列时，xgb.DMatrix 的文档 明确要求：分类特征必须编码为从 0 开始的整数，并且predict时也必须使用同一套编码。
2. factor的编码不会随模型保存。模型只记录分类列的"类型"（"c"）而不记录 levels 本身，因此在后续predict调用中，用户有责任保证 factor 列具有与训练时 DMatrix 构造相同的 levels（即相同的编码）。这一点在 xgb.DMatrix.R 与predict的文档（xgb.Booster.R）中反复强调。

输出中的分类 levels 也是 base-0

在绘图、JSON 导出、树转表等输出中，分类 levels（类别）使用 base-0 索引，无论这些特征进入模型时是整数还是factor类型。也就是说，R 用户在解释输出时，类别0对应 factor 的第 1 个 level。

DMatrix 的分类标签不做任何处理

与特征不同，DMatrix 的分类标签（label）不经过任何额外转换：用户必须直接提供 base-0 编码的标签。例如多分类任务中类别编号从 0 开始，这在 xgb.DMatrix 的 label 参数文档 中有明确说明：

# 多分类：标签必须从 0 开始编码 lb <- as.numeric(iris$Species) - 1 # 把 1/2/3 转成 0/1/2

类似的，predict 的多分类示例 中把 softmax 概率转回标签时也用max.col(pred) - 1来对齐 base-0 标签。

线性系数历史回调中的类索引：不做转换

当使用线性系数历史回调（xgb.cb.gblinear.history）获取特定类别的系数时，其类索引参数也不做任何转换——用户必须传入 base-0 的类索引。这样设计是为了与标签逻辑保持一致：传入的类索引k对应 DMatrixlabel字段中编码为k的那个类别。由于label本身是 base-0，这里保持 base-0 就不会产生错位。

为 R 接口新增功能时的索引规范

官方文档给出了明确的开发者守则（原文见 index_base.rst）：

为 R 接口新增的、接受可索引元素的功能，应当注意这些约定，并尽可能模仿 R 的行为。

也就是说，新增 API 时应遵循"对外像 R、对内转 base-0"的原则：用户可见的轮次/迭代/树编号尽量按 R 惯例（base-1、双闭区间），而在调用 C 层函数前完成转换；同时要明确区分哪些输出（如叶子编号、特征编号、分类 levels、类索引）刻意保持 base-0，避免用户对结果产生误解。相关的开发背景还可参考 adding_parameters.rst（核心库参数接入指南）与 migration_guide.rst（从旧版本迁移时的行为变化）。

实战速查：什么时候该用 1，什么时候该用 0

如果记不住细节，可以遵循两条最稳妥的规则：凡是以"轮次/迭代/树"为语义、且是 R 用户直接书写的参数（切片、iterationrange），按 R 的seq习惯从 1 开始；凡是模型内部生成并随模型保存/跨接口共享的数字（best_iterationC 属性、叶子编号、特征编号、分类 levels、标签、类索引），一律按 base-0 解读。在新增或包装 R 接口函数时，请参照 index_base.rst 中的约定表逐项核对，并参考 test_booster_slicing.R 与 test_dmatrix.R 中的测试用例验证边界行为。

【免费下载链接】xgboostScalable, Portable and Distributed Gradient Boosting (GBDT, GBRT or GBM) Library, for Python, R, Java, Scala, C and more. Runs on single machine, Hadoop, Spark, Dask, Flink and DataFlow项目地址: https://gitcode.com/gh_mirrors/xg/xgboost