XGBoost 预测详解：预测选项、输出形状、迭代切片与推理最佳实践-育师

XGBoost 预测详解：预测选项、输出形状、迭代切片与推理最佳实践

【免费下载链接】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 官方文档 doc/prediction.rst 为骨架，系统梳理 XGBoost 预测体系的完整图景：从predict家族的七种预测类型及其输出形状约定，到strict_shape、iteration_range、早停模型预测、base_margin全局偏置、分段预测缓存、就地预测（in-place prediction）、线程安全与隐私保护推理。读者阅读完本文后，将能准确预判任意模型组合下的输出维度、正确复现早停最优模型、规避并发推理的陷阱，并掌握在生产环境中选择预测接口的实战方案。

预测选项总览：`Booster.predict`的七种模式

XGBoost 的 Python 绑定中，所有预测入口都收敛于 Booster.predict。该方法通过一个内部args字典向 C 层传递预测类型，且同一时刻只允许一种预测类型生效（源码中通过assign_type校验，重复设置会抛出ValueError: One type of prediction at a time.）：

预测类型	`args["type"]`	功能说明
普通预测（默认）	`0`	输出经过目标函数变换后的预测值
`output_margin=True`	`1`	输出未变换的原始边际值（margin）
`pred_contribs=True`	`2`	输出 SHAP 特征贡献值（精确 TreeSHAP）
`pred_contribs=True, approx_contribs=True`	`3`	输出 SHAP 特征贡献值的近似估计（仅 CPU）
`pred_interactions=True`	`4`	输出 SHAP 特征交互值（精确）
`pred_interactions=True, approx_contribs=True`	`5`	输出 SHAP 交互值的近似估计（仅 CPU）
`pred_leaf=True`	`6`	输出每个样本在每棵树中的叶子索引

这段类型映射逻辑直接体现在 core.py 中：pred_contribs将类型置为2或3，pred_interactions置为4或5，pred_leaf置为6，随后通过XGBoosterPredictFromDMatrix调用 C 层，最终由_prediction_output按 C 层返回的 shape 信息重建 numpy 数组。

预测类型的关键语义

pred_contribs（SHAP 贡献值）：输出矩阵的最后一列是偏置项（bias），全部特征贡献之和等于该样本未变换的原始边际值。官方文档引用Lundberg et al. (2018)的 TreeSHAP 方法；当approx_contribs=False（默认）时，XGBoost 使用Wettenstein et al. (2026)描述的QuadratureTreeSHAP实现，在 CPU 与 GPU 上均给出精确的 TreeSHAP 归因；当approx_contribs=True时，CPU 上使用近似贡献方法，而GPU 预测器未实现近似贡献。
pred_interactions（SHAP 交互值）：每个特征对（含与自身的交互）的归因，沿最后一维求和可还原为对应的 SHAP 贡献值，整个矩阵之和等于原始边际值。
pred_leaf（叶子索引）：输出每个样本落在每棵树的叶子编号。注意叶子编号仅在同一棵树内唯一，不同树的相同编号不代表同一个叶子。

`strict_shape`：让输出维度可预测

自 1.4 版本起，XGBoost 新增了strict_shape参数，用于向用户承诺"输出维度只取决于预测类型，不随模型形态变化"。这对编写泛化推理代码（同一套代码处理二分类与多分类模型）至关重要。

各预测类型在`strict_shape=True`下的输出形状

以 doc/prediction.rst 的定义为准，假设使用xgboost.Booster：

