| name | lr-tuning |
| category | 调参优化 |
| description | 【LR评分卡调参】当用户说"LR调参"、"评分卡调优"、"调整分箱数"、"调整C值"、"LR过拟合"时使用。基于 Optuna TPE 贝叶斯优化，联合搜索 WoE 分箱参数（max_n_bins、iv_threshold）和 LR 模型参数（C、regularization），诊断驱动约束搜索空间。前置条件：需先用 lr-modeling 训练出基线模型。 |
| next_steps | [{"skill":"model-comparison","text":"多算法对比评估","prompt":"与XGBoost和DNN对比一下效果"}] |
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 调参 | 平行：同数据不同算法的调参 |
注意事项
- 数据要求：目标变量必须为 0/1 二分类
- 联合搜索：WoE 分箱与 LR 参数联合优化，确保最优组合
- 收敛判定：连续2轮提升不足 0.001 自动停止
- 最大轮数：默认最多 5 轮
- 产物位置：模型和报告保存到
<output_dir>/models/ 和 <output_dir>/
