python?配置管理框架Hydra使用指南

更新時間：2026年01月06日 08:45:18 作者：落痕的寒假

Hydra是Facebook?Research開發(fā)的開源Python配置管理框架,用于簡化復(fù)雜項目中的配置管理,它采用分層配置和動態(tài)組合設(shè)計,支持以YAML文件實現(xiàn)結(jié)構(gòu)化配置,本文給大家介紹python配置管理框架Hydra使用,感興趣的朋友跟隨小編一起看看吧

Hydra是Facebook Research開發(fā)的開源Python配置管理框架，旨在解決復(fù)雜項目中配置混亂、多環(huán)境與多參數(shù)組合管理的難題。該框架采用分層配置與動態(tài)組合設(shè)計，支持以YAML文件實現(xiàn)結(jié)構(gòu)化配置。Hydra尤其適用于簡化機器學(xué)習(xí)實驗、軟件開發(fā)及其他復(fù)雜應(yīng)用的配置管理。它的名字來源于希臘神話中的九頭蛇，寓意其能夠靈活管理多種配置組合。Hydra的核心特性包括支持多源分層配置組合、可通過命令行直接覆蓋配置、提供動態(tài)命令補全功能，同時支持本地與遠程運行，并能通過單命令執(zhí)行批量參數(shù)作業(yè)。

Hydra的官方倉庫地址為：hydra，詳細文檔可參閱：hydra-doc。Hydra功能全面，本文主要介紹其基本使用方法，更多高級功能請參考官方文檔。截至本文撰寫時，Hydra的穩(wěn)定版本為1.3，該版本兼容Python 3.6至3.11，并全面支持Linux、macOS和Windows操作系統(tǒng)。安裝命令如下：

pip install hydra-core --upgrade

1 基礎(chǔ)教程

1.1 快速入門

簡單示例

以下代碼是一個簡單的Hydra應(yīng)用示例，它會打印出配置信息，其中my_app函數(shù)是編寫業(yè)務(wù)邏輯的入口。

from omegaconf import DictConfig, OmegaConf
import hydra
@hydra.main(version_base=None)
def my_app(cfg: DictConfig) -> None:
    print(OmegaConf.to_yaml(cfg))
if __name__ == "__main__":
    my_app()

如果你直接執(zhí)行這段代碼（沒有任何命令行參數(shù)），程序會輸出一個空的配置對象：

{}

這是因為，當(dāng)運行my_app.py時，@hydra.main裝飾器會自動攔截對 my_app()的調(diào)用。此時Hydra會初始化一個空的DictConfig對象（類似于Python字典），并將其作為參數(shù)cfg 傳遞給函數(shù)。由于當(dāng)前配置為空，OmegaConf.to_yaml(cfg)將其轉(zhuǎn)換為YAML格式后，僅輸出一個空對象。OmegaConf是Hydra的底層配置引擎，Hydra基于OmegaConf實現(xiàn)上層的復(fù)雜應(yīng)用配置與運行管理，且OmegaConf可獨立使用。

此外默認情況下，Hydra會創(chuàng)建以下目錄結(jié)構(gòu)以追蹤和管理程序的運行結(jié)果：

outputs/
├── yyyy-mm-dd/          # 按日期分組
│   └── hh-mm-ss/        # 按時間精確到秒
│       └── .hydra/      # 保存本次運行的配置
│           ├── config.yaml    # 完整的配置
│           ├── hydra.yaml     # Hydra 自身的配置
│           └── overrides.yaml # 命令行覆蓋的參數(shù)
│       └── my_app.log   # 日志文件（如果配置了日志）
│       └── 其他輸出文件     # 你的程序生成的文件

可以通過以下方式為配置添加內(nèi)容：

通過命令行添加：

# 不支持直接在 +key=value 語法中傳入非 ASCII 字符
python my_app.py +name="zhangsan" +age=25

輸出：

name: zhangsan
age: 25

創(chuàng)建配置文件：
創(chuàng)建一個config.yaml文件，然后運行：

python my_app.py --config-path=. --config-name=config

在代碼中設(shè)置默認配置：
可以修改代碼，為@hydra.main裝飾器添加配置參數(shù)：

from omegaconf import DictConfig, OmegaConf
import hydra
@hydra.main(version_base=None, config_path=".", config_name="config")
def my_app(cfg):
    print(OmegaConf.to_yaml(cfg))
if __name__ == "__main__":
    my_app()

可以通過命令行覆蓋已加載配置中的值，但是注意無需添加+前綴：

python my_app.py name="lisi"

使用++前綴可實現(xiàn)若配置中已存在該參數(shù)則覆蓋，若不存在則新增：

python my_app.py ++name="wangwu" ++password=1234

要注意??：Hydra通過命令行修改配置時，僅會覆蓋或新增程序運行時內(nèi)存中的配置數(shù)據(jù)，不會改動磁盤上的原始配置文件，重啟程序后仍會配置加載文件的原始配置。

配置對象使用

通過Hydra加載配置后，可通過屬性或字典式訪問或修改已有的配置項，訪問不存在的配置項時會拋出異常：

from omegaconf import DictConfig, OmegaConf
import hydra
@hydra.main(version_base=None, config_path=".", config_name="config")
def my_app(cfg: DictConfig):
    # 屬性式訪問配置值
    assert cfg.name == "張三"
    # 字典式訪問配置值
    assert cfg["age"] == 25
    # 修改已有配置值
    cfg.name = "李四"          
    cfg["age"] = 30            
    assert cfg.name == "李四"
    assert cfg["age"] == 30
    # 訪問缺失值會拋出異常
    try:
        cfg.birth_year
    except Exception as e:
        print("error !!")
        print(e)
if __name__ == "__main__":
    my_app()

之所以不允許訪問不存在的配置鍵，僅能操作已有配置鍵，是因為Hydra默認啟用了struct模式以嚴格結(jié)構(gòu)化配置。如需新增或修改配置，可先關(guān)閉嚴格模式，允許動態(tài)新增鍵。但如果嵌套層級也未提前聲明，則需要先創(chuàng)建空嵌套，再為其添加子項：

from omegaconf import DictConfig, OmegaConf
import hydra
import os
@hydra.main(version_base=None, config_path=".", config_name="config")
def my_app(cfg: DictConfig):
    # 關(guān)閉struct模式，允許新增配置鍵
    OmegaConf.set_struct(cfg, False)
    # 同一級新增配置
    cfg.birth_year = 1995      
    cfg["hobby"] = ["籃球", "編程"]
    # 無法直接給不存在的嵌套層級鏈式賦值
    # cfg.address.city = "北京"          
    # 需要先創(chuàng)建嵌套層級，再賦值子鍵
    cfg.address = OmegaConf.create({})  # 顯式創(chuàng)建空的嵌套
    cfg.address.city = "北京"         
    cfg.address["district"] = "朝陽區(qū)"
    # 驗證寫入結(jié)果
    assert cfg.birth_year == 1995  
    assert cfg.address.district == "朝陽區(qū)"
    print("配置寫入驗證通過！")
if __name__ == "__main__":
    my_app()

對配置文件進行分組

若希望分別使用CNN和Transformer模型對數(shù)據(jù)集進行訓(xùn)練基準測試，可通過配置組（Config Group）實現(xiàn)這一需求。配置組是一個帶有名稱的分組，包含一組有效的配置項。若選擇不存在的配置項，系統(tǒng)會生成錯誤提示，并列出所有有效的配置項。

創(chuàng)建配置組時，需先新建一個目錄（例如model），用于存放各模型配置項對應(yīng)的文件。由于預(yù)計會創(chuàng)建多個配置組，建議提前將所有配置文件統(tǒng)一移至conf目錄下管理。

目錄結(jié)構(gòu)如下：

├─ conf
│  └─ model
│      ├─ cnn.yaml
│      └─ transformer.yaml
└── my_app.py

model/cnn.yaml：

backbone: resnet50
learning_rate: 0.001
batch_size: 32
epochs: 20
dropout: 0.2

model/transformer.yaml：

backbone: vit_base
learning_rate: 0.0001
batch_size: 16
epochs: 30
attention_heads: 12

所有配置文件已統(tǒng)一存放至conf目錄，需通過config_path參數(shù)告知Hydra該目錄位置，并在代碼中指定待加載的配置文件名config_name。若未明確指定具體配置文件名，Hydra無法自動推斷加載目標，最終會輸出空配置:

from omegaconf import DictConfig, OmegaConf
import hydra
@hydra.main(version_base=None, config_path="conf", config_name="model/cnn")
def my_app(cfg: DictConfig) -> None:
    print(OmegaConf.to_yaml(cfg))
if __name__ == "__main__":
    my_app()

也可以通過命令行從配置組中選擇特定配置項，命令行使用+分組名=配置項的格式，例如：

python my_app.py +model=transformer

與常規(guī)用法一致，仍可覆蓋最終配置中的單個參數(shù)值：

python my_app.py +model=transformer model.epochs=40

多文件處理

可以生成一個配置文件，在配置文件中用defaults參數(shù)添加默認配置列表。該列表用于指定Hydra組合最終配置對象的規(guī)則，按照約定，它需作為配置文件的首個配置項。如下所示：

defaults:
  - model: cnn

然后這個配置文件可以命名為任意名字，如conf文件夾下的config.yaml，這樣運行會默認加載model對應(yīng)的文件配置：

from omegaconf import DictConfig, OmegaConf
import hydra
@hydra.main(version_base=None, config_path="conf", config_name="config")
def my_app(cfg: DictConfig) -> None:
    print(OmegaConf.to_yaml(cfg))
if __name__ == "__main__":
    my_app()

默認配置列表支持疊加多個深度學(xué)習(xí)相關(guān)配置項。若同一配置組存在兩個配置文件，系統(tǒng)會將這兩個配置文件合并為一個新字典；當(dāng)配置中出現(xiàn)相同鍵名時，后加載的配置項會覆蓋先加載的配置項。示例默認配置如下：

defaults:
  - model: 
    - cnn
    - transformer

若在配置文件夾conf下的dataset目錄中，存在如下配置文件model/cifar10.yaml：

name: CIFAR-10
path: ./data/cifar10
num_classes: 10
learning_rate: 0.0001
augmentation: true  # 是否開啟數(shù)據(jù)增強

當(dāng)默認配置文件conf/config.yaml中默認配置列表的內(nèi)容如下：

defaults:
  - model: cnn
  - dataset: cifar10

由于model和dataset分屬不同的配置組，Hydra會將這兩個配置組的默認配置進行獨立合并。最終生成的完整配置結(jié)構(gòu)中，會包含model和dataset兩個一級配置項，各自保留對應(yīng)配置組的完整參數(shù)：

model:
  # 此處為conf/model/cnn.yaml中的配置內(nèi)容
dataset:
  # 此處為conf/dataset/cifar10.yaml中的配置內(nèi)容

