xgb-tuning

---
name: xgb-tuning
category: 调参优化
description: 【XGBoost超参数调优 — 唯一调参入口】当用户说"帮我调参"、"模型过拟合了怎么办"、"调整learning_rate/max_depth等参数"时使用。核心能力：基于 Optuna TPE 贝叶斯优化 + 诊断驱动的约束搜索（过拟合→收紧树深度上限，欠拟合→抬高树深度下限），每轮输出诊断报告供用户确认。不做特征探索/特征工程，不批量跑多种方案对比。前置条件：需先用 xgb-modeling 训练出基线模型。与 auto-experiment 的区别：本Skill只调整"模型超参数"，auto-experiment 负责"自主探索特征和方案"。
next_steps:
  - skill: model-explanation
    text: SHAP解释最优模型
    prompt: 哪些特征最重要？解释模型决策逻辑
---

# XGBoost 参数调优 (portable)

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

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

---

## 调优流程

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

---

## 执行模式

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

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

### 交互式模式行为规范

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

### AUTO 模式行为规范

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

---

## 参数说明

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

| 参数 | 必选 | 默认值 | 说明 |
|------|:----:|--------|------|
| `--data_path` / `-d` | ✅ | - | 数据文件路径（parquet/csv） |
| `--target` / `-t` | ✅ | - | 目标变量列名（0/1 二分类） |
| `--features` / `-f` | ✅ | - | 特征列表，逗号分隔 |
| `--time_col` | | `busi_dt` | 时间列名 |
| `--train_filter` | | 自动切分 | 训练集筛选条件（pandas query） |
| `--val_filter` | | `val_ratio` 切出 | 验证集筛选条件（已全面替代旧 `--test_filter`） |
| `--oot_filter` | | 按时间切出 | OOT 测试集条件 |
| `--oot_ratio` / `--val_ratio` | | `0.20` / `0.25` | 自动切分比例 |
| `--random_seed` | | `42` | 随机种子 |
| `--exclude_cols` | | - | 排除列，逗号分隔 |
| `--params` / `-p` | | 默认参数 | 当前参数（JSON；**推荐放 `--config` 的 `params` 字段**） |
| `--baseline` / `-b` | | - | 基线参数（JSON；**推荐放 `--config` 的 `baseline` 字段**） |
| `--round` / `-r` | | `0` | 当前轮次 |
| `--prev_val_metric` | | - | 上一轮 val 指标（用于收敛判断） |
| `--max_rounds` | | `5` | 最大调优轮数 |
| `--auto` | | - | 启用自动调优模式（flag） |
| `--metric` | | `ks` | 评估指标（`auc`/`ks`） |
| `--model_name` | | 自动生成 | 模型名称（不含扩展名） |
| `--report_output` / `-o` | | 自动生成 | 报告输出路径 |
| `--output_dir` | | `./outputs/<ts>` | **portable 独有**：产物输出目录 |
| `--warm_start` | | - | WarmStartBundle JSON 字符串或文件路径 |
| `--config` | | - | JSON 配置文件路径（由 `--config` 自动注入，一般无需手传） |

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

---

## 基线参数智能推断

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

### 数据摘要字段

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

| 字段 | 说明 | 影响参数 |
|------|------|----------|
| `train_samples` | 训练集样本量 | max_depth, n_estimators |
| `oot_samples` | OOT 样本量 | subsample |
| `n_features` | 特征数量 | colsample_bytree |
| `pos_rate` | 正样本率 | min_child_weight, scale_pos_weight |

### 推断规则

#### 样本量与树深度

| 训练集样本量 | max_depth 建议 | 理由 |
|----------------|------------------|------|
| < 5万 | 3 | 样本少，低复杂度防过拟合 |
| 5万 - 20万 | 4 | 中等样本，适中复杂度 |
| 20万 - 100万 | 5 | 样本充足，可稍复杂 |
| > 100万 | 5-6 | 大样本支撑更高复杂度 |

#### 正样本率与叶节点

