Python API 参考 

注释

从 0.23 版本开始，调用回归器上的 score 时使用的 $R^2$ 分数会使用 multioutput='uniform_average'，以保持与 r2_score() 的默认值一致。这会影响所有多输出回归器（除了 MultiOutputRegressor）的 score 方法。

set_fit_request(*, base_margin='$UNCHANGED$', base_margin_eval_set='$UNCHANGED$', eval_set='$UNCHANGED$', feature_weights='$UNCHANGED$', sample_weight='$UNCHANGED$', sample_weight_eval_set='$UNCHANGED$', verbose='$UNCHANGED$', xgb_model='$UNCHANGED$')

配置是否应请求将元数据传递给 fit 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 fit。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 fit。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 base_margin 参数的元数据路由。
base_margin_eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 base_margin_eval_set 参数的元数据路由。
eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 eval_set 参数的元数据路由。
feature_weights (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 feature_weights 参数的元数据路由。
sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight 参数的元数据路由。
sample_weight_eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight_eval_set 参数的元数据路由。
verbose (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 verbose 参数的元数据路由。
xgb_model (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 xgb_model 参数的元数据路由。
self (XGBRegressor)

返回:

self – 更新后的对象。

返回类型:

set_params(**params)

设置此估计器的参数。修改 sklearn 方法以允许未知关键字参数。这允许使用 sklearn 网格搜索中未定义为成员变量的全部 xgboost 参数。

返回类型:: self
参数:: params (Any)

set_predict_request(*, base_margin='$UNCHANGED$', iteration_range='$UNCHANGED$', output_margin='$UNCHANGED$', validate_features='$UNCHANGED$')

配置是否应请求将元数据传递给 predict 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 predict。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 predict。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 base_margin 参数的元数据路由。
iteration_range (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 iteration_range 参数的元数据路由。
output_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 output_margin 参数的元数据路由。
validate_features (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 validate_features 参数的元数据路由。
self (XGBRegressor)

返回:

self – 更新后的对象。

返回类型:

set_score_request(*, sample_weight='$UNCHANGED$')

配置是否应请求将元数据传递给 score 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 score。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 score。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – score 方法中 sample_weight 参数的元数据路由。
self (XGBRegressor)

返回:

self – 更新后的对象。

返回类型:

class xgboost.XGBClassifier(*, objective='binary:logistic', **kwargs)

Bases: ClassifierMixin, XGBModel

XGBoost 分类功能的 Scikit-learn API 实现。有关更多信息，请参阅使用 Scikit-Learn 估计器接口。

参数:

n_estimators (Optional[int]) – 提升轮数。
max_depth (Optional[int]) – 基础学习器的最大树深度。
max_leaves (Optional[int]) – 最大叶子数；0 表示无限制。
max_bin (Optional[int]) – 如果使用基于直方图的算法，则为每个特征的最大箱数。
grow_policy (Optional[str]) –
树增长策略。
- depthwise：优先在最接近节点的节点进行拆分，
- lossguide：优先在损失变化最大的节点进行拆分。
learning_rate (Optional[float]) – 提升学习率（xgb 的 “eta”）。
verbosity (Optional[int]) – 详细程度。有效值为 0（静默）- 3（调试）。
objective (Union[str, xgboost.sklearn._SklObjWProto, Callable[[Any, Any], Tuple[numpy.ndarray, numpy.ndarray]], NoneType]) –
指定学习任务和相应的学习目标或自定义目标函数。

对于自定义目标，请参阅 Custom Objective and Evaluation Metric 和 Custom objective and metric 以获取更多信息，以及函数签名的结尾说明。
booster (Optional[str]) – 指定要使用的 booster：gbtree、gblinear 或 dart。
tree_method (Optional[str]) – 指定要使用的树方法。默认为 auto。如果将此参数设置为 default，XGBoost 将选择可用的最保守选项。建议参考参数文档 tree method 来学习此选项。
n_jobs (Optional[int]) – 用于运行 xgboost 的并行线程数。当与其他 Scikit-Learn 算法（如网格搜索）一起使用时，您可以选择并行化哪个算法并平衡线程。创建线程争用会显著减慢两个算法的速度。
gamma (Optional[float]) – (min_split_loss) 在树的叶节点上进行进一步分区所需的最小损失减少。
min_child_weight (Optional[float]) – 子节点中所需的实例权重（Hessian）的最小总和。
max_delta_step (Optional[float]) – 我们允许每棵树的权重估计的最大 delta 步长。
subsample (Optional[float]) – 训练实例的子采样比例。
sampling_method (Optional[str]) –
采样方法。仅用于 hist 树方法的 GPU 版本。
- uniform：均匀选择随机训练实例。
- gradient_based：以更高的概率选择随机训练实例，
  当梯度和 Hessian 值更大时。（参见 CatBoost）。
colsample_bytree (Optional[float]) – 构建每棵树时的列子采样比例。
colsample_bylevel (Optional[float]) – 每个级别的列子采样比例。
colsample_bynode (Optional[float]) – 每个拆分的列子采样比例。
reg_alpha (Optional[float]) – 权重的 L1 正则化项（xgb 的 alpha）。
reg_lambda (Optional[float]) – 权重的 L2 正则化项（xgb 的 lambda）。
scale_pos_weight (Optional[float]) – 正负权重之间的平衡。
base_score (Union[float, List[float], NoneType]) – 所有实例的初始预测分数，全局偏差。
random_state (Union[numpy.random.mtrand.RandomState, numpy.random._generator.Generator, int, NoneType]) –
随机数种子。

注意

使用带有 shotgun 更新器的 gblinear booster 是不确定的，因为它使用了 Hogwild 算法。
missing (float) – 数据中需要被视为缺失值的值。默认为 numpy.nan。
num_parallel_tree (Optional[int]) – 用于提升随机森林。
monotone_constraints (Union[Dict[str, int], str, NoneType]) – 变量单调性的约束。有关更多信息，请参阅 tutorial。
interaction_constraints (Union[str, List[Tuple[str]], NoneType]) – 交互约束，表示允许的交互。约束必须以嵌套列表的形式指定，例如 [[0, 1], [2, 3, 4]]，其中每个内部列表是允许相互交互的特征索引组。有关更多信息，请参阅 tutorial。
importance_type (Optional[str]) –
feature_importances_ 属性的特征重要性类型。
- 对于树模型，它是“gain”、“weight”、“cover”、“total_gain”或“total_cover”之一。
- fmap (str | PathLike) – 特征映射文件的名称。
device (Optional[str]) –

2.0.0 版本新增。

设备序号，可用选项是 cpu、cuda 和 gpu。
validate_parameters (Optional[bool]) – 针对未知参数发出警告。
enable_categorical (bool) – 有关详细信息，请参阅 DMatrix 的相同参数。
feature_types (Optional[Sequence[str]]) –

在 1.7.0 版本中添加。

用于在不构建 DataFrame 的情况下指定特征类型。有关详细信息，请参阅 DMatrix。
feature_weights (Optional[ArrayLike]) – 每个特征的权重，定义了在 colsample 使用时选择每个特征的概率。所有值必须大于 0，否则会引发 ValueError。
max_cat_to_onehot (Optional[int]) –

在版本 1.6.0 中添加。

注意

此参数是实验性的

用于决定 XGBoost 是否应使用独热编码拆分进行分类数据的阈值。当类别数量小于阈值时，将选择独热编码，否则类别将被划分为子节点。此外，需要设置 enable_categorical 以支持分类特征。有关详细信息，请参阅 Categorical Data 和 Parameters for Categorical Feature。
max_cat_threshold (Optional[int]) –

在 1.7.0 版本中添加。

注意

此参数是实验性的

每个拆分考虑的最大类别数。仅用于基于分区的拆分，以防止过拟合。此外，需要设置 enable_categorical 以支持分类特征。有关详细信息，请参阅 Categorical Data 和 Parameters for Categorical Feature。
multi_strategy (Optional[str]) –

2.0.0 版本新增。

注意

此参数正在开发中。

用于训练多目标模型的策略，包括多目标回归和多类别分类。有关更多信息，请参阅 Multiple Outputs。
- one_output_per_tree：每个目标一个模型。
- multi_output_tree：使用多目标树。
eval_metric (Union[str, List[Union[str, Callable]], Callable, NoneType]) –

在版本 1.6.0 中添加。

用于监视训练结果和早期停止的指标。它可以是字符串或字符串列表，作为 XGBoost 中预定义指标的名称（参见 XGBoost Parameters），sklearn.metrics 中的指标之一，或任何其他用户定义的、类似于 sklearn.metrics 的指标。

如果同时提供了自定义目标函数，则自定义指标应实现相应的反向链接函数。

与 scikit-learn 中常用的 scoring 参数不同，当提供可调用对象时，它被假定为一个成本函数，并且默认情况下 XGBoost 在早期停止时会最小化结果。

对于早期停止的高级用法，例如直接选择最大化而不是最小化，请参阅 xgboost.callback.EarlyStopping。

有关详细信息，请参阅 Custom Objective and Evaluation Metric 和 Custom objective and metric。
```
from sklearn.datasets import load_diabetes
from sklearn.metrics import mean_absolute_error
X, y = load_diabetes(return_X_y=True)
reg = xgb.XGBRegressor(
    tree_method="hist",
    eval_metric=mean_absolute_error,
)
reg.fit(X, y, eval_set=[(X, y)])
```
early_stopping_rounds (Optional[int]) –

在版本 1.6.0 中添加。
- 激活提前停止。验证指标需要每 early_stopping_rounds 轮（或多轮）至少提高一次才能继续训练。要求 fit() 中至少有一个 eval_set 项。
- 如果发生提前停止，模型将有两个附加属性：best_score 和 best_iteration。这些属性由 predict() 和 apply() 方法使用，以在推理过程中确定最佳树的数量。如果用户想要访问完整的模型（包括在提前停止后构建的树），他们可以在这些推理方法中指定 iteration_range。此外，其他实用工具，如模型绘图，也可以使用整个模型。
- 如果您希望在 best_iteration 之后丢弃树，可以考虑使用回调函数 xgboost.callback.EarlyStopping。
- 如果 eval_set 中有多个项，则将使用最后一项进行提前停止。如果 eval_metric 中有多个指标，则将使用最后一个指标进行提前停止。
callbacks (Optional[List[xgboost.callback.TrainingCallback]]) –
在每次迭代结束时应用的 callback 函数列表。可以使用预定义的 callback，通过 Callback API。

注意

callback 中的状态在训练期间不会保留，这意味着 callback 对象在重新初始化或深度复制之前无法用于多个训练会话。
```
for params in parameters_grid:
    # be sure to (re)initialize the callbacks before each run
    callbacks = [xgb.callback.LearningRateScheduler(custom_rates)]
    reg = xgboost.XGBRegressor(**params, callbacks=callbacks)
    reg.fit(X, y)
```
kwargs (Optional[Any]) –
XGBoost Booster 对象的关键字参数。参数的完整文档可以在此处找到。尝试通过构造函数参数和 **kwargs 字典同时设置一个参数将导致 TypeError。

注意

kwargs 不被 scikit-learn 支持

kwargs 不被 scikit-learn 支持。我们不保证通过此参数传递的参数会与 scikit-learn 正常交互。

注意

自定义目标函数

可以为 objective 参数提供自定义目标函数。在这种情况下，它应该具有签名 objective(y_true, y_pred) -> [grad, hess] 或 objective(y_true, y_pred, *, sample_weight) -> [grad, hess]

y_true: 形状为 [n_samples] 的 array_like
目标值

y_pred: 形状为 [n_samples] 的 array_like
预测值

sample_weight
可选的样本权重。

grad: 形状为 [n_samples] 的 array_like
每个样本点的梯度值。

hess: 形状为 [n_samples] 的 array_like
每个样本点的二阶导数（Hessian）值

请注意，如果自定义目标函数产生的 Hessian 值为负，这些值将被截断。如果目标函数是非凸的，也可以考虑使用期望的 Hessian（Fisher 信息）。

apply(X, iteration_range=None)

为每个样本返回每棵树的预测叶。如果模型是使用提前停止训练的，那么 best_iteration 会被自动使用。

参数:

X (Any) – 输入特征矩阵。有关支持的类型列表，请参阅标记。
iteration_range (Tuple[int | integer, int | integer] | None) – 请参阅 predict()。

返回:

X_leaves – 对于 X 中的每个数据点 x 以及每棵树，返回 x 最终所在的叶子的索引。叶子的编号在 [0; 2**(self.max_depth+1)) 范围内，可能存在编号间隙。

返回类型:

array_like，形状为 [n_samples, n_trees]

property best_iteration: int: 通过提前停止获得的最佳迭代次数。此属性是基于 0 的，例如，如果最佳迭代是第一轮，则 best_iteration 为 0。

property best_score: float: 通过提前停止获得的最佳分数。

property coef_: ndarray

系数属性

注意

系数仅对线性学习器定义

当选择线性模型作为基学习器（booster=gblinear）时，系数才被定义。对于其他基学习器类型，例如树学习器（booster=gbtree），则不定义。

返回:: coef_
返回类型:: 形状为 [n_features] 或 [n_classes, n_features] 的数组

evals_result()

返回评估结果。

如果将 eval_set 传递给 fit() 函数，您可以调用 evals_result() 来获取所有传递的 eval_sets 的评估结果。当 eval_metric 也被传递给 fit() 函数时，evals_result 将包含传递给 fit() 函数的 eval_metrics。

返回的评估结果是一个字典

{'validation_0': {'logloss': ['0.604835', '0.531479']},
 'validation_1': {'logloss': ['0.41965', '0.17686']}}

返回类型:: evals_result

property feature_importances_: ndarray

特征重要性属性，返回值取决于 importance_type 参数。当模型使用多类/多标签/多目标数据集进行训练时，特征重要性会针对所有目标进行“平均”。“平均”的定义基于重要性类型。例如，如果重要性类型是“total_gain”，则分数是所有树的每次分裂造成的损失变化的总和。

返回:

feature_importances_（形状为 [n_features] 的数组，多类情况除外）
线性模型，返回一个形状为 (n_features, n_classes) 的数组

property feature_names_in_: ndarray: 在 fit() 过程中看到的特征名称。仅当 X 的特征名称全部为字符串时才定义。

fit(X, y, *, sample_weight=None, base_margin=None, eval_set=None, verbose=True, xgb_model=None, sample_weight_eval_set=None, base_margin_eval_set=None, feature_weights=None)

拟合梯度提升分类器。

请注意，多次调用 fit() 会导致模型对象从头开始重新拟合。要从先前的检查点恢复训练，请显式传递 xgb_model 参数。

参数:

X (Any) –
输入特征矩阵。有关支持的类型列表，请参阅标记。

当 tree_method 设置为 hist 时，内部会使用 QuantileDMatrix 而不是 DMatrix 来节省内存。然而，当输入数据的设备与算法不匹配时，这会影响性能。例如，如果输入是 CPU 上的 numpy 数组，但训练时使用 cuda，则数据将首先在 CPU 上处理，然后传输到 GPU。
y (Any) – 标签
sample_weight (Any | None) – 样本权重
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
eval_set (Sequence[Tuple[Any, Any]] | None) – 一系列 (X, y) 对，用作验证集，将计算其指标。验证指标将帮助我们跟踪模型的性能。
verbose (bool | int | None) – 如果 verbose 为 True 且使用了评估集，则每次提升阶段在标准输出中打印在验证集上测量的评估指标。如果 verbose 是一个整数，则在每个 verbose 提升阶段打印评估指标。最后一个提升阶段 / 使用 early_stopping_rounds 找到的提升阶段也会被打印。
xgb_model (Booster | str | XGBModel | None) – 存储的 XGBoost 模型的文件名或要在训练前加载的 ‘Booster’ 实例 XGBoost 模型（允许继续训练）。
sample_weight_eval_set (Sequence[Any] | None) – 一个列表，形式为 [L_1, L_2, …, L_n]，其中每个 L_i 是一个类似数组的对象，存储第 i 个验证集的实例权重。
base_margin_eval_set (Sequence[Any] | None) – 一个列表，形式为 [M_1, M_2, …, M_n]，其中每个 M_i 是一个类似数组的对象，存储第 i 个验证集的基值（base margin）。
feature_weights (Any | None) –

已弃用（自 3.0.0 版本起）。

请使用 __init__() 或 set_params() 中的 feature_weights。

返回类型:

XGBClassifier

get_booster()

获取此模型的底层 xgboost Booster。

如果尚未调用 fit，这将引发异常

返回:: booster
返回类型:: 底层模型的 xgboost booster

get_metadata_routing()

获取此对象的元数据路由。

请查阅用户指南，了解路由机制的工作原理。

返回:: routing – 一个 MetadataRequest，封装了路由信息。
返回类型:: MetadataRequest

get_num_boosting_rounds()

获取 xgboost 提升轮数。

返回类型:: int

get_params(deep=True)

获取参数。

参数:: deep (bool)
返回类型:: Dict[str, Any]

get_xgb_params()

获取 xgboost 特定的参数。

返回类型:: Dict[str, Any]

property intercept_: ndarray

截距（偏置）属性

对于基于树的模型，返回值是 base_score。

返回:: intercept_
返回类型:: 形状为 (1,) 或 [n_classes] 的数组

load_model(fname)

模型以 XGBoost 内部格式保存，该格式在各种 XGBoost 接口之间通用。Python Booster 对象的辅助属性（如 feature_names）仅在使用 JSON 或 UBJSON（默认）格式时保存。此外，不属于模型本身的参数（如 metrics、max_depth 等）不会被保存，更多信息请参见 Model IO。

fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）

model.save_model("model.json")
model.load_model("model.json")

# or
model.save_model("model.ubj")
model.load_model("model.ubj")

# or
buf = model.save_raw()
model.load_model(buf)

参数:: num_boosted_rounds()
返回类型:: None

property n_features_in_: int: 在 fit() 过程中看到的特征数量。

predict(X, *, output_margin=False, validate_features=True, base_margin=None, iteration_range=None)

使用 X 进行预测。如果模型是使用提前停止训练的，那么 best_iteration 会被自动使用。该估计器默认使用 inplace_predict，如果数据和估计器之间的设备不匹配，则回退到使用 DMatrix。

注意

此函数仅对 gbtree 和 dart 线程安全。

参数:

X (Any) – 用于预测的数据。有关支持的类型列表，请参阅标记。
pred_leaf (bool) – 当此选项开启时，输出将是一个 (nsample, ntrees) 的矩阵，其中每条记录表示每个样本在每棵树中的预测叶子索引。请注意，树的叶子索引在每棵树中是唯一的，因此您可能会在树 1 和树 0 中都找到叶子 1。
training (bool) –
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) –
指定在预测中使用哪层树。例如，如果一个随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（半开区间）轮次中构建的森林。

版本 1.4.0 中新增。

返回类型:

预测

predict_proba(X, validate_features=True, base_margin=None, iteration_range=None)

预测 X 中每个样本属于给定类的概率。如果模型是使用提前停止训练的，那么 best_iteration 会被自动使用。该估计器默认使用 inplace_predict，如果数据和估计器之间的设备不匹配，则回退到使用 DMatrix。

注意

此函数仅对 gbtree 和 dart 线程安全。

参数:

X (Any) – 特征矩阵。有关支持的类型列表，请参阅标记。
training (bool) –
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) – 指定在预测中使用哪层树。例如，如果一个随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（半开区间）轮次中构建的森林。

返回:

一个形状为 (n_samples, n_classes) 的 numpy 数组，包含每个数据样本属于给定类的概率。

返回类型:

预测

save_model(fname)

fname (str | PathLike) – 输出文件名。

fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）

model.save_model("model.json")
# or
model.save_model("model.ubj")

参数:: save_raw(raw_format='ubj')
返回类型:: None

score(X, y, sample_weight=None)

返回提供的数据和标签上的准确率。

在多标签分类中，这是子集准确率，这是一个严格的指标，因为它要求正确预测每个样本的每个标签集。

参数:

X (array-like of shape (n_samples, n_features)) – 测试样本。
y (array-like of shape (n_samples,) or (n_samples, n_outputs)) – X 的真实标签。
sample_weight (array-like of shape (n_samples,), default=None) – 样本权重。

返回:

score – self.predict(X) 相对于 y 的平均准确率。

返回类型:

set_fit_request(*, base_margin='$UNCHANGED$', base_margin_eval_set='$UNCHANGED$', eval_set='$UNCHANGED$', feature_weights='$UNCHANGED$', sample_weight='$UNCHANGED$', sample_weight_eval_set='$UNCHANGED$', verbose='$UNCHANGED$', xgb_model='$UNCHANGED$')

配置是否应请求将元数据传递给 fit 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 fit。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 fit。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 base_margin 参数的元数据路由。
base_margin_eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 base_margin_eval_set 参数的元数据路由。
eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 eval_set 参数的元数据路由。
feature_weights (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 feature_weights 参数的元数据路由。
sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight 参数的元数据路由。
sample_weight_eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight_eval_set 参数的元数据路由。
verbose (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 verbose 参数的元数据路由。
xgb_model (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 xgb_model 参数的元数据路由。
self (XGBClassifier)

返回:

self – 更新后的对象。

返回类型:

set_params(**params)

设置此估计器的参数。修改 sklearn 方法以允许未知关键字参数。这允许使用 sklearn 网格搜索中未定义为成员变量的全部 xgboost 参数。

返回类型:: self
参数:: params (Any)

set_predict_proba_request(*, base_margin='$UNCHANGED$', iteration_range='$UNCHANGED$', validate_features='$UNCHANGED$')

配置是否应请求将元数据传递给 predict_proba 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 predict_proba。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 predict_proba。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict_proba 方法中 base_margin 参数的元数据路由。
iteration_range (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict_proba 方法中 iteration_range 参数的元数据路由。
validate_features (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict_proba 方法中 validate_features 参数的元数据路由。
self (XGBClassifier)

返回:

self – 更新后的对象。

返回类型:

set_predict_request(*, base_margin='$UNCHANGED$', iteration_range='$UNCHANGED$', output_margin='$UNCHANGED$', validate_features='$UNCHANGED$')

配置是否应请求将元数据传递给 predict 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 predict。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 predict。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 base_margin 参数的元数据路由。
iteration_range (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 iteration_range 参数的元数据路由。
output_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 output_margin 参数的元数据路由。
validate_features (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 validate_features 参数的元数据路由。
self (XGBClassifier)

返回:

self – 更新后的对象。

返回类型:

set_score_request(*, sample_weight='$UNCHANGED$')

配置是否应请求将元数据传递给 score 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 score。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 score。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – score 方法中 sample_weight 参数的元数据路由。
self (XGBClassifier)

返回:

self – 更新后的对象。

返回类型:

class xgboost.XGBRanker(*, objective='rank:ndcg', **kwargs)

Bases: XGBRankerMixIn, XGBModel

XGBoost 排序功能的 Scikit-learn API 实现。

有关简介，请参阅学习排序。

有关更多信息，请参阅使用 Scikit-Learn 估计器接口。

参数:

n_estimators (Optional[int]) – 梯度提升树的数量。等同于提升轮数。
max_depth (Optional[int]) – 基础学习器的最大树深度。
max_leaves (Optional[int]) – 最大叶子数；0 表示无限制。
max_bin (Optional[int]) – 如果使用基于直方图的算法，则为每个特征的最大箱数。
grow_policy (Optional[str]) –
树增长策略。
- depthwise：优先在最接近节点的节点进行拆分，
- lossguide：优先在损失变化最大的节点进行拆分。
learning_rate (Optional[float]) – 提升学习率（xgb 的 “eta”）。
verbosity (Optional[int]) – 详细程度。有效值为 0（静默）- 3（调试）。
objective (Union[str, xgboost.sklearn._SklObjWProto, Callable[[Any, Any], Tuple[numpy.ndarray, numpy.ndarray]], NoneType]) –
指定学习任务和相应的学习目标或自定义目标函数。

对于自定义目标，请参阅 Custom Objective and Evaluation Metric 和 Custom objective and metric 以获取更多信息，以及函数签名的结尾说明。
booster (Optional[str]) – 指定要使用的 booster：gbtree、gblinear 或 dart。
tree_method (Optional[str]) – 指定要使用的树方法。默认为 auto。如果将此参数设置为 default，XGBoost 将选择可用的最保守选项。建议参考参数文档 tree method 来学习此选项。
n_jobs (Optional[int]) – 用于运行 xgboost 的并行线程数。当与其他 Scikit-Learn 算法（如网格搜索）一起使用时，您可以选择并行化哪个算法并平衡线程。创建线程争用会显著减慢两个算法的速度。
gamma (Optional[float]) – (min_split_loss) 在树的叶节点上进行进一步分区所需的最小损失减少。
min_child_weight (Optional[float]) – 子节点中所需的实例权重（Hessian）的最小总和。
max_delta_step (Optional[float]) – 我们允许每棵树的权重估计的最大 delta 步长。
subsample (Optional[float]) – 训练实例的子采样比例。
sampling_method (Optional[str]) –
采样方法。仅用于 hist 树方法的 GPU 版本。
- uniform：均匀选择随机训练实例。
- gradient_based：以更高的概率选择随机训练实例，
  当梯度和 Hessian 值更大时。（参见 CatBoost）。
colsample_bytree (Optional[float]) – 构建每棵树时的列子采样比例。
colsample_bylevel (Optional[float]) – 每个级别的列子采样比例。
colsample_bynode (Optional[float]) – 每个拆分的列子采样比例。
reg_alpha (Optional[float]) – 权重的 L1 正则化项（xgb 的 alpha）。
reg_lambda (Optional[float]) – 权重的 L2 正则化项（xgb 的 lambda）。
scale_pos_weight (Optional[float]) – 正负权重之间的平衡。
base_score (Union[float, List[float], NoneType]) – 所有实例的初始预测分数，全局偏差。
random_state (Union[numpy.random.mtrand.RandomState, numpy.random._generator.Generator, int, NoneType]) –
随机数种子。

注意

使用带有 shotgun 更新器的 gblinear booster 是不确定的，因为它使用了 Hogwild 算法。
missing (float) – 数据中需要被视为缺失值的值。默认为 numpy.nan。
num_parallel_tree (Optional[int]) – 用于提升随机森林。
monotone_constraints (Union[Dict[str, int], str, NoneType]) – 变量单调性的约束。有关更多信息，请参阅 tutorial。
interaction_constraints (Union[str, List[Tuple[str]], NoneType]) – 交互约束，表示允许的交互。约束必须以嵌套列表的形式指定，例如 [[0, 1], [2, 3, 4]]，其中每个内部列表是允许相互交互的特征索引组。有关更多信息，请参阅 tutorial。
importance_type (Optional[str]) –
feature_importances_ 属性的特征重要性类型。
- 对于树模型，它是“gain”、“weight”、“cover”、“total_gain”或“total_cover”之一。
- fmap (str | PathLike) – 特征映射文件的名称。
device (Optional[str]) –

2.0.0 版本新增。

设备序号，可用选项是 cpu、cuda 和 gpu。
validate_parameters (Optional[bool]) – 针对未知参数发出警告。
enable_categorical (bool) – 有关详细信息，请参阅 DMatrix 的相同参数。
feature_types (Optional[Sequence[str]]) –

在 1.7.0 版本中添加。

用于在不构建 DataFrame 的情况下指定特征类型。有关详细信息，请参阅 DMatrix。
feature_weights (Optional[ArrayLike]) – 每个特征的权重，定义了在 colsample 使用时选择每个特征的概率。所有值必须大于 0，否则会引发 ValueError。
max_cat_to_onehot (Optional[int]) –

在版本 1.6.0 中添加。

注意

此参数是实验性的

用于决定 XGBoost 是否应使用独热编码拆分进行分类数据的阈值。当类别数量小于阈值时，将选择独热编码，否则类别将被划分为子节点。此外，需要设置 enable_categorical 以支持分类特征。有关详细信息，请参阅 Categorical Data 和 Parameters for Categorical Feature。
max_cat_threshold (Optional[int]) –

在 1.7.0 版本中添加。

注意

此参数是实验性的

每个拆分考虑的最大类别数。仅用于基于分区的拆分，以防止过拟合。此外，需要设置 enable_categorical 以支持分类特征。有关详细信息，请参阅 Categorical Data 和 Parameters for Categorical Feature。
multi_strategy (Optional[str]) –

2.0.0 版本新增。

注意

此参数正在开发中。

用于训练多目标模型的策略，包括多目标回归和多类别分类。有关更多信息，请参阅 Multiple Outputs。
- one_output_per_tree：每个目标一个模型。
- multi_output_tree：使用多目标树。
eval_metric (Union[str, List[Union[str, Callable]], Callable, NoneType]) –

在版本 1.6.0 中添加。

用于监视训练结果和早期停止的指标。它可以是字符串或字符串列表，作为 XGBoost 中预定义指标的名称（参见 XGBoost Parameters），sklearn.metrics 中的指标之一，或任何其他用户定义的、类似于 sklearn.metrics 的指标。

如果同时提供了自定义目标函数，则自定义指标应实现相应的反向链接函数。

与 scikit-learn 中常用的 scoring 参数不同，当提供可调用对象时，它被假定为一个成本函数，并且默认情况下 XGBoost 在早期停止时会最小化结果。

对于早期停止的高级用法，例如直接选择最大化而不是最小化，请参阅 xgboost.callback.EarlyStopping。

有关详细信息，请参阅 Custom Objective and Evaluation Metric 和 Custom objective and metric。
```
from sklearn.datasets import load_diabetes
from sklearn.metrics import mean_absolute_error
X, y = load_diabetes(return_X_y=True)
reg = xgb.XGBRegressor(
    tree_method="hist",
    eval_metric=mean_absolute_error,
)
reg.fit(X, y, eval_set=[(X, y)])
```
early_stopping_rounds (Optional[int]) –

在版本 1.6.0 中添加。
- 激活提前停止。验证指标需要每 early_stopping_rounds 轮（或多轮）至少提高一次才能继续训练。要求 fit() 中至少有一个 eval_set 项。
- 如果发生提前停止，模型将有两个附加属性：best_score 和 best_iteration。这些属性由 predict() 和 apply() 方法使用，以在推理过程中确定最佳树的数量。如果用户想要访问完整的模型（包括在提前停止后构建的树），他们可以在这些推理方法中指定 iteration_range。此外，其他实用工具，如模型绘图，也可以使用整个模型。
- 如果您希望在 best_iteration 之后丢弃树，可以考虑使用回调函数 xgboost.callback.EarlyStopping。
- 如果 eval_set 中有多个项，则将使用最后一项进行提前停止。如果 eval_metric 中有多个指标，则将使用最后一个指标进行提前停止。
callbacks (Optional[List[xgboost.callback.TrainingCallback]]) –
在每次迭代结束时应用的 callback 函数列表。可以使用预定义的 callback，通过 Callback API。

注意

callback 中的状态在训练期间不会保留，这意味着 callback 对象在重新初始化或深度复制之前无法用于多个训练会话。
```
for params in parameters_grid:
    # be sure to (re)initialize the callbacks before each run
    callbacks = [xgb.callback.LearningRateScheduler(custom_rates)]
    reg = xgboost.XGBRegressor(**params, callbacks=callbacks)
    reg.fit(X, y)
```
kwargs (Optional[Any]) –
XGBoost Booster 对象的关键字参数。参数的完整文档可以在此处找到。尝试通过构造函数参数和 **kwargs 字典同时设置一个参数将导致 TypeError。

注意

kwargs 不被 scikit-learn 支持

kwargs 不被 scikit-learn 支持。我们不保证通过此参数传递的参数会与 scikit-learn 正常交互。

注意

XGBRanker 目前不支持自定义目标函数。

注意

查询组信息仅在排序训练时需要，在预测时不需要。可以通过一次调用 predict() 来预测多个组。

当使用 group 参数拟合模型时，您的数据需要按查询组排序。group 是一个包含每个查询组大小的数组。

同样，当使用 qid 参数拟合模型时，数据应按查询索引排序，并且 qid 是一个包含每个训练样本查询索引的数组。

例如，如果您的原始数据如下所示：

qid

label

features

1

0

x_1

1

1

x_2

1

0

x_3

2

0

x_4

2

1

x_5

2

1

x_6

2

1

x_7

那么 fit() 方法可以使用 group 数组（[3, 4]）或者使用 qid（[1, 1, 1, 2, 2, 2, 2]）作为 qid 列来调用。此外，qid 可以是输入 X 的特殊列，而不是一个单独的参数，请参阅 fit() 获取更多信息。

apply(X, iteration_range=None)

为每个样本返回每棵树的预测叶。如果模型是使用提前停止训练的，那么 best_iteration 会被自动使用。

参数:

X (Any) – 输入特征矩阵。有关支持的类型列表，请参阅标记。
iteration_range (Tuple[int | integer, int | integer] | None) – 请参阅 predict()。

返回:

X_leaves – 对于 X 中的每个数据点 x 以及每棵树，返回 x 最终所在的叶子的索引。叶子的编号在 [0; 2**(self.max_depth+1)) 范围内，可能存在编号间隙。

返回类型:

array_like，形状为 [n_samples, n_trees]

property best_iteration: int: 通过提前停止获得的最佳迭代次数。此属性是基于 0 的，例如，如果最佳迭代是第一轮，则 best_iteration 为 0。

property best_score: float: 通过提前停止获得的最佳分数。

property coef_: ndarray

系数属性

注意

系数仅对线性学习器定义

当选择线性模型作为基学习器（booster=gblinear）时，系数才被定义。对于其他基学习器类型，例如树学习器（booster=gbtree），则不定义。

返回:: coef_
返回类型:: 形状为 [n_features] 或 [n_classes, n_features] 的数组

evals_result()

返回评估结果。

如果将 eval_set 传递给 fit() 函数，您可以调用 evals_result() 来获取所有传递的 eval_sets 的评估结果。当 eval_metric 也被传递给 fit() 函数时，evals_result 将包含传递给 fit() 函数的 eval_metrics。

返回的评估结果是一个字典

{'validation_0': {'logloss': ['0.604835', '0.531479']},
 'validation_1': {'logloss': ['0.41965', '0.17686']}}

返回类型:: evals_result

property feature_importances_: ndarray

特征重要性属性，返回值取决于 importance_type 参数。当模型使用多类/多标签/多目标数据集进行训练时，特征重要性会针对所有目标进行“平均”。“平均”的定义基于重要性类型。例如，如果重要性类型是“total_gain”，则分数是所有树的每次分裂造成的损失变化的总和。

返回:

feature_importances_（形状为 [n_features] 的数组，多类情况除外）
线性模型，返回一个形状为 (n_features, n_classes) 的数组

property feature_names_in_: ndarray: 在 fit() 过程中看到的特征名称。仅当 X 的特征名称全部为字符串时才定义。

fit(X, y, *, group=None, qid=None, sample_weight=None, base_margin=None, eval_set=None, eval_group=None, eval_qid=None, verbose=False, xgb_model=None, sample_weight_eval_set=None, base_margin_eval_set=None, feature_weights=None)

拟合梯度提升排序器

请注意，多次调用 fit() 会导致模型对象从头开始重新拟合。要从先前的检查点恢复训练，请显式传递 xgb_model 参数。

参数:

X (Any) –
特征矩阵。有关支持的类型列表，请参阅标记。

当它是 pandas.DataFrame 或 cudf.DataFrame 时，它可能包含一个名为 qid 的特殊列，用于指定查询索引。使用特殊列与使用 qid 参数相同，只是与 sklearn.model_selection.cross_validation() 等 sklearn 实用函数兼容。相同的约定也适用于 XGBRanker.score() 和 XGBRanker.predict()。

qid

feat_0

feat_1

0

$x_{00}$

$x_{01}$

1

$x_{10}$

$x_{11}$

1

$x_{20}$

$x_{21}$

当 tree_method 设置为 hist 时，内部会使用 QuantileDMatrix 而不是 DMatrix 来节省内存。然而，当输入数据的设备与算法不匹配时，这会影响性能。例如，如果输入是 CPU 上的 numpy 数组，但训练时使用 cuda，则数据将首先在 CPU 上处理，然后传输到 GPU。
y (Any) – 标签
group (Any | None) – 训练数据中每个查询组的大小。其长度应与训练数据中的查询组数量相同。如果设置为 None，则用户必须提供 qid。
qid (Any | None) – 每个训练样本的查询 ID。其长度应与 n_samples 相同。如果设置为 None，则用户必须提供 group 或 X 中的特殊列。
sample_weight (Any | None) –
查询组权重

注意

对于排序任务，权重是按组分配的

在排序任务中，每个查询组/ID 都会被分配一个权重（而不是每个数据点）。这是因为我们只关心每个组内数据点的相对顺序，因此为单个数据点分配权重是没有意义的。
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
eval_set (Sequence[Tuple[Any, Any]] | None) – 一系列 (X, y) 对，用作验证集，将计算其指标。验证指标将帮助我们跟踪模型的性能。
eval_group (Sequence[Any] | None) – 一个列表，其中 eval_group[i] 是包含 eval_set 中第 i 个对所有查询组大小的列表。
eval_qid (Sequence[Any] | None) – 一个列表，其中 eval_qid[i] 是包含 eval_set 中第 i 个对的查询 ID 数组。X 中的特殊列约定也适用于验证数据集。
verbose (bool | int | None) – 如果 verbose 为 True 且使用了评估集，则每次提升阶段在标准输出中打印在验证集上测量的评估指标。如果 verbose 是一个整数，则在每个 verbose 提升阶段打印评估指标。最后一个提升阶段 / 使用 early_stopping_rounds 找到的提升阶段也会被打印。
xgb_model (Booster | str | XGBModel | None) – 存储的 XGBoost 模型的文件名或要在训练前加载的 ‘Booster’ 实例 XGBoost 模型（允许继续训练）。
sample_weight_eval_set (Sequence[Any] | None) –
形式为 [L_1, L_2, …, L_n] 的列表，其中每个 L_i 是第 i 个验证集上的组权重列表。

注意

对于排序任务，权重是按组分配的

在排序任务中，每个查询组（而不是每个数据点）都会被分配一个权重。这是因为我们只关心每个组内数据点的相对顺序，因此为单个数据点分配权重是没有意义的。
base_margin_eval_set (Sequence[Any] | None) – 一个列表，形式为 [M_1, M_2, …, M_n]，其中每个 M_i 是一个类似数组的对象，存储第 i 个验证集的基值（base margin）。
feature_weights (Any | None) – 每个特征的权重，定义了在使用 colsample 时选择每个特征的概率。所有值必须大于 0，否则会抛出 ValueError。

返回类型:

XGBRanker

get_booster()

获取此模型的底层 xgboost Booster。

如果尚未调用 fit，这将引发异常

返回:: booster
返回类型:: 底层模型的 xgboost booster

get_metadata_routing()

获取此对象的元数据路由。

请查阅用户指南，了解路由机制的工作原理。

返回:: routing – 一个 MetadataRequest，封装了路由信息。
返回类型:: MetadataRequest

get_num_boosting_rounds()

获取 xgboost 提升轮数。

返回类型:: int

get_params(deep=True)

获取参数。

参数:: deep (bool)
返回类型:: Dict[str, Any]

get_xgb_params()

获取 xgboost 特定的参数。

返回类型:: Dict[str, Any]

property intercept_: ndarray

截距（偏置）属性

对于基于树的模型，返回值是 base_score。

返回:: intercept_
返回类型:: 形状为 (1,) 或 [n_classes] 的数组

load_model(fname)

模型以 XGBoost 内部格式保存，该格式在各种 XGBoost 接口之间通用。Python Booster 对象的辅助属性（如 feature_names）仅在使用 JSON 或 UBJSON（默认）格式时保存。此外，不属于模型本身的参数（如 metrics、max_depth 等）不会被保存，更多信息请参见 Model IO。

fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）

model.save_model("model.json")
model.load_model("model.json")

# or
model.save_model("model.ubj")
model.load_model("model.ubj")

# or
buf = model.save_raw()
model.load_model(buf)

参数:: num_boosted_rounds()
返回类型:: None

property n_features_in_: int: 在 fit() 过程中看到的特征数量。

predict(X, *, output_margin=False, validate_features=True, base_margin=None, iteration_range=None)

使用 X 进行预测。如果模型使用提前停止进行训练，则会自动使用 best_iteration。该估计器默认使用 inplace_predict，如果数据和估计器之间的设备不匹配，则回退到使用 DMatrix。

注意

此函数仅对 gbtree 和 dart 线程安全。

参数:

X (Any) – 用于预测的数据。有关支持的类型列表，请参阅标记。
pred_leaf (bool) – 当此选项开启时，输出将是一个 (nsample, ntrees) 的矩阵，其中每条记录表示每个样本在每棵树中的预测叶子索引。请注意，树的叶子索引在每棵树中是唯一的，因此您可能会在树 1 和树 0 中都找到叶子 1。
training (bool) –
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) –
指定在预测中使用哪层树。例如，如果一个随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（半开区间）轮次中构建的森林。

版本 1.4.0 中新增。

返回类型:

预测

save_model(fname)

fname (str | PathLike) – 输出文件名。

fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）

model.save_model("model.json")
# or
model.save_model("model.ubj")

参数:: save_raw(raw_format='ubj')
返回类型:: None

score(X, y)

使用最后一个评估指标评估数据分数。如果模型使用提前停止进行训练，则会自动使用 best_iteration。

参数:

X (Union[pd.DataFrame, cudf.DataFrame]) – 特征矩阵。一个带有特殊 qid 列的 DataFrame。
y (Any) – 标签

返回:

排序器的第一个评估指标的结果。

返回类型:

score

set_fit_request(*, base_margin='$UNCHANGED$', base_margin_eval_set='$UNCHANGED$', eval_group='$UNCHANGED$', eval_qid='$UNCHANGED$', eval_set='$UNCHANGED$', feature_weights='$UNCHANGED$', group='$UNCHANGED$', qid='$UNCHANGED$', sample_weight='$UNCHANGED$', sample_weight_eval_set='$UNCHANGED$', verbose='$UNCHANGED$', xgb_model='$UNCHANGED$')

配置是否应请求将元数据传递给 fit 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 fit。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 fit。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 base_margin 参数的元数据路由。
base_margin_eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 base_margin_eval_set 参数的元数据路由。
eval_group (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for eval_group parameter in fit。
eval_qid (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for eval_qid parameter in fit。
eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 eval_set 参数的元数据路由。
feature_weights (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 feature_weights 参数的元数据路由。
group (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for group parameter in fit。
qid (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for qid parameter in fit。
sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight 参数的元数据路由。
sample_weight_eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight_eval_set 参数的元数据路由。
verbose (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 verbose 参数的元数据路由。
xgb_model (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 xgb_model 参数的元数据路由。
self (XGBRanker)

返回:

self – 更新后的对象。

返回类型:

set_params(**params)

设置此估计器的参数。修改 sklearn 方法以允许未知关键字参数。这允许使用 sklearn 网格搜索中未定义为成员变量的全部 xgboost 参数。

返回类型:: self
参数:: params (Any)

set_predict_request(*, base_margin='$UNCHANGED$', iteration_range='$UNCHANGED$', output_margin='$UNCHANGED$', validate_features='$UNCHANGED$')

配置是否应请求将元数据传递给 predict 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 predict。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 predict。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 base_margin 参数的元数据路由。
iteration_range (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 iteration_range 参数的元数据路由。
output_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 output_margin 参数的元数据路由。
validate_features (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 validate_features 参数的元数据路由。
self (XGBRanker)

返回:

self – 更新后的对象。

返回类型:

class xgboost.XGBRFRegressor(*, learning_rate=1.0, subsample=0.8, colsample_bynode=0.8, reg_lambda=1e-05, **kwargs)

Bases: XGBRegressor

scikit-learn API for XGBoost random forest regression. See Using the Scikit-Learn Estimator Interface for more information.

参数:

n_estimators (Optional[int]) – Random forest 中要拟合的树的数量。
max_depth (Optional[int]) – 基础学习器的最大树深度。
max_leaves (Optional[int]) – 最大叶子数；0 表示无限制。
max_bin (Optional[int]) – 如果使用基于直方图的算法，则为每个特征的最大箱数。
grow_policy (Optional[str]) –
树增长策略。
- depthwise：优先在最接近节点的节点进行拆分，
- lossguide：优先在损失变化最大的节点进行拆分。
learning_rate (Optional[float]) – 提升学习率（xgb 的 “eta”）。
verbosity (Optional[int]) – 详细程度。有效值为 0（静默）- 3（调试）。
objective (Union[str, xgboost.sklearn._SklObjWProto, Callable[[Any, Any], Tuple[numpy.ndarray, numpy.ndarray]], NoneType]) –
指定学习任务和相应的学习目标或自定义目标函数。

对于自定义目标，请参阅 Custom Objective and Evaluation Metric 和 Custom objective and metric 以获取更多信息，以及函数签名的结尾说明。
booster (Optional[str]) – 指定要使用的 booster：gbtree、gblinear 或 dart。
tree_method (Optional[str]) – 指定要使用的树方法。默认为 auto。如果将此参数设置为 default，XGBoost 将选择可用的最保守选项。建议参考参数文档 tree method 来学习此选项。
n_jobs (Optional[int]) – 用于运行 xgboost 的并行线程数。当与其他 Scikit-Learn 算法（如网格搜索）一起使用时，您可以选择并行化哪个算法并平衡线程。创建线程争用会显著减慢两个算法的速度。
gamma (Optional[float]) – (min_split_loss) 在树的叶节点上进行进一步分区所需的最小损失减少。
min_child_weight (Optional[float]) – 子节点中所需的实例权重（Hessian）的最小总和。
max_delta_step (Optional[float]) – 我们允许每棵树的权重估计的最大 delta 步长。
subsample (Optional[float]) – 训练实例的子采样比例。
sampling_method (Optional[str]) –
采样方法。仅用于 hist 树方法的 GPU 版本。
- uniform：均匀选择随机训练实例。
- gradient_based：以更高的概率选择随机训练实例，
  当梯度和 Hessian 值更大时。（参见 CatBoost）。
colsample_bytree (Optional[float]) – 构建每棵树时的列子采样比例。
colsample_bylevel (Optional[float]) – 每个级别的列子采样比例。
colsample_bynode (Optional[float]) – 每个拆分的列子采样比例。
reg_alpha (Optional[float]) – 权重的 L1 正则化项（xgb 的 alpha）。
reg_lambda (Optional[float]) – 权重的 L2 正则化项（xgb 的 lambda）。
scale_pos_weight (Optional[float]) – 正负权重之间的平衡。
base_score (Union[float, List[float], NoneType]) – 所有实例的初始预测分数，全局偏差。
random_state (Union[numpy.random.mtrand.RandomState, numpy.random._generator.Generator, int, NoneType]) –
随机数种子。

注意

使用带有 shotgun 更新器的 gblinear booster 是不确定的，因为它使用了 Hogwild 算法。
missing (float) – 数据中需要被视为缺失值的值。默认为 numpy.nan。
num_parallel_tree (Optional[int]) – 用于提升随机森林。
monotone_constraints (Union[Dict[str, int], str, NoneType]) – 变量单调性的约束。有关更多信息，请参阅 tutorial。
interaction_constraints (Union[str, List[Tuple[str]], NoneType]) – 交互约束，表示允许的交互。约束必须以嵌套列表的形式指定，例如 [[0, 1], [2, 3, 4]]，其中每个内部列表是允许相互交互的特征索引组。有关更多信息，请参阅 tutorial。
importance_type (Optional[str]) –
feature_importances_ 属性的特征重要性类型。
- 对于树模型，它是“gain”、“weight”、“cover”、“total_gain”或“total_cover”之一。
- fmap (str | PathLike) – 特征映射文件的名称。
device (Optional[str]) –

2.0.0 版本新增。

设备序号，可用选项是 cpu、cuda 和 gpu。
validate_parameters (Optional[bool]) – 针对未知参数发出警告。
enable_categorical (bool) – 有关详细信息，请参阅 DMatrix 的相同参数。
feature_types (Optional[Sequence[str]]) –

在 1.7.0 版本中添加。

用于在不构建 DataFrame 的情况下指定特征类型。有关详细信息，请参阅 DMatrix。
feature_weights (Optional[ArrayLike]) – 每个特征的权重，定义了在 colsample 使用时选择每个特征的概率。所有值必须大于 0，否则会引发 ValueError。
max_cat_to_onehot (Optional[int]) –

在版本 1.6.0 中添加。

注意

此参数是实验性的

用于决定 XGBoost 是否应使用独热编码拆分进行分类数据的阈值。当类别数量小于阈值时，将选择独热编码，否则类别将被划分为子节点。此外，需要设置 enable_categorical 以支持分类特征。有关详细信息，请参阅 Categorical Data 和 Parameters for Categorical Feature。
max_cat_threshold (Optional[int]) –

在 1.7.0 版本中添加。

注意

此参数是实验性的

每个拆分考虑的最大类别数。仅用于基于分区的拆分，以防止过拟合。此外，需要设置 enable_categorical 以支持分类特征。有关详细信息，请参阅 Categorical Data 和 Parameters for Categorical Feature。
multi_strategy (Optional[str]) –

2.0.0 版本新增。

注意

此参数正在开发中。

用于训练多目标模型的策略，包括多目标回归和多类别分类。有关更多信息，请参阅 Multiple Outputs。
- one_output_per_tree：每个目标一个模型。
- multi_output_tree：使用多目标树。
eval_metric (Union[str, List[Union[str, Callable]], Callable, NoneType]) –

在版本 1.6.0 中添加。

用于监视训练结果和早期停止的指标。它可以是字符串或字符串列表，作为 XGBoost 中预定义指标的名称（参见 XGBoost Parameters），sklearn.metrics 中的指标之一，或任何其他用户定义的、类似于 sklearn.metrics 的指标。

如果同时提供了自定义目标函数，则自定义指标应实现相应的反向链接函数。

与 scikit-learn 中常用的 scoring 参数不同，当提供可调用对象时，它被假定为一个成本函数，并且默认情况下 XGBoost 在早期停止时会最小化结果。

对于早期停止的高级用法，例如直接选择最大化而不是最小化，请参阅 xgboost.callback.EarlyStopping。

有关详细信息，请参阅 Custom Objective and Evaluation Metric 和 Custom objective and metric。
```
from sklearn.datasets import load_diabetes
from sklearn.metrics import mean_absolute_error
X, y = load_diabetes(return_X_y=True)
reg = xgb.XGBRegressor(
    tree_method="hist",
    eval_metric=mean_absolute_error,
)
reg.fit(X, y, eval_set=[(X, y)])
```
early_stopping_rounds (Optional[int]) –

在版本 1.6.0 中添加。
- 激活提前停止。验证指标在每 early_stopping_rounds 轮中至少需要改进一次才能继续训练。要求在 fit() 的 eval_set 中至少有一个项。
- 如果发生提前停止，模型将有两个额外的属性：best_score 和 best_iteration。这些属性由 predict() 和 apply() 方法使用，以确定推理期间的最佳树数量。如果用户想访问完整的模型（包括提前停止后构建的树），他们可以在这些推理方法中指定 iteration_range。此外，模型绘图等其他实用程序也可以使用整个模型。
- 如果您希望在 best_iteration 之后丢弃树，可以考虑使用回调函数 xgboost.callback.EarlyStopping。
- 如果 eval_set 中有多个项，则将使用最后一项进行提前停止。如果 eval_metric 中有多个指标，则将使用最后一个指标进行提前停止。
callbacks (Optional[List[xgboost.callback.TrainingCallback]]) –
在每次迭代结束时应用的 callback 函数列表。可以使用预定义的 callback，通过 Callback API。

注意

callback 中的状态在训练期间不会保留，这意味着 callback 对象在重新初始化或深度复制之前无法用于多个训练会话。
```
for params in parameters_grid:
    # be sure to (re)initialize the callbacks before each run
    callbacks = [xgb.callback.LearningRateScheduler(custom_rates)]
    reg = xgboost.XGBRegressor(**params, callbacks=callbacks)
    reg.fit(X, y)
```
kwargs (Optional[Any]) –
XGBoost Booster 对象的关键字参数。参数的完整文档可以在此处找到。尝试通过构造函数参数和 **kwargs 字典同时设置一个参数将导致 TypeError。

注意

kwargs 不被 scikit-learn 支持

kwargs 不被 scikit-learn 支持。我们不保证通过此参数传递的参数会与 scikit-learn 正常交互。

注意

自定义目标函数

可以为 objective 参数提供自定义目标函数。在这种情况下，它应该具有签名 objective(y_true, y_pred) -> [grad, hess] 或 objective(y_true, y_pred, *, sample_weight) -> [grad, hess]

y_true: 形状为 [n_samples] 的 array_like
目标值

y_pred: 形状为 [n_samples] 的 array_like
预测值

sample_weight
可选的样本权重。

grad: 形状为 [n_samples] 的 array_like
每个样本点的梯度值。

hess: 形状为 [n_samples] 的 array_like
每个样本点的二阶导数（Hessian）值

请注意，如果自定义目标函数产生的 Hessian 值为负，这些值将被截断。如果目标函数是非凸的，也可以考虑使用期望的 Hessian（Fisher 信息）。

apply(X, iteration_range=None)

为每个样本返回每棵树的预测叶子节点。如果模型使用提前停止进行训练，则会自动使用 best_iteration。

参数:

X (Any) – 输入特征矩阵。有关支持的类型列表，请参阅标记。
iteration_range (Tuple[int | integer, int | integer] | None) – 请参阅 predict()。

返回:

X_leaves – 对于 X 中的每个数据点 x 以及每棵树，返回 x 最终所在的叶子的索引。叶子的编号在 [0; 2**(self.max_depth+1)) 范围内，可能存在编号间隙。

返回类型:

array_like，形状为 [n_samples, n_trees]

property best_iteration: int: 通过提前停止获得的最佳迭代次数。此属性是基于 0 的，例如，如果最佳迭代是第一轮，则 best_iteration 为 0。

property best_score: float: 通过提前停止获得的最佳分数。

property coef_: ndarray

系数属性

注意

系数仅对线性学习器定义

当选择线性模型作为基学习器（booster=gblinear）时，系数才被定义。对于其他基学习器类型，例如树学习器（booster=gbtree），则不定义。

返回:: coef_
返回类型:: 形状为 [n_features] 或 [n_classes, n_features] 的数组

evals_result()

返回评估结果。

如果向 fit() 函数传递了 eval_set，则可以调用 evals_result() 来获取所有传递的 eval_sets 的评估结果。当 eval_metric 也被传递给 fit() 函数时，evals_result 将包含传递给 fit() 函数的 eval_metrics。

返回的评估结果是一个字典

{'validation_0': {'logloss': ['0.604835', '0.531479']},
 'validation_1': {'logloss': ['0.41965', '0.17686']}}

返回类型:: evals_result

property feature_importances_: ndarray

特征重要性属性，返回值取决于 importance_type 参数。当模型使用多类/多标签/多目标数据集进行训练时，特征重要性会针对所有目标进行“平均”。“平均”的定义基于重要性类型。例如，如果重要性类型是“total_gain”，则分数是所有树的每次分裂造成的损失变化的总和。

返回:

feature_importances_（形状为 [n_features] 的数组，多类情况除外）
线性模型，返回一个形状为 (n_features, n_classes) 的数组

property feature_names_in_: ndarray: 在 fit() 过程中看到的特征名称。仅当 X 具有全为字符串的特征名称时才定义。

fit(X, y, *, sample_weight=None, base_margin=None, eval_set=None, verbose=True, xgb_model=None, sample_weight_eval_set=None, base_margin_eval_set=None, feature_weights=None)

拟合梯度提升模型。

请注意，多次调用 fit() 会导致模型对象从头开始重新拟合。要从先前的检查点恢复训练，请显式传递 xgb_model 参数。

参数:

X (Any) –
输入特征矩阵。有关支持的类型列表，请参阅标记。

当 tree_method 设置为 hist 时，内部会使用 QuantileDMatrix 而不是 DMatrix 来节省内存。然而，当输入数据的设备与算法不匹配时，这会影响性能。例如，如果输入是 CPU 上的 numpy 数组，但训练时使用 cuda，则数据将首先在 CPU 上处理，然后传输到 GPU。
y (Any) – 标签
sample_weight (Any | None) – 样本权重
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
eval_set (Sequence[Tuple[Any, Any]] | None) – 一系列 (X, y) 对，用作验证集，将计算其指标。验证指标将帮助我们跟踪模型的性能。
verbose (bool | int | None) – 如果 verbose 为 True 且使用了评估集，则每次提升阶段在标准输出中打印在验证集上测量的评估指标。如果 verbose 是一个整数，则在每个 verbose 提升阶段打印评估指标。最后一个提升阶段 / 使用 early_stopping_rounds 找到的提升阶段也会被打印。
xgb_model (Booster | str | XGBModel | None) – 存储的 XGBoost 模型的文件名或要在训练前加载的 ‘Booster’ 实例 XGBoost 模型（允许继续训练）。
sample_weight_eval_set (Sequence[Any] | None) – 一个列表，形式为 [L_1, L_2, …, L_n]，其中每个 L_i 是一个类似数组的对象，存储第 i 个验证集的实例权重。
base_margin_eval_set (Sequence[Any] | None) – 一个列表，形式为 [M_1, M_2, …, M_n]，其中每个 M_i 是一个类似数组的对象，存储第 i 个验证集的基值（base margin）。
feature_weights (Any | None) –

已弃用（自 3.0.0 版本起）。

建议在 __init__() 或 set_params() 中使用 feature_weights。

返回类型:

XGBRFRegressor

get_booster()

获取此模型的底层 xgboost Booster。

如果尚未调用 fit，这将引发异常

返回:: booster
返回类型:: 底层模型的 xgboost booster

get_metadata_routing()

获取此对象的元数据路由。

请查阅用户指南，了解路由机制的工作原理。

返回:: routing – 一个 MetadataRequest，封装了路由信息。
返回类型:: MetadataRequest

get_num_boosting_rounds()

获取 xgboost 提升轮数。

返回类型:: int

get_params(deep=True)

获取参数。

参数:: deep (bool)
返回类型:: Dict[str, Any]

get_xgb_params()

获取 xgboost 特定的参数。

返回类型:: Dict[str, Any]

property intercept_: ndarray

截距（偏置）属性

对于基于树的模型，返回值是 base_score。

返回:: intercept_
返回类型:: 形状为 (1,) 或 [n_classes] 的数组

load_model(fname)

模型以 XGBoost 内部格式保存，该格式在各种 XGBoost 接口之间通用。Python Booster 对象的辅助属性（如 feature_names）仅在使用 JSON 或 UBJSON（默认）格式时保存。此外，不属于模型本身的参数（如 metrics、max_depth 等）不会被保存，更多信息请参见 Model IO。

fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）

model.save_model("model.json")
model.load_model("model.json")

# or
model.save_model("model.ubj")
model.load_model("model.ubj")

# or
buf = model.save_raw()
model.load_model(buf)

参数:: num_boosted_rounds()
返回类型:: None

property n_features_in_: int: 在 fit() 过程中看到的特征数量。

predict(X, *, output_margin=False, validate_features=True, base_margin=None, iteration_range=None)

使用 X 进行预测。如果模型使用提前停止进行训练，则会自动使用 best_iteration。该估计器默认使用 inplace_predict，如果数据和估计器之间的设备不匹配，则回退到使用 DMatrix。

注意

此函数仅对 gbtree 和 dart 线程安全。

参数:

X (Any) – 用于预测的数据。有关支持的类型列表，请参阅标记。
pred_leaf (bool) – 当此选项开启时，输出将是一个 (nsample, ntrees) 的矩阵，其中每条记录表示每个样本在每棵树中的预测叶子索引。请注意，树的叶子索引在每棵树中是唯一的，因此您可能会在树 1 和树 0 中都找到叶子 1。
training (bool) –
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) –
指定在预测中使用哪层树。例如，如果一个随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（半开区间）轮次中构建的森林。

版本 1.4.0 中新增。

返回类型:

预测

save_model(fname)

fname (str | PathLike) – 输出文件名。

fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）

model.save_model("model.json")
# or
model.save_model("model.ubj")

参数:: save_raw(raw_format='ubj')
返回类型:: None

score(X, y, sample_weight=None)

返回测试数据的决定系数。

决定系数 $R^2$ 定义为 $(1 - \frac{u}{v})$，其中 $u$ 是残差平方和 ((y_true - y_pred)** 2).sum()，$v$ 是总平方和 ((y_true - y_true.mean()) ** 2).sum()。最佳得分是 1.0，也可能是负数（因为模型可能任意差）。一个始终预测 y 期望值而不考虑输入特征的常数模型将获得 0.0 的 $R^2$ 分数。

参数:

X (array-like of shape (n_samples, n_features)) – 测试样本。对于某些估计器，这可能是一个预先计算的核矩阵或一个包含通用对象的列表，其形状为 (n_samples, n_samples_fitted)，其中 n_samples_fitted 是估计器拟合所使用的样本数。
y (array-like of shape (n_samples,) or (n_samples, n_outputs)) – X 的真实值。
sample_weight (array-like of shape (n_samples,), default=None) – 样本权重。

返回:

score – self.predict(X) 相对于 y 的 $R^2$ 分数。

返回类型:

注释

从 0.23 版本开始，调用回归器上的 score 时使用的 $R^2$ 分数会使用 multioutput='uniform_average'，以保持与 r2_score() 的默认值一致。这会影响所有多输出回归器（除了 MultiOutputRegressor）的 score 方法。

set_fit_request(*, base_margin='$UNCHANGED$', base_margin_eval_set='$UNCHANGED$', eval_set='$UNCHANGED$', feature_weights='$UNCHANGED$', sample_weight='$UNCHANGED$', sample_weight_eval_set='$UNCHANGED$', verbose='$UNCHANGED$', xgb_model='$UNCHANGED$')

配置是否应请求将元数据传递给 fit 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 fit。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 fit。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 base_margin 参数的元数据路由。
base_margin_eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 base_margin_eval_set 参数的元数据路由。
eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 eval_set 参数的元数据路由。
feature_weights (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 feature_weights 参数的元数据路由。
sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight 参数的元数据路由。
sample_weight_eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight_eval_set 参数的元数据路由。
verbose (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 verbose 参数的元数据路由。
xgb_model (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 xgb_model 参数的元数据路由。
self (XGBRFRegressor)

返回:

self – 更新后的对象。

返回类型:

set_params(**params)

设置此估计器的参数。修改 sklearn 方法以允许未知关键字参数。这允许使用 sklearn 网格搜索中未定义为成员变量的全部 xgboost 参数。

返回类型:: self
参数:: params (Any)

set_predict_request(*, base_margin='$UNCHANGED$', iteration_range='$UNCHANGED$', output_margin='$UNCHANGED$', validate_features='$UNCHANGED$')

配置是否应请求将元数据传递给 predict 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 predict。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 predict。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 base_margin 参数的元数据路由。
iteration_range (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 iteration_range 参数的元数据路由。
output_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 output_margin 参数的元数据路由。
validate_features (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 validate_features 参数的元数据路由。
self (XGBRFRegressor)

返回:

self – 更新后的对象。

返回类型:

set_score_request(*, sample_weight='$UNCHANGED$')

配置是否应请求将元数据传递给 score 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 score。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 score。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – score 方法中 sample_weight 参数的元数据路由。
self (XGBRFRegressor)

返回:

self – 更新后的对象。

返回类型:

class xgboost.XGBRFClassifier(*, learning_rate=1.0, subsample=0.8, colsample_bynode=0.8, reg_lambda=1e-05, **kwargs)

Bases: XGBClassifier

scikit-learn API for XGBoost random forest classification. See Using the Scikit-Learn Estimator Interface for more information.

参数:

n_estimators (Optional[int]) – Random forest 中要拟合的树的数量。
max_depth (Optional[int]) – 基础学习器的最大树深度。
max_leaves (Optional[int]) – 最大叶子数；0 表示无限制。
max_bin (Optional[int]) – 如果使用基于直方图的算法，则为每个特征的最大箱数。
grow_policy (Optional[str]) –
树增长策略。
- depthwise：优先在最接近节点的节点进行拆分，
- lossguide：优先在损失变化最大的节点进行拆分。
learning_rate (Optional[float]) – 提升学习率（xgb 的 “eta”）。
verbosity (Optional[int]) – 详细程度。有效值为 0（静默）- 3（调试）。
objective (Union[str, xgboost.sklearn._SklObjWProto, Callable[[Any, Any], Tuple[numpy.ndarray, numpy.ndarray]], NoneType]) –
指定学习任务和相应的学习目标或自定义目标函数。

对于自定义目标，请参阅 Custom Objective and Evaluation Metric 和 Custom objective and metric 以获取更多信息，以及函数签名的结尾说明。
booster (Optional[str]) – 指定要使用的 booster：gbtree、gblinear 或 dart。
tree_method (Optional[str]) – 指定要使用的树方法。默认为 auto。如果将此参数设置为 default，XGBoost 将选择可用的最保守选项。建议参考参数文档 tree method 来学习此选项。
n_jobs (Optional[int]) – 用于运行 xgboost 的并行线程数。当与其他 Scikit-Learn 算法（如网格搜索）一起使用时，您可以选择并行化哪个算法并平衡线程。创建线程争用会显著减慢两个算法的速度。
gamma (Optional[float]) – (min_split_loss) 在树的叶节点上进行进一步分区所需的最小损失减少。
min_child_weight (Optional[float]) – 子节点中所需的实例权重（Hessian）的最小总和。
max_delta_step (Optional[float]) – 我们允许每棵树的权重估计的最大 delta 步长。
subsample (Optional[float]) – 训练实例的子采样比例。
sampling_method (Optional[str]) –
采样方法。仅用于 hist 树方法的 GPU 版本。
- uniform：均匀选择随机训练实例。
- gradient_based：以更高的概率选择随机训练实例，
  当梯度和 Hessian 值更大时。（参见 CatBoost）。
colsample_bytree (Optional[float]) – 构建每棵树时的列子采样比例。
colsample_bylevel (Optional[float]) – 每个级别的列子采样比例。
colsample_bynode (Optional[float]) – 每个拆分的列子采样比例。
reg_alpha (Optional[float]) – 权重的 L1 正则化项（xgb 的 alpha）。
reg_lambda (Optional[float]) – 权重的 L2 正则化项（xgb 的 lambda）。
scale_pos_weight (Optional[float]) – 正负权重之间的平衡。
base_score (Union[float, List[float], NoneType]) – 所有实例的初始预测分数，全局偏差。
random_state (Union[numpy.random.mtrand.RandomState, numpy.random._generator.Generator, int, NoneType]) –
随机数种子。

注意

使用带有 shotgun 更新器的 gblinear booster 是不确定的，因为它使用了 Hogwild 算法。
missing (float) – 数据中需要被视为缺失值的值。默认为 numpy.nan。
num_parallel_tree (Optional[int]) – 用于提升随机森林。
monotone_constraints (Union[Dict[str, int], str, NoneType]) – 变量单调性的约束。有关更多信息，请参阅 tutorial。
interaction_constraints (Union[str, List[Tuple[str]], NoneType]) – 交互约束，表示允许的交互。约束必须以嵌套列表的形式指定，例如 [[0, 1], [2, 3, 4]]，其中每个内部列表是允许相互交互的特征索引组。有关更多信息，请参阅 tutorial。
importance_type (Optional[str]) –
feature_importances_ 属性的特征重要性类型。
- 对于树模型，它是“gain”、“weight”、“cover”、“total_gain”或“total_cover”之一。
- fmap (str | PathLike) – 特征映射文件的名称。
device (Optional[str]) –

2.0.0 版本新增。

设备序号，可用选项是 cpu、cuda 和 gpu。
validate_parameters (Optional[bool]) – 针对未知参数发出警告。
enable_categorical (bool) – 有关详细信息，请参阅 DMatrix 的相同参数。
feature_types (Optional[Sequence[str]]) –

在 1.7.0 版本中添加。

用于在不构建 DataFrame 的情况下指定特征类型。有关详细信息，请参阅 DMatrix。
feature_weights (Optional[ArrayLike]) – 每个特征的权重，定义了在 colsample 使用时选择每个特征的概率。所有值必须大于 0，否则会引发 ValueError。
max_cat_to_onehot (Optional[int]) –

在版本 1.6.0 中添加。

注意

此参数是实验性的

用于决定 XGBoost 是否应使用独热编码拆分进行分类数据的阈值。当类别数量小于阈值时，将选择独热编码，否则类别将被划分为子节点。此外，需要设置 enable_categorical 以支持分类特征。有关详细信息，请参阅 Categorical Data 和 Parameters for Categorical Feature。
max_cat_threshold (Optional[int]) –

在 1.7.0 版本中添加。

注意

此参数是实验性的

每个拆分考虑的最大类别数。仅用于基于分区的拆分，以防止过拟合。此外，需要设置 enable_categorical 以支持分类特征。有关详细信息，请参阅 Categorical Data 和 Parameters for Categorical Feature。
multi_strategy (Optional[str]) –

2.0.0 版本新增。

注意

此参数正在开发中。

用于训练多目标模型的策略，包括多目标回归和多类别分类。有关更多信息，请参阅 Multiple Outputs。
- one_output_per_tree：每个目标一个模型。
- multi_output_tree：使用多目标树。
eval_metric (Union[str, List[Union[str, Callable]], Callable, NoneType]) –

在版本 1.6.0 中添加。

用于监视训练结果和早期停止的指标。它可以是字符串或字符串列表，作为 XGBoost 中预定义指标的名称（参见 XGBoost Parameters），sklearn.metrics 中的指标之一，或任何其他用户定义的、类似于 sklearn.metrics 的指标。

如果同时提供了自定义目标函数，则自定义指标应实现相应的反向链接函数。

与 scikit-learn 中常用的 scoring 参数不同，当提供可调用对象时，它被假定为一个成本函数，并且默认情况下 XGBoost 在早期停止时会最小化结果。

对于早期停止的高级用法，例如直接选择最大化而不是最小化，请参阅 xgboost.callback.EarlyStopping。

有关详细信息，请参阅 Custom Objective and Evaluation Metric 和 Custom objective and metric。
```
from sklearn.datasets import load_diabetes
from sklearn.metrics import mean_absolute_error
X, y = load_diabetes(return_X_y=True)
reg = xgb.XGBRegressor(
    tree_method="hist",
    eval_metric=mean_absolute_error,
)
reg.fit(X, y, eval_set=[(X, y)])
```
early_stopping_rounds (Optional[int]) –

在版本 1.6.0 中添加。
- 激活提前停止。验证指标在每 early_stopping_rounds 轮中至少需要改进一次才能继续训练。要求在 fit() 的 eval_set 中至少有一个项。
- 如果发生提前停止，模型将有两个额外的属性：best_score 和 best_iteration。这些属性由 predict() 和 apply() 方法使用，以确定推理期间的最佳树数量。如果用户想访问完整的模型（包括提前停止后构建的树），他们可以在这些推理方法中指定 iteration_range。此外，模型绘图等其他实用程序也可以使用整个模型。
- 如果您希望在 best_iteration 之后丢弃树，可以考虑使用回调函数 xgboost.callback.EarlyStopping。
- 如果 eval_set 中有多个项，则将使用最后一项进行提前停止。如果 eval_metric 中有多个指标，则将使用最后一个指标进行提前停止。
callbacks (Optional[List[xgboost.callback.TrainingCallback]]) –
在每次迭代结束时应用的 callback 函数列表。可以使用预定义的 callback，通过 Callback API。

注意

callback 中的状态在训练期间不会保留，这意味着 callback 对象在重新初始化或深度复制之前无法用于多个训练会话。
```
for params in parameters_grid:
    # be sure to (re)initialize the callbacks before each run
    callbacks = [xgb.callback.LearningRateScheduler(custom_rates)]
    reg = xgboost.XGBRegressor(**params, callbacks=callbacks)
    reg.fit(X, y)
```
kwargs (Optional[Any]) –
XGBoost Booster 对象的关键字参数。参数的完整文档可以在此处找到。尝试通过构造函数参数和 **kwargs 字典同时设置一个参数将导致 TypeError。

注意

kwargs 不被 scikit-learn 支持

kwargs 不被 scikit-learn 支持。我们不保证通过此参数传递的参数会与 scikit-learn 正常交互。

注意

自定义目标函数

可以为 objective 参数提供自定义目标函数。在这种情况下，它应该具有签名 objective(y_true, y_pred) -> [grad, hess] 或 objective(y_true, y_pred, *, sample_weight) -> [grad, hess]

y_true: 形状为 [n_samples] 的 array_like
目标值

y_pred: 形状为 [n_samples] 的 array_like
预测值

sample_weight
可选的样本权重。

grad: 形状为 [n_samples] 的 array_like
每个样本点的梯度值。

hess: 形状为 [n_samples] 的 array_like
每个样本点的二阶导数（Hessian）值

请注意，如果自定义目标函数产生的 Hessian 值为负，这些值将被截断。如果目标函数是非凸的，也可以考虑使用期望的 Hessian（Fisher 信息）。

apply(X, iteration_range=None)

返回每棵树每个样本的预测叶子节点。如果模型使用提前停止进行训练，则会自动使用 best_iteration。

参数:

X (Any) – 输入特征矩阵。有关支持的类型列表，请参阅标记。
iteration_range (Tuple[int | integer, int | integer] | None) – 请参阅 predict()。

返回:

X_leaves – 对于 X 中的每个数据点 x 以及每棵树，返回 x 最终所在的叶子的索引。叶子的编号在 [0; 2**(self.max_depth+1)) 范围内，可能存在编号间隙。

返回类型:

array_like，形状为 [n_samples, n_trees]

property best_iteration: int: 通过提前停止获得的最佳迭代次数。此属性是基于 0 的，例如，如果最佳迭代是第一轮，则 best_iteration 为 0。

property best_score: float: 通过提前停止获得的最佳分数。

property coef_: ndarray

系数属性

注意

系数仅对线性学习器定义

当选择线性模型作为基学习器（booster=gblinear）时，系数才被定义。对于其他基学习器类型，例如树学习器（booster=gbtree），则不定义。

返回:: coef_
返回类型:: 形状为 [n_features] 或 [n_classes, n_features] 的数组

evals_result()

返回评估结果。

如果向 fit() 函数传递了 eval_set，则可以调用 evals_result() 来获取所有传递的 eval_sets 的评估结果。当 eval_metric 也被传递给 fit() 函数时，evals_result 将包含传递给 fit() 函数的 eval_metrics。

返回的评估结果是一个字典

{'validation_0': {'logloss': ['0.604835', '0.531479']},
 'validation_1': {'logloss': ['0.41965', '0.17686']}}

返回类型:: evals_result

property feature_importances_: ndarray

特征重要性属性，返回值取决于 importance_type 参数。当模型使用多类/多标签/多目标数据集进行训练时，特征重要性会针对所有目标进行“平均”。“平均”的定义基于重要性类型。例如，如果重要性类型是“total_gain”，则分数是所有树的每次分裂造成的损失变化的总和。

返回:

feature_importances_（形状为 [n_features] 的数组，多类情况除外）
线性模型，返回一个形状为 (n_features, n_classes) 的数组

property feature_names_in_: ndarray: 在 fit() 过程中看到的特征名称。仅当 X 具有全为字符串的特征名称时才定义。

fit(X, y, *, sample_weight=None, base_margin=None, eval_set=None, verbose=True, xgb_model=None, sample_weight_eval_set=None, base_margin_eval_set=None, feature_weights=None)

拟合梯度提升分类器。

请注意，多次调用 fit() 会导致模型对象从头开始重新拟合。要从先前的检查点恢复训练，请显式传递 xgb_model 参数。

参数:

X (Any) –
输入特征矩阵。有关支持的类型列表，请参阅标记。

当 tree_method 设置为 hist 时，内部会使用 QuantileDMatrix 而不是 DMatrix 来节省内存。然而，当输入数据的设备与算法不匹配时，这会影响性能。例如，如果输入是 CPU 上的 numpy 数组，但训练时使用 cuda，则数据将首先在 CPU 上处理，然后传输到 GPU。
y (Any) – 标签
sample_weight (Any | None) – 样本权重
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
eval_set (Sequence[Tuple[Any, Any]] | None) – 一系列 (X, y) 对，用作验证集，将计算其指标。验证指标将帮助我们跟踪模型的性能。
verbose (bool | int | None) – 如果 verbose 为 True 且使用了评估集，则每次提升阶段在标准输出中打印在验证集上测量的评估指标。如果 verbose 是一个整数，则在每个 verbose 提升阶段打印评估指标。最后一个提升阶段 / 使用 early_stopping_rounds 找到的提升阶段也会被打印。
xgb_model (Booster | str | XGBModel | None) – 存储的 XGBoost 模型的文件名或要在训练前加载的 ‘Booster’ 实例 XGBoost 模型（允许继续训练）。
sample_weight_eval_set (Sequence[Any] | None) – 一个列表，形式为 [L_1, L_2, …, L_n]，其中每个 L_i 是一个类似数组的对象，存储第 i 个验证集的实例权重。
base_margin_eval_set (Sequence[Any] | None) – 一个列表，形式为 [M_1, M_2, …, M_n]，其中每个 M_i 是一个类似数组的对象，存储第 i 个验证集的基值（base margin）。
feature_weights (Any | None) –

已弃用（自 3.0.0 版本起）。

建议在 __init__() 或 set_params() 中使用 feature_weights。

返回类型:

XGBRFClassifier

get_booster()

获取此模型的底层 xgboost Booster。

如果尚未调用 fit，这将引发异常

返回:: booster
返回类型:: 底层模型的 xgboost booster

get_metadata_routing()

获取此对象的元数据路由。

请查阅用户指南，了解路由机制的工作原理。

返回:: routing – 一个 MetadataRequest，封装了路由信息。
返回类型:: MetadataRequest

get_num_boosting_rounds()

获取 xgboost 提升轮数。

返回类型:: int

get_params(deep=True)

获取参数。

参数:: deep (bool)
返回类型:: Dict[str, Any]

get_xgb_params()

获取 xgboost 特定的参数。

返回类型:: Dict[str, Any]

property intercept_: ndarray

截距（偏置）属性

对于基于树的模型，返回值是 base_score。

返回:: intercept_
返回类型:: 形状为 (1,) 或 [n_classes] 的数组

load_model(fname)

模型以 XGBoost 内部格式保存，该格式在各种 XGBoost 接口之间通用。Python Booster 对象的辅助属性（如 feature_names）仅在使用 JSON 或 UBJSON（默认）格式时保存。此外，不属于模型本身的参数（如 metrics、max_depth 等）不会被保存，更多信息请参见 Model IO。

fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）

model.save_model("model.json")
model.load_model("model.json")

# or
model.save_model("model.ubj")
model.load_model("model.ubj")

# or
buf = model.save_raw()
model.load_model(buf)

参数:: num_boosted_rounds()
返回类型:: None

property n_features_in_: int: 在 fit() 过程中看到的特征数量。

predict(X, *, output_margin=False, validate_features=True, base_margin=None, iteration_range=None)

使用 X 进行预测。如果模型使用提前停止进行训练，则会自动使用 best_iteration。该估计器默认使用 inplace_predict，如果数据和估计器之间的设备不匹配，则回退到使用 DMatrix。

注意

此函数仅对 gbtree 和 dart 线程安全。

参数:

X (Any) – 用于预测的数据。有关支持的类型列表，请参阅标记。
pred_leaf (bool) – 当此选项开启时，输出将是一个 (nsample, ntrees) 的矩阵，其中每条记录表示每个样本在每棵树中的预测叶子索引。请注意，树的叶子索引在每棵树中是唯一的，因此您可能会在树 1 和树 0 中都找到叶子 1。
training (bool) –
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) –
指定在预测中使用哪层树。例如，如果一个随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（半开区间）轮次中构建的森林。

版本 1.4.0 中新增。

返回类型:

预测

predict_proba(X, validate_features=True, base_margin=None, iteration_range=None)

预测 X 中每个示例属于某个类的概率。如果模型使用提前停止进行训练，则会自动使用 best_iteration。该估计器默认使用 inplace_predict，如果数据和估计器之间的设备不匹配，则回退到使用 DMatrix。

注意

此函数仅对 gbtree 和 dart 线程安全。

参数:

X (Any) – 特征矩阵。有关支持的类型列表，请参阅标记。
training (bool) –
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) – 指定在预测中使用哪层树。例如，如果一个随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（半开区间）轮次中构建的森林。

返回:

一个形状为 (n_samples, n_classes) 的 numpy 数组，包含每个数据样本属于给定类的概率。

返回类型:

预测

save_model(fname)

fname (str | PathLike) – 输出文件名。

fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）

model.save_model("model.json")
# or
model.save_model("model.ubj")

参数:: save_raw(raw_format='ubj')
返回类型:: None

score(X, y, sample_weight=None)

返回提供的数据和标签上的准确率。

在多标签分类中，这是子集准确率，这是一个严格的指标，因为它要求正确预测每个样本的每个标签集。

参数:

X (array-like of shape (n_samples, n_features)) – 测试样本。
y (array-like of shape (n_samples,) or (n_samples, n_outputs)) – X 的真实标签。
sample_weight (array-like of shape (n_samples,), default=None) – 样本权重。

返回:

score – self.predict(X) 相对于 y 的平均准确率。

返回类型:

set_fit_request(*, base_margin='$UNCHANGED$', base_margin_eval_set='$UNCHANGED$', eval_set='$UNCHANGED$', feature_weights='$UNCHANGED$', sample_weight='$UNCHANGED$', sample_weight_eval_set='$UNCHANGED$', verbose='$UNCHANGED$', xgb_model='$UNCHANGED$')

配置是否应请求将元数据传递给 fit 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 fit。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 fit。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 base_margin 参数的元数据路由。
base_margin_eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 base_margin_eval_set 参数的元数据路由。
eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 eval_set 参数的元数据路由。
feature_weights (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 feature_weights 参数的元数据路由。
sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight 参数的元数据路由。
sample_weight_eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight_eval_set 参数的元数据路由。
verbose (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 verbose 参数的元数据路由。
xgb_model (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 xgb_model 参数的元数据路由。
self (XGBRFClassifier)

返回:

self – 更新后的对象。

返回类型:

set_params(**params)

设置此估计器的参数。修改 sklearn 方法以允许未知关键字参数。这允许使用 sklearn 网格搜索中未定义为成员变量的全部 xgboost 参数。

返回类型:: self
参数:: params (Any)

set_predict_proba_request(*, base_margin='$UNCHANGED$', iteration_range='$UNCHANGED$', validate_features='$UNCHANGED$')

配置是否应请求将元数据传递给 predict_proba 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 predict_proba。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 predict_proba。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict_proba 方法中 base_margin 参数的元数据路由。
iteration_range (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict_proba 方法中 iteration_range 参数的元数据路由。
validate_features (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict_proba 方法中 validate_features 参数的元数据路由。
self (XGBRFClassifier)

返回:

self – 更新后的对象。

返回类型:

set_predict_request(*, base_margin='$UNCHANGED$', iteration_range='$UNCHANGED$', output_margin='$UNCHANGED$', validate_features='$UNCHANGED$')

配置是否应请求将元数据传递给 predict 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 predict。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 predict。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

base_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 base_margin 参数的元数据路由。
iteration_range (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 iteration_range 参数的元数据路由。
output_margin (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 output_margin 参数的元数据路由。
validate_features (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 validate_features 参数的元数据路由。
self (XGBRFClassifier)

返回:

self – 更新后的对象。

返回类型:

set_score_request(*, sample_weight='$UNCHANGED$')

配置是否应请求将元数据传递给 score 方法。

请注意，当此估计器作为元估计器的子估计器使用，并且通过 enable_metadata_routing=True 启用了元数据路由时，此方法才相关（请参阅 sklearn.set_config()）。请查阅用户指南，了解路由机制的工作原理。

每个参数的选项是

True: 请求元数据，并在提供时将其传递给 score。如果未提供元数据，则忽略此请求。
False: 不请求元数据，元估计器不会将其传递给 score。
None: 不请求元数据，如果用户提供，元估计器将引发错误。
str: 应使用此给定别名而不是原始名称将元数据传递给元估计器。

默认值（sklearn.utils.metadata_routing.UNCHANGED）保留现有请求。这允许您更改某些参数的请求而不影响其他参数。

在 1.3 版本中添加。

参数:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – score 方法中 sample_weight 参数的元数据路由。
self (XGBRFClassifier)

返回:

self – 更新后的对象。

返回类型:

绘图 API

绘图库。请参阅 Using the Scikit-Learn Estimator Interface 获取更多信息。

xgboost.plot_importance(booster, *, ax=None, height=0.2, xlim=None, ylim=None, title='Feature importance', xlabel='Importance score', ylabel='Features', fmap='', importance_type='weight', max_num_features=None, grid=True, show_values=True, values_format='{v}', **kwargs)

基于已拟合的树绘制重要性。

参数:

booster (XGBModel | Booster | dict) – Booster 或 XGBModel 实例，或 Booster.get_fscore() 所接受的 dict。
ax (matplotlib Axes) – 目标 axes 实例。如果为 None，则会创建新的 figure 和 axes。
grid (bool) – 打开或关闭 axes 网格。默认值为 True（开启）。
importance_type (str) –
重要性如何计算：可以是 “weight”, “gain”, 或 “cover”
- “weight” 是特征在树中出现的次数
- “gain” 是使用该特征的分割的平均增益
- “cover” 是使用该特征的分割的平均覆盖率，其中覆盖率定义为受分割影响的样本数量
max_num_features (int | None) – 图上显示的前 N 个特征的最大数量。如果为 None，则显示所有特征。
height (float) – 条形高度，传递给 ax.barh()
xlim (tuple | None) – 传递给 axes.xlim() 的元组
ylim (tuple | None) – 传递给 axes.ylim() 的元组
title (str) – Axes 标题。要禁用，请传递 None。
xlabel (str) – X 轴标题标签。要禁用，请传递 None。
ylabel (str) – Y 轴标题标签。要禁用，请传递 None。
importance_type (str) – 上面定义的其中一种重要性类型。
show_values (bool) – 在图上显示值。要禁用，请传递 False。
values_format (str) – 值的格式字符串。“v”将被特征重要性值替换。例如，传递 “{v:.2f}” 以将每个打印在图上的值的小数点后的位数限制为两位。
kwargs (Any) – 传递给 ax.barh() 的其他关键字参数

返回:

ax

返回类型:

matplotlib Axes

xgboost.plot_tree(booster, *, fmap='', num_trees=None, rankdir=None, ax=None, with_stats=False, tree_idx=0, **kwargs)

绘制指定的树。

参数:

booster (Booster | XGBModel) – Booster 或 XGBModel 实例
fmap (str (optional)) – 特征映射文件的名称
num_trees (int | None) –

已弃用，版本 3.0。
rankdir (str, default "TB") – 通过 graphviz 传递给 graph_attr
ax (matplotlib Axes, default None) – 目标 axes 实例。如果为 None，则会创建新的 figure 和 axes。
with_stats (bool) –

3.0 版本新增。

请参阅 to_graphviz()。
tree_idx (int) –

3.0 版本新增。

请参阅 to_graphviz()。
kwargs (Any) – 传递给 to_graphviz() 的其他关键字参数

返回:

ax

返回类型:

matplotlib Axes

xgboost.to_graphviz(booster, *, fmap='', num_trees=None, rankdir=None, yes_color=None, no_color=None, condition_node_params=None, leaf_node_params=None, with_stats=False, tree_idx=0, **kwargs)

将指定树转换为 graphviz 实例。IPython 可以自动绘制返回的 graphviz 实例。否则，您应该调用返回的 graphviz 实例的 .render() 方法。

参数:

booster (Booster | XGBModel) – Booster 或 XGBModel 实例
fmap (str | PathLike) – 特征映射文件的名称。
num_trees (int | None) –

已弃用，版本 3.0。

指定目标树的序数。
rankdir (str | None) – 通过 graphviz 传递给 graph_attr
yes_color (str | None) – 满足节点条件时的边颜色。
no_color (str | None) – 不满足节点条件时的边颜色。
condition_node_params (dict | None) –
用于 graphviz 的条件节点配置。例如
```
{'shape': 'box',
 'style': 'filled,rounded',
 'fillcolor': '#78bceb'}
```
leaf_node_params (dict | None) –
用于 graphviz 的叶子节点配置。例如
```
{'shape': 'box',
 'style': 'filled',
 'fillcolor': '#e48038'}
```
with_stats (bool) –

3.0 版本新增。

控制是否包含分裂统计信息。
tree_idx (int) –

3.0 版本新增。

指定目标树的序数索引。
kwargs (Any) – 传递给 graphviz graph_attr 的其他关键字参数，例如 graph [ {key} = {value} ]

返回:

graph

返回类型:

graphviz.Source

回调 API

包含训练例程的回调库。请参阅 Callback Functions 获取快速入门。

class xgboost.callback.TrainingCallback

训练回调的接口。

在 1.3.0 版本中添加。

after_iteration(model, epoch, evals_log)

在每次迭代后运行。返回 True 表示应停止训练。

参数:

model (Any) – 要么是 Booster 对象，要么是 xgboost 中使用的 cv 函数的 CVPack。
epoch (int) – 当前训练迭代次数。
evals_log (Dict[str, Dict[str, List[float] | List[Tuple[float, float]]]]) –
一个包含评估历史的字典
```
{"data_name": {"metric_name": [0.5, ...]}}
```

返回类型:

after_training(model)

训练完成后运行。

参数:: model (Any)
返回类型:: Any

before_iteration(model, epoch, evals_log)

在每次迭代前运行。返回 True 表示应停止训练。详情请参阅 after_iteration()。

参数:

model (Any)
epoch (int)
evals_log (Dict[str, Dict[str, List[float] | List[Tuple[float, float]]]]])

返回类型:

before_training(model)

在训练开始前运行。

参数:: model (Any)
返回类型:: Any

class xgboost.callback.EvaluationMonitor(rank=0, period=1, show_stdv=False, logger=<function communicator_print>)

在每次迭代时打印评估结果。

在 1.3.0 版本中添加。

参数:

rank (int) – 用于打印结果的 worker。
period (int) – 打印之间的 epoch 数量。
show_stdv (bool) – 在 cv 中用于显示标准差。用户不应指定它。
logger (Callable[[str], None]) – 用于记录评估结果的可调用对象。

after_iteration(model, epoch, evals_log)

在每次迭代后运行。返回 True 表示应停止训练。

参数:

model (Any) – 要么是 Booster 对象，要么是 xgboost 中使用的 cv 函数的 CVPack。
epoch (int) – 当前训练迭代次数。
evals_log (Dict[str, Dict[str, List[float] | List[Tuple[float, float]]]]) –
一个包含评估历史的字典
```
{"data_name": {"metric_name": [0.5, ...]}}
```

返回类型:

after_training(model)

训练完成后运行。

参数:: model (Any)
返回类型:: Any

class xgboost.callback.EarlyStopping(*, rounds, metric_name=None, data_name=None, maximize=None, save_best=False, min_delta=0.0)

用于提前停止的回调函数

在 1.3.0 版本中添加。

参数:

rounds (int) – 提前停止轮数。
metric_name (str | None) – 用于提前停止的指标名称。
data_name (str | None) – 用于提前停止的数据集名称。
maximize (bool | None) – 是否最大化评估指标。None 表示自动（不推荐）。
save_best (bool | None) – 训练是应返回最佳模型还是最后一个模型。如果设置为 True，它将只保留到检测到的最佳迭代的提升轮数，丢弃之后的轮数。这仅支持树模型（不支持 gblinear）。此外，cv 函数不返回模型，此参数不适用。
min_delta (float) –

在版本 1.5.0 中添加。

被视为改进的得分的最小绝对变化。

示例

es = xgboost.callback.EarlyStopping(
    rounds=2,
    min_delta=1e-3,
    save_best=True,
    maximize=False,
    data_name="validation_0",
    metric_name="mlogloss",
)
clf = xgboost.XGBClassifier(tree_method="hist", device="cuda", callbacks=[es])

X, y = load_digits(return_X_y=True)
clf.fit(X, y, eval_set=[(X, y)])

after_iteration(model, epoch, evals_log)

在每次迭代后运行。返回 True 表示应停止训练。

参数:

model (Any) – 要么是 Booster 对象，要么是 xgboost 中使用的 cv 函数的 CVPack。
epoch (int) – 当前训练迭代次数。
evals_log (Dict[str, Dict[str, List[float] | List[Tuple[float, float]]]]) –
一个包含评估历史的字典
```
{"data_name": {"metric_name": [0.5, ...]}}
```

返回类型:

after_training(model)

训练完成后运行。

参数:: model (Any)
返回类型:: Any

before_training(model)

在训练开始前运行。

参数:: model (Any)
返回类型:: Any

class xgboost.callback.LearningRateScheduler(learning_rates)

用于调度学习率的回调函数。

在 1.3.0 版本中添加。

参数:: learning_rates (Callable[[int], float] | Sequence[float]) – 如果是可调用对象，则它应该接受一个整数参数 epoch 并返回相应的学习率。否则，它应该是一个列表或元组等序列，其大小与提升轮数相同。

after_iteration(model, epoch, evals_log)

在每次迭代后运行。返回 True 表示应停止训练。

参数:

model (Any) – 要么是 Booster 对象，要么是 xgboost 中使用的 cv 函数的 CVPack。
epoch (int) – 当前训练迭代次数。
evals_log (Dict[str, Dict[str, List[float] | List[Tuple[float, float]]]]) –
一个包含评估历史的字典
```
{"data_name": {"metric_name": [0.5, ...]}}
```

返回类型:

class xgboost.callback.TrainingCheckPoint(directory, name='model', as_pickle=False, interval=100)

检查点操作。鼓励用户为检查点创建自己的回调函数，因为 XGBoost 不处理分布式文件系统。在分布式系统上进行检查点时，请务必了解 worker 的 rank，以避免多个 worker 检查点到同一个地方。

在 1.3.0 版本中添加。

自 XGBoost 2.1.0 起，默认格式已更改为 UBJSON。

参数:

directory (str | PathLike) – 输出模型目录。
name (str) – 输出模型文件的模式。模型将保存为 name_0.ubj, name_1.ubj, name_2.ubj……。
as_pickle (bool) – 当设置为 True 时，所有训练参数将以 pickle 格式保存，而不是仅保存模型。
interval (int) – 检查点间隔。检查点很慢，因此设置较大的数字可以减少性能影响。

after_iteration(model, epoch, evals_log)

在每次迭代后运行。返回 True 表示应停止训练。

参数:

model (Any) – 要么是 Booster 对象，要么是 xgboost 中使用的 cv 函数的 CVPack。
epoch (int) – 当前训练迭代次数。
evals_log (Dict[str, Dict[str, List[float] | List[Tuple[float, float]]]]) –
一个包含评估历史的字典
```
{"data_name": {"metric_name": [0.5, ...]}}
```

返回类型: