Ray Tune 超参数搜索入门:tune_basic_example 随机搜索与网格搜索实战解析
Ray Tune 超参数搜索入门:tune_basic_example 随机搜索与网格搜索实战解析
本篇指南围绕 Ray Tune 官方基础示例 tune_basic_example 展开,它是理解 Ray Tune 核心 API(Tuner、TuneConfig、param_space、tune.report)的最佳起点。通过逐行剖析该示例,读者将掌握如何定义一个带超参数的目标函数、如何同时使用随机搜索与网格搜索组合搜索空间、如何配置优化指标与采样次数,并在最后通过 ResultGrid 取回最优超参数配置,从而能够快速上手将任意训练流程接入 Tune 进行自动调参。
示例在仓库中的位置
本文对应的关联文档是 doc/source/tune/examples/includes/tune_basic_example.rst,该 RST 文件通过 Sphinx 的 literalinclude 指令直接内嵌了位于 python/ray/tune/examples/tune_basic_example.py 的完整源码,文档本身不再重复书写代码,从而保证文档与可运行示例始终同步。因此,本文以下所有代码解析均以该 Python 文件为事实依据。
示例解决的问题
超参数搜索的本质是:给定一组超参数取值空间,反复运行同一训练流程,比较不同配置下的目标指标,最终选出最优配置。本示例用一段带 time.sleep(0.1) 的模拟计算函数代替真实模型训练,使得整个过程可以在几十秒内完成,重点展示的是 Tune 的 API 骨架,而非具体算法。
示例同时演示了两种最基础的搜索策略:
- 随机搜索(Random Search):
width、height在给定区间内均匀随机采样; - 网格搜索(Grid Search):
activation在两个离散取值(relu、tanh)上逐一穷举。
按示例注释的说明,二者会组合出 2 * num_samples 个 trial:activation 的每个取值都会被采样一次,而随机参数按 num_samples 次数采样,因此默认配置下共产生 2 * 50 = 100 个 trial。
训练目标函数与 tune.report
示例把"训练"拆成两个函数:
def evaluation_fn(step, width, height):
time.sleep(0.1)
return (0.1 + width * step / 100) ** (-1) + height * 0.1
def easy_objective(config):
# Hyperparameters
width, height = config["width"], config["height"]
for step in range(config["steps"]):
# Iterative training function - can be any arbitrary training procedure
intermediate_score = evaluation_fn(step, width, height)
# Feed the score back back to Tune.
tune.report({"iterations": step, "mean_loss": intermediate_score})
evaluation_fn模拟"每一步训练后的评估":time.sleep(0.1)模拟计算耗时,返回值是一个关于step、width、height的确定性函数,方便观察不同超参数对结果的影响。easy_objective(config)是 Tune 中的训练目标函数(trainable function),config字典中的每一项超参数(width、height、steps)都由搜索空间注入。- 每一步迭代通过
tune.report(...)把中间指标反馈给 Tune。tune.report的实现位于 python/ray/tune/trainable/trainable_fn_utils.py,从源码可以看到:每次调用都会向 Tune 会话上报一个指标字典,并可选附带 checkpoint;同时每次调用会自动递增training_iteration,其物理含义由用户决定(并不一定对应一个 epoch)。metric名称只需与这里上报的键一致即可,例如示例使用的"mean_loss"。
关键点:
tune.report可以在一个 trial 内多次调用,因此它天然支持"早停式"的中间评估——调度器(如 MedianStopping、HyperBand)可以依据中间指标提前终止表现差的 trial。
主入口与烟雾测试开关
if __name__ == "__main__":
import argparse
parser = argparse.ArgumentParser()
parser.add_argument(
"--smoke-test", action="store_true", help="Finish quickly for testing"
)
args, _ = parser.parse_known_args()
ray.init(configure_logging=False)
- 通过
argparse提供--smoke-test开关:开启后把steps从 100 降到 5、num_samples从 50 降到 5,用于 CI 或本地快速验证流程是否跑通,避免长时间等待。 ray.init(configure_logging=False)启动 Ray 运行时。Tune 运行在 Ray 之上,每个 trial 会作为独立任务分发执行。configure_logging=False只是关闭 Ray 自带的日志配置,不影响 Tune 自身的进度输出。
Tuner、TuneConfig 与 param_space 三元组
核心调用是 Tune 2.x 时代的标准入口 Tuner:
tuner = tune.Tuner(
easy_objective,
tune_config=tune.TuneConfig(
metric="mean_loss",
mode="min",
num_samples=5 if args.smoke_test else 50,
),
param_space={
"steps": 5 if args.smoke_test else 100,
"width": tune.uniform(0, 20),
"height": tune.uniform(-100, 100),
"activation": tune.grid_search(["relu", "tanh"]),
},
)
results = tuner.fit()
Tuner 构造需要三个关键部分:
- 训练目标:
easy_objective,即上文定义的函数; TuneConfig:控制优化目标与采样次数等调参行为;param_space:声明超参数搜索空间。
TuneConfig 关键字段
TuneConfig 定义在 python/ray/tune/tune_config.py,本示例使用了其中三个字段:
| 字段 | 示例取值 | 作用 |
|---|---|---|
metric |
"mean_loss" |
优化的目标指标,须与 tune.report 上报的键一致;设置后会传递给搜索算法与调度器 |
mode |
"min" |
目标是最小化还是最大化该指标,取值 min 或 max |
num_samples |
50(烟雾测试为 5) |
从搜索空间采样的次数,默认值为 1;若存在 grid_search,网格会被重复 num_samples 次;若为 -1 则持续生成样本直至命中停止条件 |
从源码可以看到 TuneConfig 还支持 search_alg(搜索算法,默认随机搜索)、scheduler(调度器,默认 FIFO,可选 MedianStopping、AsyncHyperBand、HyperBand、PopulationBasedTraining 等)、max_concurrent_trials(并发 trial 上限)、time_budget_s(全局时间预算,到点停止所有 trial)、reuse_actors(跨 trial 复用 actor,可显著加速频繁启停 actor 的实验)等字段,进阶调参时可按需启用。
param_space 中三类参数
示例的 param_space 恰好展示了 Tune 搜索空间的三类典型用法:
- 常量参数:
"steps": 100直接给定一个确定值,每个 trial 都用同样的值,不参与搜索; - 连续随机采样:
tune.uniform(0, 20)、tune.uniform(-100, 100)分别对应width、height,在每个 trial 中从区间内均匀采样一个浮点数; - 离散网格穷举:
tune.grid_search(["relu", "tanh"])保证列表中的每个值都会被采样。
随机采样 API
tune.uniform 等搜索空间函数定义在 python/ray/tune/search/sample.py,示例用到的及常用的还包括:
tune.uniform(lower, upper):区间内均匀采样浮点数,等价于np.random.uniform(lower, upper);tune.quniform(lower, upper, q):均匀采样并按q量化取整,量化后上界变为包含;tune.loguniform(lower, upper):在对数量级上均匀采样,适合学习率这类跨越多个数量级的参数;tune.choice(categories):从离散序列中等概率选择一个,等价于np.random.choice;tune.randint(lower, upper):整数均匀采样,lower包含、upper不包含,等价于np.random.randint;tune.lograndint(lower, upper):整数对数均匀采样。
grid_search 的组合规则
tune.grid_search(values) 定义在 python/ray/tune/search/variant_generator.py。从源码文档可以确认两条重要规则:
- 网格中的值保证被采样——这是网格搜索与随机搜索的本质区别,适合需要穷举验证的少数离散维度;
- 多个网格搜索变量会做笛卡尔积组合——例如
x: grid_search([10, 20])与y: grid_search(["a", "b", "c"])会生成 6 个组合样本;此时若num_samples=4,则每个组合各跑 4 次,共 24 个 trial。
本示例只有一个网格维度(activation 两个取值),因此总数就是 2 * num_samples。
从 ResultGrid 取回最优结果
print("Best hyperparameters found were: ", results.get_best_result().config)
tuner.fit() 返回一个 ResultGrid 对象,其 get_best_result() 依据 TuneConfig 中的 metric 与 mode(即最小化 mean_loss)自动返回表现最优的 trial 结果,.config 即该最优 trial 实际使用的超参数配置。因此程序结束时输出形如:
Best hyperparameters found were: {'width': 0.40, 'height': -0.62, 'steps': 100, 'activation': 'relu'}
这验证了搜索有效性:由于 mean_loss = (0.1 + width * step / 100) ** (-1) + height * 0.1,width 越小、height 越负,最终 mean_loss 越小,最优结果正是向该方向收敛的取值。
如何运行与验证
在已安装 Ray(含 Tune,Tune 随 pip install ray[tune] 或完整 ray 包一起提供)的环境下:
# 快速验证:约 5 * 5 = 25 个 trial,每个 trial 5 步
python python/ray/tune/examples/tune_basic_example.py --smoke-test
# 完整实验:默认 2 * 50 = 100 个 trial,每个 trial 100 步
python python/ray/tune/examples/tune_basic_example.py
运行过程中终端会输出 Tune 的实时进度表(每个 trial 的 mean_loss、迭代次数、状态等),结束后打印最优超参数。示例同目录下还有更多进阶示例可对照学习(见 python/ray/tune/examples),例如 hyperband_example.py(调度器早停)、pbt_example.py(种群训练)等;Tune 的入门教程与 API 文档位于 doc/source/tune。
小结
tune_basic_example 虽短,却完整覆盖了 Ray Tune 最小可用闭环:定义目标函数 → 声明搜索空间 → 配置优化目标 → 拟合取回最优结果。把 easy_objective 内部的模拟计算替换为真实模型训练循环,并在 tune.report 中上报验证损失,即可将任意 PyTorch、TensorFlow 或纯 NumPy 训练流程升级为分布式超参数搜索任务——这正是 Ray Tune 作为通用调参框架的核心价值。