经典模型

hscredit.core.models 提供统一接口的经典风控模型。

class hscredit.core.models.LogisticRegression(penalty='l2', calculate_stats=True, dual=False, tol=0.0001, C=1.0, fit_intercept=True, intercept_scaling=1, class_weight=None, random_state=None, solver='lbfgs', max_iter=100, multi_class='auto', verbose=0, warm_start=False, n_jobs=None, l1_ratio=None, positive_woe_coef='auto', target=None, scorecard_params=None)[源代码]

基类：_ProbabilityScoreCardMixin, ArtifactSerializableMixin, LogisticRegression

参数:

penalty (str)
calculate_stats (bool)
dual (bool)
tol (float)
C (float)
fit_intercept (bool)
intercept_scaling (float)
class_weight (dict | str | None)
random_state (int | None)
solver (str)
max_iter (int)
multi_class (str)
verbose (int)
warm_start (bool)
n_jobs (int | None)
l1_ratio (float | None)
positive_woe_coef (bool | str)
target (str | None)
scorecard_params (Dict[str, Any] | None)

artifact_kind = '风险模型'

扩展逻辑回归模型.

继承 sklearn.linear_model.LogisticRegression，增加统计信息计算功能。在训练时自动计算以下统计信息（当 calculate_stats=True 时）： - cov_matrix_: 参数的协方差矩阵 - std_err_intercept_: 截距的标准误差 - std_err_coef_: 系数的标准误差 - z_intercept_: 截距的z统计量 - z_coef_: 系数的z统计量 - p_val_intercept_: 截距的p值 - p_val_coef_: 系数的p值 - vif_: 方差膨胀因子（VIF）

可通过 summary() 方法获取格式化的回归结果表。

参数

参数:

penalty -- 正则化类型，可选 'l1', 'l2', 'elasticnet', 'none'，默认 'l2' - 'newton-cg', 'lbfgs', 'sag': 仅支持 'l2' - 'liblinear', 'saga': 支持 'l1', 'l2' - 'saga': 支持 'elasticnet'
calculate_stats -- 是否在训练时计算统计信息，默认 True 设置为 False 可提高训练速度，但无法使用 summary() 方法
dual -- 是否使用对偶形式，默认 False 仅当 solver='liblinear' 时有效
tol -- 优化算法的收敛容差，默认 1e-4
C -- 正则化强度的倒数，默认 1.0 必须是正浮点数，值越小正则化越强
fit_intercept -- 是否拟合截距项，默认 True
intercept_scaling -- 截距缩放系数，默认 1.0 仅当 solver='liblinear' 且 fit_intercept=True 时有效
class_weight -- 类别权重，默认 None 可选 'balanced' 或自定义字典 'balanced' 使用 n_samples / (n_classes * np.bincount(y))
random_state -- 随机数种子，默认 None 仅在 solver 为 'sag', 'saga', 'liblinear' 时有效
solver -- 优化算法，默认 'lbfgs' - 'newton-cg': 牛顿共轭梯度法 - 'lbfgs': 拟牛顿法 - 'liblinear': 坐标下降法 - 'sag': 随机平均梯度下降 - 'saga': SAGA 随机优化算法
max_iter -- 最大迭代次数，默认 100
multi_class -- 多分类策略，默认 'auto' 可选 'auto', 'ovr', 'multinomial'
verbose -- 日志详细程度，默认 0
warm_start -- 是否使用上次结果初始化，默认 False
n_jobs -- 并行计算的CPU核心数，默认 None -1 表示使用所有可用核心
l1_ratio -- 弹性网络混合参数，默认 None 0 <= l1_ratio <= 1，仅当 penalty='elasticnet' 时有效
positive_woe_coef -- WOE 模型系数正向化策略，默认 'auto' - 'auto': 仅当输入 DataFrame 被标记为 hscredit 的 WOE 编码结果时启用 - True: 始终启用。会将负系数对应列乘以 -1，并把系数改为正值 - False: 禁用，保持 sklearn 原始系数符号
target -- scorecardpipeline 风格的目标列名，默认 None
scorecard_params -- 概率评分卡部分覆盖参数，默认 PDO=50、基准分=600、范围0-1000

属性

coef_: 模型系数，形状 (n_classes, n_features) 或 (n_features,)
intercept_: 截距项，形状 (n_classes,) 或 (1,)
classes_: 类别标签数组
n_features_in_: 训练时的特征数量
feature_names_in_: 训练时的特征名称（当输入为DataFrame时）
cov_matrix_: 参数的协方差矩阵
std_err_coef_: 系数的标准误差
std_err_intercept_: 截距的标准误差
z_coef_: 系数的z统计量
z_intercept_: 截距的z统计量
p_val_coef_: 系数的p值
p_val_intercept_: 截距的p值
vif_: 方差膨胀因子数组
woe_coef_signs_: WOE 列方向调整向量，1 表示不变，-1 表示该列已翻转
raw_coef_: 原始拟合系数（正向化前，仅在启用 positive_woe_coef 后提供）