预测模式	输出维度	形状
普通预测（`strict_shape=True`）	2 维	`(rows, groups)`。回归/生存/排序/二分类下`groups == 1`，等价于列向量；`multi:softprob`下`groups == 类别数`。`strict_shape=False`时可能是 1 维或 2 维
`output_margin=True`（`strict_shape=True`）	2 维	同普通预测，但`multi:softmax`因跳过变换，输出形状与`multi:softprob`一致
`pred_contribs=True`（`strict_shape=True`）	3 维	`(rows, groups, columns + 1)`。是否使用`approx_contribs`不影响形状
`pred_interactions=True`（`strict_shape=True`）	4 维	`(rows, groups, columns + 1, columns + 1)`
`pred_leaf=True`（`strict_shape=True`）	4 维	`(n_samples, n_iterations, n_classes, n_trees_in_forest)`，其中`n_trees_in_forest`由训练时的`num_parallel_tree`决定

当strict_shape=False时，pred_leaf输出为 2 维数组（后三维被拼接成一维），且若末维为 1 会被丢弃。scikit-learn 接口的apply方法默认strict_shape=False。

重要的限制：strict_shape不支持向量叶（vector-leaf）树，也不支持标量叶与向量叶混合的模型——因为这类模型每次迭代可能包含不同数量的树。对这些模型请使用strict_shape=False。

测试用例中的形状验证

仓库测试 python-package/xgboost/testing/predict.py 直接断言了这些形状契约：

leaf = _predict_leaf(booster, m, reference, strict_shape=True) assert leaf.shape == (rows, n_rounds, classes, n_parallel) # 使用 iteration_range 切片后 sliced = _predict_leaf(booster, m, reference, iteration_range=(0, n_iters), strict_shape=True) assert sliced.shape == (rows, n_iters, classes, n_parallel)

同时测试还覆盖了pred_leaf=True, strict_shape=True遇到向量叶模型时抛出ValueError（匹配"vector leaf trees"信息）的边界场景。

R 包中的对应行为

R 包在指定strict_shape时返回array，数值内容与 Python 一致，但R 数组按列优先（column-major）存储、Python numpy 按行优先（row-major），因此所有维度顺序反转。例如 Python 的predict_leaf输出为(n_samples, n_iterations, n_classes, n_trees_in_forest)，而 R 端strict_shape=TRUE输出为(n_trees_in_forest, n_classes, n_iterations, n_samples)。

R 包 predict 方法文档还补充了strict_shape=FALSE时的细节：回归/二分类返回长度为nrows的向量；多分类返回[nrows, ngroups]矩阵；multi:softmax默认输出最可能类别（长度为nrows的向量）而非逐类概率；多分类的predcontrib输出[nrows, ngroups, nfeats+1]；predinteraction输出[nrows, nfeats+1, nfeats+1]（非多分类）或 4 维数组（多分类）。此外 R 包还提供avoid_transpose参数，置TRUE时所有维度逆序输出。

`iteration_range`：按迭代切片预测

iteration_range类似模型切片（model slicing），但并不真正切分模型，而是仅用指定区间内的树生成预测。由于多分类与随机森林的存在，每轮迭代创建的树数量为：

trees_i = num_class × num_parallel_tree

官方文档给出的实例：训练一个含 4 棵并行树（num_parallel_tree=4）的增强随机森林，数据集为 3 分类。若只想用前 2 轮迭代的树做预测，应传iteration_range=(0, 2)，此时实际参与预测的树为前2 × 3 × 4 = 24棵。区间的语义是半开区间[begin, end)，与 Python 切片一致。

从 C 层看，src/c_api/c_api.cc 将iteration_begin/iteration_end解析后传入learner->Predict(...)；当iteration_end == iteration_begin（即(0, 0)默认值）时，n_rounds被重置为BoostedRounds()，表示使用全部树。另外该文件明确指出ntree_limit已不再支持，请改用iteration_begin与iteration_end（Python 侧即iteration_range参数）。

早停模型的预测行为差异

使用早停训练模型时，原生 Python 接口与 sklearn/R 接口存在不一致的行为，这是最容易踩坑的地方：

R 与 sklearn 接口：默认自动使用best_iteration，即预测来自最优模型（最佳迭代处的模型）。
原生 Python 接口：Booster.predict与Booster.inplace_predict默认使用完整模型（包含早停后的多余轮次）。

