Optuna：超参数优化框架

:link: 官网 | :page_with_curl: 文档 | :gear: 安装指南 | :pencil: 教程 | :bulb: 示例 | Twitter | LinkedIn | Medium

Optuna 是一个自动超参数优化软件框架，专为机器学习设计。它采用命令式、即“运行时定义”的用户 API。得益于这种“运行时定义”的 API，使用 Optuna 编写的代码具有很高的模块化特性，用户可以动态地构建超参数的搜索空间。

:loudspeaker: 最新消息

帮助我们打造 Optuna 的下一个版本！

Optuna 5.0 路线图已发布，欢迎审阅。请查看 Optuna 计划中的改进内容，并在 GitHub 问题页面上分享您的反馈。我们也欢迎 PR 贡献！

请您抽出几分钟时间填写 这份调查问卷，告诉我们您目前如何使用 Optuna，以及您希望看到哪些改进。🤔 全部问题均为可选。🙇‍♂️

• 2026年3月16日：Optuna 4.8.0 发布！详情请参阅 发布说明。
• 2026年1月19日：Optuna 4.7.0 发布！详情请参阅 发布说明。
• 2025年11月10日：一篇新文章 宣布 Optuna 4.6 已发布。
• 2025年10月28日：一篇新文章 AutoSampler：全面支持多目标与约束优化 已发布。
• 2025年9月22日：一篇新文章 [Optuna v4.5] 基于高斯过程的采样器 (GPSampler) 现在可以进行约束型多目标优化 已发布。
• 2025年6月16日：Optuna 4.4.0 已发布！详情请参阅 发布博客。

:fire: 核心功能

Optuna 具备以下现代化功能：

• 轻量级、通用且平台无关的架构
  • 通过简单的安装即可处理各种任务，依赖项极少。
• 符合 Python 风格的搜索空间
  • 使用熟悉的 Python 语法（包括条件语句和循环）定义搜索空间。
• 高效的优化算法
  • 采用最先进的算法来采样超参数，并高效地剪枝无望的试验。
• 易于并行化
  • 只需对代码进行少量或无需修改，即可将研究扩展到数十甚至数百个工作者。
• 快速可视化
  • 通过多种绘图函数检查优化历史。

基本概念

我们使用以下术语：study 和 trial：

• Study：基于目标函数的优化
• Trial：目标函数的一次执行

请参考下面的示例代码。Study 的目标是通过多次 Trial（例如 n_trials=100）找到最优的超参数组合（如 regressor 和 svr_c）。Optuna 是一个旨在自动化和加速优化 Study 的框架。

import optuna
import sklearn


# 定义一个需要最小化的目标函数。
def objective(trial):

    # 调用 Trial 对象的建议方法生成超参数。
    regressor_name = trial.suggest_categorical("regressor", ["SVR", "RandomForest"])
    if regressor_name == "SVR":
        svr_c = trial.suggest_float("svr_c", 1e-10, 1e10, log=True)
        regressor_obj = sklearn.svm.SVR(C=svr_c)
    else:
        rf_max_depth = trial.suggest_int("rf_max_depth", 2, 32)
        regressor_obj = sklearn.ensemble.RandomForestRegressor(max_depth=rf_max_depth)

    X, y = sklearn.datasets.fetch_california_housing(return_X_y=True)
    X_train, X_val, y_train, y_val = sklearn.model_selection.train_test_split(X, y, random_state=0)

    regressor_obj.fit(X_train, y_train)
    y_pred = regressor_obj.predict(X_val)

    error = sklearn.metrics.mean_squared_error(y_val, y_pred)

    return error  # 与 Trial 对象关联的目标值.


study = optuna.create_study()  # 创建一个新的 study。
study.optimize(objective, n_trials=100)  # 调用目标函数的优化。

[!NOTE] 更多示例可在 optuna/optuna-examples 中找到。

这些示例涵盖了多种问题设置，如多目标优化、约束优化、剪枝以及分布式优化。

安装

Optuna 可在 Python 包索引 和 Anaconda Cloud 上获取。

# PyPI
$ pip install optuna

# Anaconda Cloud
$ conda install -c conda-forge optuna

[!IMPORTANT] Optuna 支持 Python 3.9 及以上版本。

集成

Optuna 提供了与多种第三方库的集成功能。这些集成可以在 optuna/optuna-integration 中找到，相关文档请参见 这里。

Web 仪表盘

Optuna Dashboard 是一个用于 Optuna 的实时 Web 仪表盘。 您可以通过图表和表格查看优化历史、超参数重要性等信息。 无需编写 Python 脚本来调用 Optuna 的可视化 函数。 欢迎提出功能请求和报告 bug！

optuna-dashboard 可以通过 pip 安装：

$ pip install optuna-dashboard

[!提示] 请使用下面的示例代码体验 Optuna Dashboard 的便捷性。

import optuna


def objective(trial):
    x1 = trial.suggest_float("x1", -100, 100)
    x2 = trial.suggest_float("x2", -100, 100)
    return x1**2 + 0.01 * x2**2


study = optuna.create_study(storage="sqlite:///db.sqlite3")  # 创建一个新的带有数据库的研究
study.optimize(objective, n_trials=100)

# 运行上述研究
$ python optimize_toy.py

# 基于存储 `sqlite:///db.sqlite3` 启动仪表盘
$ optuna-dashboard sqlite:///db.sqlite3
...
正在监听 http://localhost:8080/
按 Ctrl-C 退出。

OptunaHub

OptunaHub 是一个用于分享 Optuna 功能的平台。 您可以使用已注册的功能，并发布自己的软件包。

