Python API 参考 

注意

在回归器上调用 score 时使用的 $R^2$ 分数从 0.23 版本开始使用 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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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 参数范围。

返回类型:: 自身
参数:: 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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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]) – 提升轮次 (boosting rounds) 的数量。
max_depth (Optional[int]) – 基础学习器的最大树深度。
max_leaves (Optional[int]) – 最大叶子数；0 表示无限制。
max_bin (Optional[int]) – 如果使用基于直方图的算法，则每个特征的最大 bin 数
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)
  当梯度和 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 (Optional[float]) – 所有实例的初始预测得分，全局偏置。
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”。
- 对于线性模型，仅定义了“weight”，它是去除偏差后的归一化系数。
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 是否应对分类数据使用 one-hot 编码分割的阈值。当类别数量小于阈值时，选择 one-hot 编码，否则类别将被划分到子节点中。此外，需要设置 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[str], 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 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: array_like of shape [n_samples]
目标值

y_pred: array_like of shape [n_samples]
预测值

sample_weight
可选的样本权重。

grad: array_like of shape [n_samples]
每个样本点的梯度值。

hess: array_like of shape [n_samples]
每个样本点的二阶导数值

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

apply(X, iteration_range=None)

返回每个样本在每棵树上的预测叶子。如果模型使用早停训练，则自动使用 best_iteration。

参数:

X (Any) – 输入特征矩阵。有关支持的类型列表，请参见 Supported data structures for various XGBoost functions。
iteration_range (Tuple[int | integer, int | integer] | None) – 参见 predict()。

返回:

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

返回类型:

array_like, shape=[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) –
输入特征矩阵。有关支持的类型列表，请参见 Supported data structures for various XGBoost functions。

当 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 且使用了评估集，则在每个提升阶段将验证集上衡量的评估指标打印到 stdout。如果 verbose 是一个整数，则在每 verbose 个提升阶段打印评估指标。使用 early_stopping_rounds 找到的最后一个提升阶段/提升阶段也会被打印。
xgb_model (Booster | str | XGBModel | None) – 要加载的文件名或 ‘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 提升轮次 (boosting rounds) 的数量。

返回类型:: 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)

从文件或 bytearray 加载模型。

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

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)

参数:: fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）
返回类型:: 无

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) – 用于预测的数据。有关支持的类型列表，请参阅各种 XGBoost 函数支持的数据结构。
output_margin (bool) – 是否输出原始未转换的 margin 值。
validate_features (bool) – 当此参数设置为 True 时，验证 Booster 和数据的 feature_names 是否完全一致。否则，假设 feature_names 是相同的。
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) –
指定预测中使用哪一层树。例如，如果随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（左闭右开区间）轮次期间构建的森林。

在 1.4.0 版本中新增。

返回类型:

prediction

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

预测每个 X 样本属于给定类别的概率。如果模型使用早停训练，则自动使用 best_iteration。估计器默认使用 inplace_predict，如果数据与估计器之间的设备不匹配，则回退到使用 DMatrix。

注意

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

参数:

X (Any) – 特征矩阵。有关支持的类型列表，请参阅各种 XGBoost 函数支持的数据结构。
validate_features (bool) – 当此参数设置为 True 时，验证 Booster 和数据的 feature_names 是否完全一致。否则，假设 feature_names 是相同的。
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) – 指定预测中使用哪一层树。例如，如果随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（左闭右开区间）轮次期间构建的森林。

返回:

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

返回类型:

prediction

save_model(fname)

将模型保存到文件。

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

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

参数:: fname (str | PathLike) – 输出文件名
返回类型:: 无

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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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 参数范围。

返回类型:: 自身
参数:: 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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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]) – 如果使用基于直方图的算法，则每个特征的最大 bin 数
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)
  当梯度和 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 (Optional[float]) – 所有实例的初始预测得分，全局偏置。
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”。
- 对于线性模型，仅定义了“weight”，它是去除偏差后的归一化系数。
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 是否应对分类数据使用 one-hot 编码分割的阈值。当类别数量小于阈值时，选择 one-hot 编码，否则类别将被划分到子节点中。此外，需要设置 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[str], 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 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) – 输入特征矩阵。有关支持的类型列表，请参见 Supported data structures for various XGBoost functions。
iteration_range (Tuple[int | integer, int | integer] | None) – 参见 predict()。

返回:

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

返回类型:

array_like, shape=[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) –
特征矩阵。有关支持的类型列表，请参阅各种 XGBoost 函数支持的数据结构。