参考样例

基本使用:

>>> from hscredit.core.models import LogisticRegression
>>> import pandas as pd
>>> import numpy as np
>>>
>>> # 创建示例数据
>>> np.random.seed(42)
>>> X = pd.DataFrame({
...     'age': np.random.randint(18, 65, 1000),
...     'income': np.random.randint(3000, 50000, 1000),
... })
>>> y = (X['age'] + X['income'] / 1000 > 50).astype(int)
>>>
>>> # 训练模型
>>> model = LogisticRegression(calculate_stats=True, max_iter=1000)
>>> model.fit(X, y)
>>>
>>> # 查看统计摘要
>>> summary = model.summary()
>>> print(summary[['Coef.', 'Std.Err', 'P>|z|', 'VIF']])

使用样本权重:

>>> sample_weight = np.where(y == 1, 2.0, 1.0)  # 增加正样本权重
>>> model.fit(X, y, sample_weight=sample_weight)

筛选显著特征:

>>> # 获取 p < 0.05 的显著特征
>>> sig_features = model.get_significant_features(alpha=0.05)

注意事项

当 calculate_stats=True 时，会计算标准误差、z值、p值和VIF
统计计算基于高斯假设，使用协方差矩阵估计
VIF 计算需要拟合截距项（fit_intercept=True）
VIF > 10 通常表示存在严重的多重共线性

fit(X, y=None, sample_weight=None, **kwargs)[源代码]

训练逻辑回归模型.

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

在 sklearn LogisticRegression.fit() 的基础上，当 calculate_stats=True 时额外计算统计信息。

参数

参数:

X (DataFrame | ndarray) -- 训练数据，形状 (n_samples, n_features) 支持 numpy array 或 pandas DataFrame 如果是DataFrame且y为None，会尝试从X中提取target列
y (ndarray | Series | None) -- 目标变量，形状 (n_samples,)，可选二分类时为 0/1 或 -1/1 如果为None且init中指定了target，则从X中提取
sample_weight (ndarray | None) -- 样本权重，形状 (n_samples,) 默认 None，所有样本权重为1
kwargs -- 其他传递给父类 fit 方法的参数

返回类型:

LogisticRegression

返回

返回:

self，训练好的模型实例

参数:

X (DataFrame | ndarray)
y (ndarray | Series | None)
sample_weight (ndarray | None)

返回类型:

LogisticRegression

异常

抛出:

ValueError -- 输入数据格式不正确
AssertionError -- calculate_stats=False 时无法计算统计信息

参数:

X (DataFrame | ndarray)
y (ndarray | Series | None)
sample_weight (ndarray | None)

返回类型:

LogisticRegression

参考样例

基本拟合:

>>> model = LogisticRegression(calculate_stats=True)
>>> model.fit(X_train, y_train)

使用样本权重:

>>> sample_weight = np.where(y_train == 1, 2.0, 1.0)
>>> model.fit(X_train, y_train, sample_weight=sample_weight)

scorecardpipeline风格:

>>> model = LogisticRegression(target='label')
>>> model.fit(X_train)  # 从X_train中提取'label'列作为y

ensure_positive_woe_coefficients(X=None)[源代码]

将 WOE 逻辑回归的负系数归一为正，并保持预测结果不变.

做法是：对负系数对应的输入列乘以 -1，同时把系数改成绝对值。这样线性预测值保持不变，但模型摘要和评分卡解释更符合 WOE 场景。

参数:: X (DataFrame | ndarray | None)
返回类型:: LogisticRegression

predict_proba(X)[源代码]

预测各类别概率（评分卡建模常用，输入通常为 WOE 数据）。

当启用 positive_woe_coef 时，会按训练阶段确定的 WOE 列方向自动调整输入，保证概率与评分卡分数方向一致。

参数:: X (DataFrame | ndarray) -- 特征矩阵（一般为 WOE 编码后数据），DataFrame 或 ndarray
返回:: 概率数组，shape (n_samples, 2)，第 1 列为正类（坏样本）概率
返回类型:: ndarray

predict_log_proba(X)[源代码]

预测各类别的对数概率（ln(predict_proba)，数值已做下限裁剪）。

参数:: X (DataFrame | ndarray) -- 特征矩阵，DataFrame 或 ndarray
返回:: 对数概率数组，shape (n_samples, 2)
返回类型:: ndarray

decision_function(X)[源代码]

