超参数调优

hscredit.core.models.tuning 提供基于 Optuna 的超参数调优组件（pip install hscredit[tune]）。可从顶层 hscredit 懒加载导入 ModelTuner / AutoTuner / TuningObjective。

快速上手与自定义目标

完整教程见超参数搜索：入门、指标、损失与结果复盘，包含可执行 Notebook、普通函数指标、 BaseMetric、训练 BaseLoss、金额权重、时间 CV、多目标及保存续跑。

已有模型优先使用 best = model.tune(X, y, metric=...)；独立 ModelTuner.fit 返回最佳参数字典，随后用 get_best_model() 获取已重训模型。 loss 指定训练目标，metric 指定搜索评价；普通函数可用 make_metric(fn, name="业务误差", greater_is_better=False) 声明名称与方向。

训练后的完整搜索过程

两种入口都保留原始 Optuna Study 和完整绘图能力:

best = model.tune(X, y, n_trials=20)
best.tuner.visualization.plot_timeline().show()

tuner = ModelTuner(model, metric="auc", cv=3)
tuner.fit(X, y, n_trials=20)
tuner.visualization.plot_intermediate_values().show()
tuner.visualization.matplotlib.plot_optimization_history()

import optuna
optuna.visualization.plot_rank(tuner.get_study()).show()

visualization 动态提供当前 Optuna 版本的全部可视化函数；可使用 dir(tuner.visualization) 查看，参数、绘图条件和返回值遵循原生接口。原有 tuner.plot_* 便捷接口继续保留。完整样例见模型训练、调参与保存。

class hscredit.core.models.tuning.tuning.ModelTuner(model_class, search_space=None, fixed_params=None, model_params=None, metric='ks', direction=None, metric_names=None, objective=None, objective_kwargs=None, eval_ratios=None, trial_points=None, sampler='tpe', sampler_kwargs=None, storage=None, study_name=None, load_if_exists=False, target='target', cv=5, n_jobs=-1, random_state=None, verbose=False, early_stopping_rounds=20, points_to_evaluate=None, study=None, pruner=None, callbacks=None, fit_params=None, fit_params_factory=None, trial_objective=None, artifact_dir=None, store_models=True, retention=None, loss=None, record_terminator_scores=None)[源代码]

基类：ArtifactSerializableMixin

模型超参数调优器 - 支持单/多目标优化.

基于Optuna实现贝叶斯优化超参数搜索。支持单目标优化和多目标优化（帕累托最优）。

参数

参数:

model_class (Type) -- 模型类（如 XGBoost）或未拟合的模型/Pipeline 实例。
search_space (Any | None) -- 参数搜索空间，默认None则使用预定义空间
fixed_params (Dict[str, Any] | None) -- 固定参数，不参与搜索
model_params (Dict[str, Any] | None) -- 来源模型实例的构造参数；搜索空间同名参数会覆盖它， fixed_params 的显式值具有最高优先级
metric (str | Callable | List[str | Callable]) -- 优化指标（决定评估计算逻辑），可选: - 字符串: 'auc', 'ks', 'ks_diff', 'accuracy', 'precision', 'recall', 'f1', 'logloss' - 列表: 多个指标，用于多目标优化，如 ['ks', 'ks_diff'] - 函数: 自定义评估函数，接收(y_true, y_pred)返回float - 列表的函数: 多个自定义函数
direction (str | List[str | None] | None) -- 默认 None，按内置指标或 BaseMetric 自动确定方向。裸函数必须显式提供 'maximize'/'minimize'；多目标可逐项提供方向列表。
metric_names (List[str] | None) -- 指标显示名称列表（仅用于日志/报告/可视化的展示标签，不参与任何计算逻辑），默认 None 时从 metric 自动推断（内置字符串取其大写形式，自定义函数取其 __name__）。与 metric 不重复：metric 决定"算什么"，metric_names 只决定"叫什么"
cv (int) -- 交叉验证折数（默认5）、带 split 方法的分割器或 (训练位置, 验证位置) 序列。
n_jobs (int) -- 当前 trial 中模型可使用的并行任务数，默认-1； trial 本身顺序执行，确保主动中断及时生效并让自适应采样器利用全部历史结果
random_state (int | None) -- 随机种子，默认None
verbose (bool) -- 是否逐 Trial 输出得分、参数、当前最佳结果及最终摘要，默认False
early_stopping_rounds (int) -- 早停轮数，默认20
loss (Any | None) -- HSCredit 提升树训练所用 BaseLoss；metric 控制折外评分，彼此独立。
record_terminator_scores (bool | None) -- 旧版 Optuna 终止分析兼容选项，默认None。 Optuna 4.9及以后默认不调用弃用接口；True显式启用，False关闭专用CV记录。各折指标和常规搜索曲线不受影响。
objective (str | Callable | None)
objective_kwargs (Dict[str, Any] | None)
eval_ratios (List[float])
trial_points (Dict[str, Any] | List[Dict[str, Any]] | None)
sampler (str | Any | None)
sampler_kwargs (Dict[str, Any] | None)
storage (str | None)
study_name (str | None)
load_if_exists (bool)
target (str)
points_to_evaluate (Dict[str, Any] | List[Dict[str, Any]] | None)
study (Any | None)
pruner (Any | None)
callbacks (List[Callable] | None)
fit_params (Dict[str, Any] | None)
fit_params_factory (Callable | None)
trial_objective (Callable | None)
artifact_dir (str | None)
store_models (bool)
retention (str | None)

