Python程序配置框架——Hydra（基于OmegaConf）

Python程序配置框架——Hydra（基于OmegaConf）

OmegaConf是基于YAML的分层配置系统，Hydra在其基础上提供了更便于开发的功能

https://omegaconf.readthedocs.io/en/latest/index.html

Hydra | Hydra

YAML示例

1
2
3
4
5
6
7
8
9
10
11
12
A:
  a: a
  b: 0.0
  c: false
  d: null
  e: ???
  f:
    g: [1, 2]
    h:
      - hh
      - hhh
    i: {j: 3, k: k}

OmegaConf

OmegaConf作为配置对象，提供了创建、访问、操作配置的功能

1
pip install omegaconf
1
from omegaconf import OmegaConf

创建

1
2
3
4
5
6
7
8
9
10
# 可不传入数据，也可以传入字典、列表、YAML字符串
conf = OmegaConf.create(/dict/list/string)
# YAML文件路径
conf = OmegaConf.load(yaml_path)
# 由若干格式为类似key1.key2.key3=value的字符串组成的列表
conf = OmegaConf.from_dotlist(dot_list)
# 命令行参数
conf = OmegaConf.from_cli()
# 结构化配置类或对象
conf = OmegaConf.structured(ConfigClass)

访问

1
2
3
4
conf.key1.key1_1
conf['key2']['key2_2']
conf.key3[0]  # key3值为列表，[0]访问列表第一项
conf.get('missing_key', 'a default value')  # 获取不到missing_key时范围默认值

用值???表示访问前需要设置的配置，如key: ???，访问key时会报错

操作

1
2
# 改变或添加配置，值可以是数字、字符串、字典、列表等
conf.key = value

Hydra入门

Hydra的使用主要涉及四部分内容：文件结构、配置文件、程序、命令行

1
pip install hydra-core --upgrade

文件结构

将所有配置文件放在configs文件夹下，在configs文件夹下一般有一个总配置文件config.yaml供程序读取，同时还有若干个文件夹，每个文件夹作为一个配置组，里面包含同类型的配置文件

├── configs
│ ├── config.yaml
│ ├── db
│ │ ├── mysql.yaml
│ │ └── postgresql.yaml
│ ├── schema
│ │ ├── school.yaml
│ │ ├── support.yaml
│ │ └── warehouse.yaml
│ └── ui
│ ├── full.yaml
│ └── view.yaml
└── my_app.py

配置文件

简单写法

1
2
3
4
db: 
  driver: mysql
  user: omry
  password: secret

使用配置对象

1
2
3
4
5
node:                         # Config is hierarchical
  loompa: 10                  # Simple value
  zippity: ${node.loompa}     # Value interpolation
  do: "oompa ${node.loompa}"  # String interpolation
  waldo: ???                  # Missing value, must be populated prior to access

使用默认列表

默认列表中如果添加了_self_则可以包含自身配置

注意配置的顺序，后面的配置覆盖前面的配置

1
2
3
4
5
6
defaults:
 - _self_
 - db: mysql
 - db/mysql/engine: innodb
 - schema: school
 - ui: full

程序

通过@hydra.main读取配置作为一个DictConfig对象传给所注释的函数

1
2
3
4
5
6
7
8
9
from omegaconf import DictConfig, OmegaConf
import hydra

@hydra.main(version_base="1.3", config_path="程序到配置文件的相对路径", config_name="配置文件名")
def my_app(cfg: DictConfig) -> None:
    print(OmegaConf.to_yaml(cfg))

if __name__ == "__main__":
    my_app()

命令行

通过命令行可以对配置灵活操作

1
2
3
4
5
6
7
8
9
10
11
12
# 添加配置
python my_app.py +db.mysql.user=root
# 修改配置
python my_app.py db.mysql.password=123
# 不存在则添加，存在则修改
python my_app.py ++db.mysql.password=1234
# 添加配置组
python my_app.py +db=postgresql
# 修改配置组
python my_app.py db=postgresql
# 删除配置组
python my_app.py ~db

Hydra基础

Multi-run

通过命令行添加hydra.mode=MULTIRUN或--multirun(-m)可以跑不同配置下的程序，不同配置组的配置之间一一组合

1
2
3
4
5
6
# 如下命令将有2x3=6种配置组合，即db中的2个配置与schema中的3个配置进行组合
python my_app.py hydra.mode=MULTIRUN db=mysql,postgresql schema=warehouse,support,school
# 或者--multirun
python my_app.py --multirun db=mysql,postgresql schema=warehouse,support,school
# 或者-m
python my_app.py -m db=mysql,postgresql schema=warehouse,support,school

或者通过在配置文件中重写hydra.sweeper.params指定要进行组合的配置

1
2
3
4
5
hydra:
  sweeper:
    params:
      db: mysql,postgresql
      schema: warehouse,support,school

同时在命令行中还可以进一步指定配置

1
2
# 如下命令将有1x3中配置组合，即db中的mysql与schema中的3个配置进行组合
python my_app.py -m db=mysql

Output/Working directory

默认情况下，Hydra会在工作文件夹（即程序所在文件夹）下创建outputs/YYYY-mm-dd/HH-MM-SS目录作为输出文件夹，输出文件夹下的基本结构如下：

├── .hydra
│ ├── config.yaml（用户指定配置）
│ ├── hydra.yaml（Hydra配置）
│ └── overrides.yaml（命令行覆盖的配置）
└── 程序名.log

关于输出文件夹与工作文件夹的更改见Output/Working directory和Customizing working directory pattern

Logging

Hydra设置了python的logging，以方便使用。默认情况下Hydra会在控制台和日志文件中记录INFO级别的信息，如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import logging
from omegaconf import DictConfig
import hydra

# A logger for this file
log = logging.getLogger(__name__)

@hydra.main()
def my_app(_cfg: DictConfig) -> None:
    log.info("Info level message")
    log.debug("Debug level message")

if __name__ == "__main__":
    my_app()

控制台和日志文件中都会有

[YYYY-mm-dd HH:MM:SS,653][main][INFO] - Info level message

通过设置命令行的hydra.verbose可以记录DEBUG级别的信息

  • hydra.verbose=true：将所有logger的级别设为DEBUG

  • hydra.verbose=NAME：将NAME的logger的级别设为DEBUG

  • hydra.verbose=[NAME1,NAME2]：将NAME1和NAME2的logger的级别设为DEBUG

通过命令行设置hydra/job_logging=disabled取消logging输出

通过命令行设置hydra/job_logging=none和hydra/hydra_logging=none取消Hydra配置logging

关于logging的自定义见Customizing logging

Debugging

通过设置命令行的--cfg或-c打印配置

  • --cfg job：用户配置

  • --cfg hydra：Hydra配置

  • --cfg all：所有配置，即用户配置和Hydra配置的集合

通过设置命令行的--info打印信息

  • --info all：默认行为，打印所有

  • --info config：打印有助于理解配置组成的信息：配置搜索路径、默认树、默认列表和最终配置

  • --info defaults：打印最终默认列表

  • --info defaults-tree：打印默认树

  • --info plugins：打印有关已安装的插件的信息

Tab completion

见Tab completion

编程
#教程
Python程序配置框架——Hydra（基于OmegaConf）
https://wangaaayu.github.io/blog/posts/f5d8529f/
作者
WangAaayu
发布于
2024年1月10日
更新于
2024年1月15日
许可协议