当这是一个 pandas.DataFrame 或 cudf.DataFrame 时，它可能包含一个名为 qid 的特殊列，用于指定查询索引。使用特殊列与使用 qid 参数相同，只是前者与 sklearn 工具函数（如 sklearn.model_selection.cross_validation()）兼容。相同的约定也适用于 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 且使用了评估集，则在每个提升阶段将验证集上衡量的评估指标打印到 stdout。如果 verbose 是一个整数，则在每 verbose 个提升阶段打印评估指标。使用 early_stopping_rounds 找到的最后一个提升阶段/提升阶段也会被打印。
xgb_model (Booster | str | XGBModel | None) – 要加载的文件名或 ‘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 提升轮次 (boosting rounds) 的数量。

返回类型:: 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)

从文件或 bytearray 加载模型。

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

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)

参数:: fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）
返回类型:: 无

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) – 用于预测的数据。有关支持的类型列表，请参阅各种 XGBoost 函数支持的数据结构。
output_margin (bool) – 是否输出原始未转换的 margin 值。
validate_features (bool) – 当此参数设置为 True 时，验证 Booster 和数据的 feature_names 是否完全一致。否则，假设 feature_names 是相同的。
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) –
指定预测中使用哪一层树。例如，如果随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（左闭右开区间）轮次期间构建的森林。

在 1.4.0 版本中新增。

返回类型:

prediction

save_model(fname)

将模型保存到文件。

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

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

参数:: fname (str | PathLike) – 输出文件名
返回类型:: 无

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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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) – 用于 fit 方法中 eval_group 参数的元数据路由。
eval_qid (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – 用于 fit 方法中 eval_qid 参数的元数据路由。
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) – 用于 fit 方法中 group 参数的元数据路由。
qid (字符串, 真, 假, or 无, 默认值=sklearn.utils.metadata_routing.UNCHANGED) – 用于fit方法中qid参数的元数据路由。
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 参数范围。

返回类型:: 自身
参数:: 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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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)

基类： XGBRegressor

用于 XGBoost 随机森林回归的 scikit-learn API。详见使用 Scikit-Learn 估计器接口。

参数:

n_estimators (可选的[整数]) – 要拟合的随机森林中的树数量。
max_depth (Optional[int]) – 基础学习器的最大树深度。
max_leaves (Optional[int]) – 最大叶子数；0 表示无限制。
max_bin (Optional[int]) – 如果使用基于直方图的算法，则每个特征的最大 bin 数
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)
  当梯度和 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 (Optional[float]) – 所有实例的初始预测得分，全局偏置。
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”。
- 对于线性模型，仅定义了“weight”，它是去除偏差后的归一化系数。
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 是否应对分类数据使用 one-hot 编码分割的阈值。当类别数量小于阈值时，选择 one-hot 编码，否则类别将被划分到子节点中。此外，需要设置 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[str], 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 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: array_like of shape [n_samples]
目标值

y_pred: array_like of shape [n_samples]
预测值

sample_weight
可选的样本权重。

grad: array_like of shape [n_samples]
每个样本点的梯度值。

hess: array_like of shape [n_samples]
每个样本点的二阶导数值

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

apply(X, iteration_range=None)

返回每个样本在每棵树中的预测叶子。如果模型使用早停进行训练，则best_iteration会自动使用。

参数:

X (Any) – 输入特征矩阵。有关支持的类型列表，请参见 Supported data structures for various XGBoost functions。
iteration_range (元组[整数 | integer, 整数 | integer] | 无) – 详见predict()。

返回:

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

返回类型:

array_like, shape=[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) –
输入特征矩阵。有关支持的类型列表，请参见 Supported data structures for various XGBoost functions。

当 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 且使用了评估集，则在每个提升阶段将验证集上衡量的评估指标打印到 stdout。如果 verbose 是一个整数，则在每 verbose 个提升阶段打印评估指标。使用 early_stopping_rounds 找到的最后一个提升阶段/提升阶段也会被打印。
xgb_model (Booster | str | XGBModel | None) – 要加载的文件名或 ‘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 版本起已弃用。

请改用feature_weights在__init__()或set_params()中。

返回类型:

XGBRFRegressor

get_booster()

获取此模型底层的 xgboost Booster。

如果在 fit 方法未被调用时，这将引发异常。

返回:: booster
返回类型:: 底层模型的 xgboost Booster 实例

get_metadata_routing()

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

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

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

get_num_boosting_rounds()

获取 xgboost 提升轮次 (boosting rounds) 的数量。

返回类型:: 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)