要在原生接口复现"最优模型预测"，需要手动组合best_iteration与iteration_range：

bst = xgb.train(params, dtrain, num_boost_round=100, evals=[(dtest, "test")], early_stopping_rounds=10) # 使用最优迭代处的模型做预测 pred = bst.predict(dtest, iteration_range=(0, bst.best_iteration + 1))

best_iteration属性定义于 core.py，仅在启用早停时可用，否则抛出AttributeError。另外xgboost.callback.EarlyStopping的save_best参数也很实用：置True时训练回调会在结束时把模型截断到best_iteration + 1轮并保留best_iteration属性，之后直接用完整模型预测即可。实现见 callback.py：model = model[: best_iteration + 1]。注意save_best仅支持树方法（不支持gblinear），且对cv函数不适用（不返回模型）。

`base_score`与`base_margin`：全局偏置与迁移学习

XGBoost 有两个指定模型全局偏置的途径：

base_score：训练参数，属于模型的一部分。
base_margin：DMatrix的元数据（meta data），在 sklearn 接口中可通过fit方法设置。

两者的关系：如果提供了base_margin，则base_score被忽略。base_margin的典型用途是"基于其他模型继续训练"——例如先用线性模型输出作为偏置，再在其上叠加提升树，这正是官方 boost_from_prediction.py 示例所展示的"boosting from predictions"工作流。

仓库测试 run_base_margin_vs_base_score 验证了二者间的替代关系：构造DMatrix(X, y, base_margin=margin)后，即使训练参数里设置base_score=0.2，实际生效的仍是base_margin。

分段预测：结果缓存机制

使用原生接口配合DMatrix时，预测结果可以分段缓存（staged prediction）。例如先对前 4 棵树做预测，再对 8 棵树预测：

pred_4 = bst.predict(dtest, iteration_range=(0, 4)) # 前 4 棵树 pred_8 = bst.predict(dtest, iteration_range=(0, 8)) # 复用前 4 棵的缓存

第一次预测后，前 4 棵树的结果被缓存；第二次预测 8 棵树时，XGBoost 复用上次的缓存结果，只增量计算第 5～8 棵。缓存会在以下情况自动失效：

下一次predict、train或eval调用发生时；
缓存的DMatrix对象过期（例如超出作用域并被语言运行时垃圾回收）。

这也是原生predict与inplace_predict的重要区别之一——inplace_predict不做结果缓存（见 core.py 的文档说明）。

就地预测（in-place prediction）：绕开 DMatrix 构建

传统上 XGBoost 只接受DMatrix进行预测，sklearn 等封装在内部完成DMatrix的构建。Booster.inplace_predict旨在绕过DMatrix构建这一耗时耗内存的环节，适合简单推理任务，其功能受限但通常够用。

支持的数据类型

inplace_predict接受常见 Python 数据类型而非DMatrix，从 core.py 的分支逻辑可看到完整的支持清单：

numpy.ndarray（走XGBoosterPredictFromDense）
scipy.sparse.csr_matrix（走XGBoosterPredictFromCSR）
cudf.DataFrame/ cupy 数组（走 CUDA 路径，输出cupy.ndarray）
pandas DataFrame/Series、polars DataFrame/Series、Arrow Table（走列式XGBoosterPredictFromColumnar）
Python list / tuple（内部转为 numpy 数组）

其他类型会抛出TypeError: Data type: ... not supported by inplace prediction.

关键参数与注意事项

