首頁/ 資料分析/ Financial Engineer Digital Employee

Financial Engineer Digital Employee

👤 gechengling 📦 v2.0.1 ⭐ 4.6 ⬇️ 564 下載
📊 資料分析 免費

📖 技能介紹

name: "Financial Engineer Digital Employee" slug: financial-engineer-digital-employee description: "覆蓋資料探查、單變數分析、特徵工程、LR評分卡、XGBoost/DNN建模、超引數調優、模型解釋、多模型對比、分群建模、DeepModel整合全流程。從資料到模型上線的一站式機器學習建模能力。" version: "2.0.1" allowed-tools: - data-analysis - reference-framework capabilities: - knowledge-reference - analytical-framework - requires-human-review - analytical-framework

Financial Engineer Digital Employee / 金融工程專家數字員工

⚠️ 能力宣告 / Capability Notice - Type: Knowledge reference framework for financial professionals - Purpose: Provides analytical templates, reference data, and workflow guidance - 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

⚠️ 使用宣告 - 本技能提供金融行業專業知識參考框架，輔助專業人員進行分析和決策 - 所有輸出僅供專業參考，不構成投資建議、法律意見或合規保證 - 實際業務操作中需結合具體監管要求和機構內部制度執行 - 最終報告和資料須經相關責任人稽核確認後方可提交或使用 - 不替代專業培訓師、合規官或稽核人員的專業判斷## 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. 使用者可能的反饋：
  3. "繼續" / "再調一輪" → 執行下一輪
  4. "Gap 還是大" / "再保守點" → 調整策略後執行
  5. "可以了" / "停" → 生成最終報告
  6. 禁止在互動式模式下連續執行多輪調優

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，倒金字塔結構）：
  2. 執行摘要（客觀指標速覽 + Pareto 前沿標記，無推薦列）
  3. 多演算法疊加曲線（ROC/KS/Lift）
  4. 資料概覽
  5. 詳細指標總表（train/val/oot × 8 指標）
  6. Pareto 前沿候選集（無主觀權重）
  7. DeLong 顯著性檢驗
  8. 穩定性（真實 PSI + 分月 KS）
  9. 樣本級一致性（Top-K Jaccard / Spearman / 分歧數）
  10. 跨演算法特徵重疊（Jaccard + 共識特徵）
  11. 每演算法獨立評估圖
  12. LLM 推理引導：事實清單 + 開放問題，交由對話中的 AI 推理取捨

  13. 各演算法適用場景背景知識

  14. 各模型檔案：XGB(.json) / LR(.joblib) / DNN(.pt，含 imputer+scaler 後設資料)

與其他技能的關係

技能 職責 關係
xgb-tuning / lr-tuning / dnn-tuning 調參最佳化 前置：公平對比前需先調參
xgb-modeling / lr-modeling / dnn-modeling 基線建模 被複用訓練對比模型
model-explanation 模型解釋 後續：對比完成後解釋最優模型

注意事項

  1. 公平對比："哪個演算法好"只有在三個演算法都調優後對比才公平

    本技能來自小蔥技能站7w4.net。

  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 / 免責宣告

⚠️ 重要宣告 - 本技能提供參考框架和分析建議，不構成任何形式的投資建議、法律意見或專業判斷 - 所有分析結果僅供參考，最終決策須由具備相應資質的專業人員作出 - 使用者應結合實際情況獨立判斷

🤖 AI 評測

這個技能的質量較好，專業性突出，文件結構完整、引數說明詳細，覆蓋了金融建模全流程並支援多種演算法和調參模式。主要優點是功能全面、邏輯清晰；不足之處是實際內容與描述不符——文件提到很多指令碼檔案但包內根本沒有程式碼，只有說明文件，無法直接使用。

📊 多維度評分

適應性4.7
規範性4.4
有效性4.7
可靠性4.4
可信度4.9

📁 包含檔案 (3 個)

📄 SKILL.md 91 KB
📄 _meta.json 154 B
📄 skill-card.md 2.7 KB

🔗 相關推薦

AdMapix
fly0pants
⭐ 4.5 ⬇️ 192.3K
免費
Data Analysis
ivangdavila
⭐ 4.2 ⬇️ 82.9K
免費
Stock Analysis
udiedrichsen
⭐ 4.6 ⬇️ 65.1K
免費
smart-charts
hanli
⭐ 4.6 ⬇️ 63.5K
免費