超参数猎人

自动保存并从实验结果中学习，从而实现长期、持续的优化，并记住你所有的测试。

HyperparameterHunter为机器学习算法提供了一个包装器，可以保存所有重要数据。通过让HyperparameterHunter完成记录、整理和从你的测试中学习这些繁重的工作，同时继续使用你已经熟悉的库，简化实验和超参数调优的过程。不要让任何一次实验白费，开始以正确的方式进行超参数优化吧。

• 安装: pip install hyperparameter-hunter
• 源码: https://github.com/HunterMcGushion/hyperparameter_hunter
• 文档: https://hyperparameter-hunter.readthedocs.io

特性

• 自动记录实验结果
• 真正基于过往实验信息的超参数优化
• 消除交叉验证循环、预测和评分中的样板代码
• 不再需要担心跟踪超参数、分数或重复运行相同的实验
• 使用你已经喜爱的库和工具

如何使用HyperparameterHunter

不要把HyperparameterHunter看作是仅在需要进行超参数优化时才使用的另一个优化库。当然，它确实能进行优化，但更好的方式是将HyperparameterHunter视为你个人的机器学习工具箱/助手。

理念是立即开始使用HyperparameterHunter。把你所有的基准测试或一次性实验都通过它来运行。

你使用得越多，效果就会越好。如果你只用它来进行优化，它当然也能满足你的需求，但这并没有抓住HyperparameterHunter的核心价值。

如果你在整个项目过程中一直用它来进行实验和优化，那么当你决定进行超参数优化时，HyperparameterHunter已经了解了你之前的所有工作，这时它就能发挥出非凡的作用。与其他库不同，HyperparameterHunter不会从零开始优化，而是会基于你之前通过它运行的所有实验和优化轮次来继续推进。

入门指南

1) 环境:

设置一个环境来组织实验和优化结果。
我们执行的任何实验或优化轮次都会使用当前激活的环境。

from hyperparameter_hunter import Environment, CVExperiment
import pandas as pd
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import StratifiedKFold

data = load_breast_cancer()
df = pd.DataFrame(data=data.data, columns=data.feature_names)
df['target'] = data.target

env = Environment(
    train_dataset=df,  # 也可以添加保留集/测试数据框
    results_path='path/to/results/directory',  # 结果文件将保存的位置
    metrics=['roc_auc_score'],  # 可调用函数，或指向`sklearn.metrics`的字符串
    cv_type=StratifiedKFold,  # 类，或`sklearn.model_selection`中的字符串
    cv_params=dict(n_splits=5, shuffle=True, random_state=32)
)

2) 单个实验:

只需提供模型初始化器和超参数，即可使用你喜欢的库进行实验

# 与 `keras.wrappers.scikit_learn` 使用的格式相同。无需学习新内容
def build_fn(input_shape):  # `input_shape` 已为您计算好
    model = Sequential([
        Dense(100, kernel_initializer='uniform', input_shape=input_shape, activation='relu'),
        Dropout(0.5),
        Dense(1, kernel_initializer='uniform', activation='sigmoid')
    ])  # 所有层的参数（无论是显式指定的还是 Keras 默认值）都会被保存，以供将来使用
    model.compile(optimizer='adam', loss='binary_crossentropy', metrics=['accuracy'])
    return model

experiment = CVExperiment(
    model_initializer=KerasClassifier,
    model_init_params=build_fn,  # 我们会解析您的 `build_fn` 函数，以将超参数以有用且易读的格式保存下来
    model_extra_params=dict(
        callbacks=[ReduceLROnPlateau(patience=5)],  # 使用 Keras 回调函数
        batch_size=32, epochs=10, verbose=0  # 拟合/预测时的参数
    )
)

experiment = CVExperiment(
    model_initializer=LinearSVC,  # （或数十种其他 SK-Learn 算法中的任意一种）
    model_init_params=dict(penalty='l1', C=0.9)  # 对于未提供的关键字参数，将使用默认值并记录下来
)

experiment = CVExperiment(
    model_initializer=XGBClassifier,
    model_init_params=dict(objective='reg:linear', max_depth=3, n_estimators=100, subsample=0.5)
)

