Classification Model Tuning

classification-model-tuning

1. 输入依赖

2. 执行命令

<skill_dir> 指本 skill 所在目录（即本文件所在目录），执行时替换为实际绝对路径，不要依赖当前工作目录。

2.1 流程 A：超参调优（run_tuning.py）

bashCopy code
# 假设上游 classification-model-training 已产出 baseline:
#   <session_dir>/new-models/xgb-v1/

python <skill_dir>/scripts/run_tuning.py \
    --baseline_run <session_dir>/new-models/xgb-v1 \
    [--method rule|optuna] \
    [--n_trials 30] \
    [--version v1] \
    [--output_dir <session_dir>] \
    [--auto-apply]

执行步骤：

1. 读 baseline：从 config.json 恢复 cfg / data_path / algo / used_params / metrics / best_iteration

2. 算法直通：按 baseline.algo 走 xgb / dnn / lr 路径

3. 规则诊断（algo-aware）：根据 train/val/oot AUC gap、PSI、训练动力学信号推断状态

   • overfit / underfit / unstable_psi 三条规则 algo-agnostic，只看 AUC gap 与 PSI
   • underconverged 按 algo 分流：xgb 看 best_iteration / n_estimators >= 0.95；dnn 看 early_stopped=False 或 best_epoch / epochs >= 0.95；lr 看 converged=False（凸优化罕见，兜底）

   状态	触发条件（algo-agnostic 部分）
   underfit	train_auc < 0.70 或 train-oot gap < 0.005
   overfit	train-oot gap > 0.05
   unstable_psi	train→oot psi > 0.10

4. 推荐超参（algo-aware）：

   xgb 策略表：

   状态	动作
   underfit	depth+1, mcw/2, lr/2, n_est×1.5（各受 bounds 约束）
   overfit	depth-1, reg_lambda×2, mcw×2
   underconverged	n_estimators ×2（受上限 2000 约束）
   unstable_psi	subsample -0.1, colsample_bytree -0.1（受下限 0.5 约束）
   well_fit	不动

   dnn 策略表：

   状态	动作
   underfit	lr×2, dropout×0.7, epochs×1.5
   overfit	dropout+0.1, weight_decay×2
   underconverged	epochs×2, patience+5
   unstable_psi	dropout+0.1, batch_size×2（减梯度噪声）
   well_fit	不动

   lr 策略表：

   状态	动作
   underfit	C×2（减弱正则）, max_n_bins+2（更细 WoE 分箱）
   overfit	C/2（加强正则）, max_n_bins-2
   underconverged	max_iter×2
   unstable_psi	max_n_bins-2, min_bin_size×2（粗分箱更稳）
   well_fit	不动

5. 问用户：打印诊断 + 推荐参数，要 [Y/n] 确认（--auto-apply 跳过）

6. 训练：--method rule 直接用推荐参数训练；--method optuna 在 baseline 周围 ±30% 搜索 n_trials 次，取 val_auc 最优 params 重训

7. 复用 classification-model-training 产物管线：落八阶段产物到新 run_dir，config.json.runtime 含 baseline_run / diagnosis / method / recommended_params / final_params / trials_log / baseline_metrics

2.2 流程 B：特征筛选（select_features.py）

bashCopy code
# 上游需要先跑 feature-analysis，产出含 stats/iv_table/psi_table.csv 的目录

python <skill_dir>/scripts/select_features.py \
    --baseline_run <session_dir>/new-models/xgb-v1 \
    --analysis_dir <session_dir>/sample-features/feature-analysis/analysis \
    [--version v1] \
    [--output_dir <session_dir>] \
    [--no-psi] [--no-iv] [--no-missing] \
    [--psi_threshold 0.10] \
    [--iv_threshold 0.02] \
    [--missing_threshold 0.95] \
    [--auto-apply]

执行步骤：

1. 读 baseline：同流程 A

2. 算法直通：同流程 A（按 baseline.algo 走 xgb / dnn / lr）

3. 应用规则（三条独立，可分别启停）：

   规则	数据源	阈值	默认
   high_psi	psi_table.csv.psi	> psi_threshold	0.10
   low_iv	iv_table.csv.iv	< iv_threshold 或 IV=NaN	0.02
   high_missing	stats.csv.missing_rate	> missing_threshold	0.95

   csv 不存在时对应规则静默跳过（不抛错，见 selection_rules._read_csv）

4. 打印剔除明细（分规则列出 + 总数），要 [Y/n] 确认（--auto-apply 跳过）

5. 重训：用 baseline 的 used_params（不调参） + 筛选后的特征集训练，落八阶段产物

6. config.json.runtime 含 baseline_run / selection {kept/dropped/dropped_by_rule/thresholds/rules_enabled} / analysis_dir / final_params / baseline_metrics

3. 参数说明

3.1 run_tuning.py

3.2 select_features.py

4. 输出产物

• 调优 run：<session_dir>/new-models/{algo}-tuned-v{N}/（例：xgb-tuned-v1）
• 筛选 run：<session_dir>/new-models/{algo}-feat-v{N}/（例：xgb-feat-v1）
• baseline run：<session_dir>/new-models/{algo}-v{N}/（例：xgb-v1）

{N} 为按 algo+suffix 维度自动自增的版本号（扫 new-models/ 下已有目录取 max+1）。结构均与 classification-model-training 完全一致（八阶段：config / features / model / evaluation / predictions / explainability / comparison / logs）。config.json 顶部多了 produced_by: "skills/model-tuning"，所有 stage 的 _manifest.json.produced_by 也标 skills/model-tuning 便于事后追溯。

logs/ 子目录除 run.log（tee 训练核心阶段）外，还多一个进程级日志：run_tuning 入口落 logs/run_tuning.log，select_features 入口落 logs/select_features.log（均为 process_tee 捕获 run_dir 创建→完成回执全过程，写入 logs/_manifest.json 的 files 列表）。

textCopy code
<session_dir>/new-models/{algo}-tuned-v{N}/    (或 {algo}-feat-v{N}/)
├── config.json                       # 含 runtime 快照
├── config/train_config.yaml          # 条件生成，见 4.2
├── features/used-feature-list.csv    # feat run 含 dropped 明细
├── model/model.json|.pkl             # 扩展名按 algo
├── model/model_meta.json             # dnn / lr 必有；xgb 由引擎自身落盘
├── model/scorecard.csv               # 仅 lr，algo=lr 且 predictor 持有 scorecard_df 时
├── evaluation/{run_name}_{split}_eval.{json,md,xlsx}   # 三档标准化三件套
├── predictions/*.parquet + report.md
├── explainability/feature-importance.csv (+ shap-summary.csv，仅 xgb)
├── comparison/comparison_{split}.{json,md,xlsx}        # 某 split 缺 JSON 时跳过
├── logs/run.log                      # tee 训练核心阶段
├── logs/run_tuning.log 或 logs/select_features.log    # 进程级日志
└── report.md                         # 单 run 顶层整合报告
<session_dir>/model-comparison/        # 会话级横向对比聚合，每次 run 完成后自动刷新

4.1 产物内容

5. 与其他 skill 的关联

6. 执行约束

覆盖范围、不覆盖清单、何时用、session 约定、Optuna 搜索空间详情(各 algo 调哪些超参)、异常处理全表详见 references/constraints-and-exceptions.md。

7. 异常处理

异常分类与处理方式详见 references/constraints-and-exceptions.md 第 9 节。

8. 测试

bashCopy code
python -m pytest <skill_dir>/tests/ -q                 # 全量
python -m pytest <skill_dir>/tests/ -q -m "not slow"    # 仅快测

数据来源：baseline run 来自 classification-model-training 产出的 <session_dir>/new-models/{algo}-v{N}/；特征分析 csv 来自 feature-analysis 产出的 <session_dir>/sample-features/feature-analysis/analysis/。 最后更新：2026-07-05