计算线性决策值（log-odds），必要时自动应用 WOE 列方向调整。

参数:: X (DataFrame | ndarray) -- 特征矩阵，DataFrame 或 ndarray
返回:: 决策函数值数组（> 0 判为正类）
返回类型:: ndarray

predict(X)[源代码]

预测类别标签（阈值为决策值 0），必要时自动应用 WOE 列方向调整。

参数:: X (DataFrame | ndarray) -- 特征矩阵，DataFrame 或 ndarray
返回:: 预测类别数组
返回类型:: ndarray

get_feature_importances(importance_type='coef')[源代码]

获取特征重要性.

对于逻辑回归模型，使用系数绝对值作为特征重要性。

参数:: importance_type (str) -- 重要性类型，默认'coef' - 'coef': 系数绝对值 - 'p_value': 基于p值的重要性 (1 - p_value) - 'z_score': z统计量绝对值
返回:: 特征重要性Series
返回类型:: Series

property feature_importances_: ndarray

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

直接从内部模型获取系数绝对值，避免缓存逻辑在clone后出错。

summary()[源代码]

获取回归结果的统计摘要.

返回包含系数、标准误差、z统计量、p值、置信区间和VIF的DataFrame。

返回

返回:: summary_df，统计摘要表，包含以下列： - Coef.: 回归系数 - Std.Err: 标准误差 - z: z统计量（系数/标准误差） - P>|z|: p值 - [0.025: 95%置信区间下限 - 0.975]: 95%置信区间上限 - VIF: 方差膨胀因子
返回类型:: DataFrame

异常

抛出:: AssertionError -- 如果训练时 calculate_stats=False
返回类型:: DataFrame

参考样例

基本使用:

>>> model = LogisticRegression(calculate_stats=True)
>>> model.fit(X, y)
>>> summary = model.summary()
>>> print(summary)

筛选显著变量:

>>> # 筛选 p < 0.05 的显著变量
>>> significant = summary[summary['P>|z|'] < 0.05]
>>> print(significant[['Coef.', 'P>|z|', 'VIF']])

summary_with_desc(feature_map=None)[源代码]

获取带特征描述的统计摘要.

在 summary() 基础上增加特征描述列。

参数

参数:: feature_map (dict | None) -- 特征描述字典，格式为 {特征名: 描述}，默认 None
返回类型:: DataFrame

返回

返回:: summary_df，带描述的统计摘要表，增加 Features 和 Describe 列
参数:: feature_map (dict | None)
返回类型:: DataFrame

参考样例

使用特征描述:

>>> feature_map = {
...     'age': '年龄',
...     'income': '收入',
... }
>>> summary = model.summary_with_desc(feature_map)
>>> print(summary[['Features', 'Describe', 'Coef.', 'P>|z|']])

get_significant_features(alpha=0.05, include_intercept=False)[源代码]

获取统计显著的特征.

根据p值筛选显著特征。

参数

参数:

alpha (float) -- 显著性水平，默认 0.05 p < alpha 的特征被认为是显著的
include_intercept (bool) -- 是否包含截距项，默认 False

返回类型:

DataFrame

返回

返回:

significant_df，显著特征的统计信息

参数:

alpha (float)
include_intercept (bool)

返回类型:

DataFrame

参考样例

筛选显著特征:

>>> # 获取 p < 0.01 的显著特征
>>> sig_features = model.get_significant_features(alpha=0.01)
>>> print(sig_features)

check_multicollinearity(threshold=10.0)[源代码]

检查多重共线性.

基于VIF值检测多重共线性。VIF > threshold 表示存在共线性问题。

参数

参数:: threshold (float) -- VIF阈值，默认 10.0 VIF > threshold 被认为存在多重共线性
返回类型:: DataFrame

返回

返回:: high_vif_df，VIF值超过阈值的特征信息
参数:: threshold (float)
返回类型:: DataFrame

参考样例

检查共线性:

>>> # 检查 VIF > 5 的特征
>>> collinear = model.check_multicollinearity(threshold=5.0)
>>> print(collinear)

evaluate(X, y, sample_weight=None, metrics=None)[源代码]

评估模型性能（与 BaseRiskModel.evaluate 接口一致）.

参数:

X (DataFrame | ndarray) -- 特征矩阵
y (Series | ndarray) -- 真实标签
sample_weight (ndarray | None) -- 样本权重
metrics (List[str] | None) -- 评估指标列表

返回:

评估结果字典

返回类型:

dict

predict_score(X)[源代码]

使用训练坏好比对应的标准概率评分卡预测风险评分.

参数:: X (DataFrame | ndarray) -- 特征矩阵
返回:: 风险评分 (0-1000)
返回类型:: ndarray

report(datasets=None, X_train=None, y_train=None, X_test=None, y_test=None, overdue=None, dpds=None, excel_path=None, verbose=True, **kwargs)[源代码]

生成风控建模报告（与 BaseRiskModel.report() 接口一致）。

在训练/测试集上汇总模型表现（KS、AUC、分数分布、逾期率等），可选导出 Excel。

参数:

datasets -- 数据集字典（如 {'train': (X, y), 'test': (X, y)}），与 X_train/y_train/X_test/y_test 二选一
X_train -- 训练特征，与 datasets 二选一
y_train -- 训练标签
X_test -- 测试特征，可选
y_test -- 测试标签，可选
overdue -- 逾期天数字段名（多标签分析时使用），可选
dpds -- 逾期定义 DPD（如 [7, 3]），可选
excel_path -- 报告导出的 Excel 路径，提供则落盘，可选
verbose -- 是否打印进度，默认 True
kwargs -- 透传给报告生成器的其他参数

返回:

ModelReport 实例

抛出:

NotFittedError -- 模型尚未训练时

tune(X, y=None, search_space=None, fixed_params=None, metric='ks', direction='maximize', n_trials=100, cv=5, timeout=None, verbose=False, **kwargs)[源代码]

超参数调优并返回最佳模型（与 BaseRiskModel.tune 接口一致）.

集成 ModelTuner（基于 Optuna），默认使用逻辑回归的自适应搜索空间（C / penalty / class_weight / max_iter / solver）。

参数:

X (DataFrame | ndarray) -- 特征矩阵或包含 target 的 DataFrame
y (ndarray | Series | None) -- 目标变量，可选
search_space (dict | None) -- 参数搜索空间，默认使用自适应空间
fixed_params (dict | None) -- 固定参数
metric -- 优化指标，默认 'ks'
direction -- 优化方向，默认 'maximize'
n_trials (int) -- 搜索次数，默认 100
cv (int) -- 交叉验证折数，默认 5
timeout (int | None) -- 超时时间(秒)
verbose (bool) -- 是否输出详细信息
kwargs -- 其他传递给 ModelTuner 的参数（如 sampler/storage）

返回:

使用最佳参数训练好的模型实例

返回类型:

LogisticRegression

参考样例

>>> model = LogisticRegression()
>>> best_model = model.tune(X_train, y_train, n_trials=50)
>>> proba = best_model.predict_proba(X_test)

save(path, engine='auto', **kwargs)[源代码]

保存模型到文件（与 BaseRiskModel.save 接口一致）.

参数:

path (str) -- 保存路径
engine (str) -- 序列化引擎

返回:

保存路径

返回类型:

str

classmethod load(path, engine='auto', **kwargs)[源代码]

从文件加载模型（与 BaseRiskModel.load 接口一致）.

参数:

path (str) -- 模型文件路径
engine (str) -- 序列化引擎

返回:

加载的模型实例

返回类型:

LogisticRegression

get_model_info()[源代码]

获取模型摘要信息（与 BaseRiskModel.get_model_info() 接口一致）。

返回:: 含 model_type / objective / n_features / n_classes / params 等键的字典（LR 无 boosting 迭代，故 best_iteration/best_score 为 None）
抛出:: NotFittedError -- 模型尚未训练时
返回类型:: dict

get_native_model()[源代码]

获取底层原生模型（与 BaseRiskModel.get_native_model() 接口一致）。

本类直接继承 sklearn LogisticRegression 并未包装额外底层模型，故返回自身，便于与 boosting 模型（返回各自原生 booster）的统一调用。

返回:: self
抛出:: NotFittedError -- 模型尚未训练时

class hscredit.core.models.BaseRiskModel(objective='binary', eval_metric=None, target=None, early_stopping_rounds=None, validation_fraction=0.2, random_state=None, n_jobs=-1, verbose=False, scorecard_params=None, **kwargs)[源代码]

基类：_ProbabilityScoreCardMixin, ArtifactSerializableMixin, BaseEstimator, ClassifierMixin, ABC

风控模型基类.

所有风控模型的抽象基类，定义统一接口。继承sklearn的BaseEstimator和ClassifierMixin。支持scorecardpipeline风格的fit（可在init中指定target列）。

参数

参数:

