# 超参数搜索

学习率、批大小和训练轮数等超参数会显著影响训练结果。[Trainer.hyperparameter_search()](/docs/transformers/v5.23.0/zh/main_classes/trainer#transformers.Trainer.hyperparameter_search) 通过运行多次试验来寻找最佳组合，每次试验使用一组不同的值，并返回其中表现最好的一个。

每次试验都会使用 `model_init` 初始化一个全新的模型，采样新的超参数，运行完整的训练循环，并向搜索后端报告一个目标值。后端利用每个目标值来指导下一次试验。所有试验完成后，最佳超参数将以 `~trainer.utils.BestRun` 的形式返回。

## 初始化模型

每次试验开始时都使用一个全新的模型，以避免受到之前运行状态的影响。`model_init` 会在每次试验开始时被调用并返回一个新的模型实例，因此每次试验都从相同的初始权重开始。

```py
from transformers import AutoModelForCausalLM

def model_init(trial):
    return AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B")

trainer = Trainer(
    model_init=model_init,
    args=args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
)
```

不要同时传入 `model=` 和 `model_init=`，否则 [Trainer](/docs/transformers/v5.23.0/zh/main_classes/trainer#transformers.Trainer) 会抛出错误。

## 定义搜索空间

创建一个用于定义搜索空间的函数。其格式取决于后端。如果您未定义 `hp_space` 函数，默认搜索将涵盖 `learning_rate`、`num_train_epochs` 和 `per_device_train_batch_size`。

```bash
# install one of these hyperparam search backends
pip install optuna
pip install wandb
pip install ray[tune]
```

[Optuna](https://optuna.readthedocs.io/en/stable/index.html) 是一个用于超参数优化的轻量级框架。

```py
def hp_space(trial):
    return {
        "learning_rate": trial.suggest_float("learning_rate", 1e-6, 1e-4, log=True),
        "per_device_train_batch_size": trial.suggest_categorical("per_device_train_batch_size", [16, 32, 64, 128]),
    }
```

[Ray Tune](https://docs.ray.io/en/latest/tune/index.html) 是一个可扩展的超参数调优库，还可以将试验分布到多台机器上。

```py
from ray import tune

def hp_space(trial):
    return {
        "learning_rate": tune.loguniform(1e-6, 1e-4),
        "per_device_train_batch_size": tune.choice([16, 32, 64, 128]),
    }
```

[Weights & Biases](https://docs.wandb.ai/) 是一个内置超参数搜索功能的实验跟踪平台。它支持贝叶斯、随机和网格搜索策略。

```py
def hp_space(trial):
    return {
        "method": "random",
        "metric": {"name": "objective", "goal": "minimize"},
        "parameters": {
            "learning_rate": {"distribution": "uniform", "min": 1e-6, "max": 1e-4},
            "per_device_train_batch_size": {"values": [16, 32, 64, 128]},
        },
    }
```

## 运行搜索

提供一个可选的 `compute_objective` 函数来定义优化目标。如果存在 `eval_loss`，则默认使用它；否则，默认使用所有指标值的总和。请显式传入一个函数，以避免依赖此回退机制。搜索 `backend` 会在给定的 `direction` 下，针对 `n_trials` 次运行来优化该目标。

```py
def compute_objective(metrics):
    return metrics["eval_loss"]

best_run = trainer.hyperparameter_search(
    hp_space=hp_space,
    compute_objective=compute_objective,
    n_trials=30,               # how many trials to run
    direction="minimize",      # or "maximize" for metrics like accuracy/F1
    backend="optuna",          # "optuna", "ray", or "wandb"
)
```

[hyperparameter_search()](/docs/transformers/v5.23.0/zh/main_classes/trainer#transformers.Trainer.hyperparameter_search) 返回一个 `~trainer.utils.BestRun`，其中包含目标函数值以及最优的超参数组合。

```py
best_run = trainer.hyperparameter_search(...)

best_run.objective        # 0.38  (best eval loss)
best_run.hyperparameters  # {"learning_rate": 5e-5, "num_train_epochs": 4, ...}
```

将最佳超参数应用于 [TrainingArguments](/docs/transformers/v5.23.0/zh/main_classes/trainer#transformers.TrainingArguments)，并在完整数据集上重新训练。