bst.inplace_predict( data, # numpy / scipy.sparse.csr_matrix / cudf.DataFrame 等 iteration_range=(0, 10), # 与 predict 语义一致 predict_type="value", # 或 "margin"，输出原始边际值 missing=np.nan, # 缺失值表示 validate_features=True, base_margin=None, # 1.4 起支持 strict_shape=False, # 1.4 起支持 )

输出类型随输入类型变化：输入在 GPU 上时返回cupy.ndarray，否则返回numpy.ndarray（源码最后以_prediction_output(shape, dims, preds, True)的第四个参数标记是否 GPU 输出）。
若输入数据的设备序号与 booster 配置的设备不匹配，数据会被拷贝到 booster 所在设备，例如booster.set_param({"device": "cuda:0"})配合 cupy 数组使用。

线程安全：什么能并发，什么不能

自 1.4 版本起，当底层 booster 是gbtree或dart（即树模型）时，所有预测函数都是线程安全的，包括带 SHAP 值计算等各种参数的普通predict以及inplace_predict。inplace_predict的文档还特别说明"多线程仅调用inplace_predict是安全且无锁的"。

但安全性只覆盖预测本身。若在一个线程中训练模型、在另一个线程中用它做预测，行为是未定义的。这种场景比想象中更容易出现——例如在预测函数内部误调set_params：

def predict_fn(clf: xgb.XGBClassifier, X): X = preprocess(X) clf.set_params(n_jobs=1) # NOT safe! 修改模型配置 return clf.predict_proba(X, iteration_range=(0, 10)) with ThreadPoolExecutor(max_workers=10) as e: e.submit(predict_fn, ...)

正确做法是把训练/参数修改与预测彻底隔离：在线程池外完成训练与参数设置，池内只做只读的predict/inplace_predict调用。

隐私保护预测：全同态加密推理

XGBoost 社区生态中，Zama 开发的第三方开源库Concrete ML提供了与 XGBoost 类似的梯度提升类，但通过**全同态加密（Fully Homomorphic Encryption, FHE）**直接在加密数据上进行预测。典型工作流如下（来自 doc/prediction.rst 的完整示例）：

from sklearn.datasets import make_classification from sklearn.model_selection import train_test_split from concrete.ml.sklearn import XGBClassifier x, y = make_classification(n_samples=100, class_sep=2, n_features=30, random_state=42) X_train, X_test, y_train, y_test = train_test_split( x, y, test_size=10, random_state=42 ) # 明文训练并量化权重 model = XGBClassifier() model.fit(X_train, y_train) # 明文模拟预测 y_pred_clear = model.predict(X_test) # 编译为 FHE 电路 model.compile(X_train) # 生成密钥 model.fhe_circuit.keygen() # 在加密输入上执行推理！ y_pred_fhe = model.predict(X_test, fhe="execute") print("In clear :", y_pred_clear) print("In FHE :", y_pred_fhe) print(f"Similarity: {int((y_pred_fhe == y_pred_clear).mean()*100)}%")

该方案的四个阶段依次为：明文训练 → 权重量化 → FHE 电路编译 → 密钥生成与加密推理。更完整的资料可参考 Concrete ML 官方文档。

实战决策指南

综合以上内容，为生产推理场景给出如下选型建议：

输出形状可预期性优先：统一开启strict_shape=True，让推理代码只依赖预测类型而非模型形态；仅在遇到向量叶模型时回退到strict_shape=False。
简单推理优先用inplace_predict：绕开DMatrix构建开销；需要分段缓存、需要pred_contribs/pred_leaf等高级预测类型时，改用predict+DMatrix。
早停模型复现最优结果：原生接口必须显式传iteration_range=(0, best_iteration + 1)，或训练时用EarlyStopping(save_best=True)直接截断模型；sklearn/R 接口则默认已使用最优迭代。
并发推理：只读的预测调用（含 SHAP）可放心多线程；严禁在预测路径上修改模型参数或与训练并发。
可解释性：需要逐特征归因用pred_contribs（默认精确 TreeSHAP，CPU/GPU 通用）；需要特征交互分析用pred_interactions；GPU 上目前不支持近似贡献模式。

XGBoost 预测详解：预测选项、输出形状、迭代切片与推理最佳实践