Classification Model Training

classification-model-training

训练为进程内实现(xgboost / dnn / lr),按 model.algo 切换;由 scripts/run_build.py 编排。 共享配置读写代码位于 model-skills/_modelevo-shared/scripts/(config_io),通过 scripts/_bootstrap.py 注入;源在仓库根 _modelevo-shared/scripts/,由 install.sh 复制。

1. 输入依赖

2. 执行命令

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

Session 决议(由上游负责):本 skill 假定 session_dir 已由上游 classification-model-development / classification-model-orchestration 确定。若用户直接调本 skill 且无 session 上下文,请先跑:

bashCopy code
python <model-skills>/classification-model-development/scripts/list_sessions.py

用 AskUserQuestion 询问选历史 session 还是新建,确认 session_dir 后再执行训练。

输入 yaml 落盘(强制):输入 yaml 必须落 <session_dir>/new-models/{algo}-v{N}/config/train_config.yaml(model 内部 config 目录),不要放 <skill_dir>/config/ 或 session 根目录。流程:

1. 复制 <skill_dir>/config/train_config.example.yaml 到 <session_dir>/new-models/{algo}-v{N}/config/train_config.yaml({algo} 取 xgb|dnn|lr,{N} 由 next_version 自增;目录不存在则 mkdir -p 创建)
2. 编辑该 yaml 填真实值
3. 调 run_build.py 指向该 yaml:

bashCopy code
python <skill_dir>/scripts/run_build.py \
--config <session_dir>/new-models/{algo}-v{N}/config/train_config.yaml \
--output_dir <session_dir> \
--version v1                   # 可选; 否则按 yaml.run_label → 自动自增

--data_dir 可选,默认从同 session 下 <session_dir>/sample-features/ 读 splits/{train,test,oot}.parquet(由 feature-analysis 切分产出);若需用其他数据,显式传 --data_dir override(指向含 splits/ 子目录的目录)。--output_dir 直接传 <session_dir>,run_build 会在其下落 new-models/{algo}-v{N}/(无 classification-model-training/ 中间层)。test.parquet 当 val 段(early stopping);进程内用调优超参训练(tune_train.TUNED_PARAMS: depth 6 / lr 0.03 / n 800 + early-stop;比 engines/_xgb/entry.py 的强正则默认更高容量,避免欠拟合)。

训练完成后,模型报告路径需人工登记到 classification-model-recommend 台账(本 skill 不自动改 csv)。

3. 参数说明

run_build.py

version 决议优先级(本次 run 的 version 用作目录后缀,形如 v1 / v2 / custom-tag):

字符集限制 [a-zA-Z0-9_.-],非白名单字符归一为 _;空值走自动自增。

⚠️ version 保留字拦截:目录命名规则为 {algo}{suffix}-{version},若 version 含 algo(xgb/dnn/lr/lgb)或 suffix(tuned/feat)保留字 token,会叠加产生重复前缀目录(如 xgb-xgb-v1 / xgb-tuned-tuned-v1 / xgb-feat)。validate_config 与 CLI 入口(run_build.py / run_tuning.py / select_features.py)在 run_dir 创建前统一拦截,报错示例:

Copy code
ValueError: model.run_label 非法: version 标识 'lgb-v1' 含算法/后缀保留字 ['lgb'], ...

写 yaml 或跑 CLI 时,run_label / --version / --label 只填纯版本号(如 v1 / v2 / 20260710 / exp01),不要重复 algo 或 suffix。

model.boundary_filter(边界特征过滤)

职责定位:边界过滤是安全过滤(剔除会让训练失败或泄漏的特征),基于 IV/PSI 的优化筛选由 classification-model-tuning 负责。本层不参与特征优选,只剔除数据安全/正确性问题特征。

4 条规则(任一命中即剔除,并集生效):

与 tuning 阈值不重叠:本 skill missing_max=1.0 只删真全缺失;tuning missing_threshold=0.95 删高缺失。

配置字段(model.boundary_filter 段):

warn-and-skip 行为:上游 feature-analysis 缺 stats.csv/feature-quality.csv/iv_table.csv 时,对应规则打印 warning 并跳过(返回空剔除集),不阻断训练;sample_total <= 0 时 id_like 规则跳过。

产物落盘:被剔除特征落 features/used-feature-list.csv 的 dropped_<rule> 行(三列 csv: feature_name / status / dropped_by_rule);features/report.md 含"边界特征过滤"段按规则分组展示;config.json.runtime.boundary_filter 含 n_before/n_after/n_dropped/dropped_by_rule/thresholds/rules_enabled/sample_total 摘要。