属性

best_params_ / best_score_ 是最佳参数与主指标均值， best_scores_ 保存所有目标，best_trial_ 保存选中的 Optuna Trial。 study_ 与 optimization_history_ 可查看全过程；best_model_ 在第一次调用 get_best_model() 后生成。多目标默认按指标顺序优先选择帕累托解。

搜索空间定义

搜索空间可使用参数字典，或使用每个维度都设置 name 的 skopt 维度列表。内部统一转换并由 Optuna Study 执行：

整数参数: {'type': 'int', 'low': 1, 'high': 10, 'step': 1}
浮点参数: {'type': 'float', 'low': 0.01, 'high': 1.0, 'log': True}
类别参数: {'type': 'categorical', 'choices': ['a', 'b', 'c']}

同时兼容多种超参数框架的入参格式（无需安装对应库），传入后自动归一化:

bayesian-optimization 风格: {'max_depth': (2, 4, int), 'booster': ('gbtree', 'dart')}
scikit-optimize 风格: [Real(1e-3, 0.1, prior='log-uniform', name='learning_rate')]
sklearn 风格: {'C': [0.1, 1, 10]} 或 scipy 分布 {'C': scipy.stats.loguniform(1e-3, 1e1)}
hyperopt 风格: {'learning_rate': loguniform('learning_rate', log(1e-3), log(0.1)), 'penalty': choice('penalty', ['l1', 'l2'])}
optuna 分布对象: {'max_depth': optuna.distributions.IntDistribution(2, 4)}

内部建模经验

预定义空间只是搜索起点，不保证适合每个数据集。实际空间在首次 fit 后保存在 search_space 中；用户提供明确空间时优先使用该空间。部分范围会按样本数、特征数、坏样本比例调整；LightGBM 的叶子数受到 2**max_depth 上限约束。自定义训练损失不使用原生 scale_pos_weight，自动空间会去掉该无效维度；类别权重应在损失参数或 sample_weight 中设置。常用评估组合为最大化 KS/AUC，同时最小化训练/验证 KS 差异。

参考样例

>>> from hscredit.core.models import XGBoost, ModelTuner
>>> # 单目标：最大化 KS
>>> tuner = ModelTuner(XGBoost, metric='ks', direction='maximize', cv=5)
>>> tuner.fit(X_train, y_train, n_trials=50)   # 返回最佳参数 best_params_
>>> best_model = tuner.get_best_model()  # 此时才使用完整训练集重训
>>>
>>> # 多目标：同时优化 KS 与训练/测试 KS 差异（帕累托最优）
>>> tuner = ModelTuner(
...     XGBoost,
...     metric=['ks', 'ks_diff'],
...     direction=['maximize', 'minimize'],
...     sampler='nsgaii',
... )
>>> tuner.fit(X_train, y_train, n_trials=100)
>>>
>>> # 自定义搜索空间
>>> space = {'max_depth': {'type': 'int', 'low': 2, 'high': 4},
...          'learning_rate': {'type': 'float', 'low': 1e-3, 'high': 0.1, 'log': True}}
>>> tuner = ModelTuner(XGBoost, search_space=space, metric='auc')

引用

基于 Optuna 超参数优化框架（默认 TPE 采样器），见 Akiba, T. et al. (2019). Optuna: A Next-generation Hyperparameter Optimization Framework. KDD；TPE 见 Bergstra, J. et al. (2011), Algorithms for Hyper-Parameter Optimization, NeurIPS。文档：https://optuna.readthedocs.io/

fit(X, y=None, n_trials=100, timeout=None, show_progress_bar=True, sample_weight=None, groups=None, callbacks=None, catch=(<class 'Exception'>, ), gc_after_trial=False, fit_params=None, evaluation_weight=None, **optimize_kwargs)[源代码]

执行超参数调优.

支持两种调用风格:

sklearn风格:

tuner.fit(X_train, y_train, n_trials=100)

scorecardpipeline风格 (在__init__中指定target):

tuner = ModelTuner(..., target='label')
tuner.fit(df)  # df包含'label'列

参数:

