Hydra 1.4 破坏性变更完整指南：从 1.3 升级到 1.4 的兼容性迁移清单

Hydra 1.4 破坏性变更完整指南：从 1.3 升级到 1.4 的兼容性迁移清单

【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra

Hydra 1.4 与 OmegaConf 2.4 是 Hydra 框架一次大规模的行为收敛版本，移除了自 1.1、1.2 时代遗留的兼容层，并在instantiate()实例化语义与安全模型上做出了根本性调整。本文以官方升级文档（breaking_changes.md）为骨架，结合仓库源码与配套迁移指南，系统梳理你需要知道的所有破坏性变更、迁移步骤与可验证的底层实现依据，帮助你为升级到 Hydra 1.4 做好完整准备。

注意：Hydra 1.4 与 OmegaConf 2.4 仍处于开发阶段，本文所述变更是当前已知的、需要更新应用的工作清单，最终以正式发布说明（release notes）为准。建议同步阅读配套迁移文档 prepare_for_1_4.md、instantiate_resolution.md、instantiate_target_whitelist.md 与 slash_in_default.md。

平台与运行时：Python 最低版本提升

Hydra 1.4 不再支持 Python 3.7、3.8 和 3.9，要求Python 3.10 或更高版本。配套的 OmegaConf 2.4 同步不再支持 Python 3.6、3.7、3.8 和 3.9，同样要求 Python 3.10 或更高版本。这是升级前必须最先检查的环境前置条件。

Hydra 1.4 核心变更

已移除的组件与实验功能

• Torchrun launcher 与contrib插件区被移除。此前依赖contrib插件目录或 Torchrun launcher 的应用需要迁移到官方维护的 launcher 插件（如 hydra_submitit_launcher 等）。
• 实验性的on_compose_config回调被移除。该回调从未进入任何稳定的 Hydra 正式版本，仅在 2025 年 2 月至 2026 年 7 月的 Hydra 1.4 开发版本中出现过。如果你在开发版本中使用了它，需要改用其他配置组合钩子方案。

Defaults List 路径规范化

Hydra 1.4 对 Defaults List 中的配置路径施加了两条严格的语法约束，这两条约束在 defaults_list.py 的组合逻辑中直接执行：

1. 父级遍历（parent traversal）不再被接受。Defaults List 配置路径中不允许出现..形式的父级跳转。源码在组合阶段会显式检查路径内容，一旦检测到父级遍历即抛出异常并提示"Config options cannot contain parent traversal"。

2. 反斜杠不再被接受。/是唯一受支持的配置组分隔符。此前仅在 Windows 上，操作系统会把反斜杠解析为文件系统分隔符，导致形如foo\bar\baz的路径可以成功组合；在 Hydra 1.4 中，defaults_list.py 会直接拒绝包含\的路径。所有历史遗留的\路径必须改写为/。

与斜杠相关的 Defaults 选项规范化

Hydra 1.4 还会在组合早期将包含斜杠的 Defaults 条目（例如foo: bar/baz）规范化为foo/bar: baz。这一变更的详细说明见 slash_in_default.md，其影响包括：

• 命令行覆盖键从foo变为foo/bar，即原来写foo=bar/baz的地方现在必须写foo/bar=baz；
• 默认的包（package）位置从foo变为foo.bar，最终组合配置中的字典键嵌套层级可能移动；
• 如果应用依赖旧行为（嵌套在foo/bar/baz.yaml中的相对 defaults 以foo为基准解析，从而把嵌套配置放在foo/目录下），Hydra 1.4 会检测到目录不匹配并抛出清晰错误：Could not load 'foo/bar/nested'. However, a config was found at 'foo/nested'...。修复方式是移动嵌套配置文件到规范化的组目录（例如foo/nested.yaml→foo/bar/nested.yaml），或显式用规范绝对路径改写 defaults 条目。

Hydra 1.1 兼容行为被移除