从文件或 bytearray 加载模型。

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

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)

参数:: fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）
返回类型:: 无

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) – 用于预测的数据。有关支持的类型列表，请参阅各种 XGBoost 函数支持的数据结构。
output_margin (bool) – 是否输出原始未转换的 margin 值。
validate_features (bool) – 当此参数设置为 True 时，验证 Booster 和数据的 feature_names 是否完全一致。否则，假设 feature_names 是相同的。
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) –
指定预测中使用哪一层树。例如，如果随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（左闭右开区间）轮次期间构建的森林。

在 1.4.0 版本中新增。

返回类型:

prediction

save_model(fname)

将模型保存到文件。

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

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

参数:: fname (str | PathLike) – 输出文件名
返回类型:: 无

score(X, y, sample_weight=None)

返回预测的决定系数 (coefficient of determination)。

决定系数 $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$ 值。

返回类型:

注意

在回归器上调用 score 时使用的 $R^2$ 分数从 0.23 版本开始使用 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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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 参数范围。

返回类型:: 自身
参数:: 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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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)

基类： XGBClassifier

用于 XGBoost 随机森林分类的 scikit-learn API。详见使用 Scikit-Learn 估计器接口。

参数:

n_estimators (可选的[整数]) – 要拟合的随机森林中的树数量。
max_depth (Optional[int]) – 基础学习器的最大树深度。
max_leaves (Optional[int]) – 最大叶子数；0 表示无限制。
max_bin (Optional[int]) – 如果使用基于直方图的算法，则每个特征的最大 bin 数
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)
  当梯度和 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 (Optional[float]) – 所有实例的初始预测得分，全局偏置。
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”。
- 对于线性模型，仅定义了“weight”，它是去除偏差后的归一化系数。
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 是否应对分类数据使用 one-hot 编码分割的阈值。当类别数量小于阈值时，选择 one-hot 编码，否则类别将被划分到子节点中。此外，需要设置 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[str], 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 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: array_like of shape [n_samples]
目标值

y_pred: array_like of shape [n_samples]
预测值

sample_weight
可选的样本权重。

grad: array_like of shape [n_samples]
每个样本点的梯度值。

hess: array_like of shape [n_samples]
每个样本点的二阶导数值

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

apply(X, iteration_range=None)

返回每个样本在每棵树中的预测叶子。如果模型使用早停进行训练，则best_iteration会自动使用。

参数:

X (Any) – 输入特征矩阵。有关支持的类型列表，请参见 Supported data structures for various XGBoost functions。
iteration_range (元组[整数 | integer, 整数 | integer] | 无) – 详见predict()。

返回:

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

返回类型:

array_like, shape=[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) –
输入特征矩阵。有关支持的类型列表，请参见 Supported data structures for various XGBoost functions。

当 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 且使用了评估集，则在每个提升阶段将验证集上衡量的评估指标打印到 stdout。如果 verbose 是一个整数，则在每 verbose 个提升阶段打印评估指标。使用 early_stopping_rounds 找到的最后一个提升阶段/提升阶段也会被打印。
xgb_model (Booster | str | XGBModel | None) – 要加载的文件名或 ‘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 版本起已弃用。

请改用feature_weights在__init__()或set_params()中。

返回类型:

XGBRFClassifier

get_booster()

获取此模型底层的 xgboost Booster。

如果在 fit 方法未被调用时，这将引发异常。

返回:: booster
返回类型:: 底层模型的 xgboost Booster 实例

get_metadata_routing()

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

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

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

get_num_boosting_rounds()

获取 xgboost 提升轮次 (boosting rounds) 的数量。

返回类型:: 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)

从文件或 bytearray 加载模型。

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

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)

参数:: fname (PathLike | bytearray | str) – 输入文件名或内存缓冲区（另请参阅 save_raw）
返回类型:: 无

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) – 用于预测的数据。有关支持的类型列表，请参阅各种 XGBoost 函数支持的数据结构。
output_margin (bool) – 是否输出原始未转换的 margin 值。
validate_features (bool) – 当此参数设置为 True 时，验证 Booster 和数据的 feature_names 是否完全一致。否则，假设 feature_names 是相同的。
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) –
指定预测中使用哪一层树。例如，如果随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（左闭右开区间）轮次期间构建的森林。

在 1.4.0 版本中新增。

返回类型:

prediction

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

预测每个X样本属于给定类别的概率。如果模型使用早停进行训练，则best_iteration会自动使用。估计器默认使用inplace_predict，如果数据和估计器之间的设备不匹配，则会回退到使用DMatrix。