X (ndarray | DataFrame) -- 特征矩阵，或包含目标列的DataFrame（scorecardpipeline风格）
y (Series | ndarray | None) -- 目标变量，可选。如果为None，则从X中提取target列
n_trials (int) -- 搜索次数，默认100
timeout (int | None) -- 超时时间(秒)，默认None
show_progress_bar (bool) -- 是否显示进度条，默认True
sample_weight (ndarray | None) -- 仅用于训练的样本权重，不自动改变验证目标。
evaluation_weight (ndarray | None) -- 显式评估权重，按每折训练/验证位置切分；默认None保持未加权指标。
groups (Any | None) -- 传给自定义交叉验证分割器的分组标签。
callbacks (List[Callable] | None) -- 本次运行额外追加的 Study.optimize 回调。
catch (Tuple[Type[Exception], ...]) -- 允许 Optuna 标记失败后继续执行的异常类型；默认保留历史行为。
gc_after_trial (bool) -- 是否在每次试验后执行垃圾回收。
fit_params (Dict[str, Any] | None) -- 本次训练参数，覆盖构造时的同名 fit_params。
optimize_kwargs -- 透传 Optuna Study.optimize 的其他参数；n_jobs 由调参器管理。

返回:

最佳参数字典（保持旧接口；并非 self）。最佳模型需调用 get_best_model()。

返回类型:

Dict[str, Any]

相同数据再次 fit 会追加 Trial，并复用原交叉验证划分。数据、权重、固定参数或指标变化时应新建调参器和 study_name，避免混用不可比较的历史得分。

参考样例

>>> tuner = ModelTuner(XGBoost, metric=['auc', 'ks_diff'], random_state=42)
>>> best_params = tuner.fit(X_train, y_train, n_trials=20)
>>> best = tuner.get_best_model()
>>> prediction = best.predict_proba(X_test)[:, 1]

get_trial_result(number, *, load=True)[源代码]

获取单次试验的逐折模型、预测、得分与训练记录。

参数:

number -- Optuna Trial 编号，通常使用 best_trial_.number。
load -- disk 策略是否读取完整折制品；False 返回轻量摘要。

返回:

中文键字典。能否包含模型/预测取决于 retention。

参考样例

>>> result = tuner.get_trial_result(tuner.best_trial_.number)
>>> result['各折'][0]['指标']

get_oof_predictions(trial_number=None)[源代码]

返回折外预测；重复验证取平均，未参加验证的位置保留缺失值。

参数:: trial_number -- 试验编号；None 使用默认最佳试验。
返回:: 包含样本位置、真实标签、预测概率、验证次数的 DataFrame。
抛出:: ValueError -- 输入已释放或当前保留策略没有保存预测时抛出。

参考样例

>>> oof = tuner.get_oof_predictions()
>>> oof.loc[oof['验证次数'] > 0, ['真实标签', '预测概率']]

release_training_data()[源代码]

显式释放续训输入和样本级 fit 参数；已缓存最佳模型仍可预测。

不删除已保留的折结果或磁盘制品，不清理用户函数闭包。再次 fit 必须重新提供输入及所需的样本参数。

返回:: self。释放后不能重新训练或重建完整 OOF 表。

参考样例

>>> best_model = tuner.get_best_model()
>>> tuner.release_training_data()
>>> prediction = best_model.predict_proba(X_test)

save(path, **kwargs)[源代码]

保存可继续调参的完整对象，包括 Study、输入、预测、模型和自定义函数。

参数:

path -- 本地制品路径，例如 'output/tuner.pkl'。
kwargs -- 传给保存函数的参数；默认 engine='cloudpickle'。

返回:

保存后的文件路径。

参考样例

>>> path = tuner.save('output/tuner.pkl')
>>> restored = ModelTuner.load(path)

classmethod load(path, *, artifact_dir=None, **kwargs)[源代码]

加载完整过程；移动折制品后可用 artifact_dir 指定新根目录。

参数:

path -- save 生成的本地制品路径。
artifact_dir -- 可选的折制品新目录；不修改 Trial 数据。
kwargs -- 传给制品加载器的参数。

返回:

恢复后的 ModelTuner 实例。

参考样例

>>> restored = ModelTuner.load('output/tuner.pkl')
>>> restored.fit(X_train, y_train, n_trials=10)

evaluate_trials(X, y=None, trial_points=None, sample_weight=None, evaluation_weight=None, groups=None, fit_params=None)[源代码]

评估指定超参数点的模型效果.

无需运行完整调优，直接评估给定超参数配置的性能。

支持两种调用风格:

sklearn风格:

results = tuner.evaluate_trials(X_train, y_train, trial_points)

scorecardpipeline风格 (在__init__中指定target):

tuner = ModelTuner(..., target='label')
results = tuner.evaluate_trials(df, trial_points=trial_points)

参数:

X (ndarray | DataFrame) -- 特征矩阵，或包含目标列的DataFrame（scorecardpipeline风格）
y (Series | ndarray | None) -- 目标变量，可选。如果为None，则从X中提取target列
trial_points (List[Dict[str, Any]] | None) -- 超参数点列表，每个点是一个参数字典
sample_weight (ndarray | None) -- 仅训练权重。
evaluation_weight (ndarray | None) -- 显式验证指标权重，默认None，不继承之前fit的评估权重。
groups (Any | None) -- 本次交叉验证的分组标签，按当前数据重新划分。
fit_params (Dict[str, Any] | None) -- 本次评估的训练参数。以构造时 fit_params 为基础，不继承旧 fit 的临时参数。