即使設(shè)置了默認配置，仍可手動確定參數(shù)并覆蓋部分配置參數(shù)：

python my_app.py model=cnn model.epochs=30

在配置項前添加~前綴，可從默認配置列表中移除該默認項：

python my_app.py ~model

主配置的組合順序

主配置文件中可同時包含配置參數(shù)和默認配置列表。在此情況下，若需調(diào)整默認配置列表與主配置之間的覆蓋關(guān)系，可通過添加_self_關(guān)鍵字實現(xiàn)：將_self_置于默認配置列表末尾，則主配置參數(shù)將覆蓋默認配置列表中的對應(yīng)項；若將其置于列表開頭，則默認配置列表中的參數(shù)將覆蓋主配置中的內(nèi)容。

需注意的是，從Hydra 1.1版本開始，默認行為為主配置覆蓋默認配置列表中的配置；而在此之前的版本中，默認配置列表會覆蓋主配置的參數(shù)。

例如默認配置文件config.yaml內(nèi)容如下，會進行數(shù)據(jù)覆蓋，也就是說配置文件里dataset部分會覆蓋默認配置中的同名部分：

defaults:
  - model: cnn
  - dataset: cifar10 
  - _self_
dataset: 
  name: my_dataset
version: 1.0

1.2 整合應(yīng)用

隨著軟件復(fù)雜度的不斷提升，我們會采用模塊化與組合化的設(shè)計思路來保證其可維護性。這種思路同樣適用于配置文件的管理。假設(shè)我們需要為示例程序配置多類深度學(xué)習(xí)模型支持，且每個模型對應(yīng)多種訓(xùn)練策略、搭配不同的數(shù)據(jù)預(yù)處理流程。使用Hydra時，既不必為模型、策略、預(yù)處理流程的各類組合編寫?yīng)毩㈩?，也無需為其單獨編寫配置文件。我們可以借鑒底層軟件開發(fā)的核心思路：通過組合化配置來解決這一問題。

多輪運行（Multi-run）

對于使用多套配置運行同一應(yīng)用程序的場景，可以通過命令行或配置文件兩種方式為Hydra應(yīng)用啟用多輪運行功能。該功能自Hydra 1.2版本起引入，通過設(shè)置hydra.mode配置項實現(xiàn)。hydra.mode的合法取值包括RUN（單次運行）和MULTIRUN（多輪運行）。若在輸入配置中將hydra.mode設(shè)為MULTIRUN，應(yīng)用程序?qū)⒛J以多輪運行模式啟動。

例如默認配置文件為：

defaults:
  - model: cnn
  - dataset: cifar10

多輪運行命令如下：

python my_app.py hydra.mode=MULTIRUN model=cnn,transformer dataset=cifar10

只要參數(shù)值用逗號分隔，就會被Hydra識別為多取值參數(shù)，Hydra會把所有帶多個取值的參數(shù)做笛卡爾積（全組合），Hydra會把每個參數(shù)的取值兩兩配對，生成以下多個任務(wù)，依次運行：

python my_app.py hydra.mode=MULTIRUN model=cnn,transformer dataset=cifar10
# 本地啟動2個任務(wù)
#0 : model=cnn dataset=cifar10
#1 : model=transformer dataset=cifar10

該命令可以用命令行參數(shù)簡化：

python my_app.py --multirun model=cnn,transformer dataset=cifar10
# 或
python my_app.py -m model=cnn,transformer dataset=cifar10

注意Hydra會在任務(wù)啟動時延遲組合配置。若在啟動任務(wù)參數(shù)遍歷后修改代碼或配置文件，最終組合生成的配置可能會受影響。

也可以在輸入配置中通過覆蓋hydra.sweeper.params來定義參數(shù)遍歷規(guī)則并通過mode設(shè)置運行模式。沿用上述示例，以下配置可實現(xiàn)完全相同的多輪運行效果：

defaults:
  - model: cnn
  - dataset: cifar10 
hydra:
  mode: MULTIRUN # 設(shè)置運行模式
  sweeper:
    params:
      dataset: cifar10
      model: transformer, cnn

直接運行程序不使用任何附加參數(shù)，結(jié)果如下：

$ python my_app.py
# 本地啟動2個任務(wù)
#0 : model=transformer dataset=cifar10
#1 : model=cnn dataset=cifar10

1.3 信息管理

輸出目錄

Hydra能夠解決每次運行程序時需要手動指定新輸出目錄的問題，它會為每次運行自動創(chuàng)建一個專屬目錄，并在該輸出目錄中執(zhí)行代碼。默認情況下，每次運行應(yīng)用程序時，都會生成一個全新的輸出目錄?？梢酝ㄟ^讀取Hydra配置來獲取本次運行該輸出目錄的路徑，示例如下：

from omegaconf import DictConfig, OmegaConf
import hydra
import os
@hydra.main(version_base=None, config_path="conf", config_name="config")
def my_app(_cfg: DictConfig) -> None:
    print(f"工作目錄：{os.getcwd()}")
    print(f"輸出目錄：{hydra.core.hydra_config.HydraConfig.get().runtime.output_dir}")
if __name__ == "__main__":
    my_app()

通過設(shè)置hydra.job.chdir=True，可以讓Hydra的@hydra.main裝飾器在執(zhí)行用戶的主函數(shù)前，調(diào)用os.chdir將Python工作目錄切換到輸出目錄：

python my_app.py hydra.job.chdir=True

可以通過覆蓋配置項hydra.output_subdir將設(shè)為null，則會完全禁用該子目錄的創(chuàng)建。