4. 输出产物

单次 run 在 <session_dir>/new-models/{algo}-v{N}/ 下落以下子目录(--output_dir 传的是 <session_dir> 本身,无 classification-model-training/ 中间层):

• baseline run: {algo}-v1 / {algo}-v2 / ...(suffix 为空)
• 特征筛选 run(classification-model-tuning 产): {algo}-feat-v1 / {algo}-feat-v2 / ...
• 调参 run(classification-model-tuning 产): {algo}-tuned-v1 / {algo}-tuned-v2 / ...
• {N} 按 algo+suffix 维度自动自增(扫 new-models/ 下已有目录取 max+1);--version 显式指定时跳过自增。

textCopy code
{run_dir}/
├── config.json                    # 入参+训练快照(metrics/best_iteration/n_features)
├── config/                        # 入参 yaml(原地存,独立复现用)
│   ├── _manifest.json             # 含 source_yaml 指向自身 yaml 绝对路径
│   └── train_config.yaml          # 输入 yaml 原件(--config 指向此文件;未传则整段缺失)
├── features/
│   ├── _manifest.json
│   ├── used-feature-list.csv      # 单列 feature_name(供下游复现/部署)
│   └── report.md
├── model/
│   ├── _manifest.json             # 含 algo / used_params / best_iteration / has_scorecard
│   ├── model_meta.json            # 训练元信息(结构随 algo 不同, 供下游 tuning 复用)
│   ├── model.json  (xgb)          # 算法原生扩展名
│   ├── model.pkl   (dnn|lr)
│   └── scorecard.csv (lr)         # 评分卡: [feature, bin, woe, coef, score]
├── evaluation/
│   ├── _manifest.json
│   ├── {run_name}_train_eval.json     # classification-model-evaluation 产出
│   ├── {run_name}_train_eval.md
│   ├── {run_name}_train_eval.xlsx
│   ├── {run_name}_test_eval.{json,md,xlsx}
│   ├── {run_name}_oot_eval.{json,md,xlsx}
│   └── {run_name}_all_eval.{json,md,xlsx}   # train+test+oot 纵向拼接整体评估
├── predictions/
│   ├── _manifest.json
│   ├── train_predictions.parquet  # train 分档: id_cols + label + score + bucket
│   ├── test_predictions.parquet   # test  分档: 同上
│   ├── oot_predictions.parquet    # oot   分档: 同上
│   └── report.md                  # 三档分布直方图 + 数据安全提示
├── explainability/
│   ├── _manifest.json
│   ├── feature-importance.csv
│   └── shap-summary.csv           # 仅 xgb (TreeExplainer; 其他算法在 manifest 标 skipped)
├── comparison/                     # 仅当 model.baseline_eval_dir 配置时产出(延迟创建, 无产物则目录不存在)
│   ├── _manifest.json             # 含 baseline_eval_dir / splits / skipped
│   ├── comparison_train.{json,md,xlsx}  # 新模型 vs 基线 (train 档)
│   ├── comparison_test.{json,md,xlsx}   # 新模型 vs 基线 (test 档)
│   └── comparison_oot.{json,md,xlsx}    # 新模型 vs 基线 (oot 档)
├── logs/
│   ├── _manifest.json
│   ├── run.log                    # tee 捕获训练核心阶段 stdout/stderr
│   └── run_build.log              # process_tee 捕获 run_dir 创建→完成回执全过程
└── report.md                       # 单 run 顶层整合报告(各阶段摘要, 自动落)

4.0 session 级横向对比产物

每个 run 跑完自身 comparison/ 后, run_build.py 末尾固定调 invoke/session_aggregate.py:invoke_session_aggregate(output_dir), 在 <session_dir>/model-comparison/ 下产跨 run 横向 N-way 对比(与单 run 的 comparison/ 互补, 聚合 session 内所有 run 的 eval JSON):

textCopy code
<session_dir>/model-comparison/
├── _manifest.json                       # 含 included_runs / splits / skipped
├── model-comparison_train.{json,md,xlsx}   # session 内所有 run 的 train 段 eval 横向对比
├── model-comparison_test.{json,md,xlsx}    # 同上, test 段
└── model-comparison_oot.{json,md,xlsx}     # 同上, oot 段

聚合失败不影响主流程(单 run comparison/ 已落盘), 仅打 warning。included_runs 字段记录实际纳入对比的 run 列表(扫 new-models/*/evaluation/ + model-recommend/*/evaluation/ 命中的 eval JSON)。

4.1 产物内容

评估依赖(强制):

• 本 skill 不自带评估报告逻辑,评估阶段统一委托 classification-model-evaluation skill。
• predictions 阶段写完三档 parquet 后,由 scripts/invoke_evaluation.py 一次性把三档 predictions 转 CSV 喂给 classification-model-evaluation/scripts/eval_single.py(目录模式),产出标准化三件套(JSON + MD + XLSX)到 evaluation/ 子目录。
• 输出文件命名:{run_name}_{split}_eval.{json,md,xlsx},split = train / test / oot / all(共 4 档);all 档为三档样本纵向拼接后的整体评估,由 eval_single 自动产。
• 透传字段:model.algo → --model-type,model.label_expr → --target-def,model.owner → --owner,model.status → --status,训练实际超参 → --hyperparams。
• base 对比 / 训练段 vs OOT 段 PSI / 三段汇总表 不在本 skill 产出范围内;如需 base 对比请走 classification-model-comparison skill。

对比阶段(可选,评估完成后链式调用):

• model.baseline_eval_dir 配置时:评估完成后自动调 classification-model-comparison skill,对 train/test/oot 三档分别做 N-way 对比(新模型 eval JSON vs 基线 eval JSON)。
• model.baseline_eval_dir 未设置时:默认扫描 <session_dir>/model-recommend/*/evaluation/(兼容 classification-model-recommend skill 推荐的 yx_001/yx_002 等多 model_id 子目录),命中即对每个 split 做 N-way 对比;无命中则跳过,不影响主流程。
• model.baseline_eval_dir: null 显式为 null:关闭默认扫描,不产 comparison/ 子目录。
• 基线 JSON 定位:在每个 baseline_eval_dir 下 glob *_{split}_eval.json(按 model_id 去重,避免同名重复计入);新模型 JSON:{run_name}_{split}_eval.json。
• 产出:comparison/comparison_{split}.{json,md,xlsx} × 3 档 + _manifest.json。

评分卡产物(仅 algo=lr):

• LR 路径在训练完成后由 engines/_lr/_model.py:ScoreCardConverter 生成评分卡表,落盘为 model/scorecard.csv,并在 model/_manifest.json 标 has_scorecard: true。
• 列结构:[feature, bin, woe, coef, score];每行 = 一个特征分箱的 WoE / 系数 / 分数贡献。
• 分数公式:Score = base_score - factor * ln(odds),factor = pdo / ln(2);默认 base_score=600 / pdo=50 / base_odds=50(基准 odds 50:1)。
• 非 lr 路径(xgb/dnn)不产 scorecard.csv,manifest 标 has_scorecard: false。

model_meta.json:

• 统一字段:{algo, feature_names, feature_importance, train_info, params, created_at};由 scripts/stages/model.py:write_model_stage 落盘。
• xgb: 由引擎 engines/_xgb/_core/_fit.py 在 save_model 时落盘, 字段 {feature_names, feature_importance, best_iteration, params}。
• dnn: 由 stages/model.py:_write_meta_for_non_xgb 补写, feature_importance={}(MLP 无原生重要性), train_info={best_epoch, best_val_auc, total_epochs, early_stopped}。
• lr: 同函数补写, feature_importance={feat: |coef|}(取自 LrPredictor.get_feature_importance()), train_info={n_iter, converged, train_auc, val_auc, n_features, regularization, C}。

4.2 对比口径 / version 决议

对比口径:

• base 对比 / PSI / 分档走势 / 三段汇总报告由独立 skill 承担,本 skill 不自带。
• 单模型标准化评估:见 evaluation/{run_name}_{split}_eval.md(由 classification-model-evaluation 产出)。
• 多模型 / 多版本对比:调 classification-model-comparison skill。

version 决议规则见「3. 参数说明」末尾。

5. 与其他 skill 的关联

6. 执行约束

覆盖范围、"不覆盖"清单、何时用、session 决议、迭代报告、输入 yaml 落盘约束、异常处理全表详见 references/constraints-and-exceptions.md。

7. 异常处理

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

8. 测试

bashCopy code
python -m pytest <skill_dir>/tests/ -q              # 全量(含真训练 slow 用例)
python -m pytest <skill_dir>/tests/ -q -m "not slow"  # 仅快测

数据来源:输入 splits/{train,test,oot}.parquet 由 feature-analysis skill 按 model.split 切分产出(其上游 sample.parquet 来自 feature-matching),本 skill 不取数也不切分;baseline eval JSON 来自 classification-model-recommend skill 的 model-recommend/{model_id}/evaluation/ 目录;调优超参默认值见 scripts/trainers/tune_train.py:TUNED_PARAMS。 最后更新:2026-07-07