返回:

包含评估结果的DataFrame

返回类型:

DataFrame

evaluate_study_trials(trial_indices=None, X=None, y=None, sample_weight=None, evaluation_weight=None, groups=None, fit_params=None)[源代码]

评估已完成 study 中指定 trial 的模型效果.

从 self.``study_.trials[i]`` 取出对应超参数重新评估，便于复核某次采样的稳定性、或在新数据集上对比若干历史 trial 的效果。

与 evaluate_trials() 的区别：本方法的超参数来自已学习完成的 study（按 trial 索引取），而非外部传入的参数点；结果额外包含每个 trial 的索引、状态及 study 记录的原始得分（study记录值 列），便于与重新评估的得分对照。

参数:

trial_indices (int | Sequence[int] | None) -- 要评估的 trial 索引，可选: - None: 评估全部已完成（COMPLETE）的 trial - int: 评估单个 trial，如 0 或 tuner.``study_.best_trial.number`` - 序列: 评估多个 trial，如 [0, 5, 10]
X (DataFrame | ndarray | None) -- 特征矩阵，或包含目标列的DataFrame；默认复用 fit 时的训练数据
y (Series | ndarray | None) -- 目标变量，可选；默认复用 fit 时的标签
sample_weight (ndarray | None) -- 样本权重，可选；默认复用 fit 时的样本权重
evaluation_weight (ndarray | None) -- 显式指标权重；仅X未传入时默认复用fit的评估权重。
groups (Any | None) -- 传入新X时使用的分组标签；不复用旧数据的CV位置。
fit_params (Dict[str, Any] | None) -- 本次重评估训练参数；新数据仅继承构造参数，旧数据继承原 fit 参数。

返回:

包含评估结果的DataFrame，含 trial索引/trial状态/超参数/ 重新评估指标/study记录值 列

返回类型:

DataFrame

示例

>>> tuner.fit(X_train, y_train, n_trials=100)
>>> # 评估最优 trial 与前两个 trial
>>> tuner.evaluate_study_trials([tuner.study_.best_trial.number, 0, 1])
>>> # 在新数据集上复核全部 trial
>>> tuner.evaluate_study_trials(X=X_oot, y=y_oot)

enqueue_trial(params, user_attrs=None, skip_if_exists=False)[源代码]

按 Optuna Study.enqueue_trial 风格追加一个手工搜索点。

params 使用模型最终参数名和值。若某一声明需要内部潜变量采样，本方法会先完成逆变换，再把内部参数传给 Study；公开记录仍保留最终值。

参数:

params (Dict[str, Any]) -- 搜索点，可仅指定部分搜索参数，其他由采样器补全。
user_attrs (Dict[str, Any] | None) -- 写入 Trial 的附加信息字典。
skip_if_exists (bool) -- 是否跳过已经存在的相同搜索点。

返回:

self；执行下一次 fit 时优先评估此点。

返回类型:

ModelTuner

参考样例

>>> tuner.enqueue_trial({'max_depth': 3}, user_attrs={'来源': '人工经验'})
>>> tuner.fit(X_train, y_train, n_trials=10)

enqueue_trials(trial_points=None, *, param_grid=None, x0=None, user_attrs=None, skip_if_exists=False)[源代码]

按 Optuna、GridSearch 或 skopt 格式追加一个或多个搜索点。

若 study 已创建（已调用过 fit），则立即通过 study.enqueue_trial 入队，在后续 fit 的采样中优先评估；否则缓存到 self.trial_points，在下次 fit 创建 study 后入队。

参数:

trial_points (Dict[str, Any] | List[Dict[str, Any]] | None) -- Optuna/hscredit 格式，dict 或 list[dict]
param_grid (Dict[str, Sequence[Any]] | List[Dict[str, Sequence[Any]]] | None) -- GridSearch 格式，由 ParameterGrid 展开
x0 (Sequence[Any] | None) -- skopt 格式，单个值序列或多个值序列，顺序与搜索空间一致
user_attrs (Dict[str, Any] | None) -- 所有入队点共享的附加信息字典。
skip_if_exists (bool) -- 是否跳过已存在的相同搜索点。

返回:

self，便于链式调用

返回类型:

ModelTuner

参考样例

>>> tuner.enqueue_trials(param_grid={'max_depth': [2, 3], 'learning_rate': [0.01, 0.05]})
>>> tuner.fit(X_train, y_train, n_trials=4)

probe(params, lazy=True)[源代码]

按 bayesian-optimization probe 风格追加一个搜索点。

lazy 为兼容原方法保留；Optuna 后端无立即执行单点的等价操作，因此 True 与 False 都会进入同一个 Study 队列，并在下一次 optimize 时执行。