日志

由于標準logging模塊配置較為復(fù)雜，為實現(xiàn)常規(guī)的日志功能通常需要編寫較多代碼，且配置過程不夠簡便。Hydra能夠自動完成Python logging的配置，從而有效解決這一問題。默認情況下，Hydra會以INFO級別向控制臺輸出日志，同時在當(dāng)前工作目錄自動生成日志文件留存記錄。以下為使用Hydra進行日志記錄的示例：

# hydra_log_demo.py
import logging
from omegaconf import DictConfig
import hydra
# 為本文件創(chuàng)建日志器
log = logging.getLogger(__name__)
@hydra.main(version_base=None)
def my_app(_cfg: DictConfig) -> None:
    log.info("Info 級別日志消息")
    log.debug("Debug 級別日志消息")
if __name__ == "__main__":
    my_app()

可通過在命令行中指定hydra.verbose配置項來啟用DEBUG級別的日志輸出。該配置項支持布爾值、字符串或列表類型的取值，開啟全部或指定日志器的DEBUG級別輸出如下：

python hydra_log_demo.py hydra.verbose=true

若要將特定函數(shù)對應(yīng)日志器的級別設(shè)為DEBUG，可使用如下命令：

python hydra_log_demo.py hydra.verbose="[__main__,my_custom_logger]"

其效果等同于代碼：

import logging
logging.getLogger(NAME).setLevel(logging.DEBUG)

如果不希望Hydra自動配置日志系統(tǒng)，可以將hydra/job_logging（對應(yīng)程序的日志）和hydra/hydra_logging（對應(yīng)Hydra框架自身的日志）均設(shè)為none：

python my_app.py hydra/job_logging=None hydra/hydra_logging=None

調(diào)試功能

Hydra提供多種配置選項，可有效提升程序的可調(diào)試性。在命令行中使用--cfg或-c參數(shù)，即可在不運行目標函數(shù)的情況下打印應(yīng)用程序的配置信息。該參數(shù)需配合一個選項來指定打印的配置范圍：

job：打印業(yè)務(wù)代碼的配置
hydra：打印hydra框架自身的配置
all：打印完整配置內(nèi)容，即業(yè)務(wù)配置與hydra配置的合集

僅打印業(yè)務(wù)配置指令如下：

$ python my_app.py --cfg job

若只展示配置中的某一子集，可搭配參數(shù)--package或簡寫-p使用：

python my_app.py --cfg hydra --package hydra.job

默認情況下，配置中的插值表達式不會被解析。若需打印解析后的最終配置，可在--cfg參數(shù)基礎(chǔ)上，額外添加--resolve參數(shù)。

信息查詢功能

使用--info參數(shù)可查詢Hydra框架及應(yīng)用程序的各類相關(guān)信息：

--info all：默認模式，打印所有可用信息
--info config：打印配置組合相關(guān)的輔助信息，包括：配置搜索路徑、默認配置樹、默認配置列表及最終生效的配置內(nèi)容
--info defaults：打印最終的默認配置列表
--info defaults-tree：打印默認配置樹結(jié)構(gòu)
--info plugins：打印已安裝的插件信息

2 結(jié)構(gòu)化配置

在復(fù)雜項目中，配置文件常面臨類型模糊、配置錯誤難排查、缺少靜態(tài)校驗等問題。例如：字段類型不明確易引發(fā)運行時異常、多層級配置的結(jié)構(gòu)一致性難以保障、協(xié)作時難以通過工具提前發(fā)現(xiàn)配置沖突。

為此，Hydra基于Python數(shù)據(jù)類（dataclasses）定義了配置結(jié)構(gòu)與類型，其核心價值在于提供運行時類型檢查與靜態(tài)類型檢查雙重保障。它支持基礎(chǔ)類型（int、str、bool、float、Enum 等）、嵌套結(jié)構(gòu)、容器類型（List、Dict）以及可選字段，但也存在部分限制，例如僅部分支持聯(lián)合類型，且不支持自定義方法。

Hydra中結(jié)構(gòu)化配置主要有兩種使用模式，均完整保留其核心功能：

直接作為配置使用（替代配置文件），適合快速入門；
作為配置模式（schema）使用，用于校驗現(xiàn)有配置文件，適合大型或協(xié)作項目。

本教程將按此順序依次詳解兩種模式。

2.1 Hydra代碼配置

在后續(xù)的教程中，我們將使用ConfigStore類把數(shù)據(jù)類（dataclasses）注冊為Hydra中的輸入配置。ConfigStore是一個在內(nèi)存中存儲配置的單例（singleton）對象，與它交互的核心API是下文將要介紹的store方法。

class ConfigStore(metaclass=Singleton):
    def store(
        self,
        name: str,
        node: Any,
        group: Optional[str] = None,
        package: Optional[str] = "_group_",
        provider: Optional[str] = None,
    ) -> None:
        """
        將配置節(jié)點存儲至配置倉庫中
        :param name: 配置名稱
        :param node: 配置節(jié)點，支持 DictConfig、ListConfig、
            結(jié)構(gòu)化配置（Structured configs），甚至普通的 dict 和 list 類型
        :param group: 配置分組，子分組分隔符為 '/'，
            例如 hydra/launcher
        :param package: 配置節(jié)點的父級層級結(jié)構(gòu)。
            子節(jié)點分隔符為 '.'，例如 foo.bar.baz
        :param provider: 提供該配置的模塊/應(yīng)用名稱，
            有助于調(diào)試排查問題。
        """
    ...