objective (str | Callable) -- 目标函数，可选: - 'binary': 二分类(默认) - 'binary:logistic': 二分类逻辑回归 - 'regression': 回归 - 自定义可调用对象
eval_metric (str | List[str] | Callable | None) -- 评估指标，可选列表或单个指标: - 'auc': AUC - 'ks': KS统计量 - 'gini': Gini系数 - 'lift': Lift值 - 'logloss': 对数损失 - 自定义可调用对象
target (str | None) -- 目标列名，默认None - 如果指定，fit时只需传入X，会自动从X中提取target列作为y - 支持scorecardpipeline风格的有监督fit
early_stopping_rounds (int | None) -- 早停轮数，默认None
validation_fraction (float) -- 验证集比例，默认0.2
random_state (int | None) -- 随机种子，默认None
n_jobs (int) -- 并行任务数，默认-1
verbose (bool) -- 是否输出详细信息，默认False
scorecard_params (Dict[str, Any] | None) -- 概率评分卡参数，可传部分配置覆盖默认值；默认使用 PDO=50、基准分=600、坏好比由训练标签计算、分数范围0-1000且分越高风险越低
kwargs -- 模型特定参数

属性

变量:

classes_ -- 类别标签
n_features_in_ -- 特征数量
feature_names_in_ -- 特征名称
feature_importances_ -- 特征重要性
evals_result_ -- 训练过程评估结果
best_iteration_ -- 最佳迭代次数
best_score_ -- 最佳得分
tuner -- 最近一次通过 tune() 创建的 ModelTuner，未调参时为 None
bad_rate_ -- 训练集坏样本率
base_odds_ -- 训练集坏好比
scorecard_ -- 已拟合的概率评分卡

参数:

objective (str | Callable)
eval_metric (str | List[str] | Callable | None)
target (str | None)
early_stopping_rounds (int | None)
validation_fraction (float)
random_state (int | None)
n_jobs (int)
verbose (bool)
scorecard_params (Dict[str, Any] | None)

artifact_kind = '风险模型'

SUPPORTED_METRICS = ['auc', 'ks', 'gini', 'lift', 'lift@1%', 'lift@3%', 'lift@5%', 'lift@10%', 'logloss', 'accuracy', 'brier', 'precision', 'recall', 'f1', 'lift_monotonicity']

DEFAULT_METRICS = ['auc', 'ks', 'gini', 'lift@1%', 'lift@3%', 'lift@5%', 'lift@10%']

abstractmethod fit(X, y=None, sample_weight=None, eval_set=None, **fit_params)[源代码]

训练模型.

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

参数:

X (ndarray | DataFrame) -- 特征矩阵，支持numpy数组或pandas DataFrame
y (ndarray | Series | None) -- 目标变量，可选。如果未提供且init中指定了target，则从X中提取
sample_weight (ndarray | None) -- 样本权重，可选
eval_set (List[Tuple] | None) -- 验证集列表 [(X_val1, y_val1), ...]，可选
fit_params -- 其他fit参数

返回:

self

返回类型:

BaseRiskModel

abstractmethod predict(X)[源代码]

预测类别标签.

参数:: X (ndarray | DataFrame) -- 特征矩阵
返回:: 预测类别
返回类型:: ndarray

abstractmethod predict_proba(X)[源代码]

预测概率.

参数:: X (ndarray | DataFrame) -- 特征矩阵
返回:: 预测概率，形状 (n_samples, n_classes)
返回类型:: ndarray

predict_score(X)[源代码]

使用训练坏好比对应的标准概率评分卡预测风险评分.

参数:: X (ndarray | DataFrame) -- 特征矩阵
返回:: 风险评分 (0-1000)
返回类型:: ndarray

property best_iteration_

最佳迭代次数（早停后），未启用早停时为 None.

统一暴露给所有子类（XGBoost/LightGBM/CatBoost/NGBoost/sklearn 集成）。

property best_score_: 最佳得分（早停验证集上），未启用早停时为 None.

property evals_result_: Dict[str, Any]: 返回训练期间记录的验证集指标。

abstractmethod get_feature_importances(importance_type='gain')[源代码]

获取特征重要性.

参数:: importance_type (str) -- 重要性类型，可选: - 'gain': 增益 (默认) - 'split': 分裂次数 - 'weight': 权重 - 'cover': 覆盖度
返回:: 特征重要性Series
返回类型:: Series

get_model_info()[源代码]

获取模型信息.

返回:: 包含模型信息的字典
返回类型:: Dict[str, Any]

evaluate(X, y, sample_weight=None, metrics=None, positive_class=None)[源代码]

评估模型性能.

参数:

X (ndarray | DataFrame) -- 特征矩阵
y (ndarray | Series) -- 真实标签
sample_weight (ndarray | None) -- 样本权重
metrics (List[str] | None) -- 评估指标列表，默认全部
positive_class (Any | None) -- 显式正类标签；None 时使用 classes_[1]

返回:

评估结果字典

返回类型:

Dict[str, float]

generate_report(X_train, y_train, X_test=None, y_test=None, feature_names=None)[源代码]

生成模型评估报告.