参数:

params (Dict[str, Any] | Sequence[Any]) -- 参数字典或按搜索空间声明顺序排列的值序列。
lazy (bool) -- 兼容参数；均在下次 fit 执行。

返回:

self。

返回类型:

ModelTuner

参考样例

>>> tuner.probe({'max_depth': 3})
>>> tuner.fit(X_train, y_train, n_trials=1)

get_best_model(refit=False, full_data=True, **fit_params)[源代码]

获取并缓存最佳模型；默认按各折最佳轮数使用全部输入重训。

参数:

refit -- True 时强制重新训练；默认复用已训练的 best_model_
full_data -- 是否关闭最终模型的内部验证划分，使用完整输入
fit_params -- 最终训练的额外原生参数

返回:

已拟合模型。默认以各折早停最佳轮数中位数在完整输入重训。

full_data=False 保留模型早停设置；更改 full_data 会自动重新拟合。已释放训练数据时仅允许复用此前缓存的相同模式模型。

参考样例

>>> best_model = tuner.get_best_model()
>>> probability = best_model.predict_proba(X_test)[:, 1]
>>> fresh_model = tuner.get_best_model(refit=True)

get_optimization_history()[源代码]

获取优化历史.

返回:: 优化历史DataFrame
返回类型:: DataFrame

参考样例

>>> history = tuner.get_optimization_history()
>>> history.head()

get_pareto_front()[源代码]

获取帕累托前沿（多目标优化时）.

返回:: 帕累托前沿上的trial列表
返回类型:: List | None

参考样例

>>> pareto = tuner.get_pareto_front()
>>> [(trial.number, trial.values) for trial in pareto]

get_param_importance(target=None)[源代码]

获取参数重要性.

参数:: target (int | None) -- 多目标时指定要分析的指标索引，默认第一个
返回:: 参数重要性Series
返回类型:: Series | None

参考样例

>>> importance = tuner.get_param_importance(target=0)

get_study()[源代码]

获取完整的原生 Optuna Study，不过滤试验、指标、属性或中间值。

两种训练入口使用同一契约：model.tune(...) 之后可用 model.tuner.get_study()；直接使用 ModelTuner 时用 tuner.get_study()。返回值与 study_ 是同一对象，可交给任何 Optuna 原生分析和可视化函数。

返回:: 原生 optuna.study.Study 对象。
返回类型:: Any

参考样例

>>> study = tuner.get_study()
>>> study.trials_dataframe().head()

property visualization

当前 Optuna 版本的完整可视化入口，自动传入本次搜索的 Study。

例如 tuner.visualization.plot_timeline()、plot_intermediate_values()、 plot_rank(params=[...])；Matplotlib 后端使用 tuner.visualization.matplotlib.plot_optimization_history()。用 dir(tuner.visualization) 可查看当前版本的全部入口。

此入口保留 Optuna 原生语义：多目标的 target 使用函数，超体积图需要 reference_point；依赖、试验数量或指标条件不足时保留原生错误。既有 tuner.``plot_``* 便捷方法和整数 target 用法继续保留。

返回:: 自动绑定 Study 的 Optuna 可视化代理。

参考样例

>>> tuner.visualization.plot_timeline().show()

plot_optimization_history(target=None, **kwargs)[源代码]

绘制优化历史.

参数:

target (int | None) -- 多目标时指定要绘制的指标索引，默认第一个
kwargs -- 绘图参数

返回:

plotly图形对象

参考样例

>>> tuner.plot_optimization_history(target=0).show()

plot_param_importances(target=None, **kwargs)[源代码]

绘制参数重要性.

参数:

target (int | None) -- 多目标时指定要分析的指标索引，默认第一个
kwargs -- 绘图参数

返回:

plotly图形对象

参考样例

>>> tuner.plot_param_importances(target=0).show()

plot_slice(target=None, **kwargs)[源代码]

绘制参数切片图.

参数:

target (int | None) -- 多目标时指定要绘制的指标索引，默认第一个
kwargs -- 绘图参数

返回:

plotly图形对象

参考样例

>>> tuner.plot_slice(params=['max_depth'], target=0).show()

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

绘制帕累托前沿（多目标优化时）.

参数:: kwargs -- 绘图参数
返回:: plotly图形对象

参考样例

>>> tuner.plot_pareto_front().show()

plot_contour(params=None, target=None, **kwargs)[源代码]

绘制参数等高线图.

参数:

params (List[str] | None) -- 要绘制的参数列表，默认前两个
target (int | None) -- 多目标时指定要绘制的指标索引，默认第一个
kwargs -- 绘图参数

返回:

plotly图形对象

参考样例

>>> tuner.plot_contour(params=['max_depth', 'learning_rate']).show()

plot_parallel_coordinate(target=None, **kwargs)[源代码]

绘制平行坐标图.

参数:

target (int | None) -- 多目标时指定要绘制的指标索引，默认第一个
kwargs -- 绘图参数

返回:

