Boosting

hscredit.core.models.boosting 提供基于梯度提升框架的风控模型，统一继承 BaseRiskModel，需要安装对应可选依赖 （pip install hscredit[boost]）。可直接从顶层 hscredit 懒加载导入，例如 from hscredit import XGBoost。

备注

NGBoost 依赖 ngboost；构建本文档时若未安装该依赖，相关签名以 mock 形式呈现，不影响接口说明。

class hscredit.core.models.boosting.xgboost_model.XGBoost(max_depth=6, learning_rate=0.1, n_estimators=100, min_child_weight=1, subsample=0.8, colsample_bytree=0.8, colsample_bylevel=1.0, reg_alpha=0, reg_lambda=1, scale_pos_weight='auto', gamma=0, max_delta_step=0, tree_method='hist', objective='binary:logistic', eval_metric=None, early_stopping_rounds=None, early_stopping_metric=None, early_stopping_data=None, validation_fraction=0.2, random_state=None, n_jobs=-1, verbose=False, params=None, scorecard_params=None, **kwargs)

基类：BaseRiskModel

XGBoost风控模型 - 基于内部建模经验优化.

基于XGBoost的二分类模型，针对风控场景优化。 参考内部建模经验，支持自动scale_pos_weight计算、KS评估指标等。

参数

参数:

• max_depth (int) -- 树最大深度，默认6 - 内部经验: 特征>1000时建议5-13，否则3-9

• learning_rate (float) -- 学习率，默认0.1 - 内部经验: 一般0.01-0.3，常用0.1

• n_estimators (int) -- 树的数量，默认100 - 内部经验: 样本>10000时50-300，否则20-100

• min_child_weight (float) -- 叶子节点最小样本权重和，默认1 - 内部经验: 样本>10000时10-2000，否则10-300

• subsample (float) -- 样本采样比例，默认0.8 - 内部经验: 常用0.6-0.9防止过拟合

• colsample_bytree (float) -- 特征采样比例，默认0.8 - 内部经验: 常用0.6-0.9防止过拟合

• colsample_bylevel (float) -- 每层的特征采样比例，默认1.0

• reg_alpha (float) -- L1正则化系数，默认0 - 内部经验: 常用0, 0.01, 0.1, 1, 10, 100

• reg_lambda (float) -- L2正则化系数，默认1

• scale_pos_weight (str | float) -- 正负样本权重比，默认'auto' - 'auto': 自动计算 (当bad_rate<0.05时) - float: 自定义权重 - 内部经验: 当bad_rate<0.05时设置0.05 * n_samples / n_positive

• gamma (float) -- 节点分裂所需的最小损失减少，默认0

• max_delta_step (float) -- 每棵树权重改变的最大步长，默认0

• tree_method (str) -- 树构建算法，默认'hist' - 'hist': 直方图算法（推荐，速度快） - 'exact': 精确贪心算法 - 'approx': 近似算法 - 'gpu_hist': GPU直方图算法

• objective (str) -- 目标函数，默认'binary:logistic'

• eval_metric (str | List[str] | None) -- 评估指标，可选列表 - 支持'ks'作为自定义评估指标（风控常用） - 多个指标时，默认使用第一个指标进行早停

• early_stopping_rounds (int | None) -- 早停轮数，默认None - 连续N轮没有改善则停止训练 - XGBoost 2.0+ 需要在构造函数中传入此参数

• early_stopping_metric (str | None) -- 用于早停的评估指标名称，默认None（使用第一个指标） - 当eval_metric有多个时，指定用哪个指标进行早停判断 - XGBoost 2.0+ 使用方式: 传入metric名称，如 'auc', 'logloss', 'error' - 注意: 指标名称必须是eval_metric中指定的名称之一 - 例如: eval_metric=['auc','logloss']时，可指定'auc'或'logloss'作为早停指标

• early_stopping_data (str | None) -- 用于早停的验证集名称，默认None（使用第一个验证集） - XGBoost内部会自动命名为'validation_0', 'validation_1'等 - 通常不需要指定，除非有多个验证集

• validation_fraction (float) -- 验证集比例，默认0.2

• random_state (int | None) -- 随机种子，默认None

• n_jobs (int) -- 并行任务数，默认-1

• verbose (bool) -- 是否输出详细信息，默认False

• params (Dict[str, Any] | None) -- XGBoost原生参数字典，默认None - 如果传入，将覆盖其他参数设置 - 可直接使用XGBoost原生参数名

• kwargs -- 其他XGBoost参数

• scorecard_params (Dict[str, Any] | None)

属性

变量:

• feature_importances_ -- 特征重要性

• evals_result_ -- 训练过程评估结果

• best_iteration_ -- 最佳迭代次数

• best_score_ -- 最佳得分

• scale_pos_weight_ -- 实际使用的scale_pos_weight值

• booster_ -- 底层XGBoost模型

参数:

• max_depth (int)

• learning_rate (float)

• n_estimators (int)

• min_child_weight (float)

• subsample (float)

• colsample_bytree (float)

• colsample_bylevel (float)

• reg_alpha (float)

• reg_lambda (float)

• scale_pos_weight (str | float)

• gamma (float)

• max_delta_step (float)

• tree_method (str)

• objective (str)

• eval_metric (str | List[str] | None)

• early_stopping_rounds (int | None)

• early_stopping_metric (str | None)

• early_stopping_data (str | None)

• validation_fraction (float)

• random_state (int | None)

• n_jobs (int)

• verbose (bool)

• params (Dict[str, Any] | None)

• scorecard_params (Dict[str, Any] | None)

参考样例

>>> # 基础使用
>>> model = XGBoost(max_depth=5, learning_rate=0.1)
>>> model.fit(X_train, y_train)

>>> # 自动处理不平衡数据
>>> model = XGBoost(scale_pos_weight='auto')
>>> model.fit(X_train, y_train)

>>> # 使用KS作为评估指标
>>> model = XGBoost(eval_metric='ks')
>>> model.fit(X_train, y_train)

>>> # 使用原生XGBoost参数
>>> params = {'max_depth': 5, 'learning_rate': 0.05, 'subsample': 0.8}
>>> model = XGBoost(params=params)
>>> model.fit(X_train, y_train)

>>> # 早停设置 - 使用多个评估指标，指定logloss作为早停指标（越小越好）
>>> model = XGBoost(
...     n_estimators=1000,
...     eval_metric=['auc', 'logloss'],
...     early_stopping_rounds=10,
...     early_stopping_metric='logloss'
... )
>>> model.fit(X_train, y_train)
>>> print(f'最佳迭代次数: {model.best_iteration_}')

>>> # 早停设置 - 使用AUC作为早停指标（越大越好）
>>> model = XGBoost(
...     n_estimators=1000,
...     eval_metric=['auc', 'logloss'],
...     early_stopping_rounds=10,
...     early_stopping_metric='auc'
... )
>>> model.fit(X_train, y_train)

引用

基于 XGBoost 梯度提升框架，见 Chen, T. & Guestrin, C. (2016). XGBoost: A Scalable Tree Boosting System. KDD； 文档 https://xgboost.readthedocs.io/ 。

fit(X, y=None, sample_weight=None, eval_set=None, **fit_params)

训练XGBoost模型.

支持两种调用方式: 1. 常规方式: fit(X, y) 2. scorecardpipeline风格: fit(X) 在init中指定target

参数:

• X (ndarray | DataFrame) -- 特征矩阵

• y (ndarray | Series | None) -- 目标变量，可选

• sample_weight (ndarray | None) -- 样本权重

• eval_set (List[Tuple] | None) -- 验证集列表

• fit_params -- 其他fit参数

返回:

self

返回类型:

XGBoost

property best_iteration_

最佳迭代次数.

property best_score_

最佳得分.

predict(X)

预测类别标签.

