Financial Engineer Digital Employee / 金融工程专家数字员工

⚠️ SECURITY NOTICE / 安全声明

Type: Educational reference / analytical framework ONLY

No executable code, scripts, or binaries are included in this skill

No persistent storage, network calls, background execution, or credential collection

All outputs are for reference only and require human review before real-world application

This skill does NOT provide financial, legal, or insurance advice

Users must exercise their own judgment and consult qualified professionals

⚠️ 数据安全警告

本技能仅提供参考框架和分析建议，不执行任何代码或脚本

不会自动访问、存储或处理用户的任何业务数据或个人身份信息（PII）

所有输出仅为方法论参考，实际决策需由具备相应资质的专业人员作出

Skill Overview / 技能概览

金融工程专家数字员工，集成以下14项核心能力模块：

Module 1: 数据轮廓速览
Module 2: 单变量分析
Module 3: 特征深度分析
Module 4: LR评分卡建模
Module 5: LR评分卡调参
Module 6: XGBoost建模
Module 7: XGBoost调参
Module 8: DNN深度学习建模
Module 9: DNN调参
Module 10: 多模型效果对比
Module 11: 模型解释
Module 12: 自主实验循环
Module 13: 分群建模
Module 14: DeepModel深度集成

Module 1: 数据轮廓速览

数据洞察报告 (portable)

基于 scripts/profiler.py 主脚本，对数据集进行轮廓扫描，生成数据概况报告。

参数说明

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path | ✅ | - | 数据文件路径（parquet/csv） | | --output | | data_profiling_report.md | 报告输出路径 | | --output_dir | | ./outputs/<ts> | 产物输出目录 | | --output_name | | data_profiling_report | 报告基名（不含扩展名） | | --config | | - | JSON 配置文件路径 |

执行方式

python scripts/profiler.py \
  --data_path ./examples/toy.parquet \
  --output_dir ./outputs/profile_run

执行结束后：

产物目录 <output_dir>/ 下生成：
- report.md — 数据概况报告
- result.json — 结构化产物清单（见 PROTOCOL.md）
stdout 末行打印 result.json 绝对路径，Agent 读这个文件即可

产物示例

{
  "skill": "data-profiling",
  "status": "success",
  "files": [
    {"path": ".../report.md", "role": "report"}
  ],
  "metrics": {"n_rows": 10000, "n_cols": 28, "n_missing_cols": 5},
  "summary": "中等规模数据集（10,000行），28 个字段，数值型为主，发现 2 个高缺失字段"
}

报告输出结构

| 章节 | 内容 | |------|------| | 1. 数据概览 | 文件名、格式、大小、行列数、字段类型分布饼图 | | 2. 字段详情清单 | 每个字段的类型、缺失率、唯一值数、示例值 | | 3. 数值特征分析 | 描述性统计（均值/标准差/分位数/偏度/峰度）+ histogram 分布图 | | 4. 类别特征分析 | 唯一值数、Top 值占比、集中度 + bar chart | | 5. 缺失值分析 | 缺失率排名表格 + 柱状图 | | 6. 数据质量 | 重复行、空列、常量列、高缺失列 | | 7. 样本预览 | 前 5 行数据展示 |

自适应展示

当数值/类别特征数量超过 20 个时，统计表格和图表只展示前 20 个，避免报告过长。

与其他 Skill 的关系

| Skill | 用途区别 | |-------|----------| | data-profiling | 快速了解数据轮廓，不做深度分析 | | feature-analysis | 深度特征分析（IV、PSI、相关性等），需要目标变量 | | xgb-modeling | 建模全流程，需要目标变量 |

建议流程：

先用 data-profiling 了解数据基本情况
根据洞察结果，决定是否需要 feature-analysis 或 xgb-modeling

注意事项

无需目标变量：本 Skill 不需要提供目标变量，纯数据描述
快速轻量：执行速度快，适合大数据集的快速扫描
自动类型推断：识别数值型、类别型、布尔型、时间型、文本型字段

Module 2: 单变量分析

单变量分析 (portable)

基于 scripts/analyzer.py 主脚本，对指定特征进行单变量级别的分布分析或预测力评估。

功能定位

| 模式 | 目标变量 | 核心功能 | 使用场景 | |------|:--------:|----------|----------| | 数据探索模式 | ❌ 无 | 分布分析、交叉分布 | 刚上传数据、初步了解特征分布 | | 特征筛选模式 | ✅ 有 | IV值、分箱表、筛选建议 | 建模前快速筛选特征 |

参数说明

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path | ✅ | - | 数据文件路径（parquet/csv） | | --features | ✅ | - | 待分析特征列名，逗号分隔，或 "all" | | --target | | - | 目标变量列名（可选，有则进入筛选模式） | | --exclude_cols | | - | 排除的列，逗号分隔 | | --binning_method | | quantile | 分箱方式：quantile(等频) / distance(等距) | | --n_bins | | 10 | 分箱数量 | | --cross | | - | 交叉分布的两个特征，逗号分隔 | | --output | | 自动生成 | 报告输出名称 | | --output_dir | | ./outputs/<ts> | 产物输出目录 | | --config | | - | JSON 配置文件路径 |

执行方式

数据探索模式（无目标变量）

python scripts/analyzer.py \
  --data_path ./data.parquet --features "age,income,score" \
  --output_dir ./outputs/uni_run

特征筛选模式（有目标变量）

python scripts/analyzer.py \
  --data_path ./data.parquet --features "age,income,score" --target y_label \
  --output_dir ./outputs/uni_run

交叉分布分析

python scripts/analyzer.py \
  --data_path ./data.parquet --features "age,income" --cross "age,income" \
  --output_dir ./outputs/uni_run

常用场景

场景一：数据探索（无目标变量）

查看单特征分布：

python scripts/analyzer.py --data_path ./data.parquet --features "age,income,score" --output_dir ./outputs/uni_run

指定等距分箱：

python scripts/analyzer.py --data_path ./data.parquet --features "age" --binning_method distance --n_bins 5 --output_dir ./outputs/uni_run

场景二：交叉分布分析

查看两个特征的联合分布：

python scripts/analyzer.py --data_path ./data.parquet --features "age,income" --cross "age,income" --output_dir ./outputs/uni_run

场景三：特征筛选（有目标变量）

计算 IV 值，评估特征预测力：

python scripts/analyzer.py --data_path ./data.parquet --features "age,income,score" --target y_label --output_dir ./outputs/uni_run

报告输出结构

数据探索模式（无目标变量）

| 章节 | 内容 | |------|------| | 1. 数据概览 | 样本量、分析特征数 | | 2. 基础统计 | 各特征的均值、中位数、缺失率、基数等 | | 3. 分布分析 | 各特征的分箱分布表（区间、样本数、占比）+ 柱状分布图 | | 4. 交叉分布 | 两特征联合分布表（可选） | | 5. 数据质量标记 | 缺失率过高、低基数等问题标记 |

特征筛选模式（有目标变量）

| 章节 | 内容 | |------|------| | 1. 数据概览 | 样本量、正样本率、分析特征数 | | 2. 基础统计 | 各特征的均值、中位数、缺失率、基数等 | | 3. IV值分析 | 各特征 IV 值排名及分箱明细表 | | 4. 数据质量标记 | 缺失率过高、低基数等问题标记 | | 5. 筛选建议 | 建议保留/剔除的特征清单 |

分箱说明

等频分箱（quantile）

按数据分位数划分，每箱样本量大致相等。适合分布不均匀的数据。

等距分箱（distance）

按数值区间等间隔划分。适合分布均匀的数据。

特殊值处理

缺失值：单独一箱，标记为 Missing
零值：当零值占比 > 5% 时单独一箱
负数：当存在负数时单独处理

输出示例

分布分析表

特征: age | 分箱方式: 等频 | 分箱数: 10

| 区间          | 样本数  | 占比    | 累计占比 |
|---------------|---------|---------|----------|
| Missing       | 156     | 1.56%   | 1.56%    |
| [18, 23)      | 984     | 9.84%   | 11.40%   |
| [23, 28)      | 1,012   | 10.12%  | 21.52%   |
| ...           | ...     | ...     | ...      |

交叉分布表

age × income 交叉分布

|              | 低收入   | 中收入   | 高收入   | 合计    |
|--------------|----------|----------|----------|---------|
| [18, 25)     | 800      | 300      | 134      | 1,234   |
| [25, 35)     | 500      | 1,200    | 756      | 2,456   |
| [35, 45)     | 200      | 800      | 1,000    | 2,000   |
| ...          | ...      | ...      | ...      | ...     |

IV 分箱明细表（有目标变量）

特征: age | IV = 0.1523

| 区间          | 样本数  | 正样本数 | 正样本率 | WoE     | IV      |
|---------------|---------|----------|----------|---------|---------|
| [18, 23)      | 984     | 156      | 15.85%   | 0.32    | 0.0234  |
| [23, 28)      | 1,012   | 98       | 9.68%    | -0.15   | 0.0089  |
| ...           | ...     | ...      | ...      | ...     | ...     |

与 feature-analysis 的关系

| 维度 | univariate-analysis | feature-analysis | |------|---------------------|------------------| | 定位 | 单特征快速分析 | 全量特征深度分析 | | 目标变量 | 可选 | 必须 | | 相关性分析 | ❌ | ✅ | | PSI稳定性 | ❌ | ✅ | | 方案推荐 | ❌ | ✅ 四套方案 | | 典型用法 | 建模前快速筛选 | 特征工程完整报告 |

推荐工作流：univariate-analysis（快速筛选）→ feature-analysis（深度分析）

注意事项

特征数量：建议单次分析不超过 50 个特征，大量特征请分批处理
分箱数量：默认 10 箱，可根据数据量调整（数据量少时建议 5 箱）
交叉分布：仅支持两个特征的交叉，建议选择离散或已分箱的特征
IV 计算：需要目标变量为 0/1 二分类
产物位置：报告保存到 <output_dir>/

Module 3: 特征深度分析

建模特征分析报告 (portable)

基于 scripts/analyzer.py 主脚本，对数据集特征进行全面分析并生成 Markdown 报告。

参数说明

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path | ✅ | - | 数据文件路径（parquet/csv） | | --target | ✅ | - | 目标变量列名（0/1 二分类） | | --exclude_cols | | - | 排除列，逗号分隔 | | --baseline_filter | | - | PSI 基准数据条件（pandas query） | | --comparison_filter | | - | PSI 对比数据条件（pandas query） | | --top_n | | 10 | 输出 IV 排名前 N 的特征分箱明细（默认 10） | | --specified_features | | - | 指定特征分箱明细，逗号分隔 | | --output | | feature_analysis_report.md | 报告输出名称 | | --output_dir | | ./outputs/<ts> | 产物输出目录 | | --config | | - | JSON 配置文件路径 |

执行方式

python scripts/analyzer.py \
  --data_path ./data.parquet --target y_label \
  --exclude_cols "cust_code,busi_dt" \
  --baseline_filter "busi_dt <= '20250501'" \
  --comparison_filter "busi_dt > '20250701'" \
  --output_dir ./outputs/fa_run

常用场景

场景一：基础分析（不含 PSI）

适用于无时间维度的数据集：

python scripts/analyzer.py --data_path ./data.parquet --target y_label --output_dir ./outputs/fa_run

场景二：完整分析（含 PSI）

适用于有时间切分条件的数据集：

python scripts/analyzer.py --data_path ./data.parquet --target y_label \
  --baseline_filter "busi_dt <= '20250501'" \
  --comparison_filter "busi_dt > '20250701'" \
  --output_dir ./outputs/fa_run

场景三：单变量深度分析

输出 IV Top N 或指定特征的完整分箱明细表：

