新的代码仓库！ 正如你可能已经注意到的那样，这个仓库的开发在一段时间内仅限于维护和修复 bug。原因是大家正在共同努力，将 Spearmint 重构为一个新的代码库。这包括算法/理论层面以及工程实现上的改进。你可以在 https://github.com/HIPS/Spearmint 上查看新仓库。请注意，新仓库采用非商业许可，并要求签署贡献者许可协议。如果你不愿意接受该许可，仍然可以自由使用这里的代码（尽管它稍显陈旧）。

Spearmint

Spearmint 是一个用于执行贝叶斯优化的软件包，其算法基于以下论文：

机器学习算法的实用贝叶斯优化
Jasper Snoek, Hugo Larochelle 和 Ryan P. Adams
神经信息处理系统进展, 2012

该代码旨在以自动化的实验方式运行（因此得名“spearmint”），通过迭代调整多个参数，在尽可能少的试验次数内最小化某个目标函数。

Spearmint 是由 哈佛大学 和 多伦多大学 的机器学习研究人员合作开发的成果。

依赖项

本软件包需要以下依赖：

• Python 2.7

• Numpy 版本 1.6.1+ 在 Ubuntu Linux 上，你可以使用以下命令安装该包：

    apt-get install python-numpy
  

• Scipy 版本 0.9.0+ 在 Ubuntu Linux 上，你可以使用以下命令安装该包：

    apt-get install python-scipy
  

• Google Protocol Buffers（用于完全自动化版本）。 请注意，你应该能够从源码编译安装 protocol-buffers，而无需管理员权限。否则，在 Ubuntu Linux 上，你可以使用以下命令安装该包：

    apt-get install python-protobuf
  

而在 Mac 上（如果你使用 homebrew），则可以使用：

	brew install protobuf

然后在 spearmint 子目录下运行以下命令：

	bin/make_protobufs

本软件包已在 Ubuntu Linux（11.0 及以上版本）和 Mac OS X 上进行过测试。

该代码由多个部分组成。它被设计为模块化结构，允许替换不同的“驱动器”和“选择器”模块。“选择器”模块实现了诸如期望改进、UCB 或随机等采集函数。“驱动器”则决定了实验如何在系统上分布和运行。由于该代码旨在并行运行实验（一旦有结果就立即启动新实验），因此需要一定的工程实现。目前的实现位于“spearmint”和“spearmint-lite”子目录中：

Spearmint 旨在自动管理单机或集群环境中的实验启动及相应记录工作。为此，你需要提供一种受支持的语言（当前为 Python 或 Matlab）的“包装器”，以及一个配置文件，详细说明待调优的参数及其取值范围。包装器必须接受参数值，并返回一个你希望针对这些参数最小化的数值。Spearmint 将以一种寻求用最少评估次数（或成本）找到最小值的顺序，反复调用包装器，尝试不同的参数设置。

Spearmint-lite 是代码的精简版。 此版本仅通过一个平面文件驱动，不会自动运行实验。相反，它会提出新的实验方案（可能一次提出多个），并要求用户填写实验结果。这非常适合那些不适合编写包装器的情况（例如，实验根本不涉及代码），或者用户希望对整个过程拥有完全控制权的情形。此外，对 Google protocol buffers 的依赖也被 JSON 替代。

运行自动化代码：Spearmint

了解该代码最简单的方式可能是先看一个示例。要开始一项新实验，你需要创建一个包含包装器脚本和配置文件的目录。 我们为你准备了一个简单的示例，用于优化 examples/braninpy 子目录下的“Braninhoo”基准测试。请查看 config.pb 文件。它以 protocol buffer 格式包含了算法的规范。为了指定你的优化任务，你需要填写 “language”（例如 PYTHON 或 MATLAB）和 “name”（即你要优化的包装器函数名称）这两个变量。

接下来是一份“variables”列表，指定了你希望优化的变量名称、类型和数量。每个变量必须是 FLOAT、INT 或 ENUM 类型，分别对应连续实值参数、整数序列和分类变量。MAX 和 MIN 指定了优化变量的取值范围，而 SIZE 则表示具有这些范围和类型的变量数量。Spearmint 将以字典形式调用你的包装器函数，其中包含按“size”大小排列的各变量值，你可以通过指定的名称来访问它们。

现在请查看 branin.py（即 config.pb 顶部 “name” 变量中指定的包装器）。你会看到该文件包含一个函数 “main(job_id, params)”。你的包装器必须包含此函数，Spearmint 会在调用时传入一个 job_id（对你来说可能并不重要）和一个名为 “params”的字典，其中包含了 Spearmint 计划运行的下一次实验的参数向量。主函数应接收这些参数，并返回一个代表在这些输入下观测到的目标函数值的实数。

要安装 Spearmint，请进入 spearmint 子目录并输入以下命令（通常需要加上 sudo）：

python setup.py install

你应该将 spearmint 子目录添加到你的 PYTHONPATH 环境变量中。需要注意的是，你有时可以省略上述步骤，但可能需要手动将所有相关模块添加到 PYTHONPATH，并通过 main.py 从该目录调用 spearmint。

要运行 Spearmint，请进入 /bin 子目录并输入以下命令：

./spearmint ../examples/braninpy/config.pb --driver=local --method=GPEIOptChooser --method-args=noiseless=1

或者在 /spearmint 子目录中运行：

python main.py --driver=local --method=GPEIOptChooser --method-args=noiseless=1 ../examples/braninpy/config.pb

这将以 GP-EI MCMC 策略运行 Spearmint。代码将依次启动调用包装函数的进程，并轮询结果。

你会看到，代码会打印出当前已知的最佳（即最低）观测值，以及与高斯过程超参数采样和待优化候选点相关的数字序列。“method”参数指定了要使用的采集函数模块，“method-args”则用于传递该采集函数特有的参数。在本例中，由于 Branin 函数是解析函数，我们告诉高斯过程超参数采样过程不要尝试估计噪声。正确设置这一参数对于优化的顺利进行至关重要。如果你的算法是完全确定性的（例如解析函数），那么将其指定为无噪声将显著加快优化速度。然而，如果你的算法并非确定性（正如大多数机器学习算法及昂贵实验通常所具备的特性），则应省略此参数或将其设为 noiseless=0。

让程序运行一段时间后，你会发现当前最佳值逐渐下降，最终达到约 0.39 的最小值。你可以随时通过 Ctrl+C 来终止进程，并且只需重新运行 Spearmint 命令即可从上次中断的地方继续执行。

回到 braninpy 目录，你会看到 Spearmint 生成的若干新文件，用于记录和管理优化过程。其中值得关注的是 trace.csv 文件和 output 目录。“trace.csv”记录了迄今为止所有运行过的实验及其最佳结果（以及该结果对应的实验编号），按时间顺序排列。文件的每一行以 CSV 格式包含以下信息：时间戳、截至该时间戳的最佳观测值、对应的最佳观测值的作业 ID、剩余的潜在候选点数量、正在运行（未完成）的实验数量，以及已完成的实验总数。output 目录则为每个作业 ID 保存了一个文本文件，内容是该作业的输出（标准输出和标准错误）。因此，如果你想查看最佳作业的输出（如 trace.csv 所示），只需在 output 目录中查找对应的 job-id.txt 文件即可。

如果你正在调试代码，或者代码因某种原因崩溃，查看这些文件将非常有帮助。此外，为了方便起见，Spearmint 每次迭代还会生成一个名为 best_job_and_result.txt 的文件，其中包含当前最佳结果、其对应的作业 ID，以及与该结果相关的所有参数名称和取值的完整列表。

我们还提供了一个名为 bin/cleanup 的脚本，用于彻底重启一次实验并删除所有结果及中间文件。只需运行 bin/cleanup <experiment_dir> 即可。

Matlab 代码同样可以使用本工具包进行优化。为此，你需要在 config.pb 文件中指定 “type: Matlab”，并使用一个与 config.pb 中“name”字段一致的 Matlab 包装函数。该包装函数必须定义一个与文件名相同的函数，格式如下：“function result = braninhoo(job_id, params)”。上述示例假设文件名为 “braninhoo.m”。Spearmint 将向该包装函数传递一个作业 ID 和一个名为 “params”的 Matlab 结构体，其字段由 config.pb 中指定的变量决定。有关与上述 Python 示例 brinapy 对应的 Matlab 示例，请参阅 braninhoo 子目录。

若需并行运行多个作业，可在运行 Spearmint 时添加参数：--max-concurrent=<#jobs>。

Spearmint 设计为可在单机多核处理器或多节点集群环境中并行运行。不过，不同环境需要不同的任务队列管理和故障检测机制，因此分别以“驱动器”模块的形式实现。目前提供了两种驱动器模块，用户也可以根据特定环境的需求轻松开发新的驱动器模块（请参阅驱动器子目录中的示例）。

通过使用 --driver=sge 参数，Spearmint 可以在配备 Sun Grid Engine 的系统上运行，并利用 SGE 的队列机制，在多节点集群上以容错方式并行分配实验任务。该模式尤其适用于 Amazon EC2 环境。结合 StarCluster 工具，你可以在几分钟内搭建一个大型集群并开始分配实验任务。

而使用 --driver=local 参数，则可在单台具有多核处理器的机器上运行 Spearmint。该驱动器会在当前机器上直接启动新进程来执行新实验。不过，这种方式无法实现跨多台机器的任务分配。

网页状态页面

使用标志 -w 运行 Spearmint 会启动一个本地 Web 服务器，该服务器将以比命令行界面更加易懂和直观的方式显示有关优化运行的有用信息和统计数据。Spearmint 将提供一个指向状态页面的链接，您可以直接将其粘贴到浏览器窗口中。

运行基础代码：Spearmint-lite

Spearmint-lite 的设计旨在简单易用。要在 spearmint-lite 中运行实验，请按照上述说明创建一个子目录。同样地，braninpy 目录被用作演示示例。在这种情况下，必须以 JSON 格式在 config.json 文件中提供实验规范。您需要将问题表示为一系列 JSON 对象。与上述 Protocol Buffers 格式一样，每个对象都必须包含名称、类型（浮点数、整数或枚举）、最小值、最大值和大小。除此之外无需再指定其他内容。

返回顶级目录并运行：

python spearmint-lite.py braninpy

Spearmint-lite 将执行一次贝叶斯优化迭代，并将结果写入 braninpy 子目录下的 results.dat 文件中。results.dat 文件中的每一行都由空格分隔，格式如下：

<结果> <耗时> <参数列表，顺序与 config.json 中一致>

每次运行 Spearmint 时，它都会提出新的实验并将其追加到 results.dat 文件中。每个新提出的实验都会有一个标记为“pending”的结果和耗时，用字母 P 表示。用户随后需要执行该实验并填写这些值。请注意，如果选择器模块不使用耗时信息（目前只有 GPEIperSecChooser 使用），则可以安全地将耗时设置为任意值。Spearmint 在提出新实验时会基于待处理的实验进行条件判断，因此可以并行进行任意数量的实验。

此外，还提供了一个脚本 cleanup.sh，用于彻底清理实验目录中的所有中间文件和结果，并从头开始重新启动实验。

选择器模块：

选择器模块实现了用于指示 Spearmint 下一步应运行哪个任务的功能。其中一些对应于贝叶斯优化文献中的“采集函数”。Spearmint 接受 --method=ChooserModule 参数，允许轻松切换不同的采集函数。选择器还可以选择性地包含一些参数，这些参数可以通过 --method-args=argument1,argument2,etc 参数传递给 Spearmint。例如，这些参数可能包括要使用的高斯过程超参数样本数量。有关特定选择器的参数说明，请参阅选择器文件中的注释。以下是本软件包中提供的选择器模块描述：

• SequentialChooser: 使用高差异性的 Sobol 序列选择下一个实验。实验按从粗到细的网格顺序依次进行。

• RandomChooser: 实验从单位超立方体中随机采样。

• GPEIOptChooser: 来自论文中的 GP EI MCMC 算法。首先在单位超立方体上的密集网格上对任务进行密集采样，然后根据 EI 准则对最佳候选者进行“微调”优化。

• GPEIperSecChooser: 来自论文中的每秒 EI 值算法。与 GPEIOptChooser 类似，但不同之处在于，点是根据每秒 EI 值准则进行优化和评估的，每个任务都根据预期的实验运行时间进行了加权。

• GPEIChooser: 在单位超立方体上对点进行密集采样，并根据 EI 准则返回最佳点。此方法比 GPEIOptChooser 快得多，在搜索空间被网格密集覆盖的低维情况下表现良好。

重要提示！

在估计噪声时，关于噪声的高斯过程先验假设噪声水平“较低”（例如介于 -1 到 1 之间）。如果实际情况并非如此，请务必对您的函数进行缩放，使其满足这一假设（例如使函数值大致位于 -1 到 1 之间）。否则，算法可能会陷入错误的高噪声模式，从而导致性能不佳。

Spearmint 快速上手指南

Spearmint 是一个用于执行贝叶斯优化（Bayesian Optimization）的 Python 包，旨在通过最少的实验次数自动调整参数以最小化目标函数。它特别适用于机器学习算法的超参数调优。

注意：本仓库为旧版维护版本（基于 Python 2.7）。新版 Spearmint 已迁移至新仓库并采用非商业许可证。如需商业使用或最新特性，请查阅新版；若需自由使用旧代码，可继续参考本指南。

环境准备

系统要求

• 操作系统：Ubuntu Linux (11.0+) 或 Mac OS X
• Python 版本：Python 2.7

前置依赖

请确保安装以下依赖库：

1. Numpy (版本 1.6.1+)

   • Ubuntu: apt-get install python-numpy
   • 国内加速建议：可使用清华或阿里镜像源配置 pip 安装。

2. Scipy (版本 0.9.0+)

   • Ubuntu: apt-get install python-scipy

3. Google Protocol Buffers (用于全自动模式)

   • Ubuntu: apt-get install python-protobuf
   • Mac (Homebrew): brew install protobuf
   • 安装后需在 spearmint 子目录下运行编译命令：bin/make_protobufs

安装步骤

1. 进入 spearmint 子目录。
2. 执行安装命令（可能需要 sudo 权限）：

   python setup.py install
   

3. 配置环境变量： 将 spearmint 子目录添加到 PYTHONPATH 中，或者直接在该项目目录下运行。

基本使用

最简单的方式是运行自带的示例（优化 Branin 基准函数）。

1. 准备配置文件

示例位于 examples/braninpy 目录。核心文件是 config.pb，你需要确认以下字段：

• language: 设置为 PYTHON 或 MATLAB。
• name: 你的包装器函数名（例如 branin）。
• variables: 定义待优化参数的名称、类型（FLOAT/INT/ENUM）、范围（MIN/MAX）和数量（SIZE）。

2. 编写包装器脚本

创建一个 Python 文件（如 branin.py），必须包含名为 main 的函数：

def main(job_id, params):
    # params 是一个字典，包含当前实验的参数值
    # 返回一个需要最小化的实数值
    result = ... 
    return result

3. 运行优化

进入 bin 目录或 spearmint 目录执行以下命令：

方式 A（推荐，从 bin 目录运行）：

./spearmint ../examples/braninpy/config.pb --driver=local --method=GPEIOptChooser --method-args=noiseless=1

方式 B（从 spearmint 目录运行）：

python main.py --driver=local --method=GPEIOptChooser --method-args=noiseless=1 ../examples/braninpy/config.pb

参数说明：

• --driver=local: 在单机多核环境下运行。若在集群环境可使用 --driver=sge。
• --method=GPEIOptChooser: 使用高斯过程 - 期望改进（GP-EI）策略。
• --method-args=noiseless=1: 如果目标函数是确定性的（无噪声解析函数），设为 1 可加速优化；若是随机性实验（如机器学习训练），请去掉此参数或设为 0。

4. 查看结果

• 实时监控：运行时会打印当前最优值。添加 -w 参数可启动本地 Web 服务器查看可视化状态页。
• 结果文件：
  • trace.csv: 记录每次实验的时间戳、当前最优值、任务 ID 等。
  • output/: 包含每个任务的标准输出和错误日志。
  • best_job_and_result.txt: 实时更新的最优结果及对应参数。

5. 清理实验

若要重置实验并删除所有中间文件，运行：

bin/cleanup <experiment_dir>

并行运行

若需在同一台机器上并行运行多个任务，添加参数：

--max-concurrent=<任务数量>