支持传入包含target列的数据框（scorecardpipeline风格）。 基于 predict_proba 取阈值，确保自定义损失（原始分数输出）下也能返回正确类别。

参数:

X (ndarray | DataFrame)

返回类型:

ndarray

predict_proba(X)

预测概率.

支持传入包含target列的数据框（scorecardpipeline风格）。

当使用自定义损失函数（objective 为可调用对象）时，XGBoost 返回的是 未经过链接函数转换的原始分数（raw margin，一维数组），此处自动应用 sigmoid 转换为概率并补齐为二维 (n_samples, 2) 输出，与内置目标保持一致。

参数:

X (ndarray | DataFrame)

返回类型:

ndarray

get_feature_importances(importance_type='gain')

获取特征重要性.

参数:

importance_type (str) -- 重要性类型，可选: - 'gain': 平均增益 (默认) - 'weight': 分裂次数 - 'cover': 平均覆盖度 - 'total_gain': 总增益 - 'total_cover': 总覆盖度

返回:

特征重要性Series

返回类型:

Series

property feature_importances_: ndarray

特征重要性属性 (兼容sklearn风格).

直接在包装类上暴露重要性，兼容sklearn RFE/SFS等组件的 importance_getter。

get_booster()

获取底层XGBoost booster对象.

返回:

XGBoost Booster对象

返回类型:

xgb.Booster

plot_tree(num_trees=0, **kwargs)

绘制树结构.

参数:

• num_trees (int) -- 树的索引

• kwargs -- 其他绘图参数

plot_importance(max_num_features=10, **kwargs)

绘制特征重要性.

参数:

• max_num_features (int) -- 显示的最大特征数

• kwargs -- 其他绘图参数

get_leaf_indices(X)

获取叶子节点索引.

返回每棵树上的叶子节点索引，用于GBDT+LR等场景。

参数:

X (ndarray | DataFrame) -- 特征矩阵

返回:

叶子节点索引，形状 (n_samples, n_trees)

返回类型:

ndarray

参考样例

>>> model = XGBoost(n_estimators=50)
>>> model.fit(X, y)
>>> leaf_indices = model.get_leaf_indices(X)
>>> print(leaf_indices.shape)

save_model(path)

保存底层XGBoost模型（原生格式）.

参数:

path (str) -- 保存路径（.json/.ubj/.bin 格式）

load_model(path)

加载底层XGBoost模型（原生格式）.

参数:

path (str) -- 模型路径

返回:

self

返回类型:

XGBoost

class hscredit.core.models.boosting.lightgbm_model.LightGBM(num_leaves=31, max_depth=-1, learning_rate=0.1, n_estimators=100, min_child_samples=20, min_child_weight=0.001, subsample=1.0, colsample_bytree=1.0, reg_alpha=0, reg_lambda=0, scale_pos_weight=1, min_split_gain=0, boosting_type='gbdt', objective='binary', eval_metric=None, early_stopping_rounds=None, early_stopping_metric=None, first_metric_only=True, validation_fraction=0.2, random_state=None, n_jobs=-1, verbose=False, params=None, scorecard_params=None, **kwargs)

基类：BaseRiskModel

LightGBM风控模型.

基于LightGBM的二分类模型，针对风控场景优化。 LightGBM相比XGBoost训练更快，内存占用更少。

参数

参数:

• num_leaves (int) -- 叶子节点数，默认31

• max_depth (int) -- 树最大深度，默认-1(无限制)

• learning_rate (float) -- 学习率，默认0.1

• n_estimators (int) -- 树的数量，默认100

• min_child_samples (int) -- 叶子节点最小样本数，默认20

• min_child_weight (float) -- 叶子节点最小权重和，默认1e-3

• subsample (float) -- 样本采样比例，默认1.0

• colsample_bytree (float) -- 特征采样比例，默认1.0

• reg_alpha (float) -- L1正则化系数，默认0

• reg_lambda (float) -- L2正则化系数，默认0

• scale_pos_weight (float) -- 正负样本权重比，默认1

• min_split_gain (float) -- 节点分裂所需的最小增益，默认0