plotly图形对象

参考样例

>>> tuner.plot_parallel_coordinate(params=['max_depth', 'learning_rate']).show()

plot_edf(target=None, **kwargs)[源代码]

绘制经验分布函数图.

参数:

target (int | None) -- 多目标时指定要绘制的指标索引，默认第一个
kwargs -- 绘图参数

返回:

plotly图形对象

参考样例

>>> tuner.plot_edf(target=0).show()

class hscredit.core.models.tuning.tuning.AutoTuner[源代码]

基类：object

自动调优器 - 基于内部建模经验.

为常见模型提供预定义的搜索空间，并根据数据特征自动调整。

参考样例

>>> from hscredit.core.models import AutoTuner
>>>
>>> # 自动根据数据特征选择搜索空间
>>> tuner = AutoTuner.create('xgboost', metric='ks')
>>> best_params = tuner.fit(X_train, y_train, n_trials=50)
>>>
>>> # 使用多目标优化（KS + 稳定性）
>>> tuner = AutoTuner.create('lightgbm', metric=['ks', 'ks_diff'])
>>> best_params = tuner.fit(X_train, y_train, n_trials=100)
>>>
>>> # 使用自定义指标
>>> def my_metric(y_true, y_pred):
...     return custom_score(y_true, y_pred)
>>>
>>> tuner = AutoTuner.create('xgboost', metric=my_metric, direction='maximize')
>>> best_params = tuner.fit(X_train, y_train, n_trials=100)

classmethod create(model_type, metric='ks', direction=None, metric_names=None, target='target', cv=5, random_state=None, verbose=False, early_stopping_rounds=20, **kwargs)[源代码]

创建自动调优器.

参数:

model_type (str) -- 模型类型，可选: - 'xgboost' / 'xgb' - 'lightgbm' / 'lgb' - 'catboost' / 'cat' - 'ngboost' / 'ngb' - 'randomforest' / 'rf' - 'gradientboosting' / 'gbdt' - 'logisticregression' / 'lr' - 'svm' / 'svc' - 'decisiontree' / 'dt'
metric (str | Callable | List[str | Callable]) -- 优化指标，可以是字符串、函数或列表
direction (str | List[str | None] | None) -- 默认 None 按各指标推断；裸函数须明确方向，多目标可给列表。
metric_names (List[str] | None) -- 指标名称列表（多目标时用于显示）
target (str) -- 目标列名，用于scorecardpipeline风格的fit，默认'target'
cv (int) -- 折数、分割器或索引对序列，默认5折分层交叉验证。
random_state (int | None) -- 随机种子
verbose (bool) -- 是否输出详细信息
early_stopping_rounds (int) -- 早停轮数，默认20
kwargs -- 传给 ModelTuner 的其他参数，例如 search_space、fixed_params、 loss、fit_params、retention、n_jobs。search_space 可覆盖自动空间。

返回:

ModelTuner实例

返回类型:

ModelTuner

参考样例

>>> tuner = AutoTuner.create('lr', metric=['auc', 'ks_diff'], random_state=42,
...                          search_space={'C': [0.1, 1.0, 10.0]}, n_jobs=1)
>>> best_params = tuner.fit(X_train, y_train, n_trials=10)
>>> model = tuner.get_best_model()

class hscredit.core.models.tuning.tuning.TuningObjective[源代码]

基类：object

兼容既有字符串目标的业务评分集合，返回值均越大越好。

参数

本类无需实例化。各方法接收0/1标签和坏样本概率；get 可绑定业务参数。

属性

BUILTIN_OBJECTIVES 列出名称。降低坏账率使用的评分函数与原始坏账率不同；要直接最小化坏账率，推荐 losses.BadDebtMetric。

参考样例

>>> metric = TuningObjective.get("lift_head", ratio=0.1)
>>> metric.direction
'maximize'
>>> metric([0, 0, 1, 1], [0.1, 0.2, 0.8, 0.9])
2.0

BUILTIN_OBJECTIVES = ['ks', 'auc', 'lift_head', 'lift_tail', 'lift_head_monotonic', 'ks_with_lift_constraint', 'head_ks', 'ks_lift_combined', 'tail_purity_ks', 'approval_bad_rate', 'expected_profit']

static ks(y_true, y_prob, **kwargs)[源代码]

计算 KS，越大越好。

参数:

y_true -- 0/1标签。
y_prob -- 一维坏样本概率。
kwargs -- 可传 sample_weight；两类的有效权重都须大于0。

返回:

[0, 1] 内的KS。

static auc(y_true, y_prob, score_direction='auto', **kwargs)[源代码]

按统一评分方向计算 AUC，兼容既有字符串目标的自动方向。

参数:

y_true -- 0/1标签；必须同时包含有效好、坏样本。
y_prob -- [0, 1] 内的预测值。
score_direction -- auto（默认，兼容原有评分方向）、higher_risk（越大风险越高）或 higher_safe（越大风险越低）。固定坏样本概率评价可显式使用 higher_risk，或直接传入不会自动翻向的 AUCMetric 指标对象。
kwargs -- 可传 sample_weight。