| 正样本率 | min_child_weight 建议 | 理由 |
|----------|--------------------------|------|
| < 1% | 300+ | 正样本极少，需更大叶节点防止噎声 |
| 1% - 5% | 100-200 | 不平衡，适当约束 |
| 5% - 20% | 50-100 | 较平衡，标准约束 |
| > 20% | 20-50 | 平衡数据，可稍宽松 |

#### 特征数与采样率

| 特征数 | colsample_bytree 建议 | 理由 |
|----------|---------------------------|------|
| < 20 | 0.9-1.0 | 特征少，充分利用 |
| 20 - 50 | 0.7-0.9 | 中等特征，适度采样 |
| > 50 | 0.5-0.7 | 特征多，增加随机性 |

### 推断示例

```
数据摘要:
  训练集: 150,000 样本
  OOT: 50,000 样本
  特征数: 35 个
  正样本率: 2.5%

Agent 推断基线参数:
  max_depth: 4        <- 样本量中等
  min_child_weight: 150  <- 正样本率低
  colsample_bytree: 0.8  <- 特征数中等
  reg_alpha: 0.3      <- 特征多，适当正则
  reg_lambda: 1.0
  learning_rate: 0.05
  n_estimators: 500
  subsample: 0.8
```

---

## 场景化策略

Agent 应根据用户提供的**场景信息**调整调参策略。

### 金融风控场景

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

| 参数 | 建议值 | 理由 |
|------|--------|------|
| max_depth | 3-4 | 低复杂度，抗过拟合 |
| min_child_weight | 150+ | 叶节点要稳定 |
| reg_alpha | 0.3-0.5 | 强正则化 |
| reg_lambda | 1.0-2.0 | 强正则化 |

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

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

### 营销响应场景

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

| 参数 | 建议值 | 理由 |
|------|--------|------|
| max_depth | 4-5 | 允许较高复杂度 |
| min_child_weight | 50-100 | 可以稍宽松 |
| reg_alpha | 0.1-0.2 | 适中正则 |

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

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

### 平衡场景（默认）

**特点**: 兼顾效果和稳定性

| 参数 | 建议值 |
|------|--------|
| max_depth | 4-5 |
| min_child_weight | 100 |
| reg_alpha | 0.1-0.3 |
| reg_lambda | 0.5-1.0 |

**终止条件**: KS >= 0.30 且 Gap < 0.03

---

## 执行方式

复杂参数（`params`/`baseline`）建议通过 `--config` JSON 文件传入：

```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_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 模式均适用）

每轮调优结束后，**必须**输出以下结构化信息：

```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）
- 稳定性显著改善，可安全部署

如需进一步探索，请给出您的调优建议。
```

---

## 与其他技能的关系

| 技能 | 职责 | 关系 |
|------|------|------|
| `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>/`

• SKILL.md 16 KB
• _vendor/__init__.py 1 KB
• _vendor/data_utils.py 1 KB
• _vendor/model_card.py 10 KB
• _vendor/report_artifact.py 28 KB
• _vendor/result_emitter.py 7 KB
• _vendor/safety_gate.py 16 KB
• _vendor/tuning_engine.py 1 KB
• _vendor/xgb_cli.py 12 KB
• _vendor/data/__init__.py 1 KB
• _vendor/data/loading.py 3 KB
• _vendor/data/missing.py 6 KB
• _vendor/data/splitting.py 20 KB
• _vendor/data/woe_transform.py 8 KB
• _vendor/diagnostic/__init__.py 1 KB
• _vendor/diagnostic/fit_check.py 4 KB
• _vendor/diagnostic/ks_structure.py 8 KB
• _vendor/diagnostic/report.py 5 KB
• _vendor/tuning/__init__.py 1 KB
• _vendor/tuning/diagnose.py 6 KB
• _vendor/tuning/dnn_engine.py 12 KB
• _vendor/tuning/engine.py 9 KB
• _vendor/tuning/lr_engine.py 8 KB
• _vendor/tuning/search_space.py 7 KB
• _vendor/tuning/xgb_engine.py 5 KB
• _vendor/xgb_core/__init__.py 1 KB
• _vendor/xgb_core/evaluator.py 22 KB
• _vendor/xgb_core/stability.py 9 KB
• _vendor/xgb_core/trainer.py 13 KB
• scripts/tuner.py 41 KB