注意

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

参数:

X (Any) – 特征矩阵。有关支持的类型列表，请参阅各种 XGBoost 函数支持的数据结构。
validate_features (bool) – 当此参数设置为 True 时，验证 Booster 和数据的 feature_names 是否完全一致。否则，假设 feature_names 是相同的。
base_margin (Any | None) – 每个实例的全局偏差。有关详细信息，请参阅截距。
iteration_range (Tuple[int | integer, int | integer] | None) – 指定预测中使用哪一层树。例如，如果随机森林训练了 100 轮。指定 iteration_range=(10, 20)，则在此预测中仅使用在 [10, 20)（左闭右开区间）轮次期间构建的森林。

返回:

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

返回类型:

prediction

save_model(fname)

将模型保存到文件。

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

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

参数:: fname (str | PathLike) – 输出文件名
返回类型:: 无

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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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 参数范围。

返回类型:: 自身
参数:: 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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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 版本。

注意

此方法仅在此估计器用作元估计器的子估计器时相关，例如在 Pipeline 中使用时。否则，它无效。

参数:

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

返回:

self – 更新后的对象。

返回类型:

绘图API

绘图库。

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() 获取的字典
ax (matplotlib Axes) – 目标 Axes 实例。如果为 None，将创建新的图形和 Axes。
grid (bool) – 开启或关闭 Axes 网格。默认值为 True (开启)。
importance_type (str) –
重要性如何计算：可以是 “weight”、“gain” 或 “cover”
- “weight” 表示特征在树中出现的次数
- “gain” 表示使用该特征进行分割的平均增益
- “cover” 表示使用该特征进行分割的平均覆盖度，覆盖度定义为受该分割影响的样本数量
max_num_features (int | None) – 图表中显示的最大顶部特征数量。如果为 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。
fmap (str | PathLike) – 特征映射文件的名称。
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") – 通过 graph_attr 传递给 graphviz
ax (matplotlib Axes, default None) – 目标 Axes 实例。如果为 None，将创建新的图形和 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) – 通过 graph_attr 传递给 graphviz
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

包含训练例程的回调库。有关快速介绍，请参阅回调函数。

class xgboost.callback.TrainingCallback

训练回调的接口。

在 1.3.0 版本中新增。

after_iteration(model, epoch, evals_log)

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

参数:

model (Any) – Booster 对象或 CVPack（如果使用了 xgboost 中的 cv 函数）
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>)

基类： TrainingCallback

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

在 1.3.0 版本中新增。

参数:

rank (int) – 用于打印结果的工作进程排名。
period (int) – 打印评估结果的迭代间隔。
show_stdv (bool) – 在 cv 中用于显示标准差。用户不应指定此参数。
logger (Callable[[str], None]) – 用于记录评估结果的可调用对象。

after_iteration(model, epoch, evals_log)

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

参数:

model (Any) – Booster 对象或 CVPack（如果使用了 xgboost 中的 cv 函数）
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)

基类： TrainingCallback

用于提前停止的回调函数

在 1.3.0 版本中新增。

参数:

rounds (int) – 提前停止的迭代次数。
metric_name (str | None) – 用于提前停止的指标名称。
data_name (str | None) – 用于提前停止的数据集名称。
maximize (bool | None) – 是否最大化评估指标。None 表示自动（不推荐）。
save_best (bool | None) – 训练是否应返回最佳模型或最后一个模型。如果设置为 True，它将只保留检测到的最佳迭代之前的 Boosting 轮次，丢弃之后的轮次。这仅支持树方法（不支持 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 对象或 CVPack（如果使用了 xgboost 中的 cv 函数）
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)

基类： TrainingCallback

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

在 1.3.0 版本中新增。

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

after_iteration(model, epoch, evals_log)

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

参数:

model (Any) – Booster 对象或 CVPack（如果使用了 xgboost 中的 cv 函数）
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)

基类： TrainingCallback

检查点操作。建议用户创建自己的回调函数进行检查点操作，因为 XGBoost 不处理分布式文件系统。在分布式系统上进行检查点操作时，请务必了解工作进程的排名，以避免多个工作进程保存到同一位置。

在 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 对象或 CVPack（如果使用了 xgboost 中的 cv 函数）
epoch (int) – 当前训练迭代次数。
evals_log (Dict[str, Dict[str, List[float] | List[Tuple[float, float]]]]) –
包含评估历史记录的字典
```
{"data_name": {"metric_name": [0.5, ...]}}
```

返回类型: