评估指标

hscredit.core.models 提供面向风控任务的模型评估指标。

class hscredit.core.models.BaseMetric(name='自定义指标', greater_is_better=True)[源代码]

基类：ABC

可用于离线评估、训练监控及调参的统一指标。

参数

参数:

name -- 指标名称。
greater_is_better -- True 表示越大越好。

属性

direction 可直接用于 Optuna 的 maximize / minimize。

参考样例

>>> from hscredit.core.models.losses import FocalLoss
>>> metric = FocalLoss().metric()
>>> value = metric.evaluate([0, 1], [0.1, 0.9])
>>> scorer = metric.to_scorer()

自定义指标只需实现 __call__(y_true, y_pred, sample_weight=None) 并指定优化方向；不支持权重时可省略该参数，传权重会显式报错。离线场景优先调用 evaluate 以获取输入和返回值校验。

property direction

返回 'maximize' 或 'minimize'，可直接传给 Optuna。

>>> from hscredit.core.models.losses import FocalLoss
>>> FocalLoss().metric().direction
'minimize'

evaluate(y_true, y_pred, sample_weight=None, *, raw_score=False)[源代码]

离线评估统一入口，校验标签、概率、权重和返回值。

参数:

y_true -- 一维、非空 0/1 标签。
y_pred -- 一维坏样本概率，或列顺序 [0, 1] 的两列概率。 raw_score=True 时接收一维 logit，并先做 sigmoid。
sample_weight -- 可选一维非负有限数组，等长且总和大于 0；指标子类必须声明支持此参数。
raw_score -- 是否将一维原始分数转为坏样本概率，默认 False。

返回:

float，原始指标值，不根据优化方向改变符号。

抛出:

ValueError -- 输入无效、权重不支持，或指标返回非有限值。

>>> from hscredit.core.models.losses import AUCMetric
>>> AUCMetric().evaluate([0, 1], [[0.8, 0.2], [0.2, 0.8]])
1.0
>>> AUCMetric().evaluate([0, 1], [-2.0, 2.0], raw_score=True)
1.0

to_scorer()[源代码]

生成 sklearn CV 或 GridSearchCV 使用的评分器。

返回:: 独立参数快照，签名为 scorer(estimator, X, y_true, sample_weight=None)。根据 estimator.classes_ 选择类别 1 的预测概率；仅在此处对越小越好的指标取负，保持 sklearn 越大越好的约定。

>>> from hscredit.core.models.losses import AUCMetric
>>> from sklearn.model_selection import GridSearchCV
>>> search = GridSearchCV(model, {'C': [0.1, 1]}, scoring=AUCMetric().to_scorer())

to_xgboost(api='native', *, raw_score=False)[源代码]

生成 XGBoost 指标回调。

参数:

api -- 'native' 用于 xgboost.train(custom_metric=...)； 'sklearn' 用于 XGBClassifier(eval_metric=...)。
raw_score -- 使用自定义训练目标时设为 True；内置 logistic 目标通常传来概率，保持 False。转换只做一次，不能同时外部 sigmoid。

返回:

native 回调 metric(preds, DMatrix) -> (name, value)； sklearn 回调 metric(y_true, y_pred, sample_weight=None) -> value。

原生 train 还需 maximize=metric.greater_is_better；sklearn 早停需配置相同方向的 EarlyStopping 回调。HSCredit 模型可自动完成这些配置。

>>> from hscredit.core.models.losses import FocalLoss
>>> callback = FocalLoss().metric().to_xgboost(raw_score=True)
>>> sklearn_callback = FocalLoss().metric().to_xgboost(api='sklearn', raw_score=True)

to_lightgbm(api='sklearn', *, raw_score=False)[源代码]

生成 LightGBM 指标回调，返回值自动携带优化方向。

参数:

api -- 'sklearn' 用于 LGBMClassifier.fit(eval_metric=...)； 'native' 用于 lightgbm.train(feval=...)。
raw_score -- 与自定义目标一起使用时设 True，内置概率目标用 False。

返回:

返回 (name, value, greater_is_better) 的回调。 native 参数为 (preds, Dataset)，sklearn 为 (y_true, y_pred, weight=None)。