ConfigStore具備與YAML輸入配置完全一致的功能，除此之外還提供類型校驗?zāi)芰?。它既可單獨使用，也可與YAML配合使用。

基礎(chǔ)用例

假設(shè)我們有一個簡單的應(yīng)用程序，且存在一個包含cnn選項的model配置分組：

from omegaconf import DictConfig, OmegaConf
import hydra
@hydra.main(version_base=None, config_path="conf", config_name="model/cnn")
def my_app(cfg: DictConfig) -> None:
    print(OmegaConf.to_yaml(cfg))
if __name__ == "__main__":
    my_app()

目錄結(jié)構(gòu)：

├─ conf
│  └─ model
│      └─ cnn.yaml
└── my_app.py

model/cnn.yaml：

backbone: resnet50
learning_rate: 0.001
batch_size: 32
epochs: 20
dropout: 0.2

如果現(xiàn)在想要新增一個transformer選項該怎么做？我們可以直接新增model/transformer.yaml配置分組文件，但這并非唯一方式！也可以通過ConfigStore為Hydra新增model配置分組的transformer選項。

要實現(xiàn)這個需求，只需在上述代碼文件中添加幾行代碼：

from dataclasses import dataclass
import hydra
from omegaconf import DictConfig, OmegaConf
from hydra.core.config_store import ConfigStore
@dataclass
class TransformerConfig:
    optimizer: str = "sgd"
    lr: float = 0.0005
    hidden_dim: int = 256
cs = ConfigStore.instance()
# 將名為transformer的配置類注冊至model配置分組
# 注意出現(xiàn)實體文件會報錯
cs.store(name="transformer", group="model", node=TransformerConfig)
@hydra.main(version_base=None, config_path="conf")
def my_app(cfg: DictConfig) -> None:
    print(OmegaConf.to_yaml(cfg))
if __name__ == "__main__":
    my_app()

上述代碼不會生成實際的物理配置文件，它僅用于在內(nèi)存中注冊配置類?，F(xiàn)在應(yīng)用程序已經(jīng)能夠識別model配置組中的兩個選項，您可以通過以下命令運行程序來驗證效果：

python my_app.py +model=cnn

或

python my_app.py +model=transformer

在深度學(xué)習(xí)實驗中管理多個模型配置時，我們還可以借助ConfigStore支持的三種注冊方式靈活控制配置節(jié)點，實現(xiàn)不同方案間的快速切換：

from dataclasses import dataclass
import hydra
from omegaconf import DictConfig, OmegaConf
from hydra.core.config_store import ConfigStore
@dataclass
class TransformerConfig:
    optimizer: str = "sgd"
    lr: float = 0.0005
    hidden_dim: int = 256
cs = ConfigStore.instance()
# 直接使用類類型
cs.store(name="config1", node=TransformerConfig)
# 使用類實例（覆蓋部分默認值）
cs.store(name="config2", node=TransformerConfig(optimizer="rmsprop", lr=0.002))
# 使用字典（會失去運行時類型安全保障）
cs.store(name="config3", node={"optimizer": "adam", "lr": 0.003, "hidden_dim": 256})
# 3. Hydra主函數(shù)：加載并打印配置
@hydra.main(version_base=None, config_name="config1")  # 默認加載config1
def main(cfg: DictConfig) -> None:
    print("當(dāng)前加載的配置內(nèi)容：")
    print(cfg)  
if __name__ == "__main__":
    main()

配置組

在Hydra框架中，配置組是一種用于組織互斥但相關(guān)配置項的機制。以深度學(xué)習(xí)場景為例，訓(xùn)練CNN與Transformer屬于不同的模型配置，它們都屬于模型配置這一大類，但一次訓(xùn)練只能選擇其中一種，這就是配置組的典型應(yīng)用。

# 導(dǎo)入必要的庫
from dataclasses import dataclass 
from typing import Any           
import hydra                   
from hydra.core.config_store import ConfigStore 
from omegaconf import OmegaConf  
# 1. 定義CNN模型的配置
@dataclass  # 裝飾器：將普通類轉(zhuǎn)為結(jié)構(gòu)化配置類（自動生成初始化、比較等方法）
class CNNConfig:
    """CNN模型的訓(xùn)練配置（包含該模型特有的所有參數(shù)）"""
    model_type: str = "cnn"      
    batch_size: int = 32          
    learning_rate: float = 0.001  
# 2. 定義Transformer模型的配置
@dataclass
class TransformerConfig:
    """Transformer模型的訓(xùn)練配置（包含該模型特有的所有參數(shù)）"""
    model_type: str = "transformer" 
    batch_size: int = 16            
    learning_rate: float = 0.0001  
    num_heads: int = 8         
@dataclass
class Config:
    """整個訓(xùn)練程序的主配置類"""
    # model字段：用于接收配置組中選擇的模型配置（暫時標注為Any類型）
    model: Any
# 1. 獲取配置存儲庫的單例實例（整個程序只有一個ConfigStore）
cs = ConfigStore.instance()
# 2. 注冊主配置（名稱為"config"，對應(yīng)后續(xù)hydra.main的config_name）
cs.store(name="config", node=Config)
# 3. 注冊配置組：組名是"model"，包含兩個選項：
cs.store(group="model", name="cnn", node=CNNConfig)
cs.store(group="model", name="transformer", node=TransformerConfig)
# hydra.main裝飾器：標記程序入口，指定配置名稱為"config"
@hydra.main(version_base=None, config_name="config")
def train_model(cfg: Config) -> None:
    """深度學(xué)習(xí)模型訓(xùn)練的主函數(shù)"""
    print("===== 當(dāng)前使用的訓(xùn)練配置 =====")
    print(OmegaConf.to_yaml(cfg))