version_base="1.1"不再被接受，以下 1.1 时代的遗留行为全部移除：

其中strict参数的移除可以直接从源码得到印证：compose.py 中的compose()函数签名只有config_name、overrides与return_hydra_config三个参数，不再包含strict。

此外，ConfigStore schema 不再按配置名自动匹配。此前只要 schema 名与配置名一致即可自动套用 schema，1.4 起必须在 Defaults List 中显式扩展 schema。

从源码看version_base的强制收敛

version.py 定义了_MIN_SUPPORTED_VERSION_BASE = "1.3"，并实现了完整的版本校验逻辑：

• 当version_base指定的版本低于 1.3 时，直接抛出HydraException，错误信息为version_base=... is not supported in Hydra 1.4; omit version_base to use the current behavior；
• 即使在 1.3 之上指定version_base，也会触发Hydra15MigrationWarning，提示该参数将在 Hydra 1.5 中移除，建议直接省略version_base使用当前默认行为。

version_base的解析入口分别在 main.py（@hydra.main()装饰器）与 initialize.py（initialize()/initialize_config_dir()等初始化 API）中。

Hydra 1.2 迁移行为被移除

version_base="1.2"同样不再被接受，以下迁移路径全部移除：

• hydra.types.TargetConf被移除。此前用它声明带_target_字段的配置类型，现在必须改用带_target_字段的 Structured Config。
• hydra.experimental下的 compose 与初始化 API 被移除，必须直接从hydra导入（from hydra import compose, initialize）。
• hydra.job.chdir=null不再被接受，必须显式设置为True或False。
• 内部run_job()API 的直接调用者必须传入hydra_context参数。
• 第三方 Sweeper 必须使用setup()提供的HydraContext来访问 config loader。
• Optuna Sweeper 已废弃的hydra.sweeper.search_space配置被移除，改用hydra.sweeper.params。相关插件源码位于 hydra_optuna_sweeper。

Instantiation（实例化）语义的重大变更

Hydra 1.4 对hydra.utils.instantiate()的解析时机与调用点参数（call-site override）处理方式做了根本性调整，完整说明见 instantiate_resolution.md。

惰性解析：按需解析替代全量预解析

1.4 不再在实例化前急切地解析整个输入配置，而是遍历配置、在需要某个值时才解析该值。由此带来几个直接收益：

• 配置树中无关的部分不会被解析；
• 调用点参数可以直接替换一个无法解析的配置值，而不必先强制解析被替换的值；
• 前一个目标可以建立运行时状态（例如注册自定义 resolver），供后一个参数解析时使用；
• 当_recursive_=False、默认_convert_="none"且无调用点覆盖时，不再对 OmegaConf 容器做最终拷贝：从输入树透传的容器保留其对象身份、惰性插值、祖先上下文、resolver 缓存与继承的标志位。

实现层面，instantiate_node() 对DictConfig的处理区分了两种路径：非目标节点且_convert_为none时，直接构建新的DictConfig并以惰性方式解析插值（resolve interpolations lazily）；只有_convert_为ALL或PARTIAL/OBJECT且对象类型为普通 dict 时才急切解析。

调用点字典覆盖的替换语义

一个dict或DictConfig调用点参数在覆盖某个目标参数时，将替换为该参数配置的普通映射（plain mapping），而不是合并进它。唯一的例外是：当该参数配置为 Structured Config 节点时，调用点字典会与之合并并通过 schema 校验。

具体规则按配置参数的有效值（插值解析后）决定：

1. 配置值为Structured Config 节点：合并字典并做 schema 校验，字典未命名的字段保留配置值，节点内插值可以基于合并后的值解析；
2. 配置映射包含_target_：字典合并进该目标配置，保留其 target、实例化设置及字典未命名的参数；_recursive_只控制结果是否被实例化，不改变合并行为；
3. 其他任何配置映射：被整个替换。