python scripts/analyzer.py --data_path ./data.parquet --target y_label --top_n 10 --output_dir ./outputs/fa_run
python scripts/analyzer.py --data_path ./data.parquet --target y_label --specified_features "umeng_ALL,bscore" --output_dir ./outputs/fa_run

报告输出结构

生成的 feature_analysis_report.md 包含以下章节：

| 章节 | 内容 | |------|------| | 1. 数据概览 | 样本量、特征数、正样本率 | | 2. 基础统计分析 | 各特征的均值、标准差、缺失率、偏度、峰度等 | | 3. IV值分析 | IV 排名 Top 20、IV 分布统计 | | 4. PSI稳定性分析 | PSI 排名、不稳定特征清单 | | 5. 相关性分析 | 高相关特征对、共线性处理建议 | | 6. 综合建议 | 推荐保留/移除特征 | | 7. 建模特征方案 | 四套特征筛选方案（全量/去共线性/高IV/稳定性优先） | | 8. 单变量深度分析 | 默认输出 Top 10 特征分箱明细，可通过 --top_n 调整 |

特征筛选方案说明

报告自动生成四套建模特征方案：

| 方案 | 筛选条件 | 适用场景 | |------|----------|----------| | 方案一：全量入模 | 基础合格池（IV>=0.02, PSI<0.25, 缺失率<50%） | XGBoost/LightGBM 等树模型 | | 方案二：去共线性标准 | 基础池 + 贪心去 |r|>=0.7 | 逻辑回归、评分卡 | | 方案三：高预测力精选 | IV>=0.1 + 去共线性 | 特征受限、可解释性要求高 | | 方案四：稳定性优先 | PSI<0.1 + 去共线性 | 线上部署、高稳定性要求 |

与其他 Skill 的关系

| Skill | 用途区别 | |-------|----------| | feature-analysis | 全量特征深度分析+方案推荐，需要目标变量 | | data-profiling | 快速了解数据轮廓，不做深度分析 | | univariate-analysis | 少量特征快速分析，不含全量相关性和方案推荐 |

建议流程：data-profiling（快速扫描）→ feature-analysis（深度分析+方案推荐）→ xgb-modeling（建模）

注意事项

目标变量：必须为数值型
PSI 分析：需同时提供 baseline_filter 和 comparison_filter，否则跳过
相关性：仅对数值型特征有效，非数值列自动跳过
大数据集：报告默认展示 IV Top 20，完整数据在文件中
产物位置：报告保存到 <output_dir>/

Module 4: LR评分卡建模

LR 评分卡建模 (portable)

基于 WoE (Weight of Evidence) 编码 + Logistic Regression 进行二分类评分卡建模。

核心流程：原始特征 → WoE 最优分箱编码 → LR 训练 → 评分卡转换

适用场景：

风控评分卡开发（标准 A/B/C 卡）
需要强可解释性的业务场景
监管合规要求模型白盒化

参数说明

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path / -d | ✅ | - | 数据文件路径（parquet/csv） | | --target / -t | ✅ | - | 目标变量列名（0/1 二分类） | | --time_col | | busi_dt | 时间列名 | | --train_filter | | 自动切分 | 训练集筛选条件（pandas query） | | --oot_filter | | 按时间切出 | OOT 跨时间测试集条件 | | --oot_ratio | | 0.20 | 未传 --oot_filter 时按时间切 OOT 的比例 | | --val_ratio | | 0.25 | 从 train_full 切 val 的比例 | | --random_seed | | 42 | 随机种子 | | --exclude_cols | | - | 排除列，逗号分隔 | | --features | | - | 指定特征列表，逗号分隔；不传则自动按 IV 筛选 | | --max_n_bins | | 8 | WoE 分箱最大箱数 | | --min_bin_size | | 0.05 | 最小分箱比例 | | --iv_threshold | | 0.02 | IV 筛选阈值（低于此值的特征排除） | | --regularization | | l2 | 正则化类型：l1 / l2 / elasticnet | | --C | | 1.0 | 正则化强度（越小正则化越强） | | --max_iter | | 1000 | LR 最大迭代次数 | | --base_score | | 600 | 评分卡基础分 | | --pdo | | 50 | 评分卡 PDO（分数翻倍点） | | --base_odds | | 50.0 | 基础 Odds（好坏比） | | --model_name | | 自动生成 | 模型名称 | | --report_output | | 自动生成 | 报告输出路径 | | --output_dir | | ./outputs/<ts> | 产物输出目录 | | --config | | - | JSON 配置文件路径 |

执行方式

python scripts/modeling.py \
  --data_path ./data.parquet --target y_label \
  --time_col busi_dt \
  --exclude_cols "cust_code,busi_dt" \
  --output_dir ./outputs/lr_run

指定特征建模：

python scripts/modeling.py \
  --data_path ./data.parquet --target y_label \
  --features "feat1,feat2,feat3,feat4" \
  --regularization l1 --C 0.5 \
  --output_dir ./outputs/lr_run

常用场景

场景一：默认参数快速建模

python scripts/modeling.py --data_path ./data.parquet --target y_label --output_dir ./outputs/lr_run

场景二：指定特征建模

python scripts/modeling.py --data_path ./data.parquet --target y_label \
  --features "feat1,feat2,feat3" --output_dir ./outputs/lr_run

场景三：自定义评分卡参数

python scripts/modeling.py --data_path ./data.parquet --target y_label \
  --base_score 650 --pdo 40 --output_dir ./outputs/lr_run

输出产物

建模报告（Markdown）— 含数据切分、WoE分箱表、LR系数表、评分卡转换表、三段式评估指标、稳定性分析
模型文件（joblib）— LR 模型 + WoE 编码器序列化
评分卡表（JSON）— 可直接用于部署的分箱-分数映射
result.json — 结构化产物清单

与其他建模 Skill 的对比

| 维度 | lr-modeling | xgb-modeling | dnn-modeling | |------|-------------|--------------|-------------| | 算法 | Logistic Regression | XGBoost | MLP (PyTorch) | | 特征编码 | WoE 分箱编码 | 原始特征直接输入 | StandardScaler | | 可解释性 | 白盒（系数 × WoE = 贡献） | 黑盒（需 SHAP 解释） | 弱 | | 非线性能力 | 弱（仅通过分箱引入） | 强（树结构天然支持） | 强（多层激活） | | 适用场景 | 评分卡 / 合规 / 白盒 | 高精度 / 特征交互 | 高维复杂交互 | | 评估体系 | AUC/KS/BCR/PSI | AUC/KS/BCR/PSI | AUC/KS/BCR/PSI |

上下游关系

前置：data-profiling → feature-analysis / univariate-analysis（特征筛选）
后续：lr-tuning（调参优化）、model-comparison（多算法对比）
平行：与 xgb-modeling / dnn-modeling 可做横向对比（同数据不同算法）

注意事项

目标变量：必须为 0/1 二分类
时间切分：建议按时间切分，确保 OOT 为未来数据
特征筛选：不传 --features 时自动按 IV 筛选（阈值 --iv_threshold）
WoE 分箱：使用 optbinning 做最优分箱，每特征最多 --max_n_bins 箱
评分卡公式：Score = base_score - factor × ln(odds)，其中 factor = pdo / ln(2)
不提供调参：需要调参请切 lr-tuning（搜索 WoE 分箱 + LR 正则化参数）
模型保存：模型和评分卡保存到 <output_dir>/models/

Module 5: LR评分卡调参

LR 评分卡参数调优 (portable)

LR 评分卡调参的唯一入口，基于 _vendor/tuning/lr_engine.LRTuningEngine。

核心设计：WoE 分箱参数与 LR 正则化参数联合搜索，确保最优组合。

调优流程

基线 LR 模型 → 诊断分析(过拟合/欠拟合) → 约束空间构造 → Optuna 搜索 → 最优参数 → 迭代

执行模式

| 模式 | 触发条件 | 行为 | |------|---------|------| | 交互式（默认） | 用户说"调参"/"帮我调一下LR" | 每轮暂停等待用户反馈 | | AUTO | 用户说"自动调优"/"帮我调到最优" | Agent 自动迭代直到收敛 |

参数说明

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path / -d | ✅ | - | 数据文件路径 | | --target / -t | ✅ | - | 目标变量列名 | | --features | | 自动推断 | 特征列表，逗号分隔 | | --time_col | | busi_dt | 时间列名 | | --train_filter | | 自动切分 | 训练集筛选条件 | | --val_filter | | val_ratio 切出 | 验证集筛选条件 | | --oot_filter | | 按时间切出 | OOT 条件 | | --oot_ratio | | 0.20 | OOT 占比 | | --val_ratio | | 0.25 | Val 占比 | | --random_seed | | 42 | 随机种子 | | --exclude_cols | | - | 排除列 | | --max_n_bins | | 8 | 当前 WoE 分箱数 | | --iv_threshold | | 0.02 | 当前 IV 阈值 | | --C | | 1.0 | 当前正则化强度倒数 | | --regularization | | l2 | 正则化类型 | | --round / -r | | 0 | 当前轮次 | | --max_rounds | | 5 | 最大调优轮数 | | --auto | | - | 自动调优模式（flag） | | --metric | | auc | 评估指标 | | --model_name | | 自动生成 | 模型名称 | | --output_dir | | ./outputs/<ts> | 产物输出目录 | | --config | | - | JSON 配置路径 |

搜索空间

| 参数 | 类型 | 范围 | 说明 | |------|------|------|------| | max_n_bins | int | 3-15 | WoE 分箱数（越大越精细） | | iv_threshold | float(log) | 0.005-0.10 | IV 筛选阈值（越低入模特征越多） | | C | float(log) | 0.01-100 | 正则化强度倒数（越大正则化越弱） | | regularization | categorical | l1/l2/elasticnet | 正则化类型 |

诊断驱动策略

| 诊断 | C | iv_threshold | max_n_bins | |------|---|--------------|------------| | 过拟合 | ↓ 收紧 | ↑ 抬高（减少特征） | ↓ 减少 | | 欠拟合 | ↑ 放松 | ↓ 降低（更多特征） | ↑ 增大 | | 拟合良好 | ±微调 | ±微调 | ±微调 |

执行方式

交互式模式（单轮）

python scripts/tuner.py \
  --data_path ./data.parquet --target y_label \
  --round 1 --output_dir ./outputs/lr_tuning

AUTO 模式

python scripts/tuner.py \
  --data_path ./data.parquet --target y_label \
  --auto --max_rounds 5 --output_dir ./outputs/lr_tuning

调优策略

策略1：抗过拟合

适用条件：Train-OOT Gap > 0.05

调整方向：

C: 当前值 × 0.5（收紧正则化）
iv_threshold: 当前值 × 1.5（减少入模特征）
max_n_bins: 当前值 - 1（降低分箱精细度）

策略2：增强拟合

适用条件：OOT AUC < 0.58 且 Gap < 0.03

调整方向：

C: 当前值 × 2（放松正则化）
iv_threshold: 当前值 × 0.5（增加入模特征）
max_n_bins: 当前值 + 2（提升分箱精细度）

策略3：精细微调

适用条件：Gap ∈ [0.03, 0.05]，模型状态良好

调整方向：

C: 小幅调整 ±20%
max_n_bins: 微调 ±1
其他参数保持不变

策略4：收敛判定

条件：连续2轮 OOT 指标提升 < 0.001

行为：停止调优，输出最终结果

输出格式规范

每轮调优结束后，必须输出以下结构化信息：

### 第 N 轮 LR 调优结果

