Hydra 默认列表Defaults List完全指南配置组合的骨架与原理【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra导读本文以 Hydra 1.2 版本文档 advanced/defaults_list.md 为核心系统讲解 Hydra 中默认列表Defaults List这一配置组合机制它如何决定输出配置Output Config的构建方式、如何用override/optional/null关键字精确控制配置组选项、如何利用插值与_self_调整组合顺序以及如何用--info系列命令调试组合结果。读完本文你将能读懂任何复杂应用的 defaults 列表并能动手组合、覆盖、调试自己的多配置应用。文末还附带了仓库内源码级的实现原理与相关测试路径方便深入研读。:::important 本文描述的特性多为 Hydra 1.1 及以后引入的新能力。如果你在旧版本上使用请先升级到 1.1/1.2 并留意本文的版本相关说明。 :::一、什么是 Defaults List在 Hydra 中Defaults List 是输入配置Input Config中一个顶层元素它指导 Hydra 如何构建输出配置Output Config。每个输入配置都可以有自己的 Defaults List但 Defaults List 本身不会出现在输出配置中——它只是一份装配清单。1.1 YAML 语法速览defaults: (- CONFIG|GROUP_DEFAULT)* CONFIG : (CONFIG_GROUP/)?CONFIG_NAME(PACKAGE)? GROUP_DEFAULT : [optional|override]? CONFIG_GROUP(PACKAGE)?: OPTION OPTION : CONFIG_NAME|CONFIG_NAMES|null各语法要素的含义如下语法要素说明CONFIG一个用于构建输出配置的配置项例如db/mysql、db/mysqlbackup。GROUP_DEFAULT一个可被覆盖overridable的配置项例如db: mysql、dbbackup: mysql。override覆盖此前已定义的某个GROUP_DEFAULT的选项。optional默认情况下某个OPTION不存在会直接报错optional可抑制该错误。null为将来的覆盖预留的位置。若它未被覆盖则该条目被忽略。CONFIG_NAME配置文件名不含文件系统扩展名例如mysql而非mysql.yaml。CONFIG_NAMES配置名列表例如[mysql, sqlite]。CONFIG_GROUP指向一组配置的路径。路径相对于包含它的配置以/前缀可使其成为绝对路径路径分隔符永远是/与操作系统无关。OPTION当前从某个CONFIG_GROUP中选中的CONFIG_NAME或CONFIG_NAMES。PACKAGE指定该配置内容在输出配置中的放置位置默认相对于包含它的配置的 Package。详见 Packages覆盖包。从源码实现看Hydra 将每条 defaults 条目解析为两类对象见 hydra/core/default_element.pyConfigDefault普通配置项如server/apache与GroupDefault可覆盖的配置组项如db: mysql。其中GroupDefault的override、optional、deleted等字段正是override关键字、optional关键字与null占位的底层载体。1.2 一个完整示例假设配置目录结构如下├── server │ ├── db │ │ ├── mysql.yaml │ │ └── sqlite.yaml │ └── apache.yaml └── config.yaml三个输入配置分别为defaults: - server/apache debug: falsedefaults: - db: mysql name: apachename: mysqlname: sqlite运行应用后得到的输出配置为server: db: name: mysql name: apache debug: false可以看到config.yaml通过 defaults 引入server/apacheserver/apache.yaml又通过自己的 defaults 引入db: mysql。由于server/apache的默认包package是serverserver/db/mysql的默认包是server.db最终这些内容被装配进了server与server.db两个命名空间而config.yaml自身的内容debug: false保留在全局包中。仓库中server/db/mysql与server/db/sqlite的结构在 examples/patterns/multi-select/conf 等示例中也能看到类似的组group与选项option组织方式。二、覆盖 Config Group 选项override一个 Config Group 的选项可以通过带override关键字的新GROUP_DEFAULT来覆盖defaults: - server/apache - override server/db: sqlite debug: false输出变为server: db: name: sqlite name: apache debug: false如果同一个 Group Default 被覆盖多次按深度优先顺序depth first order最后一个覆盖生效。除了在配置文件中覆盖还可以在命令行直接覆盖$ python my_app.py server/dbsqlite2.1 版本行为差异重要在 Hydra 1.1 之前覆盖 Hydra 自己的配置组如hydra/launcher时不需要override关键字# Hydra 1.0 的写法 defaults: - model: resnet50 - hydra/launcher: submitit自 Hydra 1.1 起覆盖必须显式使用override关键字# Hydra 1.1 的写法 defaults: - model: resnet50 - override hydra/launcher: submitit:::warning 在 Hydra 1.2 中省略override关键字来覆盖 Hydra 的配置组会直接报错。迁移细节见 Defaults List Overrides 升级说明。 :::2.2 源码级的覆盖语义在 hydra/_internal/defaults_list.py 中覆盖行为由Overrides类承载命令行覆盖如server/dbsqlite在Overrides.__init__阶段被注册进override_choices见 defaults_list.py因此命令行覆盖总是优先于配置文件内的覆盖配置文件内的override条目在遍历 Defaults Tree 时通过add_override注册由于遍历是反向reverse深度优先第一个注册的即深度优先顺序中的最后一个于是最后一个覆盖生效得以成立见 defaults_list.py如果某条override最终没有被使用例如它指向的 Group Default 根本不存在ensure_overrides_used会抛出ConfigCompositionException并给出可选的正确选项提示对命令行覆盖还会提示如需追加请用keyvalue见 defaults_list.py。这也解释了文档中最后一个覆盖生效的底层原因不是简单的文本替换而是在 Defaults Tree 反向遍历中先注册者胜出而反向遍历中的先注册者恰好是原始顺序中的最后一个。三、组合顺序Composition Order与_self_3.1 默认组合顺序Defaults List 是有序的如果多个配置定义了同一个值最后一个定义的生效如果多个配置向同一个字典贡献内容结果是把这些字典合并默认情况下当前配置文件的内容会覆盖 defaults 列表中配置的内容。看下面的例子。config.yaml定义了db.host而db/mysql.yaml定义了db.driver与db.portdefaults: - db: mysql db: host: backupdb: driver: mysql # db/mysql.yaml host: backup # config.yaml port: 3306 # db/mysql.yaml这里db/mysql.yaml的内容先被加载随后config.yaml自身的db.host覆盖了它假设 mysql.yaml 中 host 为 localhost。3.2_self_控制当前配置在组合序列中的位置_self_条目决定当前配置在 Defaults List 中的相对位置。如果不指定它会被自动添加为最后一项。把_self_放到列表最前面就可以让当前配置的内容先被加载、从而被后面的配置覆盖defaults: - _self_ - db: mysql # 覆盖当前配置 db: host: backupdb: driver: mysql # db/mysql.yaml host: localhost # db/mysql.yaml port: 3306 # db/mysql.yaml_self_位于 Defaults List 顶部时config.yaml中定义的host字段先于db/mysql.yaml中的host字段出现因此被后者覆盖。从源码看_validate_self负责校验一个配置中_self_只能出现一次出现两次会报Duplicate _self_错误当列表为空或存在非 override 条目但缺少_self_时会自动把ConfigDefault(path_self_)追加到末尾见 defaults_list.py。仓库测试 tests/defaults_list/test_defaults_list.py 中的test_missing_self_is_appended_without_warning就验证了缺少_self_时自动追加到末尾这一行为而 tests/defaults_list/data/duplicate_self.yaml 则用于验证重复_self_报错。3.3 1.0 → 1.1 的组合顺序变化需要特别提醒Hydra 1.1 起组合顺序发生了变化。在 Hydra 1.0 中Defaults List 中的配置会覆盖config.yaml而Hydra 1.1 起config.yaml会覆盖 Defaults List 中的配置。迁移时的两条规则详见 Changes to default composition order如果新行为适合你的应用把_self_追加到 Defaults List末尾如果应用需要旧行为把_self_放到 Defaults List最前面若配置需要同时兼容 Hydra 1.0 与 1.1请把_self_作为第一项Hydra 1.0.7 会忽略_self_。使用 Structured Config 作为主配置或 schema 时同理Structured Config 主配置应在 defaults 中显式给出_self_通常放在第一项以 Structured Config 作为 schema 的 YAML 主配置则应在 defaults 中把_self_放在 schema 之后否则 schema 会反过来覆盖配置文件。四、Defaults List 中的插值InterpolationConfig Group 的选项可以通过插值来选择defaults: - server: apache - db: mysql - combination_specific_config: ${server}_${db} # apache_mysql插值键可以是带任意package覆盖的配置组例如${db/engine}、${dbbackup}combination_specific_config的最终选项取决于db与server的最终被选中的选项。例如如果db被覆盖为sqlite那么combination_specific_config将变成apache_sqlite。4.1 限制条件Defaults List 中的插值键不能引用最终配置对象中的值——因为处理 defaults 时最终配置对象还不存在Defaults List 插值键是绝对的即使在嵌套配置中也是绝对的被插值配置展开出来的子树中不允许包含 Defaults List 覆盖。关于被插值配置的子树中不允许包含 override这一点源码中有直接印证_update_overrides在处理interpolated_subtreeTrue的子树时若发现其中含override条目会抛出ConfigCompositionException并提示Default List Overrides are not allowed in the subtree of an interpolated config group见 defaults_list.py。4.2 新旧插值风格升级提示Hydra 1.0 及更早版本支持基于索引的插值风格# Hydra 1.0 及更早版本 defaults: - dataset: imagenet - model: alexnet - dataset_model: ${defaults.0.dataset}_${defaults.1.model}Hydra 1.1 及更新版本改用更简洁、基于配置组名的风格# Hydra 1.1 及更新版本 defaults: - dataset: imagenet - model: alexnet - dataset_model: ${dataset}_${model}新风格更紧凑无需指定元素在列表中的精确索引且能够引用来自递归 defaults 的配置组值。注意这是 defaults 列表独有的、非标准的插值支持旧风格的\${defaults.N.xxx}在 Hydra 1.2 中会被识别为 legacy interpolation 并直接报错见 default_element.py 与GroupDefault.resolve_interpolation中的is_legacy_interpolation分支。迁移详情见 Defaults List interpolation 升级说明。更多实战案例可参考 Patterns / Specializing Configs特化配置。五、从同一 Config Group 选择多个配置Defaults List 的值也可以是一个配置名列表CONFIG_NAMES从而实现从同一个配置组中一次选择多个配置。这是文档语法中CONFIG_NAMES的典型用法例如defaults: - site: - fb - google它等价于defaults: - site/fb - site/google命令行中也可以用列表覆盖选中项$ python my_app.py server/site[google,amazon]若配置组使用了package覆盖则命令行覆盖时也必须带上 package例如server/siteserver.httpsamazon。需要留意的是嵌套列表在 Defaults List 中会被解释为一组不可覆盖non-overridable的配置。完整示例见 Patterns / Selecting multiple configs from a Config Group可运行示例位于 examples/patterns/multi-select/conf。六、调试 Defaults List6.1 组合流程Hydra 的配置组合过程分为三步创建 Defaults Tree配置组合树通过DFS 遍历深度优先遍历Defaults Tree 得到Final Defaults List最终默认列表根据 Final Defaults List 中的条目组合出输出配置Output Config。这一流程在源码中对应create_defaults_list→_create_defaults_tree建树→_tree_to_list/_dfs_walkDFS 展平→ 输出配置组合见 hydra/_internal/defaults_list.py。ensure_no_duplicates_in_list还会在最终列表中检测同一 override key 重复出现的情况并报错见 defaults_list.py。6.2 三个调试命令你可以通过命令行参数检查上述三个阶段各自的产物--info defaults-tree显示 Defaults Tree组合树--info defaults显示 Final Defaults List最终默认列表--cfg job|hydra|all显示输出配置job 只显示应用配置hydra 只显示 Hydra 自身配置all 显示两者。6.3 示例输出--info defaults-tree展示配置组合树每个节点代表一个配置或配置组root: hydra/config: hydra/hydra_logging: default hydra/job_logging: default hydra/launcher: basic hydra/sweeper: basic hydra/output: default hydra/help: default hydra/hydra_help: default _self_ config: server/apache: server/db: mysql _self_ _self_可以看到树根root下先挂载 Hydra 自身的配置组日志、launcher、sweeper、输出、帮助等然后是主配置configconfig又展开出server/apache而server/apache自身又包含server/db: mysql。这正是每个输入配置都可以有自己的 Defaults List在树形结构中的体现。--info defaults展示最终默认列表逐条列出配置路径、包名、_self_标记与父配置Defaults List ************* | Config path | Package | _self_ | Parent | ------------------------------------------------------------------------------- | hydra/hydra_logging/default | hydra.hydra_logging | False | hydra/config | | hydra/job_logging/default | hydra.job_logging | False | hydra/config | | hydra/launcher/basic | hydra.launcher | False | hydra/config | | hydra/sweeper/basic | hydra.sweeper | False | hydra/config | | hydra/output/default | hydra | False | hydra/config | | hydra/help/default | hydra.help | False | hydra/config | | hydra/hydra_help/default | hydra.hydra_help | False | hydra/config | | hydra/config | hydra | True | root | | server/db/mysql | server.db | False | server/apache | | server/apache | server | True | config | | config | | True | root | -------------------------------------------------------------------------------这个表格把 Defaults Tree 的 DFS 遍历结果完整摊开每个条目都带有其最终包名与父配置_self_列为True的行正是各配置中自动追加或显式声明的_self_条目。--cfg job展示最终输出配置server: db: name: mysql name: apache debug: false三个命令分别对应组合流程的三步配合使用可以精确定位配置来自哪里、被谁覆盖。七、相关主题与延伸阅读Packages覆盖包详解PACKAGE、_here_、_group_、_global_等包关键字及优先级规则Defaults List 中指定的包 Package Directive 默认包Common Patterns / Extending Configs扩展配置在 defaults 中引入基础配置并覆盖/新增字段的常用手法Common Patterns / Configuring Experiments配置实验利用 defaults 组合出多组实验配置Selecting multiple configs from a Config Group多配置选择CONFIG_NAMES列表用法详解升级相关Defaults List Overrides、Defaults List interpolation、Changes to default composition order。源码与测试索引想从实现层面继续深挖的读者推荐按以下路径阅读核心实现hydra/_internal/defaults_list.pycreate_defaults_list、_create_defaults_tree、Overrides类数据类型hydra/core/default_element.pyConfigDefault、GroupDefault、DefaultsTreeNode、VirtualRoot测试用例tests/defaults_list/test_defaults_list.py 与 tests/defaults_list/data 下的数据文件覆盖_self_自动追加、重复_self_、缺失选项、插值、覆盖语义等场景。综上Defaults List 是 Hydra 配置体系的心脏理解它的语法、覆盖规则、_self_语义、插值限制与调试手段就等于掌握了任意复杂 Hydra 应用配置组合的钥匙。【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考