• boosting_type (str) -- 提升类型，默认'gbdt' - 'gbdt': 传统梯度提升树 - 'dart': Dropouts meet Multiple Additive Regression Trees - 'goss': Gradient-based One-Side Sampling - 'rf': 随机森林

• objective (str) -- 目标函数，默认'binary'

• eval_metric (str | List[str] | None) -- 评估指标，可选列表 - 多个指标时，默认使用第一个指标进行早停

• early_stopping_rounds (int | None) -- 早停轮数，默认None

• early_stopping_metric (str | None) -- 用于早停的评估指标名称，默认None（使用第一个指标） - 当eval_metric有多个时，可通过此参数指定用哪个指标进行早停判断

• first_metric_only (bool) -- 是否只用第一个评估指标进行早停，默认True - 当eval_metric为列表时，True表示只用第一个指标早停，False表示监控所有指标

• validation_fraction (float) -- 验证集比例，默认0.2

• random_state (int | None) -- 随机种子，默认None

• n_jobs (int) -- 并行任务数，默认-1

• verbose (bool) -- 是否输出详细信息，默认False

• params (Dict[str, Any] | None) -- LightGBM原生参数字典，默认None - 如果传入，将覆盖其他参数设置 - 可直接使用LightGBM原生参数名

• kwargs -- 其他LightGBM参数

• scorecard_params (Dict[str, Any] | None)

属性

变量:

• feature_importances_ -- 特征重要性

• evals_result_ -- 训练过程评估结果

• best_iteration_ -- 最佳迭代次数

• best_score_ -- 最佳得分

• booster_ -- 底层LightGBM模型

参数:

• num_leaves (int)

• max_depth (int)

• learning_rate (float)

• n_estimators (int)

• min_child_samples (int)

• min_child_weight (float)

• subsample (float)

• colsample_bytree (float)

• reg_alpha (float)

• reg_lambda (float)

• scale_pos_weight (float)

• min_split_gain (float)

• boosting_type (str)

• objective (str)

• eval_metric (str | List[str] | None)

• early_stopping_rounds (int | None)

• early_stopping_metric (str | None)

• first_metric_only (bool)

• validation_fraction (float)

• random_state (int | None)

• n_jobs (int)

• verbose (bool)

• params (Dict[str, Any] | None)

• scorecard_params (Dict[str, Any] | None)

参考样例

>>> # 基础使用
>>> model = LightGBM(num_leaves=31, learning_rate=0.1)
>>> model.fit(X_train, y_train)

>>> # 使用原生LightGBM参数
>>> params = {'num_leaves': 31, 'learning_rate': 0.05, 'subsample': 0.8}
>>> model = LightGBM(params=params)
>>> model.fit(X_train, y_train)

引用

基于 LightGBM 梯度提升框架（leaf-wise 生长 + 直方图算法），见 Ke, G. et al. (2017). LightGBM: A Highly Efficient Gradient Boosting Decision Tree. NeurIPS；文档 https://lightgbm.readthedocs.io/ 。

fit(X, y=None, sample_weight=None, eval_set=None, **fit_params)

训练LightGBM模型.

支持两种调用方式: 1. 常规方式: fit(X, y) 2. scorecardpipeline风格: fit(X) 在init中指定target

参数:

• X (ndarray | DataFrame) -- 特征矩阵

• y (ndarray | Series | None) -- 目标变量，可选

• sample_weight (ndarray | None) -- 样本权重

• eval_set (List[Tuple] | None) -- 验证集列表

• fit_params -- 其他fit参数

返回:

self

返回类型:

LightGBM

predict(X)

预测类别标签.

基于 predict_proba 取阈值，确保自定义损失（原始分数输出）下也能返回正确类别。

参数:

X (ndarray | DataFrame)

返回类型:

ndarray

predict_proba(X)

预测概率.