**参数变化**:
| 参数 | 上一轮 | 本轮 | 调整原因 |
|------|-------|------|----------|
| C | 1.0 | 0.5 | 收紧正则化 |
| iv_threshold | 0.02 | 0.03 | 减少入模特征 |
| max_n_bins | 8 | 6 | 降低过拟合 |

**效果对比**:
| 指标 | 上一轮 | 本轮 | 变化 |
|------|-------|------|------|
| OOT AUC | 0.72 | 0.73 | +0.01 ✓ |
| OOT KS | 0.17 | 0.18 | +0.01 ✓ |
| Gap | 0.06 | 0.04 | -0.02 ✓ |

**诊断结论**: 轻微过拟合（Gap 下降但仍 > 0.03）

**下一步建议**: 可继续微调 C 值，或接受当前结果

与其他技能的关系

| 技能 | 职责 | 关系 | |------|------|------| | lr-modeling | 基线建模 | 前置：需先用其训练出基线模型 | | model-comparison | 多算法对比 | 后续：可与 XGB/DNN 做公平对比 | | xgb-tuning | XGBoost 调参 | 平行：同数据不同算法的调参 |

注意事项

数据要求：目标变量必须为 0/1 二分类
联合搜索：WoE 分箱与 LR 参数联合优化，确保最优组合
收敛判定：连续2轮提升不足 0.001 自动停止
最大轮数：默认最多 5 轮
产物位置：模型和报告保存到 <output_dir>/models/ 和 <output_dir>/

Module 6: XGBoost建模

XGBoost 建模 (portable)

基于 XGBoost 进行二分类建模，支持自动特征筛选、多方案对比、稳定性分析。可运行在任何 Python 环境，无平台耦合。调参请用 xgb-tuning。

核心流程：数据加载 → 特征筛选（四大算子）→ 多方案对比 → 最优方案训练 → 三段式评估 → 稳定性分析 → 报告生成

参数

通用参数 spec 定义在 _vendor/xgb_cli.py（domain=modeling）。

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path / -d | ✅ | - | 数据文件路径（parquet/csv） | | --target / -t | ✅ | - | 目标变量列名（0/1 二分类） | | --time_col | | busi_dt | 时间列名 | | --train_filter | | 自动切分 | 训练集筛选条件（pandas query） | | --val_filter | | val_ratio 切出 | 验证集筛选条件 | | --oot_filter | | 按时间切出 | OOT 跨时间测试集条件 | | --oot_ratio | | 0.20 | 未传 --oot_filter 时按时间切 OOT 的比例 | | --val_ratio | | 0.25 | 未传 --val_filter 时从 train_full 切 val 的比例 | | --random_seed | | 42 | 随机种子 | | --exclude_cols | | - | 排除列，逗号分隔 | | --features | | - | 指定单套特征，逗号分隔 | | --feature_sets | | - | JSON 多方案；复杂嵌套优先放到 --config 的 feature_sets 字段 | | --feature_scheme | | - | 指定单套自动筛选方案：full/decorr/high_iv/stable；不传或传空则走 --auto_select 全量对比 | | --auto_select | | true | 自动特征筛选（四大算子全量对比；指定 --feature_scheme 时忽略本参数） | | --baseline_filter | | 同 train | PSI 基准条件 | | --comparison_filter | | 同 oot | PSI 对比条件 | | --sample_strategy | | auto_weight | auto_weight / undersample / none | | --model_name | | 自动生成 | 模型名称（不含扩展名） | | --report_output | | xgb_modeling_report | 报告基名 | | --output_dir | | ./outputs/<ts> | portable 独有：产物输出目录 | | --config | | - | JSON 配置文件路径（命令行 > config > 默认） |

复杂嵌套参数（如 feature_sets）不要用命令行拼转义 JSON，改走 --config config.json 结构化通道。

执行方式

python scripts/modeling.py \
  --data_path ./examples/toy.parquet \
  --target y_label \
  --time_col busi_dt \
  --output_dir ./outputs/run1

复杂 feature_sets 通过 --config 传入：

python scripts/modeling.py \
  --data_path ./examples/toy.parquet \
  --target y_label \
  --config ./config.json \
  --output_dir ./outputs/run1

执行结束后 <output_dir>/ 下生成：

xgb_modeling_report.md — 建模报告（数据概览、方案对比、最优方案、稳定性分析…）
models/<model_name>.json — XGBoost 模型文件
models/<model_name>_meta.json — 模型元数据（特征列表等）
models/<model_name>_card.json — ModelCard
result.json — 结构化产物清单（见 PROTOCOL.md）

stdout 末行打印 result.json 绝对路径，Agent 读这个文件即可获取全部产物路径与 metrics。

产物示例（result.json）

{
  "skill": "xgb-modeling",
  "status": "success",
  "files": [
    {"path": ".../xgb_modeling_report.md", "role": "report"},
    {"path": ".../models/xgb_model_20260512_143000.json", "role": "model",
     "meta": {"feature_count": 8, "scheme_name": "去共线性", "model_type": "xgboost"}},
    {"path": ".../models/xgb_model_20260512_143000_meta.json", "role": "meta"}
  ],
  "metrics": {
    "oot_auc": 0.7823, "oot_ks": 0.4215,
    "auc_gap": 0.0214, "ks_gap": 0.0312,
    "n_features": 8, "overall_score_psi": 0.0423
  },
  "summary": "xgb-modeling 完成：最优方案「去共线性」，OOT AUC=0.7823，OOT KS=0.4215，特征数=8，Gap=0.0214"
}

跨 skill 串联

下游（如 model-explanation）通过 --model_path 传入上游 result.json 中 role=model 的文件路径：

# 从上游 result.json 提取模型路径
MODEL_PATH=$(jq -r '.files[] | select(.role=="model") | .path' ./outputs/run1/result.json)

python ../model-explanation/scripts/explain.py --model_path "$MODEL_PATH" --data_path ./examples/toy.parquet

常用场景

场景一：自动特征筛选建模

不指定特征，自动执行四大算子生成四套方案对比：

python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label

场景二：指定特征建模

使用指定的特征列表：

python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --features "feat1,feat2,feat3"

场景二-b：指定单套自动筛选方案

只跑一种筛选方案（如"去共线性"）：

python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --feature_scheme decorr

可选值：full(全量入模) / decorr(去共线性) / high_iv(高预测力) / stable(稳定性优先)

场景三：多方案对比

传入多套特征方案（优先用 --config，避免命令行拼 JSON 转义）：

{
  "feature_sets": {
    "方案A": ["f1", "f2"],
    "方案B": ["f1", "f3"]
  }
}

python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --config ./config.json

场景四：保存模型

训练完成后保存最优模型，供后续 model-explanation 使用：

python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --model_name my_best_model

模型自动保存，输出：

模型文件：<output_dir>/models/my_best_model.json
元数据文件：<output_dir>/models/my_best_model_meta.json（含特征列表、参数等）

报告结构

| 章节 | 内容 | |------|------| | 执行摘要 | 4 行业务结论：最优方案、Gap 状态、PSI 状态、头部特征风险 | | 1. 数据概览 | 样本量、正样本率（Train/Test/OOT） | | 2. 特征方案对比 | 各方案 AUC/KS/Gap 横向对比 | | 3. 最优方案详情 | AUC/KS/Gini 指标、模型分数 IV 最优分箱、Lift 表、特征重要性、BCR @ Top5/10/20/30%、Brier Score + 校准曲线 | | 4. 稳定性分析 | 按月 AUC/KS（含 95% Bootstrap 置信区间）、Mann-Kendall 趋势检验、分数 PSI | | 5. 最终模型总结 | 特征列表、综合表现 |

与其他建模 Skill 的对比

| 维度 | xgb-modeling | lr-modeling | dnn-modeling | |------|-------------|-------------|--------------| | 算法 | XGBoost | Logistic Regression + WoE | MLP (PyTorch) | | 特征处理 | 原始值直接输入 | WoE 分箱编码 | StandardScaler | | 非线性能力 | 强（树结构） | 弱（仅通过分箱引入） | 强（多层激活） | | 可解释性 | 中（需 SHAP） | 强（系数 × WoE） | 弱 | | 训练速度 | 快 | 很快 | 慢 | | 适用数据量 | 任意 | 任意 | >10k | | 评估体系 | AUC/KS/BCR/PSI | AUC/KS/BCR/PSI | AUC/KS/BCR/PSI |

上下游关系

前置：data-profiling → feature-analysis（特征筛选）
后续：xgb-tuning（调参优化）、model-explanation（SHAP 解释）
平行：与 lr-modeling / dnn-modeling 可做横向对比（同数据不同算法）

依赖

见 requirements.txt（核心：xgboost, scikit-learn, optbinning）。

注意事项

目标变量：必须为 0/1 二分类
时间切分：建议按时间切分，确保 OOT 为未来数据
自动特征筛选：需要数据同时满足 IV、PSI、缺失率条件
样本策略：强不均衡场景（正样本率 < 2%）建议 --sample_strategy undersample，一般场景用默认 auto_weight
不提供调参：需要调参请切 xgb-tuning（基于 Optuna TPE + 诊断驱动的约束搜索）
模型保存：每次训练自动保存最优模型至 <output_dir>/models/，无需传 --save_model；可用 --model_name 自定义文件名
稳定性分析：基准月份取自训练集时间段；Bootstrap CI 需样本量 >= 100 才计算
BCR/校准曲线：BCR（Bad Capture Rate）反映拒绝 Top K% 人群能捕获多少坏客户；校准曲线反映模型概率输出可信度

Module 7: XGBoost调参

XGBoost 参数调优 (portable)

XGBoost 调参的唯一入口，基于 _vendor/tuning_engine.TuningEngine。核心设计：

基线参数智能推断 — 根据数据特征推荐合理起点
模型状态诊断 — 过拟合/欠拟合判定（diagnose_model）
约束式贝叶斯搜索 — 诊断结论定向收缩 Optuna 搜索空间
用户知识融合 — 接受用户领域经验调整策略

调优流程

用户需求 → 数据特征分析 → LLM 推断基线参数 → 训练评估 → 诊断分析 → 参数调整 → 迭代直到满意
                                         ↑                                        ↓
                                         └───────────── 用户反馈/知识输入 ─────────────┘

执行模式

| 模式 | 触发条件 | 行为 | |------|---------|------| | 交互式（默认） | 用户说"调参"/"帮我调一下"/"优化一下" | 每轮暂停等待用户反馈 | | AUTO | 用户说"自动调优"/"帮我调到最优"/"一直调到收敛" | Agent 自动迭代直到收敛，每轮输出进度 |

默认模式: 交互式（更安全，用户可控）

交互式模式行为规范

单轮调优后必须暂停，输出结构化诊断报告，等待用户反馈
用户可能的反馈：
- "继续" / "再调一轮" → 执行下一轮
- "Gap 还是大" / "再保守点" → 调整策略后执行
- "可以了" / "停" → 生成最终报告
禁止在交互式模式下连续执行多轮调优

AUTO 模式行为规范

每轮调优后同样输出完整的结构化诊断报告（格式同交互式模式），然后自动进入下一轮
收敛条件：Gap < 0.03 或连续2轮提升 < 0.002
收敛后自动生成最终报告

参数说明