experiment = CVExperiment(
    model_initializer=LGBMClassifier,
    model_init_params=dict(boosting_type='gbdt', num_leaves=31, max_depth=-1, min_child_samples=5, subsample=0.5)
)

experiment = CVExperiment(
    model_initializer=CatboostClassifier,
    model_init_params=dict(iterations=500, learning_rate=0.01, depth=7, allow_writing_files=False),
    model_extra_params=dict(fit=dict(verbose=True))  # 将关键字参数传递给 `fit` 方法及其他额外方法
)

experiment = CVExperiment(
    model_initializer=RGFClassifier,
    model_init_params=dict(max_leaf=1000, algorithm='RGF', min_samples_leaf=10)
)

3) 超参数优化：

与实验类似，但如果你想优化超参数，请使用下面导入的类。

from hyperparameter_hunter import Real, Integer, Categorical
from hyperparameter_hunter import optimization as opt

def build_fn(input_shape):
    model = Sequential([
        Dense(Integer(50, 150), input_shape=input_shape, activation='relu'),
        Dropout(Real(0.2, 0.7)),
        Dense(1, activation=Categorical(['sigmoid', 'softmax']))
    ])
    model.compile(
        optimizer=Categorical(['adam', 'rmsprop', 'sgd', 'adadelta']),
        loss='binary_crossentropy', metrics=['accuracy']
    )
    return model

optimizer = opt.RandomForestOptPro(iterations=7)
optimizer.forge_experiment(
    model_initializer=KerasClassifier,
    model_init_params=build_fn,
    model_extra_params=dict(
        callbacks=[ReduceLROnPlateau(patience=Integer(5, 10))],
        batch_size=Categorical([32, 64]),
        epochs=10, verbose=0
    )
)
optimizer.go()

optimizer = opt.DummyOptPro(iterations=42)
optimizer.forge_experiment(
    model_initializer=AdaBoostClassifier,  # (或 SKLearn 的其他数十种算法之一)
    model_init_params=dict(
        n_estimators=Integer(75, 150),
        learning_rate=Real(0.8, 1.3),
        algorithm='SAMME.R'
    )
)
optimizer.go()

optimizer = opt.BayesianOptPro(iterations=10)
optimizer.forge_experiment(
    model_initializer=XGBClassifier,
    model_init_params=dict(
        max_depth=Integer(low=2, high=20),
        learning_rate=Real(0.0001, 0.5),
        n_estimators=200,
        subsample=0.5,
        booster=Categorical(['gbtree', 'gblinear', 'dart']),
    )
)
optimizer.go()

optimizer = opt.BayesianOptPro(iterations=100)
optimizer.forge_experiment(
    model_initializer=LGBMClassifier,
    model_init_params=dict(
        boosting_type=Categorical(['gbdt', 'dart']),
        num_leaves=Integer(5, 20),
        max_depth=-1,
        min_child_samples=5,
        subsample=0.5
    )
)
optimizer.go()

optimizer = opt.GradientBoostedRegressionTreeOptPro(iterations=32)
optimizer.forge_experiment(
    model_initializer=CatBoostClassifier,
    model_init_params=dict(
        iterations=100,
        eval_metric=Categorical(['Logloss', 'Accuracy', 'AUC']),
        learning_rate=Real(low=0.0001, high=0.5),
        depth=Integer(4, 7),
        allow_writing_files=False
    )
)
optimizer.go()

optimizer = opt.ExtraTreesOptPro(iterations=10)
optimizer.forge_experiment(
    model_initializer=RGFClassifier,
    model_init_params=dict(
        max_leaf=1000,
        algorithm=Categorical(['RGF', 'RGF_Opt', 'RGF_Sib']),
        l2=Real(0.01, 0.3),
        normalize=Categorical([True, False]),
        learning_rate=Real(0.3, 0.7),
        loss=Categorical(['LS', 'Expo', 'Log', 'Abs'])
    )
)
optimizer.go()

输出文件结构

以下是一个简单的示例，展示了你的 Experiment 可能会生成的文件结构。有关目录结构和各文件内容的详细说明，请参阅文档中的 文件结构概述 部分。不过，核心要点如下：