当使用自定义损失函数（objective 为可调用对象）时，LightGBM 返回的是 未经过链接函数转换的原始分数（raw margin，一维数组），此处自动应用 sigmoid 转换为概率并补齐为二维 (n_samples, 2) 输出，与内置目标保持一致。

参数:

X (ndarray | DataFrame)

返回类型:

ndarray

get_feature_importances(importance_type='gain')

获取特征重要性.

参数:

importance_type (str) -- 重要性类型，可选: - 'gain': 平均增益 (默认) - 'split': 分裂次数

返回:

特征重要性Series

返回类型:

Series

property feature_importances_: ndarray

特征重要性属性 (兼容sklearn风格).

直接在包装类上暴露重要性，兼容sklearn RFE/SFS等组件的 importance_getter。

get_booster()

获取底层LightGBM booster对象.

返回:

LightGBM Booster对象

返回类型:

lgb.Booster

plot_tree(tree_index=0, **kwargs)

绘制树结构.

参数:

• tree_index (int) -- 树的索引

• kwargs -- 其他绘图参数

plot_importance(max_num_features=10, **kwargs)

绘制特征重要性.

参数:

• max_num_features (int) -- 显示的最大特征数

• kwargs -- 其他绘图参数

get_leaf_indices(X)

获取叶子节点索引.

返回每棵树上的叶子节点索引，用于GBDT+LR等场景。

参数:

X (ndarray | DataFrame) -- 特征矩阵

返回:

叶子节点索引，形状 (n_samples, n_trees)

返回类型:

ndarray

参考样例

>>> model = LightGBM(n_estimators=50)
>>> model.fit(X, y)
>>> leaf_indices = model.get_leaf_indices(X)
>>> print(leaf_indices.shape)

save_model(path)

保存底层LightGBM模型（原生格式）.

参数:

path (str) -- 保存路径（.txt/.bin 格式）

load_model(path)

加载底层LightGBM模型（原生格式）.

参数:

path (str) -- 模型路径

返回:

self

返回类型:

LightGBM

class hscredit.core.models.boosting.catboost_model.CatBoost(depth=6, learning_rate=0.1, iterations=100, l2_leaf_reg=3.0, border_count=254, random_strength=1.0, bagging_temperature=1.0, scale_pos_weight=1.0, min_data_in_leaf=1, grow_policy='SymmetricTree', objective='Logloss', eval_metric='AUC', early_stopping_rounds=None, early_stopping_metric=None, validation_fraction=0.2, random_state=None, n_jobs=-1, verbose=False, params=None, scorecard_params=None, **kwargs)

基类：BaseRiskModel

CatBoost风控模型.

基于CatBoost的二分类模型，针对风控场景优化。 CatBoost对类别特征有原生支持，无需编码。

参数

参数:

• depth (int) -- 树深度，默认6

• learning_rate (float) -- 学习率，默认0.1

• iterations (int) -- 迭代次数，默认100

• l2_leaf_reg (float) -- L2正则化系数，默认3.0

• border_count (int) -- 边界分割数，默认254

• random_strength (float) -- 随机强度，默认1

• bagging_temperature (float) -- 采样温度，默认1

• scale_pos_weight (float) -- 正负样本权重比，默认1

• min_data_in_leaf (int) -- 叶子节点最小样本数，默认1

• grow_policy (str) -- 生长策略，默认'SymmetricTree' - 'SymmetricTree': 对称树 - 'Depthwise': 逐层生长 - 'Lossguide': 按损失导向生长

• objective (str) -- 目标函数，默认'Logloss'

• eval_metric (str | List[str] | None) -- 评估指标，默认'AUC' - 支持字符串或列表（多个评估指标）

• early_stopping_rounds (int | None) -- 早停轮数，默认None - 当验证集指标连续N轮没有提升时停止训练 - CatBoost仍支持此参数（与XGBoost/LightGBM新版不同）

• early_stopping_metric (str | None) -- 用于早停的评估指标名称，默认None（使用eval_metric） - 当eval_metric有多个时，指定用哪个指标进行早停判断

• validation_fraction (float) -- 验证集比例，默认0.2

