Hydra Optuna Sweeper 插件使用指南从单目标到多目标超参数优化【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra本指南聚焦 Hydra 官方插件hydra-optuna-sweeper系统讲解如何在 Hydra 应用中接入 Optuna通过--multirun模式自动完成超参数搜索与优化。读完本文你将掌握插件的安装与启用、采样器与搜索空间search space的完整配置语法命令行与配置文件两种方式、单目标与多目标优化的完整实践以及从源码层面理解其运行机制与结果序列化逻辑。插件简介与安装hydra-optuna-sweeper是一个让 Hydra 应用能够调用 Optuna 进行实验参数优化的插件。Optuna 是专注于超参数优化的框架而该插件将其采样、调优能力接入 Hydra 的--multirun批量运行机制从而在保留 Hydra 配置管理能力的同时获得智能的搜索策略。该插件要求hydra-core1.1.0安装前先升级 Hydra 核心pip install hydra-core --upgrade然后通过 pip 安装插件pip install hydra-optuna-sweeper --upgrade关于配置插件的几种标准方式如通过defaults列表、Config Store 注册等可参考仓库文档 配置插件指南。启用 Optuna Sweeper在应用的配置文件或命令行中将 Hydra 的 sweeper 切换为optunadefaults: - override hydra/sweeper: optuna也可以在命令行追加hydra/sweeperoptuna参数完成切换。插件的默认配置定义在 config.py其结构化配置类OptunaSweeperConf通过ConfigStore.instance().store(grouphydra/sweeper, nameoptuna, ...)注册到 Hydra 的配置仓库中见 config.py。核心字段含义如下配置项类型默认值说明samplerSamplerConfigtpe采样算法默认 TPETree-structured Parzen EstimatordirectionDirection/List[Direction]minimize优化方向多目标时传方向列表storageOptional[Any]nullOptuna 存储后端 URL如sqlite:///example.db用于持久化优化结果study_nameOptional[str]null优化研究study的名称n_trialsint20函数评估总次数n_jobsint2并行 worker 数量max_failure_ratefloat0.0单批参数允许的最大失败率0~1paramsOptional[Dict[str, str]]null配置文件形式的搜索空间定义custom_search_spaceOptional[str]null指向自定义搜索空间配置函数的 dotpath可以用以下命令查看当前生效的 sweeper 全部参数python example/sphere.py hydra/sweeperoptuna --cfg hydra -p hydra.sweeper示例 1单目标优化Sphere 基准函数示例目录 plugins/hydra_optuna_sweeper/example 中的sphere.py实现了一个待最小化的简单基准函数。其核心逻辑见 sphere.pyhydra.main(config_pathconf, config_nameconfig) def sphere(cfg: DictConfig) - float: x: float cfg.x y: float cfg.y if cfg.get(error, False): raise RuntimeError(cfg.error is True) return x**2 y**2hydra.main()装饰的函数返回一个 float 作为目标值我们要最小化它。该函数的最小值为 0在x: 0, y: 0处取得。运行优化需在plugins/hydra_optuna_sweeper目录下python example/sphere.py --multirun对应的默认配置输出通过--cfg hydra -p hydra.sweeper可查看如下# package hydra.sweeper sampler: _target_: optuna.samplers.TPESampler seed: 123 consider_prior: true prior_weight: 1.0 consider_magic_clip: true consider_endpoints: false n_startup_trials: 10 n_ei_candidates: 24 multivariate: false warn_independent_sampling: true _target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeper direction: minimize storage: null study_name: sphere n_trials: 20 n_jobs: 1 search_space: x: type: float low: -5.5 high: 5.5 step: 0.5 y: type: categorical choices: - -5 - 0 - 5对应示例仓库中的配置文件 example/conf/config.yaml搜索空间定义在hydra.sweeper.params下x使用range(-5.5, 5.5, step0.5)y使用choice(-5, 0, 5)。也可以在命令行直接覆盖搜索空间参数化方式python example/sphere.py --multirun xinterval(-5.0, 5.0) yinterval(0, 10)优化结束后multirun日志目录下会生成optimization_results.yaml记录最优参数与最优值name: optuna best_params: x: 0.0 y: 0 best_value: 0.0从源码看该文件的序列化逻辑位于 optuna_sweeper.py 中OptunaSweeper类它通过instantiate()实例化采样器白名单限定hydra_plugins.hydra_optuna_sweeper.*与optuna.samplers.*并将实际逻辑委托给OptunaSweeperImpl。单目标情况下sweep()结束时调用study.best_trial取出最优试验写出best_params与best_value见 optuna_sweeper.py。采样器Sampler配置插件支持 Optuna 的全部采样器。可通过覆盖hydra/sweeper/sampler切换采样器类型或在hydra.sweeper.sampler下调整其内部参数。从 config.py 可以看出插件以结构化配置方式预注册了以下采样器均挂载在hydra/sweeper/sampler配置组下配置名对应 Optuna 采样器关键参数默认值tpeoptuna.samplers.TPESamplerseedNone、n_startup_trials10、n_ei_candidates24、multivariateFalserandomoptuna.samplers.RandomSamplerseedNonecmaesoptuna.samplers.CmaEsSamplerseedNone、sigma0None、restart_strategyNonensgaiioptuna.samplers.NSGAIISamplerseedNone、population_size50、crossover_prob0.9、swapping_prob0.5gridoptuna.samplers.GridSampler搜索空间在运行时根据hydra.sweeper.params填充_partial_Truegpoptuna.samplers.GPSamplerseedNone、n_startup_trials10qmcoptuna.samplers.QMCSamplerseedNone、qmc_typesobol、scrambleFalse此外由于 Optuna 4.0 移除了motpe采样器插件保留了motpe配置名但将其_target_指向 config.py 中的raise_motpe_removed函数——一旦使用该配置会抛出明确错误提示改用hydra/sweeper/samplertpeTPESampler 已原生支持多目标优化。搜索空间配置Search Space插件支持用 Optuna 的分布distributions来配置搜索空间既可以通过命令行覆盖定义也可以在配置文件中定义。命令行覆盖方式Hydra 提供了语法丰富的覆盖解析器其词法/语法定义位于 hydra/grammar/OverrideLexer.g4 与 hydra/grammar/OverrideParser.g4。三种常用的搜索空间覆盖语法如下。interval 覆盖默认情况下interval被转换为FloatDistribution。将区间端点强制为int并使用log标签可分别得到IntDistribution、LogUniformDistribution语义在 Optuna 当前 API 中体现为IntDistribution(logTrue)/FloatDistribution(logTrue)。python example/sphere.py --multirun xint(interval(-5.0, 5.0)) ytag(log, interval(1, 10))运行输出示例[HYDRA] Study name: sphere [HYDRA] Storage: None [HYDRA] Sampler: TPESampler [HYDRA] Directions: [minimize] [HYDRA] Launching 1 jobs locally [HYDRA] #0 : x-3 y1.6859762540733367 [HYDRA] Launching 1 jobs locally [HYDRA] #1 : x1 y5.237816870668193 ... [HYDRA] Best parameters: {x: 0, y: 1.0929184723430116} [HYDRA] Best value: 1.1944707871885822range 覆盖range默认转换为IntDistribution整数均匀分布。如果对其应用shuffle则改用CategoricalDistribution即先枚举区间内的整数再打乱作为类别选择。python example/sphere.py --multirun xrange(-5.0, 5.0) yshuffle(range(-5, 5))运行输出示例[HYDRA] Study name: sphere [HYDRA] Storage: None [HYDRA] Sampler: TPESampler [HYDRA] Directions: [minimize] [HYDRA] Launching 1 jobs locally [HYDRA] #0 : x-3 y-4 [HYDRA] Launching 1 jobs locally [HYDRA] #1 : x1 y-1 ... [HYDRA] Best parameters: {x: 0, y: -1} [HYDRA] Best value: 1.0choice 覆盖choice被转换为CategoricalDistribution。python example/sphere.py --multirun xchoice(-5.0, 0.0, 5.0) ychoice(0, 1, 2, 3, 4, 5)运行输出示例[HYDRA] Study name: sphere [HYDRA] Storage: None [HYDRA] Sampler: TPESampler [HYDRA] Directions: [minimize] [HYDRA] Launching 1 jobs locally [HYDRA] #0 : x5.0 y5 [HYDRA] Launching 1 jobs locally [HYDRA] #1 : x5.0 y2 ... [HYDRA] Best parameters: {x: 0.0, y: 0} [HYDRA] Best value: 0.0从源码看命令行覆盖到 Optuna 分布的转换逻辑集中在 _impl.py 的create_optuna_distribution_from_override函数中interval结合log标签与端点类型决定分布类型range依据端点/步长是否为 float 决定FloatDistribution或IntDistribution遇shuffle则转CategoricalDistributionchoice直接构造类别分布。配置文件方式配置文件方式支持三类参数字段含义如下。int 参数type:intlow: 下界high: 上界step: 离散化步长可选log: 若为true搜索空间转换到对数域当logfalse时映射为IntUniformDistribution即IntDistribution否则映射为IntLogUniformDistribution即IntDistribution(logTrue)。注意logtrue时不能设置step。float 参数type:floatlow: 下界high: 上界step: 离散化步长log: 若为true搜索空间转换到对数域当logfalse时依据是否存在step字段分别映射为UniformDistribution即FloatDistribution无step或DiscreteUniformDistribution即FloatDistribution(step...)有step否则映射为LogUniformDistribution即FloatDistribution(logTrue)。同样logtrue时不能设置step。categorical 参数type:categoricalchoices: 候选值列表映射为CategoricalDistribution。配置示例对应--cfg hydra -p hydra.sweeper的输出search_space: x: type: float low: -5.5 high: 5.5 step: 0.5 y: type: categorical choices: [-5, 0, 5]固定参数与删除覆盖命令行解析器create_params_from_overrides见 _impl.py还会把非 sweep 覆盖视为固定参数fixed params把~删除覆盖透传为固定覆盖fixed overrides。每个 trial 生成时_configure_trials会调用trial._suggest()采样搜索空间参数、trial.set_user_attr()设置固定参数并检测搜索空间参数与固定参数是否重叠重叠会抛出ValueError。固定参数在创建 study 前会被从 Optuna 搜索空间中移除见 _impl.py确保它们不参与采样。自定义搜索空间扩展除声明式搜索空间外插件还支持通过custom_search_space指向一个 instantiate 风格的 dotpath其签名应为Callable[[DictConfig, optuna.trial.Trial], None]用于在每次 trial 中按 Python 逻辑动态追加参数。仓库示例 example/custom-search-space-objective.py 演示了该能力def configure(cfg: DictConfig, trial: Trial) - None: x_value trial.params[x] trial.suggest_float( z, x_value - cfg.max_z_difference_from_x, x_value cfg.max_z_difference_from_x, ) trial.suggest_float(w, 0.0, 1.0) # note w here, not w as w is a new parameter这里z的取值区间依赖同一个 trial 中已采样的xw前缀表示追加一个全新参数。对应的配置见 example/custom-search-space/config.yaml其中custom_search_space: custom-search-space-objective.configure指向该函数。源码中该函数在 _impl.py 中通过get_method(custom_search_space)解析并在_configure_trials中对每个 trial 调用。示例 2多目标优化Binh-and-Korn 基准函数同一示例目录下的multi-objective.py实现了具有两个目标值的基准函数我们要同时最小化这两个目标。其核心逻辑见 multi-objective.pyhydra.main(config_pathmulti-objective-conf, config_nameconfig) def binh_and_korn(cfg: DictConfig) - Tuple[float, float]: x: float cfg.x y: float cfg.y v0 4 * x**2 4 * y**2 v1 (x - 5) ** 2 (y - 5) ** 2 return v0, v1运行优化在plugins/hydra_optuna_sweeper目录下python example/multi-objective.py --multirun对应的多目标配置通过--cfg hydra -p hydra.sweeper查看# package hydra.sweeper sampler: _target_: optuna.samplers.NSGAIISampler seed: 123 population_size: 50 mutation_prob: null crossover_prob: 0.9 swapping_prob: 0.5 constraints_func: null _target_: hydra_plugins.hydra_optuna_sweeper.optuna_sweeper.OptunaSweeper direction: - minimize - minimize storage: null study_name: multi-objective n_trials: 20 n_jobs: 1 search_space: x: type: float low: 0 high: 5 step: 0.5 y: type: float low: 0 high: 3 step: 0.5对应的仓库配置文件为 example/multi-objective-conf/config.yaml其中通过override hydra/sweeper/sampler: nsgaii切换为多目标演化采样器 NSGA-IIdirection: [minimize, minimize]声明两个目标均最小化。对于目标之间存在权衡trade-off的问题往往不存在同时最小化两个目标的单一解而是得到一组最优解即 Pareto 最优解它们展示了各目标之间可能的最佳权衡。下图蓝点即为优化结果中的 Pareto 最优解多目标优化示例中的 Pareto 最优解蓝点为 Pareto 前沿从源码看多目标分支的处理在 _impl.py当direction数量大于 1 时sweeper 不再取单一best_trial而是收集study.best_trials组成 Pareto 前沿序列化到optimization_results.yaml的solutions字段每个解包含params与values并在日志中输出 Pareto 解的数量与明细。相应地被优化的任务函数必须返回与目标数量一致的 float 可转换值列表/元组见 _impl.py否则会抛出明确的 ValueError。底层运行机制sweep 主循环理解插件的运行闭环有助于排查问题。从 optuna_sweeper.py 的sweep()实现可以看到整体流程合并配置文件中的params与命令行参数经create_params_from_overrides解析为搜索空间分布、固定参数与固定覆盖若使用grid采样器先将离散分布展开为候选值列表_to_grid_sampler_choices并把n_trials裁剪为网格组合数通过optuna.create_study(study_name..., storage..., sampler..., directions..., load_if_existsTrue)创建或复用 study按n_jobs分批每批调用study.ask()生成 trial_configure_trials将分布与固定参数翻译为 Hydra 覆盖串再交给launcher.launch()批量启动任务收集返回的目标值后study.tell()回报给 Optuna单目标要求返回值可转 float多目标要求返回值与目标数量一致若失败批次占比超过max_failure_rate则触发错误并委托给JobReturn抛出真实 traceback循环直至n_trials耗尽最后将optimization_results.yaml写入hydra.sweep.dir目录。这种「study.ask / launcher.launch / study.tell」的闭环设计使得 Optuna 的采样策略与 Hydra 的并行启动、配置隔离机制解耦用户自定义 launcher如 Submitit、Ray 等也可无缝复用该优化流程。小结通过override hydra/sweeper: optuna一行配置即可将 Hydra 应用接入 Optuna 优化搜索空间既可在配置文件中声明int/float/categorical三种类型也可用interval/range/choice在命令行灵活覆盖采样器覆盖 TPE、随机、CMA-ES、NSGA-II、网格、GP、QMC 等多种算法默认 TPE多目标优化通过direction列表 NSGA-II 等采样器实现结果以 Pareto 前沿形式写入optimization_results.yaml自定义搜索空间可通过custom_search_space挂载 Python 回调函数满足参数间存在依赖关系的复杂场景。相关文件索引插件默认配置 | 插件主实现 | 底层实现 | 单目标示例 | 多目标示例【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