>>> from hscredit.core.models.losses import FocalLoss
>>> callback = FocalLoss().metric().to_lightgbm(raw_score=True)
>>> native_callback = FocalLoss().metric().to_lightgbm(api='native', raw_score=True)

to_catboost()[源代码]

生成 CatBoost 指标对象，自动将原始分数转换为概率。

返回:: 提供 evaluate、get_final_error、is_max_optimal 的对象。 evaluate 返回 (指标值 × 权重和, 权重和)，最终结果还原为指标值。标记为不可加，以保留 AUC、KS、排序和逐行金额指标的全量评估语义。

>>> from hscredit.core.models.losses import FocalLoss
>>> callback = FocalLoss().metric().to_catboost()
>>> callback.is_max_optimal()
False

class hscredit.core.models.KSMetric(name='ks')[源代码]

基类：BaseMetric

KS (Kolmogorov-Smirnov) 指标.

衡量模型区分好坏客户的能力，KS值越大表示模型区分能力越强。

KS = max(|累积好客户比例 - 累积坏客户比例|)

参数:: name (str) -- 指标名称，默认为"ks"

参考样例

>>> import numpy as np
>>> from hscredit.core.models.losses import KSMetric
>>>
>>> ks_metric = KSMetric()
>>> y_true = np.array([0, 0, 1, 1, 0, 1, 0, 1])
>>> y_pred = np.array([0.1, 0.2, 0.8, 0.9, 0.3, 0.7, 0.4, 0.6])
>>> ks_value = ks_metric(y_true, y_pred)
>>> print(f"KS: {ks_value:.4f}")

>>> # 在LightGBM中使用
>>> import lightgbm as lgb
>>> train_data = lgb.Dataset(X_train, label=y_train)
>>> bst = lgb.train(
...     params={'objective': 'binary'},
...     train_set=train_data,
...     feval=ks_metric.to_lightgbm(api="native"),
...     num_boost_round=100
... )

引用

KS（Kolmogorov–Smirnov）统计量：https://en.wikipedia.org/wiki/Kolmogorov–Smirnov_test ；其在信用评分中的应用见 Siddiqi, N. (2006). Credit Risk Scorecards. Wiley。

class hscredit.core.models.GiniMetric(name='gini', score_direction='auto')[源代码]

基类：BaseMetric

Gini系数指标.

Gini = 2 * AUC - 1

衡量模型区分能力，Gini越大越好。

参数:

name (str) -- 指标名称，默认为"gini"
score_direction (str) -- 同 metrics.auc，默认auto；higher_risk保留原始方向

参考样例

>>> from hscredit.core.models.losses import GiniMetric
>>> gini_metric = GiniMetric()
>>> gini_value = gini_metric(y_true, y_pred)

class hscredit.core.models.PSIMetric(expected=None, n_bins=10, name='psi')[源代码]

基类：BaseMetric

PSI (Population Stability Index) 指标.

衡量样本分布的稳定性，常用于模型监控。

PSI = sum((实际占比 - 期望占比) * ln(实际占比/期望占比))

参数:

expected (ndarray | None) -- 基准预测分数的一维非空有限数组，默认 None，为 None 时需要在 __call__ 中提供；不要求与当前样本等长。
n_bins (int) -- 基准分位分箱的最大数量，整数且至少为 2，默认 10。
name (str) -- 指标名称，默认为"psi"

参考样例

>>> from hscredit.core.models.losses import PSIMetric
>>>
>>> # 使用训练集作为基准
>>> psi_metric = PSIMetric(expected=y_train_pred, n_bins=10)
>>>
>>> # 计算测试集的PSI
>>> psi_value = psi_metric(y_test, y_test_pred)
>>> print(f"PSI: {psi_value:.4f}")

注意

复用 hscredit.core.metrics.psi 的冻结基准分箱，不丢弃落在基准最小值和最大值之外的样本。低基数或常量基准遵循公共 PSI 的类别口径。本指标不支持样本权重；它衡量分布漂移，不能单独代替 AUC 等区分度指标。

PSI解释: - PSI < 0.1: 分布稳定 - 0.1 <= PSI < 0.25: 分布有轻微变化 - PSI >= 0.25: 分布变化显著，需要关注