通用参数 spec 定义在 _vendor/xgb_cli.py（domain=tuning）。

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path / -d | ✅ | - | 数据文件路径（parquet/csv） | | --target / -t | ✅ | - | 目标变量列名（0/1 二分类） | | --features / -f | ✅ | - | 特征列表，逗号分隔 | | --time_col | | busi_dt | 时间列名 | | --train_filter | | 自动切分 | 训练集筛选条件（pandas query） | | --val_filter | | val_ratio 切出 | 验证集筛选条件（已全面替代旧 --test_filter） | | --oot_filter | | 按时间切出 | OOT 测试集条件 | | --oot_ratio / --val_ratio | | 0.20 / 0.25 | 自动切分比例 | | --random_seed | | 42 | 随机种子 | | --exclude_cols | | - | 排除列，逗号分隔 | | --params / -p | | 默认参数 | 当前参数（JSON；推荐放 --config 的 params 字段） | | --baseline / -b | | - | 基线参数（JSON；推荐放 --config 的 baseline 字段） | | --round / -r | | 0 | 当前轮次 | | --prev_val_metric | | - | 上一轮 val 指标（用于收敛判断） | | --max_rounds | | 5 | 最大调优轮数 | | --auto | | - | 启用自动调优模式（flag） | | --metric | | ks | 评估指标（auc/ks） | | --model_name | | 自动生成 | 模型名称（不含扩展名） | | --report_output / -o | | 自动生成 | 报告输出路径 | | --output_dir | | ./outputs/<ts> | portable 独有：产物输出目录 | | --warm_start | | - | WarmStartBundle JSON 字符串或文件路径 | | --config | | - | JSON 配置文件路径（由 --config 自动注入，一般无需手传） |

--params / --baseline 传复杂 JSON 时优先放 --config，避免命令行双引号转义问题。

基线参数智能推断

Agent 应根据 tuner.py 输出的数据摘要推断合理的基线参数，而非使用固定默认值。

数据摘要字段

tuner.py 会输出以下数据特征供 Agent 分析：

| 字段 | 说明 | 影响参数 | |------|------|----------| | train_samples | 训练集样本量 | max_depth, n_estimators | | oot_samples | OOT 样本量 | subsample | | n_features | 特征数量 | colsample_bytree | | pos_rate | 正样本率 | min_child_weight, scale_pos_weight |

推断规则

样本量与树深度

| 训练集样本量 | max_depth 建议 | 理由 | |----------------|------------------|------| | < 5万 | 3 | 样本少，低复杂度防过拟合 | | 5万 - 20万 | 4 | 中等样本，适中复杂度 | | 20万 - 100万 | 5 | 样本充足，可稍复杂 | | > 100万 | 5-6 | 大样本支撑更高复杂度 |

正样本率与叶节点

| 正样本率 | min_child_weight 建议 | 理由 | |----------|--------------------------|------| | < 1% | 300+ | 正样本极少，需更大叶节点防止噎声 | | 1% - 5% | 100-200 | 不平衡，适当约束 | | 5% - 20% | 50-100 | 较平衡，标准约束 | | > 20% | 20-50 | 平衡数据，可稍宽松 |

特征数与采样率

| 特征数 | colsample_bytree 建议 | 理由 | |----------|---------------------------|------| | < 20 | 0.9-1.0 | 特征少，充分利用 | | 20 - 50 | 0.7-0.9 | 中等特征，适度采样 | | > 50 | 0.5-0.7 | 特征多，增加随机性 |

推断示例

数据摘要:
  训练集: 150,000 样本
  OOT: 50,000 样本
  特征数: 35 个
  正样本率: 2.5%

Agent 推断基线参数:
  max_depth: 4        <- 样本量中等
  min_child_weight: 150  <- 正样本率低
  colsample_bytree: 0.8  <- 特征数中等
  reg_alpha: 0.3      <- 特征多，适当正则
  reg_lambda: 1.0
  learning_rate: 0.05
  n_estimators: 500
  subsample: 0.8

场景化策略

Agent 应根据用户提供的场景信息调整调参策略。

金融风控场景

特点: 模型长期使用，稳定性优先

| 参数 | 建议值 | 理由 | |------|--------|------| | max_depth | 3-4 | 低复杂度，抗过拟合 | | min_child_weight | 150+ | 叶节点要稳定 | | reg_alpha | 0.3-0.5 | 强正则化 | | reg_lambda | 1.0-2.0 | 强正则化 |

调参优先级: Gap 控制 > KS 提升

终止条件: Gap < 0.02，即使 KS 略低也接受

营销响应场景

特点: 短期使用，效果优先

| 参数 | 建议值 | 理由 | |------|--------|------| | max_depth | 4-5 | 允许较高复杂度 | | min_child_weight | 50-100 | 可以稍宽松 | | reg_alpha | 0.1-0.2 | 适中正则 |

调参优先级: KS 提升 > Gap 控制

终止条件: KS 达标，Gap < 0.05 可接受

平衡场景（默认）

特点: 兼顾效果和稳定性

| 参数 | 建议值 | |------|--------| | max_depth | 4-5 | | min_child_weight | 100 | | reg_alpha | 0.1-0.3 | | reg_lambda | 0.5-1.0 |

终止条件: KS >= 0.30 且 Gap < 0.03

执行方式

复杂参数（params/baseline）建议通过 --config JSON 文件传入：

# 自动调优（推荐：通过 config.json 传复杂参数）
python scripts/tuner.py \
  --data_path ./data.parquet --target y_label --features "f1,f2,f3" \
  --auto --max_rounds 5 --output_dir ./outputs/tuning \
  --config ./config.json

config.json 示例：

{
  "params": {"max_depth": 4, "learning_rate": 0.05, "n_estimators": 500},
  "baseline": {"max_depth": 4, "learning_rate": 0.1}
}

交互式模式（单轮调优）

python scripts/tuner.py \
  --data_path ./data.parquet --target y_label --features "f1,f2,f3" \
  --round 1 --output_dir ./outputs/tuning

AUTO 模式（自动调优循环）

python scripts/tuner.py \
  --data_path ./data.parquet --target y_label --features "f1,f2,f3" \
  --auto --max_rounds 5 --metric auc \
  --output_dir ./outputs/tuning

脚本通过单出口协议 [RESULT:{json}] 输出模型、报告、state 更新；LLM 不要复述脚本已产出的图表。

诊断知识库

模型状态诊断

| 诊断结果 | 判定条件 | 说明 | |----------|----------|------| | 过拟合 | Train-OOT Gap > 0.05 | 训练集表现远超测试集，模型记忆训练数据 | | 轻微过拟合 | Gap ∈ [0.04, 0.05] | 存在一定过拟合风险，需关注 | | 拟合良好 | Gap ∈ [0.02, 0.04] | 模型泛化能力正常 | | 欠拟合 | OOT AUC < 0.55 且 Gap < 0.02 | 模型拟合能力不足 | | 收敛 | 连续2轮提升 < 0.001 | 优化空间有限，可停止 |

过拟合信号

Train AUC 持续上升，OOT AUC 下降或停滞
Train-OOT Gap 逐轮增大
验证集效果不稳定

欠拟合信号

Train AUC 和 OOT AUC 都较低
增加训练轮数后效果持续提升
Gap 很小但整体 AUC 不足

XGBoost 参数语义

| 参数 | 作用 | 取值范围 | 过拟合时 | 欠拟合时 | |------|------|----------|----------|----------| | max_depth | 树深度，控制模型复杂度 | 2-8 | ↓ 减小 | ↑ 增大 | | min_child_weight | 叶节点最小样本权重 | 10-300 | ↑ 增大 | ↓ 减小 | | reg_alpha | L1 正则化强度 | 0-2.0 | ↑ 增大 | ↓ 减小 | | reg_lambda | L2 正则化强度 | 0.1-10 | ↑ 增大 | ↓ 减小 | | subsample | 样本采样率 | 0.5-1.0 | ↓ 减小 | ↑ 增大 | | colsample_bytree | 特征采样率 | 0.5-1.0 | ↓ 减小 | ↑ 增大 | | learning_rate | 学习率 | 0.005-0.15 | ↓ 减小 | ↑ 增大 | | n_estimators | 树数量 | 100-1000 | ↓ 减小 | ↑ 增大 |

参数调整优先级

过拟合场景（按优先级）：

增大 reg_alpha / reg_lambda（最直接）
减小 max_depth（控制复杂度）
增大 min_child_weight（限制分裂）
减小 subsample / colsample_bytree（增加随机性）

欠拟合场景（按优先级）：

增大 max_depth（增加复杂度）
增加 n_estimators（更多迭代）
减小正则化参数
适当增大 learning_rate

用户指令理解

| 用户表达 | 参数映射 | 调整幅度 | |----------|----------|----------| | "正则化大一点" | reg_alpha ↑ 或 reg_lambda ↑ | +50%~100% | | "正则化小一点" | reg_alpha ↓ 或 reg_lambda ↓ | -30%~50% | | "树深度深一点" | max_depth ↑ | +1 | | "树深度浅一点" | max_depth ↓ | -1 | | "学习率低一些" | learning_rate ↓ | -30%~50% | | "学习率高一些" | learning_rate ↑ | +30%~50% | | "多训几轮" | n_estimators ↑ | +50%~100% | | "少训几轮" | n_estimators ↓ | -30%~50% | | "防过拟合" | 综合：正则化↑, 深度↓, subsample↓ | 组合调整 | | "拟合强一点" | 综合：深度↑, 正则化↓ | 组合调整 | | "更激进一点" | learning_rate ↑, max_depth ↑ | 较大幅度 | | "更保守一点" | learning_rate ↓, 正则化↑ | 较小幅度 | | "继续自动调优" | 从当前参数启动新一轮 AUTO | - | | "就用这个" / "确认" | 结束调优，输出最终配置 | - |

调优策略

策略1：抗过拟合

适用条件：Gap > 0.05

调整方向：

reg_alpha: 当前值 × 2（如 0.1 → 0.2）
reg_lambda: 当前值 × 1.5
max_depth: 当前值 - 1（最小为 2）
min_child_weight: 当前值 × 1.5

策略2：增强拟合

适用条件：OOT AUC < 0.58 且 Gap < 0.03

调整方向：

max_depth: 当前值 + 1（最大为 8）
n_estimators: 当前值 × 1.5
reg_alpha: 当前值 × 0.5
learning_rate: 当前值 × 1.2

策略3：精细微调

适用条件：Gap ∈ [0.03, 0.05]，模型状态良好

调整方向：

learning_rate: 小幅调整 ±20%
subsample: 小幅调整 ±10%
其他参数保持不变

策略4：收敛判定

条件：连续2轮 OOT 指标提升 < 0.001

行为：停止调优，输出最终结果

策略 5：约束空间下的定向搜索

tuner.py 在 AUTO 模式下每轮调用 TuningEngine.run_round(diagnosis, tried_directions) 在诊断约束空间内跑 5 个 Optuna trial，直接取本轮最优参数进入下轮。tried_directions 会自动记录每轮参数增减方向及效果，若某个方向未改善，下一轮会自动冻结该维度。Agent 无需手动追踪，但在每轮报告中应说明"本轮诊断为 XX → 搜索空间重点是 XX"，帮助用户理解调优推演。

输出格式规范

核心原则：每轮必须完整输出 禁止只输出最终调参报告。每一轮调参完成后，不论交互式还是 AUTO 模式，必须立即输出该轮的完整诊断分析过程和结果，包括：参数变化及调整理由、训练指标详情、与上一轮的对比、诊断结论、下一步建议。用户需要看到每一轮的诊断推理过程，而非仅看到最终参数。

单轮调优输出（每轮必须使用，交互式和 AUTO 模式均适用）

每轮调优结束后，必须输出以下结构化信息：

### 第 N 轮调优结果

**参数变化**:
| 参数 | 上一轮 | 本轮 | 调整原因 |
|------|-------|------|----------|
| max_depth | 4 | 3 | 降低过拟合 |
| reg_alpha | 0.1 | 0.3 | 增强正则化 |

**效果对比**:
| 指标 | 上一轮 | 本轮 | 变化 |
|------|-------|------|------|
| OOT KS | 0.17 | 0.18 | +0.01 ✓ |
| OOT AUC | 0.72 | 0.73 | +0.01 ✓ |
| Gap (KS) | 0.06 | 0.04 | -0.02 ✓ |

**诊断结论**: 轻微过拟合（Gap 下降但仍 > 0.03）

**下一步建议**: 可继续微调正则化，或接受当前结果

最终报告（调优结束时生成，不能替代逐轮输出）

当用户确认结束或 AUTO 模式收敛时，在逐轮输出完毕后，额外生成完整汇总报告：

注意：最终报告是对逐轮输出的汇总补充，不能替代逐轮输出。即使是 AUTO 模式，也必须先逐轮输出再汇总。

# XGBoost 调参报告

## 1. 调优概览

| 项目 | 内容 |
|------|------|
| 执行模式 | 交互式 / AUTO |
| 总轮数 | 3 |
| 收敛原因 | Gap < 0.03 达标 / 用户确认停止 |

## 2. 调参推演记录

| 轮次 | 参数 (depth/eta/reg) | OOT KS | OOT AUC | Gap (KS) | 诊断 | 调整决策 |
|------|---------------------|--------|---------|----------|------|----------|
| 基线 | 4 / 0.1 / 0.1 | 0.16 | 0.71 | 0.08 | 过拟合 | 降低 depth |
| R1 | 3 / 0.1 / 0.2 | 0.17 | 0.72 | 0.05 | 轻微过拟合 | 增强正则化 |
| R2 | 3 / 0.08 / 0.5 | 0.18 | 0.73 | 0.03 | 良好 | 收敛停止 |

## 3. 最终效果

| 指标 | 基线 | 最终 | 提升 |
|------|------|------|------|
| OOT KS | 0.16 | 0.18 | +0.02 |
| OOT AUC | 0.71 | 0.73 | +0.02 |
| Gap (KS) | 0.08 | 0.03 | -0.05 |

## 4. 最终参数

```json
{
  "max_depth": 3,
  "learning_rate": 0.08,
  "reg_alpha": 0.5,
  "reg_lambda": 1.0,
  "min_child_weight": 100,
  "subsample": 0.8,
  "colsample_bytree": 0.8,
  "n_estimators": 500
}

5. 调参结论

相比基线模型，最终模型：

OOT KS 提升 0.02（0.16 → 0.18）
OOT AUC 提升 0.02（0.71 → 0.73）
Gap (KS) 降低 0.05（0.08 → 0.03）
稳定性显著改善，可安全部署

如需进一步探索，请给出您的调优建议。


---

## 与其他技能的关系

| 技能 | 职责 | 关系 |
|------|------|------|
| `xgb-modeling` | 基线建模 | 前置：需先用其训练出基线模型 |
| `model-explanation` | SHAP 解释 | 后续：调参完成后解释最优模型 |
| `model-comparison` | 多算法对比 | 平行：可与 LR/DNN 调参后做公平对比 |
| `auto-experiment` | 特征探索 | 区别：本 Skill 调参数，auto-experiment 探索特征 |

---

## 注意事项

1. **数据要求**：目标变量必须为 0/1 二分类
2. **特征要求**：需提供已筛选的特征列表（`--features` 必填）
3. **基线参数**：可传入自定义基线参数，否则使用默认值
4. **收敛判定**：连续2轮提升不足 0.001 自动停止
5. **最大轮数**：默认最多 5 轮，避免过度调优
6. **复杂 JSON**：`--params` / `--baseline` 等复杂 JSON 优先通过 `--config config.json` 传入
7. **产物位置**：模型和报告保存到 `<output_dir>/models/` 和 `<output_dir>/`


---

## Module 8: DNN深度学习建模

# DNN 深度学习建模 (portable)

基于 PyTorch 实现 MLP (Multi-Layer Perceptron) 进行二分类建模。

**核心流程**：特征标准化 → MLP 训练（BatchNorm + Dropout + Early Stopping） → 概率预测 → 三段式评估

**适用场景**：
- 高维特征交互建模
- 特征间存在复杂非线性关系
- 数据量充足（>10k 样本）
- 对模型性能有极致追求（可与 XGBoost 做 ensemble）

---

## 参数说明

| 参数 | 必选 | 默认值 | 说明 |
|------|:----:|--------|------|
| `--data_path` / `-d` | ✅ | - | 数据文件路径（parquet/csv） |
| `--target` / `-t` | ✅ | - | 目标变量列名（0/1 二分类） |
| `--time_col` | | `busi_dt` | 时间列名 |
| `--train_filter` | | 自动切分 | 训练集筛选条件（pandas query） |
| `--oot_filter` | | 按时间切出 | OOT 跨时间测试集条件 |
| `--oot_ratio` | | `0.20` | 未传 `--oot_filter` 时按时间切 OOT 的比例 |
| `--val_ratio` | | `0.25` | 从 train_full 切 val 的比例 |
| `--random_seed` | | `42` | 随机种子 |
| `--exclude_cols` | | - | 排除列，逗号分隔 |
| `--features` | | - | 指定特征列表，逗号分隔；不传则自动推断 |
| `--hidden_dims` | | `128,64,32` | 隐藏层维度，逗号分隔 |
| `--dropout` | | `0.3` | Dropout 比率 |
| `--learning_rate` | | `0.001` | 学习率 |
| `--batch_size` | | `512` | 批次大小 |
| `--epochs` | | `100` | 最大训练轮次 |
| `--patience` | | `10` | 早停耐心轮数 |
| `--weight_decay` | | `1e-4` | 权重衰减（L2 正则化） |
| `--pos_weight` | | `auto` | 正样本权重（auto=自动计算） |
| `--model_name` | | 自动生成 | 模型名称 |
| `--report_output` | | 自动生成 | 报告输出路径 |
| `--output_dir` | | `./outputs/<ts>` | 产物输出目录 |
| `--config` | | - | JSON 配置文件路径 |

---

## 执行方式

默认参数运行：

```bash
python scripts/modeling.py \
  --data_path ./data.parquet --target y_label \
  --time_col busi_dt \
  --exclude_cols "cust_code,busi_dt" \
  --output_dir ./outputs/dnn_run

自定义网络结构：

python scripts/modeling.py \
  --data_path ./data.parquet --target y_label \
  --hidden_dims "256,128,64" \
  --dropout 0.4 \
  --learning_rate 0.0005 \
  --epochs 200 \
  --output_dir ./outputs/dnn_run

常用场景

场景一：默认参数快速建模

python scripts/modeling.py --data_path ./data.parquet --target y_label --output_dir ./outputs/dnn_run

场景二：自定义网络结构

python scripts/modeling.py --data_path ./data.parquet --target y_label \
  --hidden_dims "256,128,64" --dropout 0.4 --learning_rate 0.0005 \
  --output_dir ./outputs/dnn_run

场景三：指定特征建模

python scripts/modeling.py --data_path ./data.parquet --target y_label \
  --features "feat1,feat2,feat3" --output_dir ./outputs/dnn_run

输出产物

建模报告（Markdown）— 含数据切分、网络结构、训练曲线、三段式评估指标、稳定性分析
模型文件（.pt）— PyTorch state_dict + 模型配置
训练日志（JSON）— 每 epoch 的 loss/AUC/KS 记录
result.json — 结构化产物清单

与其他建模 Skill 的对比

| 维度 | dnn-modeling | xgb-modeling | lr-modeling | |------|-------------|--------------|-------------| | 算法 | MLP (PyTorch) | XGBoost | LR + WoE | | 特征处理 | StandardScaler | 原始值 | WoE 分箱 | | 非线性能力 | 强（多层激活） | 强（树结构） | 弱 | | 可解释性 | 弱 | 中（SHAP） | 强（系数） | | 训练速度 | 慢 | 快 | 很快 | | 适用数据量 | >10k | 任意 | 任意 | | 评估体系 | AUC/KS/BCR/PSI | AUC/KS/BCR/PSI | AUC/KS/BCR/PSI |

上下游关系

前置：data-profiling → feature-analysis（特征筛选）
后续：dnn-tuning（调参优化）、model-comparison（多算法对比）
平行：与 xgb-modeling / lr-modeling 可做横向对比

注意事项

数据要求：目标变量必须为 0/1 二分类
数据量：建议训练样本 > 10k，DNN 在小样本上易过拟合
缺失值：脚本自动使用中位数填充 + 添加缺失指示列
标准化：自动对数值特征做 StandardScaler 标准化
早停：当 val loss 连续 patience 轮不下降时自动停止
不提供调参：需要调参请切 dnn-tuning（搜索网络架构 + 训练参数）
GPU：自动检测 CUDA，无 GPU 时回退到 CPU
模型保存：模型文件保存到 <output_dir>/models/

Module 9: DNN调参

DNN 深度学习参数调优 (portable)

DNN 调参的唯一入口，基于 _vendor/tuning/dnn_engine.DNNTuningEngine。

核心设计：搜索期间缩减 epochs（加速），诊断驱动动态约束搜索空间。

调优流程

基线 DNN 模型 → 诊断分析(过拟合/欠拟合) → 约束空间构造 → Optuna 搜索(30 epochs) → 最优参数 → 迭代

执行模式

| 模式 | 触发条件 | 行为 | |------|---------|------| | 交互式（默认） | 用户说"调参"/"帮我调一下DNN" | 每轮暂停等待用户反馈 | | AUTO | 用户说"自动调优"/"帮我调到最优" | Agent 自动迭代直到收敛 |

默认模式: 交互式（更安全，用户可控）

参数说明

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path / -d | ✅ | - | 数据文件路径（parquet/csv） | | --target / -t | ✅ | - | 目标变量列名（0/1 二分类） | | --features | | 自动推断 | 特征列表，逗号分隔 | | --time_col | | busi_dt | 时间列名 | | --train_filter | | 自动切分 | 训练集筛选条件 | | --val_filter | | val_ratio 切出 | 验证集筛选条件 | | --oot_filter | | 按时间切出 | OOT 条件 | | --oot_ratio | | 0.20 | OOT 占比 | | --val_ratio | | 0.25 | Val 占比 | | --random_seed | | 42 | 随机种子 | | --exclude_cols | | - | 排除列，逗号分隔 | | --n_layers | | 3 | 隐藏层数 | | --layer_width | | 128 | 首层宽度 | | --dropout | | 0.3 | Dropout 率 | | --learning_rate | | 0.001 | 学习率 | | --weight_decay | | 1e-4 | L2 正则化 | | --batch_size | | 512 | 批次大小 | | --epochs | | 100 | 完整训练 epochs | | --search_epochs | | 30 | 搜索期间 epochs（加速） | | --round / -r | | 0 | 当前轮次 | | --max_rounds | | 5 | 最大调优轮数 | | --auto | | - | 自动调优模式（flag） | | --metric | | auc | 评估指标 | | --model_name | | 自动生成 | 模型名称 | | --output_dir | | ./outputs/<ts> | 产物输出目录 | | --config | | - | JSON 配置路径 |

搜索空间

| 参数 | 类型 | 范围 | 说明 | |------|------|------|------| | n_layers | int | 2-4 | 隐藏层数 | | layer_width | int | 32-256 | 首层宽度（递减结构） | | dropout | float | 0.1-0.5 | Dropout 比率 | | learning_rate | float(log) | 1e-4 ~ 0.01 | Adam 学习率 | | weight_decay | float(log) | 1e-5 ~ 1e-3 | L2 正则化 | | batch_size | categorical | 128/256/512/1024 | 批次大小 |

诊断驱动策略

| 诊断 | dropout | weight_decay | n_layers | layer_width | |------|---------|-------------|----------|-------------| | 过拟合 | ↑ 抬高 | ↑ 增强 | ↓ 减少 | ↓ 缩小 | | 欠拟合 | ↓ 降低 | ↓ 减弱 | ↑ 增加 | ↑ 增大 | | 拟合良好 | ±微调 | ±微调 | ±微调 | ±微调 |

执行方式

交互式模式（单轮调优）

python scripts/tuner.py \
  --data_path ./data.parquet --target y_label \
  --round 1 --output_dir ./outputs/dnn_tuning

AUTO 模式（自动调优循环）

python scripts/tuner.py \
  --data_path ./data.parquet --target y_label \
  --auto --max_rounds 5 --output_dir ./outputs/dnn_tuning

调优策略

策略1：抗过拟合

适用条件：Train-Val Gap > 0.05

调整方向：

dropout: 当前值 + 0.1（上限 0.5）
weight_decay: 当前值 × 2
n_layers: 当前值 - 1（最小为 2）
layer_width: 当前值 - 32（最小为 32）

策略2：增强拟合

适用条件：Val AUC < 0.58 且 Gap < 0.03

调整方向：

n_layers: 当前值 + 1（最大为 4）
layer_width: 当前值 + 32（最大为 256）
weight_decay: 当前值 × 0.5
learning_rate: 当前值 × 1.2

策略3：精细微调

适用条件：Gap ∈ [0.03, 0.05]，模型状态良好

调整方向：

learning_rate: 小幅调整 ±20%
dropout: 小幅调整 ±0.05
其他参数保持不变

策略4：收敛判定

条件：连续2轮 Val 指标提升 < 0.001

行为：停止调优，输出最终结果

输出格式规范

与 xgb-tuning 保持一致的逐轮诊断报告格式。

每轮调优结束后，必须输出以下结构化信息：

### 第 N 轮 DNN 调优结果

**参数变化**:
| 参数 | 上一轮 | 本轮 | 调整原因 |
|------|-------|------|----------|
| n_layers | 3 | 3 | 不变 |
| layer_width | 128 | 96 | 降低过拟合 |
| dropout | 0.3 | 0.4 | 增强正则化 |

**效果对比**:
| 指标 | 上一轮 | 本轮 | 变化 |
|------|-------|------|------|
| Val AUC | 0.72 | 0.73 | +0.01 ✓ |
| OOT AUC | 0.70 | 0.71 | +0.01 ✓ |
| Gap | 0.06 | 0.04 | -0.02 ✓ |

**诊断结论**: 轻微过拟合（Gap 下降但仍 > 0.03）

**下一步建议**: 可继续微调 dropout，或接受当前结果

与其他技能的关系

| 技能 | 职责 | 关系 | |------|------|------| | dnn-modeling | 基线建模 | 前置：需先用其训练出基线模型 | | model-comparison | 多算法对比 | 后续：可与 XGB/LR 做公平对比 | | xgb-tuning | XGBoost 调参 | 平行：同数据不同算法的调参 |

注意事项

数据要求：目标变量必须为 0/1 二分类
搜索加速：搜索期间使用 search_epochs=30，最终模型使用 epochs=100
收敛判定：连续2轮提升不足 0.001 自动停止
最大轮数：默认最多 5 轮
产物位置：模型和报告保存到 <output_dir>/models/ 和 <output_dir>/

Module 10: 多模型效果对比

多模型效果对比 (portable)

基于同一份数据切分，横向运行多种算法，统一评估并生成客观事实报告。

设计原则（v3 重要变更）：

只陈述事实，不做主观推荐：删除了旧版的"五维加权综合评分"与"门禁淘汰"。主观权重本质上将多个不可比指标压成一个数，丢失信息并引入拍脑袋假设；门禁阈值则不同业务差异巨大。
Pareto 前沿（无主观权重）：在 OOT AUC / OOT KS / BCR@10% / KS Gap / PSI 五个方向明确的目标上，识别未被任何算法严格优于的候选集。
LLM 推理接手：报告末尾提供「已知事实清单 + 开放问题」，交由对话中的 AI 结合业务背景推理取舍。
同数据同切分 → 消除数据差异对对比结论的干扰
多维指标原始陈述 → OOT AUC/KS/BCR/Brier + KS Gap + PSI + 特征数 + 可解释性
统计显著性 → DeLong 检验回答"差距是真的还是采样噪声"

推荐工作流：先调参再对比

"哪个算法好"这个问题只有在三个算法都调优后对比才公平。默认超参下对比只能作为初筛。推荐三步调用：

1. xgb-tuning  → 产出 xgb_tuning_best_*_meta.json
2. lr-tuning   → 产出 lr_tuning_best_*_meta.json
3. dnn-tuning  → 产出 dnn_tuning_best_*_meta.json
4. model-comparison --use_tuned   → 自动扫描上述产物使用最优超参跑对比

参数说明

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path / -d | ✅ | - | 数据文件路径（parquet/csv） | | --target / -t | ✅ | - | 目标变量列名（0/1 二分类） | | --time_col | | busi_dt | 时间列（用于 OOT 切分与分月表现） | | --train_filter | | 自动切分 | 训练集筛选条件 | | --oot_filter | | 按时间切出 | OOT 测试集条件 | | --oot_ratio | | 0.20 | OOT 占比 | | --val_ratio | | 0.25 | Val 占比 | | --random_seed | | 42 | 随机种子 | | --exclude_cols | | - | 排除列，逗号分隔 | | --features | | - | 指定特征，逗号分隔；不传则自动推断 | | --algorithms | | xgb,lr,dnn | 对比算法列表，逗号分隔 | | --scenario | | general | general / scorecard / fraud / stability_first | | --use_tuned | flag | 关 | 自动扫描 models 目录加载最新调参最优参数 | | --tuned_params_file | | - | 显式指定 {"xgb":{},"lr":{},"dnn":{}} JSON | | --config | | - | 手工覆盖各算法超参的 JSON（优先级高于 tuned） | | --model_name | | 自动生成 | 产物名称前缀 | | --output_dir | | ./outputs/<ts> | 产物输出目录 |

场景预设（`--scenario`）

场景仅作为业务上下文标签，供 LLM 推理时使用；不再参与加权评分、不做门禁淘汰。

| 场景 | 描述 | |------|------| | general | 通用；首次对比探索 | | scorecard | 评分卡 / 白盒合规；LR + WoE 天然占优 | | fraud | 反欺诈 / 高风险；关注 OOT KS / BCR | | stability_first | 存量运维；重点关注 PSI 与分月 KS |

执行方式

默认三算法 + 通用场景：

python scripts/comparison.py \
  --data_path ./data.parquet --target y_label \
  --exclude_cols "cust_code,busi_dt" \
  --output_dir ./outputs/compare

评分卡场景（只跑 XGB + LR）：

python scripts/comparison.py \
  --data_path ./data.parquet --target y_label \
  --algorithms "xgb,lr" --scenario scorecard \
  --output_dir ./outputs/compare

使用历史调参最优参数：

python scripts/comparison.py \
  --data_path ./data.parquet --target y_label \
  --use_tuned --scenario fraud \
  --output_dir ./outputs/compare

对比维度（原始指标，不做加权）

| 维度 | 字段 | 说明 | |------|------|------| | 效果 | OOT AUC / KS / Gini / BCR@10% / Precision@10% / Recall@10% / Brier / LogLoss | 全量原始指标陈列 | | 泛化 | KS Gap = Train KS - OOT KS | 越小越好；>0.10 标记过拟合风险 | | 稳定 | PSI（OOT vs Train 分数分布）+ 分月 KS 波动 σ | 越小越稳；≥0.25 标记显著漂移 | | 可解释 | LR 强 / XGB 中 / DNN 弱 | 仅作文本标签，不参与计算 | | 简洁 | 入模特征数 | 仅作参考 |

统计显著性（DeLong 检验）

两两算法 AUC 差异通过 Fast-DeLong 做渐近正态检验（O(N log N)，10w+ 样本也秒级完成）：

p < 0.05 → 差距统计显著
p ≥ 0.05 → 差距可能是采样波动

输出产物

对比报告（Markdown，倒金字塔结构）：
- 执行摘要（客观指标速览 + Pareto 前沿标记，无推荐列）
- 多算法叠加曲线（ROC/KS/Lift）
- 数据概览
- 详细指标总表（train/val/oot × 8 指标）
- Pareto 前沿候选集（无主观权重）
- DeLong 显著性检验
- 稳定性（真实 PSI + 分月 KS）
- 样本级一致性（Top-K Jaccard / Spearman / 分歧数）
- 跨算法特征重叠（Jaccard + 共识特征）
- 每算法独立评估图
- LLM 推理引导：事实清单 + 开放问题，交由对话中的 AI 推理取舍
- 各算法适用场景背景知识
各模型文件：XGB(.json) / LR(.joblib) / DNN(.pt，含 imputer+scaler 元数据)

与其他技能的关系

| 技能 | 职责 | 关系 | |------|------|------| | xgb-tuning / lr-tuning / dnn-tuning | 调参优化 | 前置：公平对比前需先调参 | | xgb-modeling / lr-modeling / dnn-modeling | 基线建模 | 被复用训练对比模型 | | model-explanation | 模型解释 | 后续：对比完成后解释最优模型 |

注意事项

公平对比："哪个算法好"只有在三个算法都调优后对比才公平
同数据同切分：本技能确保所有算法使用完全相同的数据切分
DeLong 检验：p < 0.05 才认为差距统计显著
Pareto 前沿：只识别未被任何算法严格优于的候选集，不做主观排序
场景标签：--scenario 仅作文本标签，不参与加权评分
产物位置：模型和报告保存到 <output_dir>/

Module 11: 模型解释

模型解释报告 (portable)

基于 SHAP (SHapley Additive exPlanations) 对 XGBoost 模型进行可解释性分析，生成包含可视化图表的 Markdown 报告。

参数说明

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --model_path | ✅ | - | XGBoost 模型文件路径 (.json) | | --data_path | ✅ | - | 数据文件路径（parquet/csv） | | --target | ✅ | - | 目标变量列名 | | --features | | auto | 特征列表，逗号分隔。不传时从 <model>_meta.json 自动读取 | | --sample_id | | - | 单样本解释：样本索引或ID | | --sample_filter | | - | 单样本解释：pandas query 条件 | | --top_n | | 20 | 全局解释显示 Top N 特征 | | --interaction_features | | - | 交互分析特征对，如 f1,f2 | | --output_dir | | ./outputs/<ts> | 产物输出目录 | | --output_name | | model_explanation_report | 报告基名 | | --config | | - | JSON 配置文件路径 |

执行方式

python scripts/explainer.py \
  --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet \
  --target y_label \
  --output_dir ./outputs/explain_run

单样本解释：

python scripts/explainer.py \
  --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet \
  --target y_label \
  --sample_id 1001 \
  --output_dir ./outputs/explain_run

特征交互分析：

python scripts/explainer.py \
  --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet \
  --target y_label \
  --interaction_features "age,income" \
  --output_dir ./outputs/explain_run

常用场景

场景一：全局特征重要性分析

解释模型整体决策逻辑：

python scripts/explainer.py --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet --target y_label \
  --output_dir ./outputs/explain_run

输出：

SHAP Summary Plot（特征重要性排序）
SHAP Bar Plot（平均绝对 SHAP 值）
特征重要性表格

场景二：单样本预测解释

解释特定样本的预测原因：

python scripts/explainer.py --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet --target y_label \
  --sample_id 1001 --output_dir ./outputs/explain_run

输出：

SHAP Force Plot（推动预测的正负特征）
瀑布图（特征贡献分解）
该样本特征值与分布对比

场景三：特征交互分析

分析两个特征的交互效应：

