Hydra 1.4 破坏性变更完整指南从 1.3 升级到 1.4 的兼容性迁移清单【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydraHydra 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即原来写foobar/baz的地方现在必须写foo/barbaz默认的包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_base1.1不再被接受以下 1.1 时代的遗留行为全部移除遗留行为Hydra 1.4 中的处理省略config_path时自动把调用目录加入配置搜索路径不再自动添加需要显式指定搜索路径hydra.job.chdir默认为True默认改为False需要在配置中显式设置hydra.job.chdir: True.yml扩展名配置文件被接受直接拒绝必须使用.yaml{group: option, optional: true}旧式 defaults 语法拒绝改用optional group: option替换 Hydra 配置组的 defaults 条目可以不带关键字必须显式加override关键字${defaults.0.dataset}这类索引式 defaults 插值不再接受_group_、_name_作为符号化包名展开不再展开为符号包值hydra.compose()的strict参数参数被移除其中strict参数的移除可以直接从源码得到印证compose.py 中的compose()函数签名只有config_name、overrides与return_hydra_config三个参数不再包含strict。此外ConfigStore schema 不再按配置名自动匹配。此前只要 schema 名与配置名一致即可自动套用 schema1.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.pyhydra.main()装饰器与 initialize.pyinitialize()/initialize_config_dir()等初始化 API中。Hydra 1.2 迁移行为被移除version_base1.2同样不再被接受以下迁移路径全部移除hydra.types.TargetConf被移除。此前用它声明带_target_字段的配置类型现在必须改用带_target_字段的 Structured Config。hydra.experimental下的 compose 与初始化 API 被移除必须直接从hydra导入from hydra import compose, initialize。hydra.job.chdirnull不再被接受必须显式设置为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 校验。具体规则按配置参数的有效值插值解析后决定配置值为Structured Config 节点合并字典并做 schema 校验字典未命名的字段保留配置值节点内插值可以基于合并后的值解析配置映射包含_target_字典合并进该目标配置保留其 target、实例化设置及字典未命名的参数_recursive_只控制结果是否被实例化不改变合并行为其他任何配置映射被整个替换。这一点在 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_TARGETSfrom 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的DictConfigOmegaConf.get_type()对包含None的节点返回NoneType且None与NoneType注解会经过校验。解析行为OmegaConf.resolve()在插值解引用缺失???值时抛出InterpolationToMissingValueError不再把节点替换为???OmegaConf.to_container(..., resolveTrue)在单次转换过程中每个被解析节点上的自定义 resolver 最多执行一次依赖同一 resolver 重复副作用side effects的代码行为可能改变键路径分隔符前的反斜杠现在会转义该分隔符这改变了包含以反斜杠结尾的键名的键路径解释。升级实操分阶段迁移路线详细的迁移路线见 prepare_for_1_4.md核心思路是先在 1.3 上做准备再切到 1.4 验证。阶段一仍运行在 Hydra 1.3 时给每个hydra.main()和 Hydra 初始化调用显式加上version_base1.3替换任何已有值。不要在 1.3 上移除version_base因为省略仍会选中旧的 1.1 兼容行为设为1.3只是脱离旧行为并不等于 1.4 兼容处理所有 Hydra 与 OmegaConf 的弃用警告运行应用测试。如果应用需要从 Hydra 输出目录运行显式设置hydra.job.chdirTrue。阶段二在 Hydra 1.4 开发版上验证1.4 尚未定稿当前依赖 OmegaConf 2.4 的预发布版本两者都是包含大量破坏性变更的大版本。早期测试者应预期正式版前还有更多未公开的破坏性变更。安装命令python -m pip install --upgrade --pre hydra-core1.4.0.dev0,1.5建议使用独立环境非强制上限1.5防止误装更高版本安装与 Hydra 1.4 匹配的 launcher/sweeper 插件版本不要把 1.4 开发版用于生产环境测试时移除version_base以消除预期的Hydra15MigrationWarning在 1.3 上以version_base1.3通过测试并不足以证明 1.4 兼容性。阶段三暂不升级则锁定 1.3不打算升级的应用应把 Hydra 钉在 1.3 发布线hydra-core1.3,1.4并在求值hydra.main()或调用 Hydra 初始化 API之前配置警告过滤器import warnings from hydra.errors import Hydra14MigrationWarning warnings.filterwarnings(ignore, categoryHydra14MigrationWarning)这样只压制 1.4 迁移警告不会影响其他警告。小结Hydra 1.4 是一次向新版本收敛的版本它彻底移除 1.1/1.2 时代的version_base兼容层与一系列旧语法在 Defaults List 路径上强制使用/并禁止父级遍历同时重写了instantiate()的解析时机、调用点覆盖语义与目标白名单安全模型。升级前建议按上述三阶段路线执行先在 1.3 上显式version_base1.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