1. 每个 Experiment 会在 HyperparameterHunterAssets/Experiments 子目录下创建一个以 experiment_id 命名的文件。
2. 每个 Experiment 还会向 HyperparameterHunterAssets/Leaderboards/GlobalLeaderboard.csv 添加一条记录。
3. 你可以通过 Environment 的 file_blacklist 和 do_full_save 参数来自定义要创建的文件（详见 这里）。

HyperparameterHunterAssets
|   Heartbeat.log
|
└───Experiments
|   |
|   └───Descriptions
|   |   |   <描述实验结果、条件等的文件>.json
|   |
|   └───Predictions<OOF/Holdout/Test>
|   |   |   <包含针对指定数据集的实验预测结果的文件>.csv
|   |
|   └───Heartbeats
|   |   |   <包含实验日志的文件>.log
|   |
|   └───ScriptBackups
|       |   <包含创建该实验的脚本副本的文件>.py
|
└───Leaderboards
|   |   GlobalLeaderboard.csv
|   |   <其他排行榜>.csv
|
└───TestedKeys
|   |   <按 Environment 键命名的文件，包含超参数键>.json
|
└───KeyAttributeLookup
    |   <将实验中使用的复杂对象与其哈希值关联起来的文件>

安装

pip install hyperparameter-hunter

如果你喜欢走在技术前沿，并希望获得最新的功能，请运行：

pip install git+https://github.com/HunterMcGushion/hyperparameter_hunter.git

如果你想为 HyperparameterHunter 做贡献，请从 这里 开始。

我还是不太明白

没关系。不用感到不好意思。这确实有点难以理解。下面是一个示例，说明了各个部分是如何相互关联的：

from hyperparameter_hunter import Environment, CVExperiment, BayesianOptPro, Integer
from hyperparameter_hunter.utils.learning_utils import get_breast_cancer_data
from xgboost import XGBClassifier

# 首先创建一个 `Environment` - 这里定义了实验（以及优化）的执行方式
env = Environment(
    train_dataset=get_breast_cancer_data(target='target'),
    results_path='HyperparameterHunterAssets',
    metrics=['roc_auc_score'],
    cv_type='StratifiedKFold',
    cv_params=dict(n_splits=10, shuffle=True, random_state=32),
)

# 接下来进行一次 `Experiment`
# 这会告诉 HyperparameterHunter 使用当前 `Environment` 中的设置来训练具有这些超参数的模型
experiment = CVExperiment(
    model_initializer=XGBClassifier,
    model_init_params=dict(
        objective='reg:linear',
        max_depth=3
    )
)

# 就这样。无需繁琐的样板代码来拟合模型并记录结果。
# 现在，`Environment` 的 `results_path` 目录中将会出现描述刚刚完成的实验的新文件。

# 现在是有趣的部分。我们将通过首先定义想要使用的 `OptPro`（优化协议）来设置超参数优化。
optimizer = BayesianOptPro(verbose=1)

# 接下来我们要指定要优化的超参数。

# 注意，这里的写法与我们上面的 `experiment` 完全一致
optimizer.forge_experiment(
    model_initializer=XGBClassifier,
    model_init_params=dict(
        objective='reg:linear',  # 我们将其设定为一个常量指导原则——这不是需要优化的参数
        max_depth=Integer(2, 10)  # 与上面的 `experiment` 不同，这里我们提供了一个搜索空间，而不是直接指定一个整数值
    )
)
# 请注意，`max_depth` 的取值范围包含了我们之前 `experiment` 中使用的 `max_depth=3` 这个值

optimizer.go()  # 现在，我们开始运行

assert experiment.experiment_id in [_[2] for _ in optimizer.similar_experiments]
# 在这里，我们验证最初执行的 `experiment` 已被 `optimizer` 找到，并作为学习素材使用
# 你也可以通过控制台看到，`optimizer` 找到了该 `experiment` 的保存文件，并以此为基础开始了优化过程

last_experiment_id = optimizer.current_experiment.experiment_id
# 让我们保存一下刚刚由 `optimizer` 执行的那次实验的 ID

optimizer.go()  # 现在，我们再次启动 `optimizer`……

# 我们可以看到，第二次优化不仅借鉴了我们第一次的 `experiment`，还吸收了第一次优化的结果
assert experiment.experiment_id in [_[2] for _ in optimizer.similar_experiments]
assert last_experiment_id in [_[2] for _ in optimizer.similar_experiments]
# 更令人惊喜的是，这一切都无需我们手动指定要从哪些实验中学习

# 想象一下，当你的超参数优化能够同时借鉴：
# - 你过去的所有实验，以及
# - 你过去的所有优化轮次
# 会变得多么高效？而最棒的是：HyperparameterHunter 能够自动判断哪些实验是兼容的。
# 你无需担心告诉它 KFold=5 和 KFold=10 是不同的，
# 或者 max_depth=12 超出了 max_depth=Integer(2, 10) 的范围。

测试过的库
----------------
* [Keras](https://github.com/HunterMcGushion/hyperparameter_hunter/blob/master/examples/lib_keras_example.py)
* [scikit-learn](https://github.com/HunterMcGushion/hyperparameter_hunter/blob/master/examples/lib_sklearn_example.py)
* [LightGBM](https://github.com/HunterMcGushion/hyperparameter_hunter/blob/master/examples/lib_lightgbm_example.py)
* [CatBoost](https://github.com/HunterMcGushion/hyperparameter_hunter/blob/master/examples/lib_catboost_example.py)
* [XGBoost](https://github.com/HunterMcGushion/hyperparameter_hunter/blob/master/examples/simple_experiment_example.py)
* [rgf_python](https://github.com/HunterMcGushion/hyperparameter_hunter/blob/master/examples/lib_rgf_example.py)
* …更多正在开发中

常见问题/FAQ
------------
以下是一些可能会“坑”到你的地方

### 一般情况：
- **无法向 `OptPro` 提供初始搜索点吗？**
   - 这是故意设计的。如果你希望优化轮次从特定的搜索点开始（这些点尚未被记录），只需在初始化 `OptPro` 之前先执行一次 `CVExperiment`。
   - 假设这两者具有相同的指导性超参数，并且 `Experiment` 符合 `OptPro` 定义的搜索空间，优化器就会找到并读取该 `Experiment` 的结果。
   - 请记住，完成一次后最好移除该 `Experiment`，因为其结果已被保存。如果保留它，优化器会不断重复执行相同的实验。
- **修改了 `HyperparameterHunterAssets` 目录中的内容后，一切都不工作了？**
   - 是的，千万不要这样做。尤其是不要动“Descriptions”、“Leaderboards”或“TestedKeys”这些文件。
   - HyperparameterHunter 会直接读取这些文件来判断当前状态。删除它们或更改内容会导致许多功能失效。

### Keras：
- **无法找到使用简单 Dense/Activation 层的神经网络的相似实验吗？**
   - 这很可能是因为你在使用单独的 `Activation` 层，或者在 `Dense` 层中直接使用 `activation` 参数之间切换造成的。
   - 每一层都被视为一组独立的超参数（同时也是超参数本身），因此对 HyperparameterHunter 来说，以下两种写法并不等价：
      - ```Dense(10, activation='sigmoid')```
      - ```Dense(10); Activation('sigmoid')```
   - 我们正在努力解决这个问题，但目前的应对方法就是保持模型中添加激活层的方式一致：
      - 要么全部使用单独的 `Activation` 层，要么全部在其他层中使用 `activation` 参数，并坚持一种方式。
- **无法同时优化 `model.compile` 中的 `optimizer` 和 `optimizer_params` 吗？**
   - 这是因为 Keras 的不同优化器需要不同的参数。
   - 例如，当 `optimizer=Categorical(['adam', 'rmsprop'])` 时，对应的 `optimizer_params` 可能是两个完全不同的字典。
   - 目前，你只能分别优化 `optimizer` 和 `optimizer_params`。
   - 一个可行的方法是先选择几个你想测试的优化器，而不指定具体的 `optimizer_params` 值。这样每个优化器都会使用其默认参数。
      - 然后你可以选出表现最好的优化器，将其设置为 `optimizer=<最佳优化器>`，再针对你选定的优化器的具体参数调整 `optimizer_params`。

### CatBoost：
- **无法找到 CatBoost 的相似实验吗？**
   - 这可能是因为 CatBoost 模型 `__init__` 方法中预期的参数默认值是在其他地方定义的，而在其函数签名中却被赋予了占位符值 `None`。
   - 因此，如果用户没有显式地提供某个参数的值，HyperparameterHunter 就会认为该参数的默认值确实是 `None`。
   - 显然事实并非如此，但我一直未能找到 CatBoost 实际使用的默认值所在位置。如果有哪位朋友知道如何解决这个问题，请务必告知我！

HyperparameterHunter 快速上手指南

HyperparameterHunter 是一个机器学习实验管理工具，能够自动记录实验结果、组织数据并利用历史实验进行智能超参数优化。它支持 Scikit-Learn、Keras、XGBoost、LightGBM、CatBoost 等主流库，让你无需重复编写交叉验证和评分代码，专注于模型本身。

环境准备

• 系统要求：支持 Windows、Linux 和 macOS。
• Python 版本：建议 Python 3.6 及以上。
• 前置依赖：
  • 基础科学计算库：pandas, numpy, scikit-learn
  • 根据你使用的模型框架安装相应库（如 tensorflow/keras, xgboost, lightgbm, catboost 等）。

安装步骤

使用 pip 进行安装。国内用户推荐使用清华或阿里镜像源以加速下载。

# 使用默认源安装
pip install hyperparameter-hunter

# 推荐：使用清华大学镜像源安装（国内加速）
pip install hyperparameter-hunter -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

HyperparameterHunter 的核心工作流程分为三步：配置环境 -> 运行实验 -> 执行优化。

1. 配置环境 (Environment)

首先初始化一个 Environment，用于定义数据集、评估指标、交叉验证策略以及结果保存路径。所有后续实验都将在此环境中运行。

from hyperparameter_hunter import Environment, CVExperiment
import pandas as pd
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import StratifiedKFold

# 加载示例数据
data = load_breast_cancer()
df = pd.DataFrame(data=data.data, columns=data.feature_names)
df['target'] = data.target

# 初始化环境
env = Environment(
    train_dataset=df,  # 训练数据集 (也可添加 holdout/test 数据)
    results_path='path/to/results/directory',  # 实验结果保存目录
    metrics=['roc_auc_score'],  # 评估指标 (支持 sklearn.metrics 中的函数名或 callable)
    cv_type=StratifiedKFold,  # 交叉验证类型
    cv_params=dict(n_splits=5, shuffle=True, random_state=32)  # 交叉验证参数
)

2. 运行单个实验 (Experimentation)

使用 CVExperiment 运行单次实验。HyperparameterHunter 会自动处理交叉验证循环、预测和评分，并记录所有超参数和结果。以下以 XGBoost 为例：

from xgboost import XGBClassifier

experiment = CVExperiment(
    model_initializer=XGBClassifier,
    model_init_params=dict(
        objective='reg:linear', 
        max_depth=3, 
        n_estimators=100, 
        subsample=0.5
    )
)
# 实验运行完毕后，结果会自动保存到 Environment 指定的目录中

提示：该工具同样支持 Keras, Scikit-Learn, LightGBM, CatBoost 等库，只需更换 model_initializer 和对应的参数即可。

3. 超参数优化 (Optimization)

当需要进行超参数搜索时，利用已积累的实验历史数据进行优化。定义搜索空间（使用 Integer, Real, Categorical），选择优化算法并启动。

from hyperparameter_hunter import Real, Integer, Categorical
from hyperparameter_hunter import optimization as opt
from xgboost import XGBClassifier

# 选择优化算法 (例如：贝叶斯优化)，设置迭代次数
optimizer = opt.BayesianOptPro(iterations=10)

# 定义实验模板及超参数搜索空间
optimizer.forge_experiment(
    model_initializer=XGBClassifier,
    model_init_params=dict(
        max_depth=Integer(low=2, high=20),       # 整数范围
        learning_rate=Real(0.0001, 0.5),         # 浮点数范围
        n_estimators=200,                        # 固定值
        subsample=0.5,                           # 固定值
        booster=Categorical(['gbtree', 'gblinear', 'dart']), # 类别选择
    )
)

# 开始优化
# 注意：优化器会自动读取之前运行过的 Experiment 历史数据，避免从零开始
optimizer.go()

通过上述步骤，你可以轻松实现从单次实验记录到基于历史数据的智能超参数优化的完整流程。