xgb-tuning

XGBoost 参数调优 (portable)

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

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

---

调优流程

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

---

执行模式

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

交互式模式行为规范

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

AUTO 模式行为规范

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

---

参数说明

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

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

---

基线参数智能推断

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

数据摘要字段

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

推断规则

样本量与树深度

正样本率与叶节点

特征数与采样率

推断示例

数据摘要:
  训练集: 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 应根据用户提供的场景信息调整调参策略。

金融风控场景

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

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

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

营销响应场景

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

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

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

平衡场景（默认）

特点: 兼顾效果和稳定性

终止条件: 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 AUC 持续上升，OOT AUC 下降或停滞
• Train-OOT Gap 逐轮增大
• 验证集效果不稳定

欠拟合信号

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

---

XGBoost 参数语义

参数调整优先级

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

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

---

用户指令理解

---

调优策略

策略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>/`