• random_state (int | None) -- 随机种子，默认None

• verbose (bool) -- 是否输出详细信息，默认False

• params (Dict[str, Any] | None) -- CatBoost原生参数字典，默认None - 如果传入，将覆盖其他参数设置 - 可直接使用CatBoost原生参数名

• kwargs -- 其他CatBoost参数

• n_jobs (int)

• scorecard_params (Dict[str, Any] | None)

属性

变量:

• feature_importances_ -- 特征重要性

• evals_result_ -- 训练过程评估结果

• best_iteration_ -- 最佳迭代次数

• best_score_ -- 最佳得分

参数:

• depth (int)

• learning_rate (float)

• iterations (int)

• l2_leaf_reg (float)

• border_count (int)

• random_strength (float)

• bagging_temperature (float)

• scale_pos_weight (float)

• min_data_in_leaf (int)

• grow_policy (str)

• objective (str)

• eval_metric (str | List[str] | None)

• early_stopping_rounds (int | None)

• early_stopping_metric (str | None)

• validation_fraction (float)

• random_state (int | None)

• n_jobs (int)

• verbose (bool)

• params (Dict[str, Any] | None)

• scorecard_params (Dict[str, Any] | None)

参考样例

>>> # 基础使用
>>> model = CatBoost(depth=6, learning_rate=0.1)
>>> model.fit(X_train, y_train)

>>> # 使用原生CatBoost参数
>>> params = {'depth': 6, 'learning_rate': 0.05, 'l2_leaf_reg': 3.0}
>>> model = CatBoost(params=params)
>>> model.fit(X_train, y_train)

引用

基于 CatBoost 梯度提升框架（有序提升 + 类别特征原生处理），见 Prokhorenkova, L. et al. (2018). CatBoost: unbiased boosting with categorical features. NeurIPS；文档 https://catboost.ai/docs/ 。

fit(X, y=None, sample_weight=None, eval_set=None, cat_features=None, **fit_params)

训练CatBoost模型.

支持两种调用方式: 1. 常规方式: fit(X, y) 2. scorecardpipeline风格: fit(X) 在init中指定target

参数:

• X (ndarray | DataFrame) -- 特征矩阵

• y (ndarray | Series | None) -- 目标变量，可选

• sample_weight (ndarray | None) -- 样本权重

• eval_set (List[Tuple] | None) -- 验证集列表

• cat_features (List[int] | None) -- 类别特征索引列表

• fit_params -- 其他fit参数

返回:

self

返回类型:

CatBoost

predict(X)

预测类别标签.

基于 predict_proba 取阈值，确保自定义损失（原始分数输出）下也能返回正确类别。

参数:

X (ndarray | DataFrame)

返回类型:

ndarray

predict_proba(X)

预测概率.

当使用自定义损失函数（loss_function 为可调用对象）时，CatBoost 返回的是 未经过链接函数转换的原始分数（raw margin，一维数组），此处自动应用 sigmoid 转换为概率并补齐为二维 (n_samples, 2) 输出，与内置目标保持一致。

参数:

X (ndarray | DataFrame)

返回类型:

ndarray

get_feature_importances(importance_type='PredictionValuesChange')

获取特征重要性.

参数:

importance_type (str) -- 重要性类型，可选: - 'PredictionValuesChange': 预测值变化 (默认) - 'LossFunctionChange': 损失函数变化 - 'FeatureImportance': 分裂次数

返回:

特征重要性Series

返回类型:

Series

property feature_importances_: ndarray

特征重要性属性 (兼容sklearn风格).

直接在包装类上暴露重要性，兼容sklearn RFE/SFS等组件的 importance_getter。

plot_tree(tree_index=0, **kwargs)

绘制树结构.

参数:

• tree_index (int) -- 树的索引

• kwargs -- 其他绘图参数

get_leaf_indices(X)

获取叶子节点索引.

返回每棵树上的叶子节点索引，用于GBDT+LR等场景。

参数:

