Optuna MCP

🚀 Optuna MCP Server

Optuna MCP Server是一个基于Model Context Protocol (MCP)的服务器，它借助Optuna实现自动化优化与分析，能有效提升工作效率，为用户提供便捷的优化解决方案。

🚀 快速开始

Optuna MCP Server在多个场景中都能发挥重要作用，以下是一些具体的使用场景示例：

• 通过大语言模型（LLMs）实现自动化超参数优化。
• 通过聊天界面交互式分析Optuna的优化结果。
• 优化其他MCP工具的输入和输出。

更多详细信息，请查看示例部分。

📦 安装指南

Optuna MCP服务器可以使用uv或Docker进行安装。下面以Claude Desktop作为示例MCP客户端，介绍如何安装Optuna MCP服务器。

使用uv安装

在开始安装过程之前，请先从Astral安装uv。

然后，将Optuna MCP服务器配置添加到MCP客户端。若要将其添加到Claude Desktop中，请依次点击Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.json，并添加以下内容：

{
  "mcpServers": {
    "Optuna": {
      "command": "uvx",
      "args": [
        "optuna-mcp"
      ]
    }
  }
}

此外，你可以使用--storage参数指定Optuna存储，以持久化结果：

{
  "mcpServers": {
    "Optuna": {
      "command": "uvx",
      "args": [
        "optuna-mcp",
        "--storage",
        "sqlite:///optuna.db"
      ]
    }
  }
}

添加完成后，请重新启动Claude Desktop应用程序。有关Claude Desktop的更多信息，请查看快速入门页面。

使用Docker安装

你也可以使用Docker运行Optuna MCP服务器。请确保你的机器上已经安装并运行了Docker。

{
  "mcpServers": {
    "Optuna": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--net=host",
        "-v",
        "/PATH/TO/LOCAL/DIRECTORY/WHICH/INCLUDES/DB/FILE:/app/workspace",
        "optuna/optuna-mcp:latest",
        "--storage",
        "sqlite:////app/workspace/optuna.db"
      ]
    }
  }
}

✨ 主要特性

Optuna MCP提供了以下工具，具体而言，它提供了Optuna的基本功能，如研究（Study）、试验（Trial）、可视化（Visualization）和仪表盘（Dashboard）。由于MCP客户端了解工具列表和每个工具的详细信息，用户无需记忆这些细节。

研究（Study）

• create_study - 使用给定的研究名称和优化方向创建一个新的Optuna研究。如果研究已经存在，则直接加载。
  • study_name : 研究名称（字符串，必需）。
  • directions : 优化方向（由字面字符串minimize/maximize组成的列表，可选）。
• set_sampler - 为研究设置采样器。
  • name : 采样器名称（字符串，必需）。
• get_all_study_names - 从存储中获取所有研究名称。
• set_metric_names - 设置指标名称。指标名称用于区分每个目标值的标签。
  • metric_names : 每个目标的指标名称列表（字符串列表，必需）。
• get_metric_names - 获取指标名称。
  • 无需参数。
• get_directions - 获取研究的优化方向。
  • 无需参数。
• get_trials - 以CSV格式获取所有试验。
  • 无需参数。
• best_trial - 获取最佳试验。
  • 无需参数。
• best_trials - 返回研究中位于帕累托前沿的试验。
  • 无需参数。

试验（Trial）

• ask - 使用Optuna建议新的参数。
  • search_space : Optuna的搜索空间（字典，必需）。
• tell - 报告试验结果。
  • trial_number : 试验编号（整数，必需）。
  • values : 试验结果（浮点数或浮点数列表，必需）。
• set_trial_user_attr - 为试验设置用户属性。
  • trial_number : 试验编号（整数，必需）。
  • key : 用户属性的键（字符串，必需）。
  • value : 用户属性的值（任意类型，必需）。
• get_trial_user_attrs - 获取试验中的用户属性。
  • trial_number : 试验编号（整数，必需）。

可视化（Visualization）

• plot_optimization_history - 以图像形式返回优化历史图。
  • target : 指定要显示的值的索引（整数，可选）。
  • target_name : 要在轴标签上显示的目标名称（字符串，可选）。
• plot_hypervolume_history - 以图像形式返回超体积历史图。
  • reference_point : 用于计算超体积的参考点列表（浮点数列表，必需）。
• plot_pareto_front - 以图像形式返回多目标优化的帕累托前沿图。
  • target_names : 用作轴标题的目标名称列表（字符串列表，可选）。
  • include_dominated_trials : 包含所有被支配试验的目标值的标志（布尔值，可选）。
  • targets : 指定要显示的目标值的索引列表（整数列表，可选）。
• plot_contour - 以图像形式返回等高线图。
  • params : 要可视化的参数列表（字符串列表，可选）。
  • target : 指定要显示的值的索引（整数，必需）。
  • target_name : 要在颜色条上显示的目标名称（字符串，必需）。
• plot_parallel_coordinate - 以图像形式返回平行坐标图。
  • params : 要可视化的参数列表（字符串列表，可选）。
  • target : 指定要显示的值的索引（整数，必需）。
  • target_name : 要在轴标签和图例上显示的目标名称（字符串，必需）。
• plot_slice - 以图像形式返回切片图。
  • params : 要可视化的参数列表（字符串列表，可选）。
  • target : 指定要显示的值的索引（整数，必需）。
  • target_name : 要在轴标签上显示的目标名称（字符串，必需）。
• plot_param_importances - 以图像形式返回参数重要性图。
  • params : 要可视化的参数列表（字符串列表，可选）。
  • target : 指定要显示的值的索引（整数/空，可选）。
  • target_name : 要在图例上显示的目标名称（字符串，必需）。
• plot_edf - 以图像形式返回经验分布函数（EDF）图。
  • target : 指定要显示的值的索引（整数，必需）。
  • target_name : 要在轴标签上显示的目标名称（字符串，必需）。
• plot_timeline - 以图像形式返回时间线图。
  • 无需参数。
• plot_rank - 以图像形式返回排名图。
  • params : 要可视化的参数列表（字符串列表，可选）。
  • target : 指定要显示的值的索引（整数，必需）。
  • target_name : 要在颜色条上显示的目标名称（字符串，必需）。

网络仪表盘（Web Dashboard）

• launch_optuna_dashboard - 启动Optuna仪表盘。
  • port : 服务器端口（整数，可选，默认值：58080）。

💻 使用示例

基础用法

优化二维球面函数

以下是一个优化二维球面函数的简单示例，同时展示了示例提示和大语言模型（LLM）响应的摘要：

启动Optuna仪表盘并分析优化结果

你还可以通过MCP服务器启动Optuna仪表盘，以交互式方式分析优化结果。

默认情况下，Optuna仪表盘将在端口58080上启动。你可以在Web浏览器中访问http://localhost:58080，如下所示：

Optuna仪表盘提供了各种可视化工具，用于分析优化结果，如优化历史、参数重要性等。

优化FFmpeg编码参数

此演示展示了如何使用Optuna MCP服务器自动找到最佳的FFmpeg编码参数。它优化x264编码选项，以在保证合理编码时间的同时，最大化视频质量（通过SSIM分数衡量）。

详细信息请查看examples/ffmpeg.md。

优化饼干配方

在这个示例中，我们将优化一个饼干配方，参考了题为"Bayesian Optimization for a Better Dessert"的论文。

详细信息请查看examples/cookie-recipe。

优化Matplotlib配置

此示例优化了Matplotlib配置。

详细信息请查看examples/auto-matplotlib。

📄 许可证

本项目采用MIT许可证（请参阅LICENSE）。