python scripts/explainer.py --model_path ./models/my_model.json \
  --data_path ./examples/toy.parquet --target y_label \
  --interaction_features "age,income" --output_dir ./outputs/explain_run

输出：

SHAP Dependence Plot（特征值 vs SHAP 值）
交互热力图

跨 skill 串联（推荐流程）

xgb-modeling 产物的 result.json 中 role=model 的 path 可直接喂给 model-explanation：

# 1) 训练
python ../xgb-modeling/scripts/modeling.py \
  --data_path ./examples/toy.parquet --target y_label \
  --exclude_cols "cust_code" --output_dir ./outputs/mdl

# 2) 从 result.json 提模型路径
MODEL=$(jq -r '.files[] | select(.role=="model") | .path' ./outputs/mdl/result.json)

# 3) 解释（特征自动从 <model>_meta.json 读取）
python scripts/explainer.py \
  --model_path "$MODEL" \
  --data_path ./examples/toy.parquet --target y_label \
  --output_dir ./outputs/xpl

特征列表来源

--features "f1,f2,..." 显式传入
config.json 中 "features": [...]
自动发现 <model>_meta.json（xgb-modeling 产物自带）

报告输出结构

生成的 model_explanation_report.md 包含以下章节：

| 章节 | 内容 | |------|------| | 1. 模型概览 | 模型路径、特征数量、样本规模 | | 2. 全局特征解释 | SHAP Summary Plot、Top N 特征重要性表 | | 3. 单样本解释 | Force Plot、瀑布图、特征值对比（如指定样本） | | 4. 特征交互分析 | Dependence Plot、交互效应说明（如指定） | | 5. 可视化附件 | 生成的 PNG 图表文件列表 |

产物目录

<output_dir>/
├── model_explanation_report.md
└── assets/
    ├── shap_summary.png
    ├── shap_bar.png
    ├── force_plot_sample_1001.png
    └── dependence_age_income.png

与其他技能的关系

| 技能 | 职责 | 关系 | |------|------|------| | xgb-modeling | 训练模型 | 前置：需先用其训练并保存模型 | | model-comparison | 多算法对比 | 后续：可与 LR/DNN 模型做对比解释 | | feature-analysis | 特征分析 | 区别：feature-analysis 分析建模前特征质量 |

依赖

shap、matplotlib（图表）
xgboost、pandas、numpy

注意事项

模型格式：仅支持 XGBoost JSON 格式模型文件
数据一致性：--data_path 需与训练时使用的数据字段一致
样本定位：--sample_id 为数据框的整数索引，非业务ID
内存占用：大数据集的全局 SHAP 计算可能耗时较长
图表依赖：需要 matplotlib 和 shap 库支持
base_score 兼容：XGBoost >= 1.7 的 base_score 为数组，脚本会自动修复为标量以兼容 SHAP

Module 12: 自主实验循环

自主实验循环 (portable)

自动发现数据中的特征分组，执行四阶段渐进式探索实验，每轮完整展示探索逻辑和量化结果。

核心理念

借鉴 autoresearch 的自主循环思想，升级为组级探索：

发现特征组 → 组独立评估 → 组间叠加 → 组级消融 → 精细筛选

四阶段探索流程

Phase 1: 特征组独立评估

自动发现数据中的特征分组（按前缀聚合: firefly_*, mob3_*, umeng_* 等）
逐组单独建模，评估每组的独立预测能力
输出各组的独立 AUC/KS 排名

Phase 2: 组间增量叠加

从 Phase 1 表现最佳的组开始
逐步叠加下一个最强组，观察边际增量
找到最优组合点

Phase 3: 组级消融分析

从全量特征出发，逐组移除
量化每个组的不可替代性
如果移除后指标不降，说明该组信息已被其他组覆盖

Phase 4: 组内精细筛选

在最优组合内，逐个尝试移除特征
剔除冗余特征，精简模型

参数说明

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path | ✅ | - | 数据文件路径（parquet/csv） | | --target | ✅ | - | 目标变量列名（0/1 二分类） | | --exploration | ✅ | - | 探索方向描述，如 "不同特征组对mob3逾期的贡献" | | --max_rounds | | 5 | 最大实验轮数 | | --metric | | ks | 优化指标（auc/ks） | | --direction | | maximize | 优化方向（maximize/minimize） | | --significance | | 2.0 | 显著性阈值（MAD倍数） | | --baseline_features | | - | 基线特征列表，JSON格式（默认使用全量特征） | | --time_col | | busi_dt | 时间列名 | | --train_filter | | - | 训练集筛选条件 | | --val_filter | | - | 验证集筛选条件 | | --test_filter | | - | [Deprecated] 等价 --val_filter，仅作向后兼容 | | --oot_filter | | - | OOT测试集条件 | | --val_ratio | | 0.25 | val 在 train_full 内占比 | | --oot_ratio | | 0.20 | OOT 在全量内占比 | | --output_dir | | ./outputs/<ts> | 产物输出目录 | | --config | | - | JSON 配置文件 |

执行方式

python scripts/run_experiment.py \
  --data_path ./data.parquet --target y_label \
  --exploration "不同特征组(firefly/子模型/友盟)对mob3逾期的贡献" \
  --max_rounds 10 \
  --output_dir ./outputs/exp

常用场景

场景一：探索各特征组贡献

python scripts/run_experiment.py \
  --data_path ./data.parquet --target y_label \
  --exploration "不同特征组(firefly模型/子模型/友盟数据)对mob3逾期预测的贡献" \
  --max_rounds 10 --output_dir ./outputs/exp

场景二：探索特定时间窗口特征

python scripts/run_experiment.py \
  --data_path ./data.parquet --target y_label \
  --exploration "mob3相关的逾期、还款特征" \
  --max_rounds 8 --output_dir ./outputs/exp

场景三：在已有基线上探索新组

python scripts/run_experiment.py \
  --data_path ./data.parquet --target y_label \
  --baseline_features '["feat1","feat2","feat3"]' \
  --exploration "添加mob6时间窗口特征组" \
  --max_rounds 5 --output_dir ./outputs/exp

输出内容

核心原则：每轮必须完整输出探索逻辑和结果 禁止只输出最终汇总。每一轮实验完成后，必须立即输出：探索策略、推理逻辑、假设描述、新增/移除特征、训练指标详情、与基线的对比、显著性检验、决策理由。

数据概览（实验开始前）

数据规模、特征数、正样本率
自动发现的特征分组及其统计

单轮输出格式（每轮必须使用）

### Round N/总轮数

**Phase X: 探索策略名称**

**探索逻辑**:
[Phase 1/3/5] 特征组独立评估
目标: 单独测试「firefly」组的 12 个特征
逻辑: 先让每个特征组独立上场，获得各组的独立贡献排名

**本轮假设**: 独立评估特征组「firefly」(12个特征)

**模型评估** (共 12 个特征):
| 指标 | Train | Test | 基线Test | 变化 |
|------|-------|------|----------|------|
| AUC | 0.812 | 0.735 | 0.726 | +0.009 |

**Top-5 特征重要性**:
| # | 特征 | 重要性 |
|---|------|--------|
| 1 | firefly_score [NEW] | 0.2341 |

**显著性检验**: [PASS] 2.3x MAD → 改进显著
**决策**: [+] KEEP - 改进显著

最终汇总（所有轮次后输出）

实验总览表（Round/阶段/假设/指标/决策）
最终 vs 基线对比
保留和丢弃的特征组/特征列表
下一步建议

统计显著性检验

使用 MAD (Median Absolute Deviation) 判断改进是否显著：

| 置信度 | 标记 | 含义 | |--------|------|------| | ≥ 2.0× | [PASS] | 改进可能是真实的 | | 1.0-2.0× | [EDGE] | 高于噪声但边缘 | | < 1.0× | [FAIL] | 在噪声范围内 |

与其他技能的关系

| 技能 | 职责 | 关系 | |------|------|------| | xgb-modeling | 单次训练和评估 | 被本技能复用 | | xgb-tuning | 超参调优 | 可在循环后使用 | | feature-analysis | 特征分析 | 辅助假设生成 |

注意事项

探索方向：可以是宽泛的（如"探索各特征组贡献"），系统会自动发现分组
轮数建议：设置为特征组数的2-3倍（如6个组建议10-15轮），以覆盖多个探索阶段
基线策略：默认使用全量特征作为基线，也可指定特定特征集
显著性阈值：默认2.0×，数据量小时可适当降低
可打断：用户可随时停止，已有结果会保留
产物位置：报告和模型保存到 <output_dir>/

Module 13: 分群建模

分群自主探索 (portable)

在用户指定或 AI 自主发现的分群策略下，拆分客群训练子模型，自动探索最优分群方案。

核心理念：

探索空间（策略 × 参数 × 组合）
        │
        ▼
Try → Measure → Keep/Discard → Repeat
        │
        ▼
    最优分群方案 + 子模型

三种分群策略

| 策略 | 说明 | 适用场景 | |------|------|---------| | 规则分群 | 用户指定规则（如 age < 30） | 有业务先验知识 | | 聚类分群 | K-Means 等无监督自动发现 | 探索数据内在结构 | | 决策树分群 | 有监督找最优分割点 | 直接优化目标变量 |

参数说明

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path | ✅ | - | 数据文件路径（parquet/csv） | | --target | ✅ | - | 目标变量列名（0/1 二分类） | | --mode | | auto | 模式: auto(自主探索) / manual(指定策略) | | --max_rounds | | 5 | 自主探索最大轮数 | | --segment_rules | | - | 规则分群，JSON格式 | | --segment_col | | - | 直接指定分群列名 | | --n_clusters | | 3 | 聚类分群数 | | --tree_depth | | 2 | 决策树分群深度 | | --tree_features | | - | 决策树使用的特征，逗号分隔 | | --min_segment_ratio | | 0.05 | 最小分群占比（<5%会警告） | | --merge_strategy | | route | 汇总策略: route / stacking | | --metric | | ks | 优化指标（auc/ks） | | --significance | | 2.0 | 显著性阈值（MAD倍数） | | --time_col | | busi_dt | 时间列名 | | --train_filter | | - | 训练集筛选条件 | | --val_filter | | - | 验证集筛选条件 | | --output_dir | | ./outputs/<ts> | 产物输出目录 | | --config | | - | JSON 配置文件 |

执行方式

自主探索最优分群

python scripts/run_segment.py \
  --data_path ./data.parquet --target y_label \
  --mode auto --max_rounds 5 \
  --output_dir ./outputs/seg

用户规则分群

python scripts/run_segment.py \
  --data_path ./data.parquet --target y_label \
  --mode manual \
  --segment_rules '{"年轻": "age < 30", "中年": "age >= 30 and age < 50", "高龄": "age >= 50"}' \
  --output_dir ./outputs/seg

聚类自动分群

python scripts/run_segment.py \
  --data_path ./data.parquet --target y_label \
  --mode manual --n_clusters 4 \
  --output_dir ./outputs/seg

决策树分群

python scripts/run_segment.py \
  --data_path ./data.parquet --target y_label \
  --mode manual \
  --tree_depth 3 --tree_features "age,income,credit_score" \
  --output_dir ./outputs/seg

输出内容

实时进度（流式输出）

━━━ Round 1/5: 基线（不分群）━━━
单一模型 AUC: 0.742

━━━ Round 2/5: 用户规则分群 ━━━
规则: age < 30 | 30-50 | > 50
分群样本: [12,340 | 18,560 | 14,288]
子模型 AUC: [0.71 | 0.75 | 0.78]
汇总 AUC: 0.758 (+2.2%)
决策: ✅ KEEP

