Optuna-超参搜索

1. 方法概述

Optuna-超参搜索 的真实核心位于 core/optuna_calculator.py。虽然目录名很宽泛，但这份实现实际上是一个随机森林超参数搜索器，而不是任意模型的通用 Optuna 框架。

它只支持两种 estimator：

• RandomForestClassifier
• RandomForestRegressor

设数据集为

$$ \mathcal{D}=\{(x_i,y_i)\}_{i=1}^{N} \tag{1} $$

其中 \(x_i\) 是特征向量，\(y_i\) 是目标值。程序先做交叉验证搜索，再用最优参数在训练集上拟合并在测试集评估。

2. 数据约束与预处理

2.1 特征列与目标列

除目标列外，其余所有列都被当成特征：

$$ X=\mathcal{D}\backslash\{y\},\qquad y=\mathcal{D}[\text{target\_column}] \tag{2} $$

这套实现不区分类别特征和数值特征，也没有单独的预处理流水线。

2.2 全数值要求

代码会对全部特征列执行：

$$ \tilde X=\mathrm{to\_numeric}(X) \tag{3} $$

也就是 X_raw.apply(pd.to_numeric, errors="coerce")。随后：

• 如果出现 NaN，直接报错；
• 如果出现非有限值（inf/-inf），直接报错。

因此这个模块只接受全数值、无缺失、无无穷大的特征矩阵。它不做缺失值填补，也不做 One-Hot 编码。

对目标列的约束则是：

• 分类任务：不能缺失，至少 2 个类别，且每类至少 2 条样本；
• 回归任务：必须能转成数值，且不能有非法值。

3. 搜索空间与目标函数

3.1 固定搜索空间

搜索空间不是由 UI 自定义输入，而是写死在 _trial_to_params() 中。设超参数向量为

$$ \theta=(n_{\text{estimators}},d_{\max},s_{\text{split}},s_{\text{leaf}},m_{\text{feat}}) \tag{4} $$

其真实范围为：

• n_estimators ∈ [50, 300]
• max_depth ∈ [2, 20]
• min_samples_split ∈ [2, 10]
• min_samples_leaf ∈ [1, 5]
• max_features ∈ {"sqrt", "log2", None}

所以这不是任意模型的通用搜索器，而是“随机森林 5 维超参数搜索”。

3.2 交叉验证目标

Optuna 试验的目标值定义为交叉验证平均分：

$$ f(\theta)=\frac{1}{K}\sum_{k=1}^{K}\mathrm{Score}\big(\mathrm{RF}_\theta,\mathcal{D}^{(k)}_{\text{train}},\mathcal{D}^{(k)}_{\text{valid}}\big) \tag{5} $$

其中 cv=K 由界面参数指定。

评分函数是固定的：

• 分类任务：accuracy
• 回归任务：r2

也就是说，这个模块并不允许用户切换 f1、roc_auc、mse 等 Optuna 目标。

4. Optuna 与随机回退

4.1 Optuna 路径

如果环境中成功导入 optuna，程序会建立：

• optuna.create_study(direction="maximize")
• 若设置了随机种子，则 sampler 为 TPESampler(seed=...)

因此真实搜索器是 Optuna 的 TPE，而不是 CMA-ES、Grid、RandomSampler 等别的 sampler。

4.2 无 Optuna 时的回退

若 import optuna 失败，代码不会中止，而是自动走 _random_search_fallback()。也就是说：

$$ \text{engine}= \begin{cases} \text{Optuna(TPE)}, & \text{if optuna is available}\\ \text{Random Search}, & \text{otherwise} \end{cases} \tag{6} $$

这个回退逻辑在 UI 层没有单独强调，所以从论文说明角度必须写清：目录名虽然叫 Optuna，但运行环境缺少 optuna 时，真实算法会变成随机搜索。

5. 数据划分与最终评估

5.1 训练/测试划分

找到最优参数后，程序再做一次 train_test_split()：

$$ \mathcal{D}_{\text{train}}\cup\mathcal{D}_{\text{test}}=\mathcal{D} \tag{7} $$

其中测试集比例来自 test_size。分类任务会使用 stratify=y，回归任务不分层。

代码还会在运行前检查：

• cv <= 样本数
• 分类任务时 cv <= 最小类别样本数
• test_size 不会让训练/测试样本数小于类别数

5.2 分类指标

分类任务最终导出：

$$ \mathrm{Accuracy}=\frac{1}{|\mathcal{D}_{\text{test}}|}\sum_i \mathbf{1}(\hat y_i=y_i) \tag{8} $$

以及：

• f1_weighted
• f1_macro

其中 best_score_cv 是交叉验证 accuracy，test_score 与 accuracy 相同。

5.3 回归指标

回归任务最终导出：

$$ \mathrm{MSE}=\frac{1}{n}\sum_{i=1}^{n}(y_i-\hat y_i)^2 \tag{9} $$

$$ \mathrm{RMSE}=\sqrt{\mathrm{MSE}} \tag{10} $$

$$ \mathrm{MAE}=\frac{1}{n}\sum_{i=1}^{n}|y_i-\hat y_i| \tag{11} $$

$$ R^2=1-\frac{\sum_i(y_i-\hat y_i)^2}{\sum_i(y_i-\bar y)^2} \tag{12} $$

其中：

• best_score_cv 对应交叉验证 r2
• test_score 对应测试集 r2

6. 输出结果与复现

6.1 Excel 工作表

save_to_excel() 的真实输出工作表为：

• RawData
• Processed
• TestPreds
• BestParams
• Metrics
• Parameters
• Trials
• Charts

其中：

• Processed 是目标列与数值化后的特征表拼接结果；
• BestParams 以两列表形式保存最优超参数；
• Metrics 保存 best_score_cv、测试集指标等；
• Trials 保存每次试验的 number/value/params_*。

6.2 图表

该模块会生成一张 optimization_history.png。它不是 Optuna 官方可视化组件画出来的，而是 save_to_excel() 里用 PIL.Image 手动画的折线图：

• 蓝线：每次 trial 的得分
• 绿线：cummax 形成的历史最优轨迹

6.3 复现脚本

结果页会导出 repro_optuna.py。这个脚本会：

• 把输入数据复制到 repro_inputs/
• 重新构造 OptunaCalculator
• 复跑 calc.run()
• 再导出 optuna_repro.xlsx

所以复现脚本调用的仍然是当前这个“随机森林 + Optuna/TPE 或随机回退”的实现。

7. 实现说明与注意事项

从真实代码出发，这个模块在论文说明里应明确写出以下边界：

1. 它不是通用超参搜索平台，而是随机森林专用搜索器。
2. 输入特征必须全部可转成数值，且不能有缺失值或无穷大；没有类别编码、缺失值填补和标准化。
3. 搜索指标固定为分类 accuracy / 回归 r2，不能在界面上更换。
4. 环境里没有 optuna 时，会自动退化成随机搜索。
5. Trials 工作表在 Optuna 模式和随机回退模式下列名保持相近，但本质上一个来自 study.trials_dataframe()，一个来自手工记录的随机试验表。

8. 论文写作模板

8.1 方法描述模板

可在论文“方法部分”中写为：

“本文采用 Optuna 超参数优化方法对随机森林模型进行自动调参。首先，对数据执行数值校验并构造交叉验证评估方案；其次，在设定的参数搜索空间内，由 Optuna 逐轮采样参数组合并训练随机森林模型；随后，以交叉验证平均指标作为优化目标，持续更新当前最优参数组合及其性能表现；最后，输出最优参数、trial 搜索历史和性能轨迹图，用于分析参数搜索过程和最优模型效果。”

8.2 结果解释模板

结果部分可写为：Optuna 在多轮 trial 中逐步逼近最优参数区域，并以 best_score_cv 反映交叉验证下的最优性能。若最优分数在前若干 trial 后趋于稳定，则说明搜索空间已被较充分探索；若最优参数在不同运行中波动较大，则应讨论搜索随机性与参数敏感性。

8.3 表格标题模板

表题可写为：Optuna 超参数搜索最优结果与 trial 统计表。

8.4 图表题注模板

图注可写为：Optuna trial 过程中最优分数演化曲线。

8.5 表格示例

建议列名：trial 编号、参数组合、交叉验证分数、当前最优分数、最优参数、测试集指标。

9. 论文写作建议

论文中建议把 Optuna 结果至少拆成三部分展示：

1. 参数搜索空间；
2. 最优参数与最优交叉验证分数；
3. Trial 历史与收敛曲线。

若运行环境实际退化成随机搜索，正文里应如实说明，不宜继续直接写成“采用 Optuna 完成搜索”。对随机森林而言，也建议把最终测试集性能与最优搜索分数分开报告。

10. 单篇终审补充

10.1 图题与表题对齐建议

当前 Optuna 模块的真实工作簿包含：

• RawData
• Processed
• TestPreds
• BestParams
• Metrics
• Parameters
• Trials
• Charts

其中 Trials 是最适合在论文中体现搜索轨迹的结果表，BestParams 和 Metrics 则适合作为正文最优结果汇总。不要把 Processed 写成完整训练流水线输出矩阵，当前实现只是数值化后的特征与目标拼接结果。

当前图只有一张：

• optimization_history.png

因此图题建议写成“Optuna trial 得分与历史最优轨迹图”。这张图虽然名字叫 optimization_history，但它不是 Optuna 官方可视化组件直接生成的，而是项目内手工绘制。

10.2 终审说明

这篇文档最需要强调的工程事实，是它本质上是“随机森林专用搜索器”，且环境缺少 optuna 时会退化为随机搜索。因此论文里若写“采用 Optuna 完成超参数优化”，必须先确认实际运行时没有走回退路径。

另外，当前 repro 脚本的输入口径是 DATA_CSV = 'repro_inputs/optuna_repro_data.csv'，不是单一 INPUT_FILE。这意味着它采用的是“结果目录相对路径 + 固定副本文件名”的新框架复现逻辑。

10.3 全量强化补充

本篇终审补充绑定的真实算法目录为 具体的算法3/可解释与AutoML/Optuna-超参搜索，本次采用的代表性结果目录为 具体的算法3/可解释与AutoML/Optuna-超参搜索/results/Optuna-超参搜索分析结果_20260323_210528。该目录里同时保留了一份主结果工作簿和一份 repro 再生产物工作簿。

目录下实际存在：

• 具体的算法3/可解释与AutoML/Optuna-超参搜索/results/Optuna-超参搜索分析结果_20260323_210528/optuna_results_20260323_210528.xlsx
• 具体的算法3/可解释与AutoML/Optuna-超参搜索/results/Optuna-超参搜索分析结果_20260323_210528/optuna_repro.xlsx
• 具体的算法3/可解释与AutoML/Optuna-超参搜索/results/Optuna-超参搜索分析结果_20260323_210528/plots/optimization_history.png

两份工作簿实测工作表一致，均包含：

• RawData
• Processed
• TestPreds
• BestParams
• Metrics
• Parameters
• Trials
• Charts

因此这篇文档应明确区分：optuna_results_20260323_210528.xlsx 是该轮主结果工作簿，optuna_repro.xlsx 是同目录下由复现脚本重新产出的再生产物。两者虽然页名一致、尺寸接近，但不能被描述成同一份主结果。

复现实物方面，该目录实际包含：

• 具体的算法3/可解释与AutoML/Optuna-超参搜索/results/Optuna-超参搜索分析结果_20260323_210528/repro_optuna.py
• 具体的算法3/可解释与AutoML/Optuna-超参搜索/results/Optuna-超参搜索分析结果_20260323_210528/repro_inputs/optuna_repro_data.csv

脚本里使用的不是 INPUT_FILE，而是 DATA_CSV = 'repro_inputs/optuna_repro_data.csv'，并将输出固定写到 optuna_repro.xlsx。因此文档中若要说明复现链路，应按 DATA_CSV 这一真实变量口径写，而不要套用别的算法的 INPUT_FILE 模板。

11. 软件实现核查补充（2026-07）

• 当前主结果目录应写作 具体的算法3/可解释与AutoML/Optuna-超参搜索/results/Optuna-超参搜索分析结果_20260323_210528。
• 正文应围绕 RawData、Processed、TestPreds、BestParams、Metrics、Parameters、Trials、Charts 来写。
• 图证应对应 trials_score_curve.png 与 best_score_trajectory.png，并把主结果和 optuna_repro.xlsx 区分开。
• 复现脚本应按 repro_optuna.py + repro_inputs/optuna_repro_data.csv 的口径说明。