Financial Engineer Digital Employee

覆盖数据探查、单变量分析、特征工程、LR评分卡、XGBoost/DNN建模、超参数调优、模型解释、多模型对比、分群建模、DeepModel集成全流程。从数据到模型上线的一站式机器学习建模能力。

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项核心能力模块：

1. Module 1: 数据轮廓速览
2. Module 2: 单变量分析
3. Module 3: 特征深度分析
4. Module 4: LR评分卡建模
5. Module 5: LR评分卡调参
6. Module 6: XGBoost建模
7. Module 7: XGBoost调参
8. Module 8: DNN深度学习建模
9. Module 9: DNN调参
10. Module 10: 多模型效果对比
11. Module 11: 模型解释
12. Module 12: 自主实验循环
13. Module 13: 分群建模
14. 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	建模全流程，需要目标变量

建议流程：

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

---

注意事项

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

---

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（深度分析）

---

注意事项

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

---

注意事项

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

---

输出产物

1. 建模报告（Markdown）— 含数据切分、WoE分箱表、LR系数表、评分卡转换表、三段式评估指标、稳定性分析
2. 模型文件（joblib）— LR 模型 + WoE 编码器序列化
3. 评分卡表（JSON）— 可直接用于部署的分箱-分数映射
4. 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 可做横向对比（同数据不同算法）

---

注意事项

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

---

注意事项

1. 数据要求：目标变量必须为 0/1 二分类
2. 联合搜索：WoE 分箱与 LR 参数联合优化，确保最优组合
3. 收敛判定：连续2轮提升不足 0.001 自动停止
4. 最大轮数：默认最多 5 轮
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）。

---

注意事项

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

---

Module 7: XGBoost调参

XGBoost 参数调优 (portable)

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

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

---

调优流程

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

---

执行模式

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

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

交互式模式行为规范

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

AUTO 模式行为规范

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

---

参数说明

通用参数 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	↓ 减小	↑ 增大

参数调整优先级

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

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

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

1. 增大 max_depth（增加复杂度）
2. 增加 n_estimators（更多迭代）
3. 减小正则化参数
4. 适当增大 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

---

输出产物

1. 建模报告（Markdown）— 含数据切分、网络结构、训练曲线、三段式评估指标、稳定性分析
2. 模型文件（.pt）— PyTorch state_dict + 模型配置
3. 训练日志（JSON）— 每 epoch 的 loss/AUC/KS 记录
4. 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 可做横向对比

---

注意事项

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

---

注意事项

1. 数据要求：目标变量必须为 0/1 二分类
2. 搜索加速：搜索期间使用 search_epochs=30，最终模型使用 epochs=100
3. 收敛判定：连续2轮提升不足 0.001 自动停止
4. 最大轮数：默认最多 5 轮
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 → 差距可能是采样波动

---

输出产物

1. 对比报告（Markdown，倒金字塔结构）：

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

2. 各模型文件：XGB(.json) / LR(.joblib) / DNN(.pt，含 imputer+scaler 元数据)

---

与其他技能的关系

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

---

注意事项

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

---

特征列表来源

1. --features "f1,f2,..." 显式传入
2. config.json 中 "features": [...]
3. 自动发现 <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

---

注意事项

1. 模型格式：仅支持 XGBoost JSON 格式模型文件
2. 数据一致性：--data_path 需与训练时使用的数据字段一致
3. 样本定位：--sample_id 为数据框的整数索引，非业务ID
4. 内存占用：大数据集的全局 SHAP 计算可能耗时较长
5. 图表依赖：需要 matplotlib 和 shap 库支持
6. 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	特征分析	辅助假设生成

---

注意事项

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

---

注意事项

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

---

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（含调参）

---

注意事项

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

---

Disclaimer / 免责声明

⚠️ 重要声明

• 本技能提供参考框架和分析建议，不构成任何形式的投资建议、法律意见或专业判断
• 所有分析结果仅供参考，最终决策须由具备相应资质的专业人员作出
• 用户应结合实际情况独立判断