返回:

[0, 1] 内的AUC；非法输入抛异常，不伪装成0分。

static lift_head(y_true, y_prob, ratio=0.1, **kwargs)[源代码]

计算高风险头部坏率 / 整体坏率，人数向上取整，同分边界等比例计入。

参数:

y_true -- 0/1标签。
y_prob -- 坏样本概率。
ratio -- 头部人数占比，(0, 1]，默认0.1。
kwargs -- 可传 sample_weight，只加权统计、不改变名单人数。

返回:

头部提升倍数，越大越好；没有坏样本时返回0以兼容补充诊断。

static lift_tail(y_true, y_prob, ratio=0.1, **kwargs)[源代码]

计算低风险尾部好率 / 整体好率，越大越好。

参数:

y_true -- 0/1标签。
y_prob -- 坏样本概率。
ratio -- 尾部人数占比，(0, 1]，默认0.1。
kwargs -- 可传 sample_weight。

返回:

纯净度提升倍数；没有好样本时返回0。

static lift_head_monotonic(y_true, y_prob, n_bins=10, penalty=0.5, **kwargs)[源代码]

按概率等频分箱，以 KS × (1 - 违反坏率单调的比例 × penalty) 评分。

参数:

y_true -- 0/1标签。
y_prob -- 坏样本概率；同分概率放在同一箱内。
n_bins -- 期望分箱数，至少2；实际箱数可因同分值减少。
penalty -- 违反单调性的惩罚系数，[0, 1]。
kwargs -- 本指标暂不支持 sample_weight。

返回:

越大越好的惩罚后KS；使用统一分箱器和 compute_bin_stats。

static ks_with_lift_constraint(y_true, y_prob, min_lift_ratio=0.05, min_lift_value=2.0, **kwargs)[源代码]

满足头部提升约束时返回KS，否则返回0。

参数:

y_true -- 0/1标签。
y_prob -- 坏样本概率。
min_lift_ratio -- 头部人数占比，(0, 1]。
min_lift_value -- 最低提升倍数，非负有限数。
kwargs -- 可传 sample_weight。

返回:

越大越好的KS评分；0仅表示不满足约束，不表示试验失败。

static head_ks(y_true, y_prob, ratio=0.3, **kwargs)[源代码]

计算高风险头部内的KS，边界同分样本按比例加权。

参数:

y_true -- 0/1标签。
y_prob -- 坏样本概率。
ratio -- 头部人数占比，(0, 1]。
kwargs -- 可传 sample_weight。

返回:

[0, 1] 内的KS；头部只有单类时返回0。

static ks_lift_combined(y_true, y_prob, ks_weight=0.5, lift_ratio=0.05, **kwargs)[源代码]

计算 ks_weight × KS + (1-ks_weight) × min(头部LIFT/10, 1)。

参数:

y_true -- 0/1标签。
y_prob -- 坏样本概率。
ks_weight -- KS占比，[0, 1]，默认0.5。
lift_ratio -- 头部人数占比，(0, 1]。
kwargs -- 可传 sample_weight。

返回:

越大越好的联合评分；LIFT除以10为沿用的业务缩放约定。

static tail_purity_ks(y_true, y_prob, tail_ratio=0.3, **kwargs)[源代码]

计算 0.5 × KS + 0.5 × min(尾部好率提升, 1)，保留旧业务缩放约定。

参数:

y_true -- 0/1标签。
y_prob -- 坏样本概率。
tail_ratio -- 低风险尾部人数占比，(0, 1]。
kwargs -- 可传 sample_weight。

返回:

越大越好的联合评分。若需要完整尾部提升差异，请单用 lift_tail。

static approval_bad_rate(y_true, y_prob, approval_rate=0.3, bad_rate_weight=1.0, **kwargs)[源代码]

固定人数通过率下计算 approval_rate × (1 - 通过坏率 × bad_rate_weight)。

参数:

y_true -- 0/1标签。
y_prob -- 坏样本概率；优先通过低风险客户。
approval_rate -- 通过人数占比，(0, 1]，默认0.3。
bad_rate_weight -- 坏率惩罚权重，非负有限数。
kwargs -- 可传 sample_weight。

返回:

越大越好的审批评分；原始坏率应使用 BadDebtMetric 最小化。

static expected_profit(y_true, y_prob, approval_rate=0.3, good_profit=1.0, bad_loss=5.0, **kwargs)[源代码]

固定通过人数占比时的人均已实现利润，全体申请客户为分母。

参数:

y_true -- 0/1标签。
y_prob -- 坏样本概率；优先通过低风险客户，同分边界等比例计入。
approval_rate -- 通过人数占比，(0, 1]，默认0.3。
good_profit -- 通过好客户的收益，非负有限数。
bad_loss -- 通过坏客户的损失，非负有限数。
kwargs -- 可传 sample_weight。