X (ndarray | DataFrame) -- 特征矩阵

返回:

叶子节点索引，形状 (n_samples, n_trees)

返回类型:

ndarray

参考样例

>>> model = CatBoost(iterations=50)
>>> model.fit(X, y)
>>> leaf_indices = model.get_leaf_indices(X)
>>> print(leaf_indices.shape)

save_model(path)

保存底层CatBoost模型（原生格式）.

参数:

path (str) -- 保存路径（.cbm/.json 格式）

load_model(path)

加载底层CatBoost模型（原生格式）.

参数:

path (str) -- 模型路径

返回:

self

返回类型:

CatBoost

class hscredit.core.models.boosting.ngboost_model.NGBoost(n_estimators=500, learning_rate=0.01, minibatch_frac=1.0, col_sample=1.0, base_max_depth=3, base_criterion='friedman_mse', base_min_samples_split=2, base_min_samples_leaf=1, natural_gradient=True, objective='binary', eval_metric=None, early_stopping_rounds=None, validation_fraction=0.2, random_state=None, n_jobs=-1, verbose=False, params=None, scorecard_params=None, **kwargs)

基类：BaseRiskModel

NGBoost风控模型.

基于NGBoost的二分类模型，针对风控场景优化。 NGBoost通过自然梯度提升进行概率预测，能够输出预测不确定性， 适合风控中需要概率校准和不确定性量化的场景。

参数

参数:

• n_estimators (int) -- 提升迭代次数（基学习器数量），默认500

• learning_rate (float) -- 学习率，默认0.01 - NGBoost对学习率较敏感，通常使用较小的值

• minibatch_frac (float) -- 每次迭代使用的样本比例，默认1.0 - 设为<1.0可进行随机梯度提升，加速训练

• col_sample (float) -- 每次迭代使用的特征比例，默认1.0 - 类似XGBoost的colsample_bytree

• base_max_depth (int) -- 基学习器（决策树）最大深度，默认3 - NGBoost使用回归树作为基学习器

• base_criterion (str) -- 基学习器分裂准则，默认'friedman_mse'

• base_min_samples_split (int) -- 基学习器节点分裂最小样本数，默认2

• base_min_samples_leaf (int) -- 基学习器叶子节点最小样本数，默认1

• natural_gradient (bool) -- 是否使用自然梯度，默认True - True: 使用自然梯度（推荐） - False: 使用普通梯度

• objective (str) -- 目标函数，默认'binary'

• eval_metric (str | List[str] | None) -- 评估指标，可选列表

• early_stopping_rounds (int | None) -- 早停轮数，默认None - 连续N轮验证集loss没有改善则停止训练

• validation_fraction (float) -- 验证集比例，默认0.2

• random_state (int | None) -- 随机种子，默认None

• n_jobs (int) -- 并行任务数，默认-1（NGBoost基学习器内部使用）

• verbose (bool) -- 是否输出详细信息，默认False

• params (Dict[str, Any] | None) -- NGBoost原生参数字典，默认None - 如果传入，将覆盖其他参数设置

• kwargs -- 其他NGBoost参数

• scorecard_params (Dict[str, Any] | None)

属性

变量:

• feature_importances_ -- 特征重要性（基于loc参数的基学习器）

• evals_result_ -- 训练过程评估结果

• best_iteration_ -- 最佳迭代次数（验证集最优时的迭代轮数）

• best_score_ -- 最佳得分

参数:

• n_estimators (int)

• learning_rate (float)

• minibatch_frac (float)

• col_sample (float)

• base_max_depth (int)

• base_criterion (str)

• base_min_samples_split (int)

• base_min_samples_leaf (int)

• natural_gradient (bool)

• objective (str)

• eval_metric (str | List[str] | None)

• early_stopping_rounds (int | None)

• validation_fraction (float)

• random_state (int | None)

• n_jobs (int)

• verbose (bool)

• params (Dict[str, Any] | None)

• scorecard_params (Dict[str, Any] | None)

参考样例

>>> # 基础使用
>>> model = NGBoost(n_estimators=500, learning_rate=0.01)
>>> model.fit(X_train, y_train)

>>> # 使用验证集早停
>>> model = NGBoost(
...     n_estimators=1000,
...     learning_rate=0.01,
...     early_stopping_rounds=50
... )
>>> model.fit(X_train, y_train)

>>> # 使用原生NGBoost参数
>>> params = {'n_estimators': 500, 'learning_rate': 0.01, 'minibatch_frac': 0.8}
>>> model = NGBoost(params=params)
>>> model.fit(X_train, y_train)

>>> # 获取概率分布（不确定性估计）
>>> dist = model.pred_dist(X_test)
>>> print(dist.params)

引用

基于 NGBoost（自然梯度提升，输出概率分布以量化预测不确定性），见 Duan, T. et al. (2020). NGBoost: Natural Gradient Boosting for Probabilistic Prediction. ICML；文档 https://stanfordmlgroup.github.io/projects/ngboost/ 。

fit(X, y=None, sample_weight=None, eval_set=None, **fit_params)

训练NGBoost模型.

支持两种调用方式: 1. 常规方式: fit(X, y) 2. scorecardpipeline风格: fit(X) 在init中指定target

参数:

• X (ndarray | DataFrame) -- 特征矩阵

• y (ndarray | Series | None) -- 目标变量，可选

• sample_weight (ndarray | None) -- 样本权重

• eval_set (List[Tuple] | None) -- 验证集列表 [(X_val, y_val)]

• fit_params -- 其他fit参数

返回:

self

返回类型:

NGBoost

property best_iteration_

最佳迭代次数.

property best_score_

最佳得分.

predict(X)

预测类别标签.

支持传入包含target列的数据框（scorecardpipeline风格）。

参数:

X (ndarray | DataFrame)

返回类型:

ndarray

predict_proba(X)

预测概率.

支持传入包含target列的数据框（scorecardpipeline风格）。

参数:

X (ndarray | DataFrame) -- 特征矩阵

返回:

预测概率，形状 (n_samples, 2)

返回类型:

ndarray

pred_dist(X)

预测概率分布.

返回NGBoost分布对象，可用于获取预测不确定性。

参数:

X (ndarray | DataFrame) -- 特征矩阵

返回:

NGBoost分布对象

参考样例

>>> model = NGBoost()
>>> model.fit(X_train, y_train)
>>> dist = model.pred_dist(X_test)
>>> print(dist.params)

get_feature_importances(importance_type='gain')

获取特征重要性.

NGBoost为每个分布参数维护独立的基学习器序列。 对于二分类(Bernoulli)，使用第一个参数(p)的特征重要性。

参数:

importance_type (str) -- 重要性类型（保留参数，NGBoost使用基学习器默认重要性）

返回:

特征重要性Series

返回类型:

Series

property feature_importances_: ndarray

特征重要性属性 (兼容sklearn风格).

返回一维numpy数组，与其他RiskModel保持一致。

staged_predict(X)

阶段预测.

返回每个迭代阶段的预测结果列表。

参数:

X (ndarray | DataFrame) -- 特征矩阵

返回:

预测结果列表，长度为n_estimators

返回类型:

List[ndarray]

staged_pred_dist(X)

阶段分布预测.

返回每个迭代阶段的完整分布预测。

参数:

X (ndarray | DataFrame) -- 特征矩阵

返回:

分布对象列表

返回类型:

list

plot_importance(max_num_features=10, figsize=(10, 6), **kwargs)

绘制特征重要性.

参数:

• max_num_features (int) -- 显示的最大特征数

• figsize (Tuple) -- 图像大小

• kwargs -- 其他绘图参数

save_model(path)

保存底层NGBoost模型（pickle格式）.

参数:

path (str) -- 保存路径（.pkl格式）

load_model(path)

加载底层NGBoost模型（pickle格式）.

参数:

path (str) -- 模型路径（.pkl格式）

返回:

self

返回类型:

NGBoost