模型报告已统一由 hscredit.report.ModelReport 生成，本方法为其兼容入口，等价于直接构造 ModelReport；如需多 Sheet Excel / 多标签等完整能力，推荐使用 report()。

参数:

X_train (ndarray | DataFrame) -- 训练集特征
y_train (ndarray | Series) -- 训练集标签
X_test (DataFrame | ndarray | None) -- 测试集特征，可选
y_test (ndarray | Series | None) -- 测试集标签，可选
feature_names (List[str] | None) -- 特征名称列表，可选

返回:

ModelReport 对象

返回类型:

ModelReport

report(datasets=None, X_train=None, y_train=None, X_test=None, y_test=None, feature_names=None, target=None, overdue=None, dpds=None, excel_path=None, verbose=True, n_bins=10, amount_col=None, date_col=None, group_col=None, **kwargs)[源代码]

生成风控建模报告（支持多数据集/overdue/dpds）.

委托给 hscredit.report.auto_model_report，生成包含多 Sheet 的 Excel / 控制台报告。

支持三种调用方式:

datasets API（推荐）:

model.report(datasets={'训练集': train_df, '测试集': test_df})
model.report(datasets=[train_df, test_df])

sklearn 风格:

model.report(X_train=X, y_train=y, X_test=X_val, y_test=y_val)

overdue/dpds 自动构建标签:

model.report(datasets={'训练集': df}, overdue='dpds', dpds=[15, 7, 0])

参数:

datasets (List | Dict | None) -- 数据集字典/列表
X_train -- 训练集特征（兼容旧API）
y_train -- 训练集标签（兼容旧API）
X_test -- 测试集特征（兼容旧API）
y_test -- 测试集标签（兼容旧API）
feature_names (List[str] | None) -- 特征名称列表
target (str | Dict | None) -- 目标列配置
overdue (str | List[str] | None) -- 逾期列名
dpds (int | float | List[int | float] | None) -- 逾期天数阈值
excel_path (str | None) -- Excel 报告输出路径
verbose (bool) -- 是否打印控制台报告
n_bins (int) -- 分箱数
amount_col (str | None) -- 金额字段
date_col (str | None) -- 日期字段
group_col (str | None) -- 分组字段
kwargs -- 传递给 auto_model_report 的其他参数

返回:

ModelReport 实例

返回类型:

ModelReport

save(path, engine='auto', **kwargs)[源代码]

保存模型到文件.

支持多种格式: - pickle/joblib: 保存完整模型对象（默认） - json: 保存模型参数和元数据（仅限支持的框架）

参数:

path (str) -- 保存路径，支持 .pkl, .joblib, .pkl.gz, .json 等后缀
engine (str) -- 序列化引擎，可选 'auto', 'joblib', 'pickle', 'dill', 'cloudpickle'
kwargs -- 传递给 save_pickle 的其他参数（如 compression, compression_level）

返回:

保存路径

返回类型:

str

参考样例

>>> model.save('model.pkl')
>>> model.save('model.joblib')
>>> model.save('model.pkl.gz')
>>> model.save('model.pkl', engine='dill')

classmethod load(path, engine='auto', **kwargs)[源代码]

从文件加载模型.

参数:

path (str) -- 模型文件路径
engine (str) -- 序列化引擎，可选 'auto', 'joblib', 'pickle', 'dill', 'cloudpickle'
kwargs -- 传递给 load_pickle 的其他参数

返回:

加载的模型实例

返回类型:

BaseRiskModel

参考样例

>>> model = XGBoost.load('model.pkl')
>>> model = LightGBM.load('model.joblib')
>>> model = BaseRiskModel.load('model.pkl')  # 自动推断模型类型

tune(X, y=None, search_space=None, fixed_params=None, metric='ks', direction='maximize', n_trials=100, cv=5, timeout=None, verbose=None, **kwargs)[源代码]

超参数调优并返回最佳模型.

集成 ModelTuner，一键完成超参数搜索、最佳模型训练。

参数:

X (ndarray | DataFrame) -- 特征矩阵或包含target的DataFrame
y (ndarray | Series | None) -- 目标变量，可选
search_space (Dict[str, Dict[str, Any]] | None) -- 参数搜索空间，默认使用自适应空间
fixed_params (Dict[str, Any] | None) -- 固定参数
metric (str | Callable | List) -- 优化指标
direction (str | List[str]) -- 优化方向
n_trials (int) -- 搜索次数
cv (int) -- 交叉验证折数
timeout (int | None) -- 超时时间(秒)
verbose (bool | None) -- 是否输出详细信息
kwargs -- 其他传递给 ModelTuner 的参数

返回:

使用最佳参数训练好的模型实例

返回类型:

BaseRiskModel

参考样例