# 程序啟動入口
if __name__ == "__main__":
    train_model()

代碼運行直接輸出為：

model: ???

??? 表示：該字段本應(yīng)有值，但目前處于缺失狀態(tài)。由于我們未給模型配置組設(shè)置默認值，因此必須通過命令行顯式指定要使用的模型配置。注意命令中的+是必需的，因為模型配置組沒有默認值，+在這里表示添加并覆蓋該配置字段：

python my_app.py +model=cnn

在上面實現(xiàn)中，model字段被標注為Any類型，這雖然不會阻礙程序運行，但卻把配置對象當(dāng)作一個缺乏類型信息的黑箱字典，使得IDE無法提供智能提示，靜態(tài)類型檢查也完全失效，從而降低了代碼的可維護性和長期可靠性。要解決這一問題，解決方法是將不同模型配置之間的公共字段進行抽象，創(chuàng)建一個BaseModelConfig基礎(chǔ)配置類：

from dataclasses import dataclass
from typing import Any
import hydra
from omegaconf import MISSING  # 標記字段“無默認值”
from hydra.core.config_store import ConfigStore 
from omegaconf import OmegaConf  
@dataclass
class BaseModelConfig:
    """所有深度學(xué)習(xí)模型的基礎(chǔ)配置（抽離公共字段）"""
    model_type: str = MISSING       # 模型類型：無默認值（必須由子類指定）
    batch_size: int = 32            # 公共字段：默認批次大?。ㄗ宇惪芍貙懀?
    learning_rate: float = 0.001    # 公共字段：默認學(xué)習(xí)率（子類可重寫）
# 1. 定義CNN模型的配置
@dataclass  # 裝飾器：將普通類轉(zhuǎn)為結(jié)構(gòu)化配置類（自動生成初始化、比較等方法）
class CNNConfig(BaseModelConfig):
    """CNN模型的訓(xùn)練配置（包含該模型特有的所有參數(shù)）"""
    model_type: str = "cnn"      
    batch_size: int = 32          
    learning_rate: float = 0.001  
# 2. 定義Transformer模型的配置
@dataclass
class TransformerConfig(BaseModelConfig):
    """Transformer模型的訓(xùn)練配置（包含該模型特有的所有參數(shù)）"""
    model_type: str = "transformer" 
    batch_size: int = 16            
    learning_rate: float = 0.0001   
    num_heads: int = 8         
@dataclass
class Config:
    """整個訓(xùn)練程序的主配置類"""
    # 不再是Any，而是BaseModelConfig
    model: BaseModelConfig
# 1. 獲取配置存儲庫的單例實例（整個程序只有一個ConfigStore）
cs = ConfigStore.instance()
# 2. 注冊主配置（名稱為"config"，對應(yīng)后續(xù)hydra.main的config_name）
cs.store(name="config", node=Config)
# 3. 注冊配置組：組名是"model"，包含兩個選項：
cs.store(group="model", name="cnn", node=CNNConfig)
cs.store(group="model", name="transformer", node=TransformerConfig)
# hydra.main裝飾器：標記程序入口，指定配置名稱為"config"
@hydra.main(version_base=None, config_name="config")
def train_model(cfg: Config) -> None:
    """深度學(xué)習(xí)模型訓(xùn)練的主函數(shù)"""
    print("===== 當(dāng)前使用的訓(xùn)練配置 =====")
    print(OmegaConf.to_yaml(cfg))
# 程序啟動入口
if __name__ == "__main__":
    train_model()

可以在主結(jié)構(gòu)化配置中設(shè)置默認值，方法與在config.yaml配置文件中定義相似。以下是一個深度學(xué)習(xí)模型配置的示例，新增了默認配置列表，使其默認加載model=cnn。只需在代碼中添加默認列表，并相應(yīng)修改配置類即可：

from dataclasses import dataclass, field
from typing import Any, List       
# 定義默認配置列表：從配置組"model"中加載名為"cnn"的配置
defaults = [
    {"model": "cnn"}
    # 設(shè)為 MISSING，則可強制用戶在命令行中指定該參數(shù)的值。
    # {"model": MISSING}
]
@dataclass
class Config:
    """整個訓(xùn)練程序的主配置類"""
    # 受@dataclass限制，此處需通過field定義默認配置列表（默認加載cnn配置）
    defaults: List[Any] = field(default_factory=lambda: defaults)
    # Hydra會根據(jù)默認配置列表自動填充該字段，類型為BaseModelConfig
    model: BaseModelConfig = MISSING

你也可以通過命令行覆蓋默認配置，指定使用Transformer模型，注意不要+號，因為這是覆蓋操作：

python my_app.py model=transformer

2.2 配置模式

Hydra的結(jié)構(gòu)化配置本質(zhì)是用代碼定義的結(jié)構(gòu)化規(guī)則來管理配置。它除了可以用代碼定義的結(jié)構(gòu)化配置替代傳統(tǒng)的YAML配置文件外，還能將結(jié)構(gòu)化配置作為配置規(guī)則模板（Schema），用于校驗已有YAML配置文件是否符合規(guī)范。Schema能夠在程序啟動時校驗配置的合法性，提前攔截所有配置錯誤。這對于保障大型項目的穩(wěn)定性至關(guān)重要，尤其適合多人協(xié)作的場景，可以有效避免配置錯寫、漏寫字段等問題。