返回:

越大越好的利润；与使用固定概率阈值的 ProfitMetric 口径不同。

classmethod get(name, **kwargs)[源代码]

按名称创建可在离线、训练和调参中复用的指标。

参数:

name -- BUILTIN_OBJECTIVES 中的名称，不区分大小写。
kwargs -- 绑定对应方法的业务参数；未知参数立即报错。

返回:

BaseMetric 对象，其 direction 为 maximize。

>>> metric = TuningObjective.get("lift_head", ratio=0.05)
>>> metric.name
'LIFT_HEAD'

class hscredit.core.models.tuning.tuning.Metric(metric, name=None, direction=None)[源代码]

基类：object

统一管理搜索目标的名称、数值及优化方向。

参数

参数:

metric -- 内置名称、BaseMetric、BaseLoss，或 (y_true, probability)->float 函数。 BaseLoss 自动转换为配套指标。sklearn scorer 与框架回调需先还原为概率指标。
name -- 展示名称；多目标搜索中不可重名。
direction -- maximize 或 minimize；默认内置/指标对象自行声明。裸函数必须显式传方向，也可先用 make_metric 包装。

属性

name、direction、scorer；log_loss 为正交叉熵，默认最小化。旧名 logloss 保留负交叉熵最大化语义，便于旧 Study 继续使用。字符串 auc 沿用 score_direction='auto'；传入 AUCMetric() 或绑定 score_direction='higher_risk' 的目标时，保持显式风险方向。

参考样例

>>> Metric("log_loss").direction
'minimize'
>>> Metric("ks_diff").direction
'minimize'

BUILTIN_METRICS = {'accuracy': {'direction': 'maximize'}, 'approval_bad_rate': {'direction': 'maximize'}, 'auc': {'direction': 'maximize'}, 'brier': {'direction': 'minimize'}, 'expected_profit': {'direction': 'maximize'}, 'f1': {'direction': 'maximize'}, 'head_ks': {'direction': 'maximize'}, 'ks': {'direction': 'maximize'}, 'ks_diff': {'direction': 'minimize'}, 'ks_lift_combined': {'direction': 'maximize'}, 'ks_with_lift_constraint': {'direction': 'maximize'}, 'lift_head': {'direction': 'maximize'}, 'lift_head_monotonic': {'direction': 'maximize'}, 'lift_tail': {'direction': 'maximize'}, 'log_loss': {'direction': 'minimize'}, 'logloss': {'direction': 'maximize'}, 'neg_log_loss': {'direction': 'maximize'}, 'precision': {'direction': 'maximize'}, 'recall': {'direction': 'maximize'}, 'tail_purity_ks': {'direction': 'maximize'}}

validate_evaluation_weight()[源代码]

在训练开始前拒绝不支持 sample_weight 的评估函数。

返回:: None；不支持时抛出中文 ValueError。

hscredit.core.models.losses.make_metric(function, *, name='自定义指标', greater_is_better, **kwargs)[源代码]

用一行代码定义离线、训练及调参共用的自定义指标。

参数:

function -- (y_true, probability, **kwargs) -> float 的函数。输入是坏样本概率，不能传 sklearn scorer 或 XGBoost/LightGBM 回调。
name -- 显示名称，默认“自定义指标”。
greater_is_better -- True 表示越大越好，False 表示越小越好；必须显式提供。
kwargs -- 转交函数的固定业务参数，不能包含样本数组权重。

返回:

CallableMetric，可直接传 ModelTuner(metric=...) 或 LightGBM(eval_metric=...)；CV 使用返回对象的 to_scorer()。

参考样例

>>> from sklearn.metrics import log_loss
>>> metric = make_metric(log_loss, name="交叉熵", greater_is_better=False, labels=[0, 1])
>>> metric.direction
'minimize'
>>> round(metric([0, 1], [0.1, 0.9]), 3)
0.105

class hscredit.core.models.losses.CallableMetric(function, *, name='自定义指标', greater_is_better, **kwargs)[源代码]

基类：BaseMetric

包装返回标量的概率评估函数。

参数

参数:

function -- function(y_true, probability, **kwargs) -> float。第一项为0/1标签，第二项为坏样本概率；不接受 sklearn scorer 或框架回调协议。
name -- 中文显示名称，默认“自定义指标”。多指标时请使用不同名称。
greater_is_better -- 必须明确指定 True（最大化）或 False（最小化）。
kwargs -- 固定业务参数，例如阈值或收益参数；创建时复制。样本权重请在评价时通过 sample_weight 提供，不可绑定整个数据集。

属性

direction、evaluate、to_scorer 和框架适配方法继承自 BaseMetric。

参考样例

>>> import numpy as np
>>> def error(y, p):
...     return float(np.mean((y - p) ** 2))
>>> metric = CallableMetric(error, name="概率均方误差", greater_is_better=False)
>>> round(metric([0, 1], [0.1, 0.9]), 2)
0.01