>>> model = XGBoost()
>>> best_model = model.tune(X_train, y_train, n_trials=50)
>>> proba = best_model.predict_proba(X_test)

>>> # scorecardpipeline风格
>>> model = LightGBM(target='target')
>>> best_model = model.tune(df, n_trials=50)

get_native_model()[源代码]

获取底层原生模型对象.

用于需要访问底层模型特定功能的场景，如: - 获取叶子节点索引 - 绘制树结构 - 访问底层模型特有的方法

返回:: 底层模型对象（如xgboost.Booster、lgb.Booster等）
返回类型:: Any

参考样例

>>> model = XGBoost()
>>> model.fit(X, y)
>>> native_model = model.get_native_model()
>>> leaf_indices = native_model.apply(X)

plot_feature_importance(X=None, y=None, top_n=20, importance_type='gain', method='traditional', figsize=(10, 8), title=None, show=True, **kwargs)[源代码]

绘制特征重要性图.

支持传统特征重要性和SHAP值两种方法。

参数:

X (DataFrame | ndarray | None) -- 特征矩阵，SHAP方法必需
y (ndarray | Series | None) -- 目标变量，可选
top_n (int) -- 显示前N个特征，默认20
importance_type (str) -- 重要性类型（传统方法），默认'gain'
method (str) -- 计算方法，默认'traditional' - 'traditional': 传统特征重要性 - 'shap': SHAP值重要性 - 'combined': 两者对比
figsize (Tuple[int, int]) -- 图表大小，默认(10, 8)
title (str | None) -- 图表标题，可选
show (bool) -- 是否显示图表，默认True
kwargs -- 其他绘图参数

返回:

matplotlib Figure对象

返回类型:

matplotlib.figure.Figure

参考样例

>>> # 传统特征重要性
>>> fig = model.plot_feature_importance(top_n=15)
>>> fig.savefig('importance.png')

>>> # SHAP特征重要性
>>> fig = model.plot_feature_importance(X_test, method='shap', top_n=15)

>>> # 组合对比图
>>> fig = model.plot_feature_importance(X_test, method='combined', top_n=10)

get_shap_explainer(**kwargs)[源代码]

获取SHAP解释器.

参数:: kwargs -- ModelExplainer的初始化参数
返回:: ModelExplainer对象
返回类型:: ModelExplainer

参考样例

>>> explainer = model.get_shap_explainer()
>>> shap_values = explainer.compute_shap_values(X_test)
>>> explainer.plot_shap_summary(X_test)

class hscredit.core.models.RandomForest(n_estimators=100, max_depth=None, min_samples_split=2, min_samples_leaf=1, max_features='sqrt', bootstrap=True, class_weight=None, criterion='gini', random_state=None, n_jobs=-1, verbose=False, scorecard_params=None, **kwargs)[源代码]

基类：SklearnRiskModel

随机森林风控模型.

基于sklearn的RandomForestClassifier封装。

参数

参数:

n_estimators (int) -- 树的数量，默认100
max_depth (int | None) -- 树最大深度，默认None
min_samples_split (int | float) -- 节点分裂最小样本数，默认2
min_samples_leaf (int | float) -- 叶子节点最小样本数，默认1
max_features (str | int | float) -- 最大特征数，默认'sqrt'
bootstrap (bool) -- 是否使用自助采样，默认True
class_weight (str | Dict | None) -- 类别权重，默认None
criterion (str) -- 分裂标准，默认'gini'
random_state (int | None) -- 随机种子，默认None
n_jobs (int) -- 并行任务数，默认-1
verbose (bool) -- 是否输出详细信息，默认False
scorecard_params (Dict[str, Any] | None)

class hscredit.core.models.ExtraTrees(n_estimators=100, max_depth=None, min_samples_split=2, min_samples_leaf=1, max_features='sqrt', bootstrap=False, class_weight=None, criterion='gini', random_state=None, n_jobs=-1, verbose=False, scorecard_params=None, **kwargs)[源代码]

基类：SklearnRiskModel

极端随机树风控模型.

基于sklearn的ExtraTreesClassifier封装。比普通随机森林随机性更强，训练更快。

参数

参数:

n_estimators (int) -- 树的数量，默认100
max_depth (int | None) -- 树最大深度，默认None
min_samples_split (int | float) -- 节点分裂最小样本数，默认2
min_samples_leaf (int | float) -- 叶子节点最小样本数，默认1
max_features (str | int | float) -- 最大特征数，默认'sqrt'
bootstrap (bool) -- 是否使用自助采样，默认False
class_weight (str | Dict | None) -- 类别权重，默认None
criterion (str) -- 分裂标准，默认'gini'
random_state (int | None) -- 随机种子，默认None
n_jobs (int) -- 并行任务数，默认-1
verbose (bool) -- 是否输出详细信息，默认False
scorecard_params (Dict[str, Any] | None)