━━━ Round 3/5: 决策树分群 (depth=2) ━━━
自动分割: income < 5000 → ...
汇总 AUC: 0.772 (+1.8%)
决策: ✅ KEEP (新最佳!)

最终报告

最优分群方案详情
各策略对比表
子模型列表及指标
vs 基线提升幅度
分群稳定性分析（PSI）

评估标准

| 指标 | 说明 | 阈值 | |------|------|------| | 整体 AUC | 分群模型汇总后效果 | 越高越好 | | vs 基线 | 相比不分群的提升 | > 0 | | 分群稳定性 | OOT分群比例变化 | PSI < 0.1 | | 最小覆盖率 | 最小群占比 | > 5% |

与其他技能的关系

| 技能 | 职责 | 关系 | |------|------|------| | xgb-modeling | 单模型训练 | 被复用训练子模型 | | auto-experiment | 特征探索 | 可在分群后对各群独立优化 | | feature-analysis | 特征分析 | 辅助选择分群特征 |

注意事项

分群数量：建议 2-5 群，太多易过拟合
最小样本量：每群建议 > 5% 总样本
稳定性：关注 OOT 分群比例是否稳定
业务可解释：决策树分群规则更易解释
组合使用：可先分群再对各群做特征探索

Module 14: DeepModel深度集成

XGBoost DeepModel — 分群集成建模 (portable)

分群训练多个 XGBoost 子模型，通过 OOF Stacking 融合成主模型，评估集成收益。

阶段1：训练分群子模型

参数说明

参数 spec：_vendor/xgb_cli.py 中 domain=deepmodel-sub。复杂嵌套 JSON（segments / features_per_segment / pos_weight_per_segment）必须走 --config。

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path / -d | ✅ | - | 数据文件路径 | | --target / -t | ✅ | - | 目标变量列名 | | --segments | ✅* | - | 分群条件 JSON（推荐通过 --config 的 segments 字段） | | --segment_col | ✅* | - | 按列唯一值自动分群（与 segments 二选一） | | --time_col | | busi_dt | 时间列名 | | --train_filter | | 自动切分 | 全局训练集筛选条件 | | --val_filter | | val_ratio 切出 | 全局验证集筛选条件 | | --oot_filter | | 按时间切出 | OOT 测试集条件 | | --exclude_cols | | - | 排除列，逗号分隔 | | --features | | 自动筛选 | 全局特征列表，逗号分隔 | | --features_per_segment | | - | 分群差异化特征 JSON（走 --config） | | --sample_weight_col | | - | 样本权重列名 | | --pos_weight_per_segment | | - | 各分群正样本权重 JSON（走 --config） | | --auto | | false | flag。对 OOT Gap > 0.05 的分群自动调参 | | --output_dir | | ./outputs/<ts> | 子模型保存目录 | | --config | | - | JSON 配置路径 |

执行方式

python scripts/sub_trainer.py \
  --data_path ./data.parquet --target y_label \
  --time_col busi_dt --exclude_cols "cust_code,busi_dt" \
  --auto --output_dir ./outputs/deepmodel

配合 --config 传入结构化 JSON：

{
  "segments": {"高风险": "risk_score > 500", "低风险": "risk_score <= 500"},
  "pos_weight_per_segment": {"高风险": 2.0, "低风险": 1.0}
}

python scripts/sub_trainer.py \
  --data_path ./data.parquet --target y_label \
  --auto --config ./config.json --output_dir ./outputs/deepmodel

输出

每个分群的模型文件：{output_dir}/{segment_name}.json
Markdown 报告：各分群 Train/Val/OOT AUC/KS/Gap 对比表、质量门控检查结果

阶段2：Stacking 融合

参数说明

参数 spec：domain=deepmodel-stack。submodel_paths / segments 等结构化 JSON 走 --config。

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path / -d | ✅ | - | 数据文件路径 | | --target / -t | ✅ | - | 目标变量列名 | | --submodel_paths | ✅ | - | 子模型路径 JSON 列表（走 --config） | | --segments | ✅* | - | 与 sub_trainer 一致的分群条件 | | --segment_col | ✅* | - | 与 sub_trainer 一致的分群列 | | --time_col | | busi_dt | 时间列名 | | --train_filter | | 自动切分 | 训练集条件（与 sub_trainer 一致） | | --val_filter | | val_ratio 切出 | 验证集条件 | | --oot_filter | | 按时间切出 | OOT 条件 | | --cv_folds | | 5 | OOF 交叉验证折数 | | --output_dir | | ./outputs/<ts> | Meta-learner 保存目录 | | --config | | - | JSON 配置路径 |

执行方式

python scripts/stacker.py \
  --data_path ./data.parquet --target y_label \
  --cv_folds 5 --output_dir ./outputs/deepmodel

配合 --config：

{
  "submodel_paths": ["./outputs/deepmodel/高风险.json", "./outputs/deepmodel/低风险.json"],
  "segments": {"高风险": "risk_score > 500", "低风险": "risk_score <= 500"}
}

python scripts/stacker.py \
  --data_path ./data.parquet --target y_label \
  --config ./config.json --output_dir ./outputs/deepmodel

输出

Meta-learner 模型文件：{output_dir}/stack_meta.json
OOF 预测分分布图（各子模型 OOF AUC vs Meta-learner）

阶段3：集成对比报告

参数说明

参数 spec：domain=deepmodel-compare。

| 参数 | 必选 | 默认值 | 说明 | |------|:----:|--------|------| | --data_path / -d | ✅ | - | 数据文件路径 | | --target / -t | ✅ | - | 目标变量列名 | | --stack_model_path | | - | Stacking 模型路径（可选） | | --submodel_paths | ✅ | - | 子模型路径 JSON 列表（走 --config） | | --segments | ✅* | - | 分群条件 | | --segment_col | ✅* | - | 分群列 | | --time_col | | busi_dt | 时间列名 | | --train_filter | | 自动切分 | 训练集条件 | | --val_filter | | val_ratio 切出 | 验证集条件 | | --oot_filter | | 按时间切出 | OOT 条件 | | --baseline_model_path | | - | 单模型基线路径（不传则自动训练一个全量基线） | | --extra_baseline_algos | | - | 额外单模型基线算法，逗号分隔（可选值：lr,dnn） | | --output_dir | | ./outputs/<ts> | 产物保存目录 | | --config | | - | JSON 配置路径 |

执行方式

python scripts/comparator.py \
  --data_path ./data.parquet --target y_label \
  --stack_model_path ./outputs/deepmodel/stack_meta.json \
  --output_dir ./outputs/deepmodel

配合 --config：

{
  "submodel_paths": ["./outputs/deepmodel/高风险.json", "./outputs/deepmodel/低风险.json"],
  "segments": {"高风险": "risk_score > 500", "低风险": "risk_score <= 500"}
}

python scripts/comparator.py \
  --data_path ./data.parquet --target y_label \
  --stack_model_path ./outputs/deepmodel/stack_meta.json \
  --config ./config.json --output_dir ./outputs/deepmodel

输出

对比表：单模型 XGB 基线 / （可选 LR 基线 / DNN 基线）/ 最优子模型 / Stacking 集成（Train/Val/OOT AUC/KS/Gap）
每个分群在各模型下的 OOT KS 对比
最终推荐：是否 Stacking / 最优子模型 / 基线

提示：如需严格的多算法公平对比（含调参），请切换回 Agent 模式调用 xgb-tuning → lr-tuning → dnn-tuning → model-comparison --use_tuned。本技能的 --extra_baseline_algos 仅走默认超参，定位为"低成本初筛对照"。

完整工作流示例

# 阶段1：训练分群子模型
python scripts/sub_trainer.py \
  --data_path ./data.parquet --target y_label \
  --config ./config.json --auto --output_dir ./outputs/deepmodel

# 阶段2：Stacking 融合
python scripts/stacker.py \
  --data_path ./data.parquet --target y_label \
  --config ./config.json --output_dir ./outputs/deepmodel

# 阶段3：集成对比报告
python scripts/comparator.py \
  --data_path ./data.parquet --target y_label \
  --stack_model_path ./outputs/deepmodel/stack_meta.json \
  --config ./config.json --output_dir ./outputs/deepmodel

质量门控标准

| 检查项 | 标准 | 不达标处理 | |--------|------|-----------| | 各分群样本量 | ≥ 500 | 建议合并该分群 | | 各分群 OOT Gap | < 0.05 | 启用 --auto | | Stacking OOT AUC | ≥ max(子模型 OOT AUC) - 0.01 | 说明集成无明显增益 | | 集成 vs 基线 OOT AUC | 集成更高 | 建议放弃集成，用最优子模型或基线 |

与其他技能的关系

| 技能 | 职责 | 关系 | |------|------|------| | xgb-modeling | 单模型训练 | 被复用训练子模型和基线 | | segment-modeling | 分群策略探索 | 区别：segment-modeling 探索最优分群，本 Skill 按指定分群做 Stacking | | model-comparison | 多算法公平对比 | 后续：严格对比请用 model-comparison（含调参） |

注意事项

分群互斥：各分群条件应互斥（一个样本只属于一个分群），否则 Stacking 会有信息泄漏
样本量：每个分群的训练样本应 ≥ 500，过少的分群建议合并
OOF 生成：Stacking 的 OOF 预测在各分群内独立做 k-fold，保证无标签泄漏
Meta-learner：固定使用保守参数（max_depth=2），不做超参搜索，避免过拟合
子模型路径传递：stacker 和 comparator 支持从 --config 读取子模型路径
三阶段顺序：必须先 sub_trainer → stacker → comparator，阶段间通过文件系统传递产物

Disclaimer / 免责声明

⚠️ 重要声明

本技能提供参考框架和分析建议，不构成任何形式的投资建议、法律意见或专业判断

所有分析结果仅供参考，最终决策须由具备相应资质的专业人员作出

用户应结合实际情况独立判断

financial-engineer-digital-employee

Financial Engineer Digital Employee / 金融工程专家数字员工

Skill Overview / 技能概览

Module 1: 数据轮廓速览

数据洞察报告 (portable)

参数说明

执行方式

产物示例

报告输出结构

自适应展示

与其他 Skill 的关系

注意事项

Module 2: 单变量分析

单变量分析 (portable)

功能定位

参数说明

执行方式

数据探索模式（无目标变量）

特征筛选模式（有目标变量）

交叉分布分析

常用场景

场景一：数据探索（无目标变量）

场景二：交叉分布分析

场景三：特征筛选（有目标变量）

报告输出结构

数据探索模式（无目标变量）

特征筛选模式（有目标变量）

分箱说明

等频分箱（quantile）

等距分箱（distance）

特殊值处理

输出示例

分布分析表

交叉分布表

IV 分箱明细表（有目标变量）

与 feature-analysis 的关系

注意事项

Module 3: 特征深度分析

建模特征分析报告 (portable)

参数说明

执行方式

常用场景

场景一：基础分析（不含 PSI）

场景二：完整分析（含 PSI）

场景三：单变量深度分析

报告输出结构

特征筛选方案说明

与其他 Skill 的关系

注意事项

Module 4: LR评分卡建模

LR 评分卡建模 (portable)

参数说明

执行方式

常用场景

场景一：默认参数快速建模

场景二：指定特征建模

场景三：自定义评分卡参数

输出产物

与其他建模 Skill 的对比

上下游关系

注意事项

Module 5: LR评分卡调参

LR 评分卡参数调优 (portable)

调优流程

执行模式

参数说明

搜索空间

诊断驱动策略

执行方式

交互式模式（单轮）

AUTO 模式

调优策略

策略1：抗过拟合

策略2：增强拟合

策略3：精细微调

策略4：收敛判定

输出格式规范

与其他技能的关系

注意事项

Module 6: XGBoost建模