| name | xgb-modeling |
| category | 建模训练 |
| description | 【XGBoost建模】当用户需要"训练模型"、"跑一个基线"、"建个模型试试"、"对比特征方案效果"、"预测一下"、"跑个xgb"、"看AUC/KS/BCR"时使用。支持多特征方案对比、AUC/KS/BCR/Brier评估、Bootstrap置信区间、概率校准曲线、稳定性分析（Mann-Kendall趋势检验）。前提条件：需要已完成特征分析并确定特征方案。**不做超参数调优，调参请用 xgb-tuning**；不做特征工程。与 auto-experiment 的区别：本 Skill 按用户指定方案训练，auto-experiment 自主探索特征组合。 |
| next_steps | [{"skill":"xgb-tuning","text":"调参优化模型效果","prompt":"帮我调参，优化模型效果"},{"skill":"model-explanation","text":"SHAP解释模型决策","prompt":"哪些特征最重要？解释模型决策逻辑"}] |
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 — ModelCardresult.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"}
]
跨 skill 串联
下游（如 model-explanation）通过 --model_path 传入上游 result.json 中 role=model 的文件路径：
MODEL_PATH=$(jq -r '.files[] | select(.role=="model") | .path' ./outputs/run1/result.json)
python ../model-explanation/scripts/explain.py --model_path "$MODEL_PATH" --data_path ./examples/toy.parquet
常用场景
场景一：自动特征筛选建模
不指定特征，自动执行四大算子生成四套方案对比：
python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label
场景二：指定特征建模
使用指定的特征列表：
python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --features "feat1,feat2,feat3"
场景二-b：指定单套自动筛选方案
只跑一种筛选方案（如"去共线性"）：
python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --feature_scheme decorr
可选值：full(全量入模) / decorr(去共线性) / high_iv(高预测力) / stable(稳定性优先)
场景三：多方案对比
传入多套特征方案（优先用 --config，避免命令行拼 JSON 转义）：
{
"feature_sets": {
"方案A": ["f1", "f2"],
"方案B": ["f1", "f3"]
}
}
python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --config ./config.json
场景四：保存模型
训练完成后保存最优模型，供后续 model-explanation 使用：
python scripts/modeling.py --data_path ./examples/toy.parquet --target y_label --model_name my_best_model
模型自动保存，输出：
- 模型文件：
<output_dir>/models/my_best_model.json
- 元数据文件：
<output_dir>/models/my_best_model_meta.json（含特征列表、参数等）
报告结构
| 章节 | 内容 |
|---|
| 执行摘要 | 4 行业务结论：最优方案、Gap 状态、PSI 状态、头部特征风险 |
| 1. 数据概览 | 样本量、正样本率（Train/Test/OOT） |
| 2. 特征方案对比 | 各方案 AUC/KS/Gap 横向对比 |
| 3. 最优方案详情 | AUC/KS/Gini 指标、模型分数 IV 最优分箱、Lift 表、特征重要性、BCR @ Top5/10/20/30%、Brier Score + 校准曲线 |
| 4. 稳定性分析 | 按月 AUC/KS（含 95% Bootstrap 置信区间）、Mann-Kendall 趋势检验、分数 PSI |
| 5. 最终模型总结 | 特征列表、综合表现 |
与其他建模 Skill 的对比
| 维度 | xgb-modeling | lr-modeling | dnn-modeling |
|---|
| 算法 | XGBoost | Logistic Regression + WoE | MLP (PyTorch) |
| 特征处理 | 原始值直接输入 | WoE 分箱编码 | StandardScaler |
| 非线性能力 | 强（树结构） | 弱（仅通过分箱引入） | 强（多层激活） |
| 可解释性 | 中（需 SHAP） | 强（系数 × WoE） | 弱 |
| 训练速度 | 快 | 很快 | 慢 |
| 适用数据量 | 任意 | 任意 | >10k |
| 评估体系 | AUC/KS/BCR/PSI | AUC/KS/BCR/PSI | AUC/KS/BCR/PSI |
上下游关系
- 前置：
data-profiling → feature-analysis（特征筛选）
- 后续：
xgb-tuning（调参优化）、model-explanation（SHAP 解释）
- 平行：与
lr-modeling / dnn-modeling 可做横向对比（同数据不同算法）
依赖
见 requirements.txt（核心：xgboost, scikit-learn, optbinning）。
注意事项
- 目标变量：必须为 0/1 二分类
- 时间切分：建议按时间切分，确保 OOT 为未来数据
- 自动特征筛选：需要数据同时满足 IV、PSI、缺失率条件
- 样本策略：强不均衡场景（正样本率 < 2%）建议
--sample_strategy undersample，一般场景用默认 auto_weight
- 不提供调参：需要调参请切 xgb-tuning（基于 Optuna TPE + 诊断驱动的约束搜索）
- 模型保存：每次训练自动保存最优模型至
<output_dir>/models/，无需传 --save_model；可用 --model_name 自定义文件名
- 稳定性分析：基准月份取自训练集时间段；Bootstrap CI 需样本量 >= 100 才计算
- BCR/校准曲线：BCR（Bad Capture Rate）反映拒绝 Top K% 人群能捕获多少坏客户；校准曲线反映模型概率输出可信度