这一点在 instantiate_resolution.md 中有明确示例：配置tags: {"env": "prod", "team": "ml"}时，调用instantiate(cfg, tags={"env": "dev"})在 1.3 返回{"env": "dev", "team": "ml"}，而 1.4 返回{"env": "dev"}。如果需要合并结果，必须在调用点显式合并，例如OmegaConf.merge(cfg["tags"], {"env": "dev"})。

dataclass / attrs 实例按运行时对象透传

instantiate()现在把调用点传入的已构造 dataclass 与 attrs 实例原样透传，不再将其解释为 Structured Config、与输入配置合并或递归实例化——即使实例定义了_target_字段也是如此。若确实要把实例当作配置，需要显式转换：OmegaConf.structured(instance)。

调用点覆盖必须为具体运行时值

hydra.utils.instantiate()拒绝在纯 Python 调用点覆盖中出现???与插值语法（${...}）。源码在 instantiate() 入口处通过_validate_callsite_override()递归校验所有 args/kwargs：字符串为???或包含${时抛出InstantiationException。需要传缺失值或插值时，应使用显式的 OmegaConf 容器（保留正常 OmegaConf 语义）。

插件配置的非递归实例化

Launcher 与 Sweeper 插件的配置以非递归方式实例化。Hydra 核心只实例化注册的插件类本身；如果插件配置中包含嵌套的_target_，应在插件构造函数中接收嵌套配置，并由插件代码以插件自己的 whitelist 调用instantiate()。相关说明与示例见 instantiate_target_whitelist.md 的 "Plugin authors" 一节。

安全敏感模块默认不可实例化

部分安全敏感模块默认不再可被实例化。必须强调的是：这个限制不是安全边界（security boundary），不应依赖它来保证不受信任配置的安全性。相关机制在 _instantiate2.py 中以DEFAULT_BLOCKLISTED_MODULES黑名单与DEFAULT_BLOCKLISTED_MODULE_PREFIXES前缀黑名单实现，覆盖builtins.eval、builtins.exec、ctypes.CDLL、os.system、subprocess.Popen等高风险目标，并支持通过环境变量HYDRA_INSTANTIATE_ALLOWLIST_OVERRIDE显式放行。

Target Whitelist：实例化的新安全模型

与实例化变更配套，Hydra 1.4 引入_target_whitelist_机制（详见 instantiate_target_whitelist.md）：解析_target_需要调用点的可信 Python 代码提供白名单。因为配置文件有时随包、模型、checkpoint 或其他下载产物分发，来自不受信任源的配置可能触发任意代码执行。

直接调用迁移

from hydra.utils import instantiate model = instantiate(cfg.model, _target_whitelist_="my_app.models.*")

包装调用迁移

当另一个函数内部调用instantiate()时，用target_whitelist()上下文管理器包裹该调用，也便于多个调用共享同一白名单：

from hydra.utils import target_whitelist with target_whitelist("my_app.*"): framework_function(cfg)

框架作者与插件作者的实践

框架作者应在内部解析框架配置的instantiate()调用处白名单框架自有目标，应用自有目标（例如模型）的信任决策留给应用；框架若也实例化应用对象，应用可以在框架调用外层再包一层自己的白名单，内外层白名单按前缀合并。插件作者则按前述"非递归实例化"方式处理嵌套_target_。

白名单模式规则与旧行为保留

• 白名单条目可以是精确目标名或以.*结尾的包前缀，单独的*通配符不允许（源码在_validate_target_whitelist_pattern()中校验）；
• 注意命名空间包与插件命名空间：my_app.*会放行该 Python 命名空间下的任何可导入目标，包括其他已安装发行版贡献的模块，共享命名空间下优先使用精确目标名或更窄的前缀；
• 需要保留旧的"放行所有目标"行为时，显式传入UNSAFE_ALLOW_ALL_TARGETS：

  from hydra.utils import UNSAFE_ALLOW_ALL_TARGETS, instantiate obj = instantiate(cfg.component, _target_whitelist_=UNSAFE_ALLOW_ALL_TARGETS)

• 1.4 中不带_target_whitelist_调用instantiate()仍然可以工作，但解析_target_时会发出弃用警告（该警告将在 1.5 变为错误），旧模式继续使用 Hydra 的目标黑名单作为纵深防御。

OmegaConf 2.4 破坏性变更

容器与类型语义

• 原生元组创建不可变的TupleConfig，不再创建可变的ListConfig；转换操作返回元组而非列表；
• OmegaConf.create(None)返回None，不再返回包装None的DictConfig；
• OmegaConf.get_type()对包含None的节点返回NoneType，且None与NoneType注解会经过校验。

解析行为

• OmegaConf.resolve()在插值解引用缺失（???）值时抛出InterpolationToMissingValueError，不再把节点替换为???；
• OmegaConf.to_container(..., resolve=True)在单次转换过程中，每个被解析节点上的自定义 resolver 最多执行一次，依赖同一 resolver 重复副作用（side effects）的代码行为可能改变；
• 键路径分隔符前的反斜杠现在会转义该分隔符，这改变了包含以反斜杠结尾的键名的键路径解释。

升级实操：分阶段迁移路线

详细的迁移路线见 prepare_for_1_4.md，核心思路是"先在 1.3 上做准备，再切到 1.4 验证"。

阶段一：仍运行在 Hydra 1.3 时

1. 给每个@hydra.main()和 Hydra 初始化调用显式加上version_base="1.3"（替换任何已有值）。不要在 1.3 上移除version_base，因为省略仍会选中旧的 1.1 兼容行为；设为"1.3"只是脱离旧行为，并不等于 1.4 兼容；
2. 处理所有 Hydra 与 OmegaConf 的弃用警告；
3. 运行应用测试。如果应用需要从 Hydra 输出目录运行，显式设置hydra.job.chdir=True。

阶段二：在 Hydra 1.4 开发版上验证

1.4 尚未定稿，当前依赖 OmegaConf 2.4 的预发布版本，两者都是包含大量破坏性变更的大版本。早期测试者应预期正式版前还有更多未公开的破坏性变更。安装命令：

python -m pip install --upgrade --pre "hydra-core>=1.4.0.dev0,<1.5"

• 建议使用独立环境（非强制）；上限<1.5防止误装更高版本；
• 安装与 Hydra 1.4 匹配的 launcher/sweeper 插件版本；
• 不要把 1.4 开发版用于生产环境；
• 测试时移除version_base以消除预期的Hydra15MigrationWarning；
• 在 1.3 上以version_base="1.3"通过测试并不足以证明 1.4 兼容性。

阶段三：暂不升级则锁定 1.3

不打算升级的应用应把 Hydra 钉在 1.3 发布线：

hydra-core>=1.3,<1.4

并在求值@hydra.main()或调用 Hydra 初始化 API之前配置警告过滤器：

import warnings from hydra.errors import Hydra14MigrationWarning warnings.filterwarnings("ignore", category=Hydra14MigrationWarning)

这样只压制 1.4 迁移警告，不会影响其他警告。

小结

Hydra 1.4 是一次"向新版本收敛"的版本：它彻底移除 1.1/1.2 时代的version_base兼容层与一系列旧语法，在 Defaults List 路径上强制使用/并禁止父级遍历，同时重写了instantiate()的解析时机、调用点覆盖语义与目标白名单安全模型。升级前建议按上述三阶段路线执行：先在 1.3 上显式version_base="1.3"并清理全部警告，再在独立环境中用预发布版验证，同时对照本清单逐项排查instantiate()调用、插件配置与 OmegaConf 使用方式。最终请以正式发布说明为准，并持续关注本升级目录下的其他配套文档（hydra_job_override_dirname.md、nevergrad_sweeper.md 等）。

【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra