229
下载量
8
安装量
0
收藏量
★ 4.9
综合评分ⓘ
Financial Engineer Digital Employee / 金融工程专家数字员工#
⚠️ SECURITY NOTICE / 安全声明
- Type: Educational reference / analytical framework ONLY
- No bundled executable payload: this skill ships no runnable package, installer, background task or scheduled job. The commands, scripts and configuration snippets shown in the text are illustrative reference material, to be read and, if useful, run by the user inside their own authorised environment.
- 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: 分群建模
全局建模口径与最新动态（2026-09-21 新增）#
建模与合规动态#
动态类型内容摘要发布时间对建模流程的影响应对动作模型治理金融机构模型全生命周期管理与可解释要求持续强化2026-Q3模型需可解释、可复现、可审计保留特征清单、参数与版本记录AI应用银行业保险业AI安全开发应用指导意见落地，高风险场景需可解释可审计2026-06-18评分卡与复杂模型均需解释材料每个模型输出解释与局限性说明数据安全个人信息保护与数据最小化要求在建模场景执行细化2026-Q3特征可解释“为什么要这个字段”建立字段准入与留痕自动化建模自动化特征工程与自动调参工具普及，人工判断价值转向“问题定义”2026-Q3调参不再是主要瓶颈把精力放在口径、切分与验证上模型监控模型上线后漂移监控成为标配环节2026-Q3一次性建模不够增加监控指标与预警阈值
数据截止: 2026-09-21 | 来源：公开行业信息与监管公开信息 声明: 以上动态供参考，具体以官方最新发布为准
建模流程通用的六道关卡#
关卡要回答的问题不通过的处理问题定义预测什么、在哪个时点预测、给谁用先回去定义清楚，不要开始建模口径与切分训练集/验证集/OOT 如何切，是否有泄漏重做切分，按时间切优先特征准入每个字段为什么可用、是否有未来信息剔除无法解释来源的字段基线对比比简单基线好多少不优于基线则不值得上线稳定性跨时间、跨群的表现是否稳定不稳定的模型限制使用范围可解释与留痕能否解释单个预测与整体行为补解释材料后再评审
常用指标速查与易错点#
指标定义易错点AUC正负样本排序能力的综合度量样本极度不均衡时单独看AUC会乐观KS好坏样本累计分布的最大差值对切分点敏感，需看曲线形状PSI分布稳定性指标分箱方式不同结果差异大Lift / Gain前若干分位的提升倍数只看Top分位会忽略整体召回率/精确率正样本的覆盖与命中单一阈值下比较会误导OOT Gap训练集与OOT表现的差用随机切分掩盖时间效应
输出质量自检（所有模块通用）#
自检项不通过表现处理动作数据有来源与授权使用来源不明的字段补来源与授权说明，否则剔除无未来信息使用了预测时点之后才可得的字段剔除该特征并重训结论有边界写成确定性的“必然”改为“在……假设下，可能……”风险有提示只讲效果不讲局限补齐局限与风险段未夹带敏感信息出现未脱敏的原始明细先脱敏再输出已过人工复核未经复核即外发标注“待复核”，确认后再发送可复现未记录参数、版本与随机种子补齐实验记录
保存与外发前确认#
- 在对话中完整展示报告、指标与图表，供用户逐段确认；
- 用户确认后再写入文件或对外发送；未经确认不得落盘、不得发送；
- 落盘时同时记录：运行时间、数据时间窗、主要参数、模型版本、审核人。
- 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 配置文件路径
执行方式#
bash
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 读这个文件即可
产物示例#
json
{
"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 chart5. 缺失值分析缺失率排名表格 + 柱状图6. 数据质量重复行、空列、常量列、高缺失列7. 样本预览前 5 行数据展示
自适应展示#
当数值/类别特征数量超过 20 个时，统计表格和图表只展示前 20 个，避免报告过长。
与其他 Skill 的关系#
Skill用途区别data-profiling快速了解数据轮廓，不做深度分析feature-analysis深度特征分析（IV、PSI、相关性等），需要目标变量xgb-modeling建模全流程，需要目标变量
建议流程：
- 先用
data-profiling了解数据基本情况 - 根据洞察结果，决定是否需要
feature-analysis或xgb-modeling
注意事项#
- 无需目标变量：本 Skill 不需要提供目标变量，纯数据描述
- 快速轻量：执行速度快，适合大数据集的快速扫描
- 自动类型推断：识别数值型、类别型、布尔型、时间型、文本型字段
输出示例与自检（2026-09-21 新增）#
轮廓报告的判读要点
现象可能原因处理建议某字段缺失率 > 90%采集不全或字段冗余评估后剔除，不默认填充唯一值数 = 样本数主键或泄露字段确认是否为ID类字段并剔除类别字段取值极多高基数字段考虑合并低频取值分布集中在单一值采集口径问题回溯数据源确认时间字段跨度异常数据窗口截断明确训练数据时间窗
自检：轮廓扫描只描述事实，不做归因；任何“该字段无用”的结论都须结合业务含义，不能仅凭缺失率下判断。
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 配置文件路径
执行方式#
数据探索模式（无目标变量）#
bash
python scripts/analyzer.py \
--data_path ./data.parquet --features "age,income,score" \
--output_dir ./outputs/uni_run
特征筛选模式（有目标变量）#
bash
python scripts/analyzer.py \
--data_path ./data.parquet --features "age,income,score" --target y_label \
--output_dir ./outputs/uni_run
交叉分布分析#
bash
python scripts/analyzer.py \
--data_path ./data.parquet --features "age,income" --cross "age,income" \
--output_dir ./outputs/uni_run
常用场景#
场景一：数据探索（无目标变量）#
查看单特征分布：
bash
python scripts/analyzer.py --data_path ./data.parquet --features "age,income,score" --output_dir ./outputs/uni_run
指定等距分箱：
bash
python scripts/analyzer.py --data_path ./data.parquet --features "age" --binning_method distance --n_bins 5 --output_dir ./outputs/uni_run
场景二：交叉分布分析#
查看两个特征的联合分布：
bash
python scripts/analyzer.py --data_path ./data.parquet --features "age,income" --cross "age,income" --output_dir ./outputs/uni_run
场景三：特征筛选（有目标变量）#
计算 IV 值，评估特征预测力：
bash
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% 时单独一箱
- 负数：当存在负数时单独处理
输出示例#
分布分析表#
text
特征: age | 分箱方式: 等频 | 分箱数: 10
| 区间 | 样本数 | 占比 | 累计占比 |
|---------------|---------|---------|----------|
| Missing | 156 | 1.56% | 1.56% |
| [18, 23) | 984 | 9.84% | 11.40% |
| [23, 28) | 1,012 | 10.12% | 21.52% |
| ... | ... | ... | ... |
交叉分布表#
text
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 分箱明细表（有目标变量）#
text
特征: 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-analysisfeature-analysis定位单特征快速分析全量特征深度分析目标变量可选必须相关性分析❌✅PSI稳定性❌✅方案推荐❌✅ 四套方案典型用法建模前快速筛选特征工程完整报告
推荐工作流： univariate-analysis（快速筛选）→ feature-analysis（深度分析）
注意事项#
- 特征数量：建议单次分析不超过 50 个特征，大量特征请分批处理
- 分箱数量：默认 10 箱，可根据数据量调整（数据量少时建议 5 箱）
- 交叉分布：仅支持两个特征的交叉，建议选择离散或已分箱的特征
- IV 计算：需要目标变量为 0/1 二分类
- 产物位置：报告保存到
<output_dir>/
输出示例与自检（2026-09-21 新增）#
单变量结论的规范写法
不规范规范原因“年龄越大风险越高”“在样本区间内，年龄与坏样本率呈单调上升，需结合客群结构判断”单变量未控制其他因素“这个字段没有用”“该字段单变量区分度低，可在多变量环境中再评估”单变量弱不代表无用“缺失就是坏客户”“缺失本身有区分度，但需确认缺失机制”缺失可能含采集偏差
自检：单变量分析不得直接推导因果；涉及分箱时须说明分箱方法与样本量下限，样本过少的箱须合并。
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 配置文件路径
执行方式#
bash
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）#
适用于无时间维度的数据集：
bash
python scripts/analyzer.py --data_path ./data.parquet --target y_label --output_dir ./outputs/fa_run
场景二：完整分析（含 PSI）#
适用于有时间切分条件的数据集：
bash
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 或指定特征的完整分箱明细表：
bash
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``8WoE 分箱最大箱数--min_bin_size``0.05最小分箱比例--iv_threshold``0.02IV 筛选阈值（低于此值的特征排除）--regularization``l2正则化类型： l1 / l2 / elasticnet``--C``1.0正则化强度（越小正则化越强）--max_iter``1000LR 最大迭代次数--base_score``600评分卡基础分--pdo``50评分卡 PDO（分数翻倍点）--base_odds``50.0基础 Odds（好坏比）--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/lr_run
指定特征建模：
bash
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
常用场景#
场景一：默认参数快速建模#
bash
python scripts/modeling.py --data_path ./data.parquet --target y_label --output_dir ./outputs/lr_run
场景二：指定特征建模#
bash
python scripts/modeling.py --data_path ./data.parquet --target y_label \
--features "feat1,feat2,feat3" --output_dir ./outputs/lr_run
场景三：自定义评分卡参数#
bash
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-modelingxgb-modelingdnn-modeling算法Logistic RegressionXGBoostMLP (PyTorch)特征编码WoE 分箱编码原始特征直接输入StandardScaler可解释性白盒（系数 × WoE = 贡献）黑盒（需 SHAP 解释）弱非线性能力弱（仅通过分箱引入）强（树结构天然支持）强（多层激活）适用场景评分卡 / 合规 / 白盒高精度 / 特征交互高维复杂交互评估体系AUC/KS/BCR/PSIAUC/KS/BCR/PSIAUC/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/
输出示例与自检（2026-09-21 新增）#
评分卡落地的检查清单
检查项标准不达标处理分箱单调性业务上可解释调整分箱或合箱每箱样本量满足最低样本要求合并稀疏箱系数符号与业务常识一致检查共线性与特征定义OOT Gap在可接受范围检查切分与时间效应PSI跨时间稳定重新校准或更换特征
自检：评分卡的优势是可解释，若出现“系数符号与业务常识相反且无法解释”，不得直接上线，须回到特征定义排查。
Module 5: LR评分卡调参#
LR 评分卡参数调优 (portable)#
LR 评分卡调参的 唯一入口，基于 _vendor/tuning/lr_engine.LRTuningEngine。
核心设计：WoE 分箱参数与 LR 正则化参数 联合搜索，确保最优组合。
调优流程#
text
基线 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.20OOT 占比--val_ratio``0.25Val 占比--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_binsint3-15WoE 分箱数（越大越精细）iv_thresholdfloat(log)0.005-0.10IV 筛选阈值（越低入模特征越多）Cfloat(log)0.01-100正则化强度倒数（越大正则化越弱）regularizationcategoricall1/l2/elasticnet正则化类型
诊断驱动策略#
诊断Civ_thresholdmax_n_bins过拟合↓ 收紧↑ 抬高（减少特征）↓ 减少欠拟合↑ 放松↓ 降低（更多特征）↑ 增大拟合良好±微调±微调±微调
执行方式#
交互式模式（单轮）#
bash
python scripts/tuner.py \
--data_path ./data.parquet --target y_label \
--round 1 --output_dir ./outputs/lr_tuning
AUTO 模式#
bash
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
行为：停止调优，输出最终结果
输出格式规范#
每轮调优结束后， 必须 输出以下结构化信息：
markdown
### 第 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-tuningXGBoost 调参平行：同数据不同算法的调参
注意事项#
- 数据要求：目标变量必须为 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同 trainPSI 基准条件--comparison_filter同 ootPSI 对比条件--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结构化通道。
执行方式#
bash
python scripts/modeling.py \
--data_path ./examples/toy.parquet \
--target y_label \
--time_col busi_dt \
--output_dir ./outputs/run1
复杂 feature_sets 通过 --config 传入：
bash
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— ModelCardresult.json— 结构化产物清单（见 PROTOCOL.md）
stdout 末行打印 result.json 绝对路径，Agent 读这个文件即可获取全部产物路径与 metrics。
产物示例（result.json）#
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 的文件路径：
bash
# 从上游 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
常用场景#
场景一：自动特征筛选建模#
不指定特征，自动执行四大算子生成四套方案对比：
bash
python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label
场景二：指定特征建模#
使用指定的特征列表：
bash
python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --features "feat1,feat2,feat3"
场景二-b：指定单套自动筛选方案#
只跑一种筛选方案（如"去共线性"）：
bash
python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --feature_scheme decorr
可选值： full(全量入模) / decorr(去共线性) / high_iv(高预测力) / stable(稳定性优先)
场景三：多方案对比#
传入多套特征方案（ 优先用 --config，避免命令行拼 JSON 转义）：
json
{
"feature_sets": {
"方案A": ["f1", "f2"],
"方案B": ["f1", "f3"]
}
}
bash
python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --config ./config.json
场景四：保存模型#
训练完成后保存最优模型，供后续 model-explanation 使用：
bash
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 趋势检验、分数 PSI5. 最终模型总结特征列表、综合表现
与其他建模 Skill 的对比#
维度xgb-modelinglr-modelingdnn-modeling算法XGBoostLogistic Regression + WoEMLP (PyTorch)特征处理原始值直接输入WoE 分箱编码StandardScaler非线性能力强（树结构）弱（仅通过分箱引入）强（多层激活）可解释性中（需 SHAP）强（系数 × WoE）弱训练速度快很快慢适用数据量任意任意>10k评估体系AUC/KS/BCR/PSIAUC/KS/BCR/PSIAUC/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% 人群能捕获多少坏客户；校准曲线反映模型概率输出可信度
输出示例与自检（2026-09-21 新增）#
树模型常见过拟合信号
信号表现处理训练与验证差距大训练AUC接近1、验证明显低降低复杂度、加正则、早停早停轮次过早验证曲线尚未收敛调整早停耐心值特征重要度集中少数特征主导检查是否有泄漏特征OOT明显下滑跨时间不稳定按时间切分重训
自检：树模型必须报告 OOT 表现而非仅验证集表现；上线前须完成特征重要度与单样本解释，说明模型为何给出该判断。
Module 7: XGBoost调参#
XGBoost 参数调优 (portable)#
XGBoost 调参的 唯一入口，基于 _vendor/tuning_engine.TuningEngine。核心设计：
- 基线参数智能推断 — 根据数据特征推荐合理起点
- 模型状态诊断 — 过拟合/欠拟合判定（
diagnose_model） - 约束式贝叶斯搜索 — 诊断结论定向收缩 Optuna 搜索空间
- 用户知识融合 — 接受用户领域经验调整策略
调优流程#
text
用户需求 → 数据特征分析 → 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_estimatorsoot_samplesOOT 样本量subsamplen_features特征数量colsample_bytreepos_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 建议理由< 200.9-1.0特征少，充分利用20 - 500.7-0.9中等特征，适度采样> 500.5-0.7特征多，增加随机性
推断示例#
text
数据摘要:
训练集: 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_depth3-4低复杂度，抗过拟合min_child_weight150+叶节点要稳定reg_alpha0.3-0.5强正则化reg_lambda1.0-2.0强正则化
调参优先级: Gap 控制 > KS 提升
终止条件: Gap < 0.02，即使 KS 略低也接受
营销响应场景#
特点: 短期使用，效果优先
参数建议值理由max_depth4-5允许较高复杂度min_child_weight50-100可以稍宽松reg_alpha0.1-0.2适中正则
调参优先级: KS 提升 > Gap 控制
终止条件: KS 达标，Gap < 0.05 可接受
平衡场景（默认）#
特点: 兼顾效果和稳定性
参数建议值max_depth4-5min_child_weight100reg_alpha0.1-0.3reg_lambda0.5-1.0
终止条件: KS >= 0.30 且 Gap < 0.03
执行方式#
复杂参数（ params/ baseline）建议通过 --config JSON 文件传入：
bash
# 自动调优（推荐：通过 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 示例：
json
{
"params": {"max_depth": 4, "learning_rate": 0.05, "n_estimators": 500},
"baseline": {"max_depth": 4, "learning_rate": 0.1}
}
交互式模式（单轮调优）#
bash
python scripts/tuner.py \
--data_path ./data.parquet --target y_label --features "f1,f2,f3" \
--round 1 --output_dir ./outputs/tuning
AUTO 模式（自动调优循环）#
bash
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_alphaL1 正则化强度0-2.0↑ 增大↓ 减小reg_lambdaL2 正则化强度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.5max_depth: 当前值 - 1（最小为 2）min_child_weight: 当前值 × 1.5
策略2：增强拟合#
适用条件：OOT AUC < 0.58 且 Gap < 0.03
调整方向：
max_depth: 当前值 + 1（最大为 8）n_estimators: 当前值 × 1.5reg_alpha: 当前值 × 0.5learning_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 模式均适用）#
每轮调优结束后， 必须 输出以下结构化信息：
markdown
### 第 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 模式，也必须先逐轮输出再汇总。
markdown
# 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）
- 稳定性显著改善，可安全部署
如需进一步探索，请给出您的调优建议。
text
---
## 与其他技能的关系
| 技能 | 职责 | 关系 |
|------|------|------|
| `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
自定义网络结构：
bash
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
常用场景#
场景一：默认参数快速建模#
bash
python scripts/modeling.py --data_path ./data.parquet --target y_label --output_dir ./outputs/dnn_run
场景二：自定义网络结构#
bash
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
场景三：指定特征建模#
bash
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-modelingxgb-modelinglr-modeling算法MLP (PyTorch)XGBoostLR + WoE特征处理StandardScaler原始值WoE 分箱非线性能力强（多层激活）强（树结构）弱可解释性弱中（SHAP）强（系数）训练速度慢快很快适用数据量>10k任意任意评估体系AUC/KS/BCR/PSIAUC/KS/BCR/PSIAUC/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（加速），诊断驱动动态约束搜索空间。
调优流程#
text
基线 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.20OOT 占比--val_ratio``0.25Val 占比--random_seed``42随机种子--exclude_cols-排除列，逗号分隔--n_layers``3隐藏层数--layer_width``128首层宽度--dropout``0.3Dropout 率--learning_rate``0.001学习率--weight_decay``1e-4L2 正则化--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_layersint2-4隐藏层数layer_widthint32-256首层宽度（递减结构）dropoutfloat0.1-0.5Dropout 比率learning_ratefloat(log)1e-4 ~ 0.01Adam 学习率weight_decayfloat(log)1e-5 ~ 1e-3L2 正则化batch_sizecategorical128/256/512/1024批次大小
诊断驱动策略#
诊断dropoutweight_decayn_layerslayer_width过拟合↑ 抬高↑ 增强↓ 减少↓ 缩小欠拟合↓ 降低↓ 减弱↑ 增加↑ 增大拟合良好±微调±微调±微调±微调
执行方式#
交互式模式（单轮调优）#
bash
python scripts/tuner.py \
--data_path ./data.parquet --target y_label \
--round 1 --output_dir ./outputs/dnn_tuning
AUTO 模式（自动调优循环）#
bash
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: 当前值 × 2n_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.5learning_rate: 当前值 × 1.2
策略3：精细微调#
适用条件：Gap ∈ [0.03, 0.05]，模型状态良好
调整方向：
learning_rate: 小幅调整 ±20%dropout: 小幅调整 ±0.05- 其他参数保持不变
策略4：收敛判定#
条件：连续2轮 Val 指标提升 < 0.001
行为：停止调优，输出最终结果
输出格式规范#
与 xgb-tuning 保持一致的逐轮诊断报告格式。
每轮调优结束后， 必须 输出以下结构化信息：
markdown
### 第 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-tuningXGBoost 调参平行：同数据不同算法的调参
注意事项#
- 数据要求：目标变量必须为 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 检验回答"差距是真的还是采样噪声"
推荐工作流：先调参再对比#
"哪个算法好"这个问题只有在 三个算法都调优后 对比才公平。默认超参下对比只能作为初筛。推荐三步调用：
text
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.20OOT 占比--val_ratio``0.25Val 占比--random_seed``42随机种子--exclude_cols-排除列，逗号分隔--features-指定特征，逗号分隔；不传则自动推断--algorithms``xgb,lr,dnn对比算法列表，逗号分隔--scenario``general``general / scorecard / fraud / stability_first``--use_tunedflag关自动扫描 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 / BCRstability_first存量运维；重点关注 PSI 与分月 KS
执行方式#
默认三算法 + 通用场景：
bash
python scripts/comparison.py \
--data_path ./data.parquet --target y_label \
--exclude_cols "cust_code,busi_dt" \
--output_dir ./outputs/compare
评分卡场景（只跑 XGB + LR）：
bash
python scripts/comparison.py \
--data_path ./data.parquet --target y_label \
--algorithms "xgb,lr" --scenario scorecard \
--output_dir ./outputs/compare
使用历史调参最优参数：
bash
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>/
输出示例与自检（2026-09-21 新增）#
公平对比的前提
前提说明违反后果同一数据切分各模型用相同训练/验证/OOT结果不可比同一特征集特征口径一致把特征差异当成模型差异同一评价指标且在不均衡数据上补充召回/精确单一指标误导同等调参投入否则对比不公平高估调参多的一方
自检：对比结论须说明“在何种数据与调参投入下”；差异小于噪声水平时，应优先选择更简单、更易解释的模型。
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 配置文件路径
执行方式#
bash
python scripts/explainer.py \
--model_path ./models/my_model.json \
--data_path ./examples/toy.parquet \
--target y_label \
--output_dir ./outputs/explain_run
单样本解释：
bash
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
特征交互分析：
bash
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
常用场景#
场景一：全局特征重要性分析#
解释模型整体决策逻辑：
bash
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 值）
- 特征重要性表格
场景二：单样本预测解释#
解释特定样本的预测原因：
bash
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（推动预测的正负特征）
- 瀑布图（特征贡献分解）
- 该样本特征值与分布对比
场景三：特征交互分析#
分析两个特征的交互效应：
bash
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：
bash
# 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 图表文件列表
产物目录#
text
<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
输出示例与自检（2026-09-21 新增）#
解释输出的三层要求
层级回答什么常用材料全局模型整体依赖哪些因素特征重要度、方向群体某类客群为何被判高风险分群对比单样本这一个客户为何被拒绝单样本归因与贡献分解
自检：解释结果只说明“模型为什么这样算”，不等于“业务上应该这样决策”；涉及对客决策时须结合合规与人工复核。
Module 12: 自主实验循环#
自主实验循环 (portable)#
自动发现数据中的特征分组，执行四阶段渐进式探索实验，每轮完整展示探索逻辑和量化结果。
核心理念#
借鉴 autoresearch 的自主循环思想，升级为 组级探索：
text
发现特征组 → 组独立评估 → 组间叠加 → 组级消融 → 精细筛选
四阶段探索流程#
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.25val 在 train_full 内占比--oot_ratio``0.20OOT 在全量内占比--output_dir``./outputs/<ts>产物输出目录--config-JSON 配置文件
执行方式#
bash
python scripts/run_experiment.py \
--data_path ./data.parquet --target y_label \
--exploration "不同特征组(firefly/子模型/友盟)对mob3逾期的贡献" \
--max_rounds 10 \
--output_dir ./outputs/exp
常用场景#
场景一：探索各特征组贡献#
bash
python scripts/run_experiment.py \
--data_path ./data.parquet --target y_label \
--exploration "不同特征组(firefly模型/子模型/友盟数据)对mob3逾期预测的贡献" \
--max_rounds 10 --output_dir ./outputs/exp
场景二：探索特定时间窗口特征#
bash
python scripts/run_experiment.py \
--data_path ./data.parquet --target y_label \
--exploration "mob3相关的逾期、还款特征" \
--max_rounds 8 --output_dir ./outputs/exp
场景三：在已有基线上探索新组#
bash
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
输出内容#
核心原则：每轮必须完整输出探索逻辑和结果 禁止只输出最终汇总。每一轮实验完成后， 必须 立即输出：探索策略、推理逻辑、假设描述、新增/移除特征、训练指标详情、与基线的对比、显著性检验、决策理由。
数据概览（实验开始前）#
- 数据规模、特征数、正样本率
- 自动发现的特征分组及其统计
单轮输出格式（每轮必须使用）#
markdown
### 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 自主发现的分群策略下，拆分客群训练子模型，自动探索最优分群方案。
核心理念：
text
探索空间（策略 × 参数 × 组合）
│
▼
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 配置文件
执行方式#
自主探索最优分群#
bash
python scripts/run_segment.py \
--data_path ./data.parquet --target y_label \
--mode auto --max_rounds 5 \
--output_dir ./outputs/seg
用户规则分群#
bash
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
聚类自动分群#
bash
python scripts/run_segment.py \
--data_path ./data.parquet --target y_label \
--mode manual --n_clusters 4 \
--output_dir ./outputs/seg
决策树分群#
bash
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
输出内容#
实时进度（流式输出）#
text
━━━ 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 分群比例是否稳定
- 业务可解释：决策树分群规则更易解释
- 组合使用：可先分群再对各群做特征探索
输出示例与自检（2026-09-21 新增）#
分群方案的评价维度
维度问法不达标的信号业务可解释这个分群有业务含义吗只是数据切出来的簇样本量每群样本是否充足某群样本过少分群间差异各群是否真的不同子模型效果接近单模型增益分群后是否优于整体建模增益低于维护成本稳定性分群边界随时间是否稳定客群漂移导致边界失效
自检：分群建模会提高维护复杂度，只有当增益明显且分群稳定时才值得；否则优先用单一模型加特征表达客群差异。
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``falseflag。对 OOT Gap > 0.05 的分群自动调参--output_dir``./outputs/<ts>子模型保存目录--config-JSON 配置路径
执行方式#
bash
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：
json
{
"segments": {"高风险": "risk_score > 500", "低风险": "risk_score <= 500"},
"pos_weight_per_segment": {"高风险": 2.0, "低风险": 1.0}
}
bash
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``5OOF 交叉验证折数--output_dir``./outputs/<ts>Meta-learner 保存目录--config-JSON 配置路径
执行方式#
bash
python scripts/stacker.py \
--data_path ./data.parquet --target y_label \
--cv_folds 5 --output_dir ./outputs/deepmodel
配合 --config：
json
{
"submodel_paths": ["./outputs/deepmodel/高风险.json", "./outputs/deepmodel/低风险.json"],
"segments": {"高风险": "risk_score > 500", "低风险": "risk_score <= 500"}
}
bash
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 配置路径
执行方式#
bash
python scripts/comparator.py \
--data_path ./data.parquet --target y_label \
--stack_model_path ./outputs/deepmodel/stack_meta.json \
--output_dir ./outputs/deepmodel
配合 --config：
json
{
"submodel_paths": ["./outputs/deepmodel/高风险.json", "./outputs/deepmodel/低风险.json"],
"segments": {"高风险": "risk_score > 500", "低风险": "risk_score <= 500"}
}
bash
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仅走默认超参，定位为"低成本初筛对照"。
完整工作流示例#
bash
# 阶段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启用 --autoStacking OOT AUC≥ max(子模型 OOT AUC) - 0.01说明集成无明显增益集成 vs 基线 OOT AUC集成更高建议放弃集成，用最优子模型或基线
与其他技能的关系#
技能职责关系xgb-modeling单模型训练被复用训练子模型和基线segment-modeling分群策略探索区别：segment-modeling 探索最优分群，本 Skill 按指定分群做 Stackingmodel-comparison多算法公平对比后续：严格对比请用 model-comparison（含调参）
注意事项#
- 分群互斥：各分群条件应互斥（一个样本只属于一个分群），否则 Stacking 会有信息泄漏
- 样本量：每个分群的训练样本应 ≥ 500，过少的分群建议合并
- OOF 生成：Stacking 的 OOF 预测在各分群内独立做 k-fold，保证无标签泄漏
- Meta-learner：固定使用保守参数（max_depth=2），不做超参搜索，避免过拟合
- 子模型路径传递：stacker 和 comparator 支持从
--config读取子模型路径 - 三阶段顺序：必须先 sub_trainer → stacker → comparator，阶段间通过文件系统传递产物
输出示例与自检（2026-09-21 新增）#
集成前的三项前置检查
检查项标准不通过怎么办子模型差异性子模型错误不完全重合增加异质模型或特征视角各子模型OOT均达到可用水平先修子模型，不要靠集成救集成增益相对最优子模型有提升直接用最优子模型
自检：集成不是万能补丁。若子模型本身存在数据泄漏或口径问题，集成只会把问题包装得更隐蔽；集成后仍须完成解释与留痕。
Disclaimer / 免责声明#
⚠️ 重要声明
- 本技能提供参考框架和分析建议，不构成任何形式的投资建议、法律意见或专业判断
- 所有分析结果仅供参考，最终决策须由具备相应资质的专业人员作出
- 用户应结合实际情况独立判断
相关推荐
A股量化 AkShare
Mmbpzv1.0.1
A股量化数据分析工具，基于AkShare库获取A股行情、财务数据、板块信息等。用于回答关于A股股票查询、行情数据、财务分析、选股等问题。
行业专业
Stock Analysis
Uudiedrichsenv6.2.0
基于雅虎财经数据，分析股票与加密货币。支持投资组合管理、自选股预警、股息分析、8维评分、热门趋势扫描及传闻/早期信号探测。适用于股票分析、持仓追踪、财报异动、加密监控、热门股追踪或提前发掘非主流传闻。
行业专业
All-Market Financial Data Hub
Ffinancial-ai-analystv1.0.12
基于东方财富数据库，支持自然语言查询金融数据，覆盖A股、港股、美股、基金、债券等资产，提供实时行情、公司信息、估值、财务报表等，适用于投资研究、交易复盘、市场监控、行业分析、信用研究、财报审计、资产配置等场景，满足机构与个人需求。返回结果为xlsx和Markdown文件。
行业专业需 API Key
