dnn-tuning

DNN deep learning hyperparameter tuning (portable)

Theonly entry pointfor DNN tuning, based on _vendor/tuning/dnn_engine.DNNTuningEngine。

Core design: reduce epochs during search (for speed), diagnostic-driven dynamic constrained search space.

---

Tuning workflow

基线 DNN 模型 → 诊断分析(过拟合/欠拟合) → 约束空间构造 → Optuna 搜索(30 epochs) → 最优参数 → 迭代

---

Execution mode

Mode	Trigger condition	Behavior
Interactive(default)	User says "tune" / "help me tune the DNN"	Pause each round waiting for user feedback
AUTO	User says "auto-tune" / "help me tune to the optimum"	Agent iterates automatically until convergence

Default mode: Interactive (safer, user-controllable)

---

Parameter description

Parameter	Required	Default value	Description
--data_path / -d	✅	-	Data file path (parquet/csv)
--target / -t	✅	-	Target variable column name (0/1 binary classification)
--features		Auto-inferred	Feature list, comma-separated
--time_col		busi_dt	Time column name
--train_filter		Auto-split	Training set filter condition
--val_filter		val_ratio cut out	Validation set filter condition
--oot_filter		Split by time	OOT condition
--oot_ratio		0.20	OOT proportion
--val_ratio		0.25	Val proportion
--random_seed		42	Random seed
--exclude_cols		-	Excluded columns, comma-separated
--n_layers		3	Number of hidden layers
--layer_width		128	First layer width
--dropout		0.3	Dropout rate
--learning_rate		0.001	Learning rate
--weight_decay		1e-4	L2 regularization
--batch_size		512	Batch size
--epochs		100	Full training epochs
--search_epochs		30	Epochs during search (for speed)
--round / -r		0	Current round
--max_rounds		5	Maximum number of tuning rounds
--auto		-	Auto-tuning mode (flag)
--metric		auc	Evaluation metric
--model_name		Auto-generated	Model name
--output_dir		./outputs/<ts>	Artifact output directory
--config		-	JSON config path

---

Search space

Parameter	Type	Range	Description
n_layers	int	2-4	Number of hidden layers
layer_width	int	32-256	First layer width (decreasing structure)
dropout	float	0.1-0.5	Dropout ratio
learning_rate	float(log)	1e-4 ~ 0.01	Adam learning rate
weight_decay	float(log)	1e-5 ~ 1e-3	L2 regularization
batch_size	categorical	128/256/512/1024	Batch size

---

Diagnostic-driven strategy

Diagnosis	dropout	weight_decay	n_layers	layer_width
Overfitting	↑ Raise	↑ Strengthen	↓ Reduce	↓ Shrink
Underfitting	↓ Lower	↓ Weaken	↑ Increase	↑ Enlarge
Good fit	± Fine-tune	± Fine-tune	±fine-tune	±fine-tune

---

Execution Mode

Interactive mode (single-round tuning)

python scripts/tuner.py \
  --data_path ./data.parquet --target y_label \
  --round 1 --output_dir ./outputs/dnn_tuning

AUTO mode (automatic tuning loop)

python scripts/tuner.py \
  --data_path ./data.parquet --target y_label \
  --auto --max_rounds 5 --output_dir ./outputs/dnn_tuning

---

Tuning Strategy

Strategy 1: Anti-overfitting

Applicable Conditions：Train-Val Gap > 0.05

Adjustment Direction：

• dropout: current value + 0.1 (upper limit 0.5)
• weight_decay: current value × 2
• n_layers: current value - 1 (minimum 2)
• layer_width: current value - 32 (minimum 32)

Strategy 2: Enhanced fitting

Applicable Conditions: Val AUC < 0.58 and Gap < 0.03

Adjustment Direction：

• n_layers: current value + 1 (maximum 4)
• layer_width: current value + 32 (maximum 256)
• weight_decay: current value × 0.5
• learning_rate: current value × 1.2

Strategy 3: Fine-tuning

Applicable Conditions: Gap ∈ [0.03, 0.05], model state is good

Adjustment Direction：

• learning_rate: minor adjustment ±20%
• dropout: minor adjustment ±0.05
• Other parameters remain unchanged

Strategy 4: Convergence Determination

Condition: for 2 consecutive rounds, Val metric improvement < 0.001

Behavior: stop tuning, output final result

---

Output Format Specification

Maintain the same round-by-round diagnostic report format as xgb-tuning.

After each round of tuning,mustoutput the following structured information:

### 第 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，或接受当前结果

---

Relationship with Other Skills

Skill	Responsibility	Relationship
dnn-modeling	Baseline Modeling	Prerequisite: need to first use it to train a baseline model
model-comparison	Multi-algorithm Comparison	Follow-up: can perform fair comparison with XGB/LR
xgb-tuning	XGBoost Parameter Tuning	Parallel: parameter tuning of different algorithms on the same data

---

Notes

1. Data Requirements: the target variable must be 0/1 binary classification
2. Search Acceleration: use during search search_epochs=30, final model uses epochs=100
3. Convergence Determination: automatically stop after 2 consecutive rounds of improvement less than 0.001
4. Maximum Rounds: default maximum 5 rounds
5. Artifact Location: model and report are saved to <output_dir>/models/ and <output_dir>/