同一配置組內(nèi)的Schema校驗

以深度學(xué)習(xí)訓(xùn)練場景的模型配置為例，下文將拆解如何通過預(yù)設(shè)的Schema模板，校驗同一配置分組下各配置文件的字段、類型等是否符合規(guī)范要求。

給定如下配置目錄結(jié)構(gòu)：

conf/
├── config.yaml          # 主配置（包含訓(xùn)練、模型、數(shù)據(jù)等）
└── model                # 模型配置組
    ├── resnet.yaml      # ResNet模型配置
    └── transformer.yaml # Transformer模型配置

需為上述每個配置文件添加結(jié)構(gòu)化配置Schema，核心方式是在YAML文件的defaults列表中聲明要繼承的Schema模板，并將這些Schema以base_config、model/resnet.yaml、model/transformer.yaml為名注冊至Hydra配置倉庫。各配置文件的defaults列表配置如下：

config.yaml：

defaults:
  - base_config          # 繼承基礎(chǔ)配置Schema
  - model: resnet        # 默認使用ResNet模型配置
  - _self_               # 自身配置覆蓋默認值
# 自定義訓(xùn)練參數(shù)
train:
  batch_size: 32
  lr: 0.001
debug: true

model/resnet.yaml：

defaults:
  - base_resnet  # 繼承ResNet基礎(chǔ)Schema
# ResNet專屬參數(shù)
layers: 50
pretrained: true
num_classes: 1000

model/transformer.yaml：

defaults:
  - base_transformer  # 繼承Transformer基礎(chǔ)Schema
# Transformer專屬參數(shù)
num_heads: 8
num_layers: 6
hidden_dim: 512
max_seq_len: 512

通過Python dataclass定義各種Schema規(guī)則，并注冊到Hydra配置倉庫，使YAML配置文件可關(guān)聯(lián)到對應(yīng)的校驗規(guī)則：

from dataclasses import dataclass
from omegaconf import OmegaConf, MISSING
import hydra
from hydra.core.config_store import ConfigStore
# -------------------------- 基礎(chǔ)Schema定義 --------------------------
@dataclass
class BaseModelConfig:
    """所有模型的基礎(chǔ)配置Schema"""
    model_type: str = MISSING  # 必選字段，無默認值
    device: str = "cuda"       # 可選字段，默認值cuda
    dropout: float = MISSING   # 必選字段，無默認值
@dataclass
class ResNetConfig(BaseModelConfig):
    """ResNet模型專屬Schema（繼承基礎(chǔ)模型配置）"""
    model_type: str = "resnet"  # 固定值，標識模型類型
    dropout: float = 0.1        # 覆蓋默認值
    layers: int = MISSING       # ResNet專屬必選字段
    pretrained: bool = MISSING
    num_classes: int = MISSING
@dataclass
class TransformerConfig(BaseModelConfig):
    """Transformer模型專屬Schema（繼承基礎(chǔ)模型配置）"""
    model_type: str = "transformer"  # 固定值
    dropout: float = 0.1             # 覆蓋默認值
    num_heads: int = MISSING         # Transformer專屬必選字段
    num_layers: int = MISSING
    hidden_dim: int = MISSING
    max_seq_len: int = MISSING
@dataclass
class TrainConfig:
    """訓(xùn)練配置Schema"""
    batch_size: int = MISSING
    lr: float = MISSING
    epochs: int = 10  # 默認訓(xùn)練10輪
@dataclass
class Config:
    """整體配置Schema"""
    model: BaseModelConfig = MISSING  # 模型配置（必選）
    train: TrainConfig = MISSING     # 訓(xùn)練配置（必選）
    debug: bool = False              # 調(diào)試模式（可選）
# -------------------------- 注冊Schema到配置倉庫 --------------------------
cs = ConfigStore.instance()
cs.store(name="base_config", node=Config)  # 注冊主配置Schema
cs.store(group="model", name="base_resnet", node=ResNetConfig)  # 注冊ResNet Schema
cs.store(group="model", name="base_transformer", node=TransformerConfig)  # 注冊Transformer Schema
# -------------------------- 主函數(shù) --------------------------
@hydra.main(version_base=None, config_path="conf", config_name="config")
def train_app(cfg: Config) -> None:
    """深度學(xué)習(xí)訓(xùn)練入口，打印最終配置"""
    print("最終訓(xùn)練配置：")
    print(OmegaConf.to_yaml(cfg))
if __name__ == "__main__":
    train_app()

運行代碼時，Hydra會先加載YAML配置文件，再通過關(guān)聯(lián)的Schema完成合法性校驗，若配置存在錯誤會立即拋出異常：

# 正常運行（使用默認ResNet配置）
python my_app.py
# 模擬配置錯誤（layers字段應(yīng)為int類型，傳入字符串觸發(fā)校驗失?。?
python my_app.py model.layers='attention'

跨配置組的Schema校驗

在前文的模型訓(xùn)練場景中，Schema都定義在主程序里。但實際開發(fā)中，常會遇到第三方庫提供標準化的Schema，我們需要跨配置組引用這些Schema來校驗自己的配置文件，而非把所有Schema都寫在主程序中。

假設(shè)存在一個公共的optimizer_lib庫，該庫預(yù)先定義了所有模型的標準Schema并注冊在獨立配置組中；本地conf/optimizer配置組下的YAML文件（如sgd.yaml、adam.yaml）僅需編寫YAML配置文件，并關(guān)聯(lián)這個外部庫的Schema完成校驗，無需重復(fù)定義模型規(guī)則，配置目錄結(jié)構(gòu)如下：