使用已注册的功能

optunahub 可以通过 pip 安装：

$ pip install optunahub
# 安装 AutoSampler 的依赖（对于 PyTorch 来说，仅 CPU 版本就足够了）
$ pip install cmaes scipy torch --extra-index-url https://download.pytorch.org/whl/cpu

您可以使用 optunahub.load_module 加载已注册的模块。

import optuna
import optunahub


def objective(trial: optuna.Trial) -> float:
    x = trial.suggest_float("x", -5, 5)
    y = trial.suggest_float("y", -5, 5)
    return x**2 + y**2


module = optunahub.load_module(package="samplers/auto_sampler")
study = optuna.create_study(sampler=module.AutoSampler())
study.optimize(objective, n_trials=10)

print(study.best_trial.value, study.best_trial.params)

更多详情，请参阅 optunahub 文档。

发布您的软件包

您可以通过 optunahub-registry 发布您的软件包。 请参阅 OptunaHub 中的 贡献者教程。

沟通

• GitHub Discussions 用于提问。
• GitHub Issues 用于报告 bug 和提出功能请求。

贡献

我们非常欢迎对 Optuna 的任何贡献！

如果您是 Optuna 的新手，请查看 good first issues。这些问题相对简单、定义明确，通常是您熟悉贡献流程和其他开发人员的好起点。

如果您已经为 Optuna 做过贡献，我们建议您关注其他 contribution-welcome issues。

有关如何为项目做出贡献的通用指南，请参阅 CONTRIBUTING.md。

参考文献

如果您在某个研究项目中使用了 Optuna，请引用我们的 KDD 论文 “Optuna：下一代超参数优化框架”：

@inproceedings{akiba2019optuna,
  title={{O}ptuna: A Next-Generation Hyperparameter Optimization Framework},
  author={Akiba, Takuya and Sano, Shotaro and Yanase, Toshihiko and Ohta, Takeru and Koyama, Masanori},
  booktitle={The 25th ACM SIGKDD International Conference on Knowledge Discovery \& Data Mining},
  pages={2623--2631},
  year={2019}
}

许可证

MIT 许可证（详见 LICENSE）。

Optuna 使用了 SciPy 和 fdlibm 项目的代码（详见 LICENSE_THIRD_PARTY）。

Optuna 快速上手指南

Optuna 是一个专为机器学习设计的自动超参数优化框架。它采用“定义即运行（define-by-run）”的 API 风格，允许用户使用原生 Python 代码（包括条件判断和循环）动态构建搜索空间，具有轻量、高效且易于并行的特点。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.9, 3.10, 3.11, 3.12, 3.13 或 3.14
• 前置依赖：无特殊强制依赖，基础安装仅需 pip 或 conda。若需使用可视化仪表盘或特定深度学习框架集成，请参考后续可选安装部分。

安装步骤

方式一：使用 pip 安装（推荐）

可以使用国内镜像源加速安装：

pip install optuna -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 Conda 安装

conda install -c conda-forge optuna

可选组件安装

• 安装可视化仪表盘 (Optuna Dashboard)：用于实时查看优化历史和超参数重要性。

  pip install optuna-dashboard -i https://pypi.tuna.tsinghua.edu.cn/simple
  

• 安装功能共享平台客户端 (OptunaHub)：用于加载社区分享的采样器等功能模块。

  pip install optunahub -i https://pypi.tuna.tsinghua.edu.cn/simple
  

基本使用

以下示例展示了如何使用 Optuna 结合 scikit-learn 进行最简单的超参数优化。该脚本会自动尝试不同的回归模型（SVR 或 RandomForest）及其对应的超参数，以最小化均方误差。

import optuna
import sklearn


# 定义需要最小化的目标函数
def objective(trial):

    # 使用 trial 对象的 suggest 方法生成超参数
    # 动态选择回归器类型
    regressor_name = trial.suggest_categorical("regressor", ["SVR", "RandomForest"])
    
    if regressor_name == "SVR":
        # 如果是 SVR，搜索 C 参数 (对数空间)
        svr_c = trial.suggest_float("svr_c", 1e-10, 1e10, log=True)
        regressor_obj = sklearn.svm.SVR(C=svr_c)
    else:
        # 如果是随机森林，搜索最大深度
        rf_max_depth = trial.suggest_int("rf_max_depth", 2, 32)
        regressor_obj = sklearn.ensemble.RandomForestRegressor(max_depth=rf_max_depth)

    # 准备数据
    X, y = sklearn.datasets.fetch_california_housing(return_X_y=True)
    X_train, X_val, y_train, y_val = sklearn.model_selection.train_test_split(X, y, random_state=0)

    # 训练与预测
    regressor_obj.fit(X_train, y_train)
    y_pred = regressor_obj.predict(X_val)

    # 计算误差并返回
    error = sklearn.metrics.mean_squared_error(y_val, y_pred)

    return error  # 返回与 Trial 对象关联的目标值


# 创建一个新的研究 (Study)
study = optuna.create_study()

# 执行优化，运行 100 次试验 (Trials)
study.optimize(objective, n_trials=100)

# 输出最佳结果
print(f"最佳试验值：{study.best_trial.value}")
print(f"最佳超参数：{study.best_trial.params}")

核心概念说明

• Study (研究)：基于目标函数进行的优化过程整体。
• Trial (试验)：目标函数的单次执行。Optuna 通过多次 Trial 寻找最优的超参数组合。
• suggest 方法：trial.suggest_* 系列方法用于在定义的范围内采样超参数，支持分类 (categorical)、浮点数 (float) 和整数 (int) 类型。