class hscredit.core.models.GradientBoosting(n_estimators=100, learning_rate=0.1, max_depth=3, min_samples_split=2, min_samples_leaf=1, subsample=1.0, max_features=None, criterion='friedman_mse', validation_fraction=0.1, n_iter_no_change=None, random_state=None, verbose=False, scorecard_params=None, **kwargs)[源代码]

基类：SklearnRiskModel

梯度提升树风控模型.

基于sklearn的GradientBoostingClassifier封装。

参数

参数:

n_estimators (int) -- 树的数量，默认100
learning_rate (float) -- 学习率，默认0.1
max_depth (int) -- 树最大深度，默认3
min_samples_split (int | float) -- 节点分裂最小样本数，默认2
min_samples_leaf (int | float) -- 叶子节点最小样本数，默认1
subsample (float) -- 样本采样比例，默认1.0
max_features (str | int | float | None) -- 最大特征数，默认None
criterion (str) -- 分裂标准，默认'friedman_mse'
random_state (int | None) -- 随机种子，默认None
verbose (bool) -- 是否输出详细信息，默认False
validation_fraction (float)
n_iter_no_change (int | None)
scorecard_params (Dict[str, Any] | None)

fit(X, y=None, sample_weight=None, eval_set=None, **fit_params)[源代码]

训练模型.

支持两种调用方式: 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)

返回类型:

GradientBoosting

class hscredit.core.models.SVM(C=1.0, kernel='rbf', degree=3, gamma='scale', coef0=0.0, shrinking=True, probability=True, tol=0.001, class_weight=None, max_iter=-1, random_state=None, n_jobs=1, verbose=False, scorecard_params=None, **kwargs)[源代码]

基类：SklearnRiskModel

基于 sklearn SVC 的概率型支持向量机模型。

参数

参数:

C (float) -- 正则强度倒数，默认 1.0
kernel (str) -- 核函数，默认 'rbf'
degree (int) -- 多项式核次数，默认 3
gamma (str | float) -- 核系数，默认 'scale'
probability (bool) -- 是否启用概率估计，只允许 True
class_weight (str | Dict | None) -- 类别权重，默认 None
random_state (int | None) -- 随机种子，默认 None
n_jobs (int) -- hscredit 包装层并行预算，不传给 SVC，默认 1
verbose (bool) -- 是否输出训练日志，默认 False
coef0 (float)
shrinking (bool)
tol (float)
max_iter (int)
scorecard_params (Dict[str, Any] | None)

属性

classes_: 训练类别标签
feature_names_in_: 训练字段名称
tuner: 最近一次调优使用的 ModelTuner

参考样例

>>> from hscredit.core.models import SVM
>>> model = SVM(C=1.0, kernel="rbf", random_state=42)
>>> model.fit(X_train, y_train)
>>> probability = model.predict_proba(X_test)[:, 1]

set_params(**params)[源代码]: 设置 sklearn 参数，同时禁止关闭统一概率能力。

class hscredit.core.models.DecisionTreeClassifier(criterion='gini', splitter='best', max_depth=None, min_samples_split=2, min_samples_leaf=1, max_features=None, class_weight=None, ccp_alpha=0.0, random_state=None, n_jobs=1, scorecard_params=None, **kwargs)[源代码]

基类：SklearnRiskModel

基于 sklearn DecisionTreeClassifier 的统一风控模型。

参数

参数:

criterion (str) -- 节点划分质量指标，默认 'gini'
splitter (str) -- 节点划分策略，默认 'best'
max_depth (int | None) -- 最大树深，默认 None
min_samples_split (int | float) -- 节点分裂最小样本数，默认 2
min_samples_leaf (int | float) -- 叶节点最小样本数，默认 1
max_features (str | int | float | None) -- 每次分裂考虑的最大特征数，默认 None
class_weight (str | Dict | None) -- 类别权重，默认 None
ccp_alpha (float) -- 最小代价复杂度剪枝系数，默认 0.0
random_state (int | None) -- 随机种子，默认 None
n_jobs (int) -- hscredit 包装层并行预算，不传给底层决策树，默认 1
scorecard_params (Dict[str, Any] | None)

属性

feature_importances_: 决策树原生特征重要性
classes_: 训练类别标签
feature_names_in_: 训练字段名称

参考样例

>>> from hscredit.core.models import DecisionTreeClassifier
>>> model = DecisionTreeClassifier(max_depth=4, min_samples_leaf=20, random_state=42)
>>> model.fit(X_train, y_train)
>>> probability = model.predict_proba(X_test)[:, 1]