# 項目整體目錄
├── my_app.py               # 主程序
├── optimizer_lib.py        # 獨立的優(yōu)化器Schema庫
└── conf/
    ├── config.yaml         # 主配置
    └── optimizer/          # 本地優(yōu)化器配置組
        ├── sgd.yaml        
        └── adam.yaml

optimizer_lib.py代碼如下：

from dataclasses import dataclass
from omegaconf import MISSING
from hydra.core.config_store import ConfigStore
# -------------------------- 優(yōu)化器基礎(chǔ)Schema --------------------------
@dataclass
class BaseOptimizerConfig:
    """所有優(yōu)化器的基礎(chǔ)Schema（獨立庫定義）"""
    opt_type: str = MISSING    # 必選字段：優(yōu)化器類型
    lr: float = MISSING        # 必選字段：學(xué)習(xí)率
    weight_decay: float = 0.0  # 可選字段：權(quán)重衰減，默認0
# -------------------------- 具體優(yōu)化器Schema --------------------------
@dataclass
class SGDConfig(BaseOptimizerConfig):
    """SGD優(yōu)化器專屬Schema"""
    opt_type: str = "sgd"      # 固定標識
    momentum: float = MISSING  # SGD專屬必選字段
    nesterov: bool = False     # 可選字段：是否使用Nesterov動量
@dataclass
class AdamConfig(BaseOptimizerConfig):
    """Adam優(yōu)化器專屬Schema"""
    opt_type: str = "adam"     # 固定標識
    betas: tuple[float, float] = (0.9, 0.999)  # 可選字段：beta參數(shù)
    eps: float = MISSING                       # Adam專屬必選字段
# -------------------------- 注冊跨配置組的Schema --------------------------
def register_optimizer_configs() -> None:
    cs = ConfigStore.instance()
    # 注冊到獨立分組：optimizer_lib/optimizer
    cs.store(
        group="optimizer_lib/optimizer",
        name="sgd",
        node=SGDConfig
    )
    cs.store(
        group="optimizer_lib/optimizer",
        name="adam",
        node=AdamConfig
    )

主程序my_app.py中定義整體配置Schema，并調(diào)用optimizer_lib的注冊函數(shù)，將跨配置組的Schema納入Hydra配置倉庫：

from dataclasses import dataclass
from omegaconf import MISSING, OmegaConf
import hydra
from hydra.core.config_store import ConfigStore
import optimizer_lib  # 導(dǎo)入獨立的優(yōu)化器庫
# -------------------------- 整體配置Schema --------------------------
@dataclass
class TrainConfig:
    """訓(xùn)練配置Schema"""
    batch_size: int = 32
    epochs: int = 10
@dataclass
class Config:
    """主配置Schema"""
    optimizer: optimizer_lib.BaseOptimizerConfig = MISSING  # 引用獨立庫的Schema
    train: TrainConfig = MISSING
    debug: bool = False
# -------------------------- 注冊本地Schema并加載跨組Schema --------------------------
cs = ConfigStore.instance()
cs.store(name="base_config", node=Config)  # 注冊主配置Schema
optimizer_lib.register_optimizer_configs()  # 注冊跨配置組的優(yōu)化器Schema
# -------------------------- 主函數(shù) --------------------------
@hydra.main(version_base=None, config_path="conf", config_name="config")
def train_app(cfg: Config) -> None:
    """訓(xùn)練入口，打印最終配置并觸發(fā)Schema校驗"""
    print("最終訓(xùn)練配置（含跨組優(yōu)化器配置）：")
    print(OmegaConf.to_yaml(cfg))
if __name__ == "__main__":
    train_app()

本地conf/optimizer下的YAML文件需要通過絕對路徑引用optimizer_lib中的Schema，并通過@_here_指定包路徑，確保Schema的校驗作用域與當(dāng)前配置一致。

conf/optimizer/sgd.yaml：

defaults:
  - /optimizer_lib/optimizer/sgd@_here_  # 絕對路徑引用跨組Schema，@_here_統(tǒng)一包作用域
# SGD專屬配置（需符合SGDConfig的Schema規(guī)則）
lr: 0.01
momentum: 0.9
weight_decay: 0.0001

conf/optimizer/adam.yaml：

defaults:
  - /optimizer_lib/optimizer/adam@_here_  # 絕對路徑引用跨組Schema
  - _self_  # 自身配置覆蓋Schema默認值（組合順序：Schema先加載，自身配置后覆蓋）
# Adam專屬配置（需符合AdamConfig的Schema規(guī)則）
lr: 0.001
betas: (0.9, 0.999)
eps: 1e-08
weight_decay: 0.0005

主配置conf/config.yaml：

defaults:
  - base_config          # 主配置Schema
  - optimizer: sgd      # 默認使用SGD優(yōu)化器配置
  - _self_
# 自定義訓(xùn)練參數(shù)
train:
  batch_size: 64
  epochs: 20
debug: true

運行代碼時，Hydra會先加載第三方庫的Schema，再校驗本地YAML配置：

# 正常運行（SGD配置符合Schema規(guī)則）
python my_app.py
# 配置錯誤（momentum應(yīng)為float，傳入字符串觸發(fā)校驗失?。?
python my_app.py optimizer.momentum='high'
# 配置錯誤（Adam必選字段eps缺失，啟動時直接報錯）
python my_app.py optimizer=adam optimizer.eps=none