hydra config

ad_official·2025년 3월 4일

기타

목록 보기

1/1

Hydra의 @hydra.main(config_path=CONFIG_PATH, config_name=CONFIG_NAME) 데코레이터는 프로그램의 진입점을 구성할 때 설정(configuration)을 자동으로 로드하고 주입하는 역할을 합니다. 이 데코레이터가 구체적으로 어떻게 동작하는지 단계별로 자세히 설명하면 다음과 같습니다.

1. 설정 파일의 위치와 이름 지정

config_path:
- 이 인자는 YAML 구성 파일들이 위치한 디렉토리 경로를 지정합니다.
- 예를 들어, CONFIG_PATH가 "config/simulation"으로 설정되어 있다면, Hydra는 이 디렉토리 안에서 설정 파일을 찾습니다.
config_name:
- 이 인자는 불러올 기본 구성 파일의 이름(확장자 .yaml은 생략 가능)을 지정합니다.
- 예를 들어, CONFIG_NAME이 "default_simulation"이라면, Hydra는 "default_simulation.yaml" 파일을 찾습니다.

2. Hydra가 구성 파일을 찾는 규칙

Hydra는 config_path를 기준으로 설정 파일들을 검색합니다.
- 만약 config_path가 상대 경로라면, 기본적으로 현재 실행 중인 스크립트의 위치나 Hydra의 검색 경로(search path)에 따라 해석됩니다.
- 예를 들어, 프로젝트 루트가 ~/PycharmProjects/Diffusion-Planner일 때, config/simulation 폴더가 프로젝트 내에 존재한다면, Hydra는
  ~/PycharmProjects/Diffusion-Planner/config/simulation/default_simulation.yaml 파일을 찾게 됩니다.
구성 파일의 조합 및 상속:
- Hydra는 여러 YAML 파일을 조합하여 최종 설정을 구성할 수 있습니다.
- 기본 구성 파일(예: default_simulation.yaml)에 포함된 defaults 리스트를 통해 다른 구성 파일들을 참조(구성 요소 합성)할 수 있습니다.
명령줄 오버라이드:
- Hydra는 프로그램 실행 시 커맨드라인 인자로 전달된 설정 오버라이드를 자동으로 반영합니다.
- 예를 들어, 실행 명령어에 +simulation=closed_loop 같은 오버라이드를 포함하면, 이 값이 최종 설정에 병합됩니다.

3. 구성 파일 로드 및 DictConfig 생성

Hydra는 지정된 경로에서 "default_simulation.yaml" 파일을 읽어옵니다.
이 YAML 파일의 내용은 OmegaConf의 DictConfig 객체로 변환되어, 설정 값들이 계층적(중첩 구조)으로 저장됩니다.
DictConfig 객체는 이후 프로그램의 인자로 전달되어, 코드 내에서 설정 값을 쉽게 참조할 수 있게 합니다.

4. 작업 디렉토리 변경 및 실행 환경 구성

Hydra는 실행 시 자동으로 새 출력 디렉토리를 생성
- 이 디렉토리는 보통 실행 시간, 실험 고유 식별자 등을 포함하여 구성되며, 결과, 로그, 구성 파일 사본 등이 저장됩니다.
이렇게 하면 각 실행(run)마다 별도의 환경이 준비되어, 실험 결과의 재현성이 보장됩니다.

5. 최종 동작

데코레이터가 붙은 함수(예: main 함수)는 Hydra가 구성 파일을 로드한 후, 해당 DictConfig 객체를 인자로 받아 실행됩니다.
개발자는 이 설정 객체(cfg)를 사용하여 필요한 구성 요소(예: 시나리오 빌더, 플래너, 콜백 등)를 초기화할 수 있습니다.

요약

config_path=CONFIG_PATH는 설정 파일들이 있는 폴더를 지정하고,
config_name=CONFIG_NAME는 불러올 기본 YAML 파일의 이름을 지정합니다.
예를 들어, CONFIG_PATH가 "config/simulation"이고 CONFIG_NAME이 "default_simulation"이면, Hydra는
~/PycharmProjects/Diffusion-Planner/config/simulation/default_simulation.yaml 파일을 찾아서 DictConfig로 로드합니다.
또한, Hydra는 여러 YAML 파일의 조합, 명령줄 오버라이드, 출력 디렉토리 생성 등의 기능을 제공하여 실행 환경을 자동으로 구성합니다.

이러한 방식으로, Hydra는 복잡한 설정 관리 과정을 단순화하고, 실험 실행 전에 필요한 모든 설정을 자동으로 준비해줍니다.

2. 심화

GPT의 설명

Hydra 문법 정리

초기화 (initialize):
- hydra.initialize(config_path=...)를 사용하여 설정 파일들이 위치한 디렉토리를 지정
구성 합성 (compose):
- hydra.compose(config_name=..., overrides=[...])를 통해 기본 설정 파일을 로드하고, 오버라이드를 적용해 최종 구성(cfg)을 만듦
오버라이드 문자열:
- key=value 형식으로 설정 값을 직접 덮어쓸 수 있습니다.
- 리스트 형태의 오버라이드는 여러 값을 동시에 설정할 때 유용
- hydra.searchpath와 같이 특별한 키를 사용해 Hydra의 동작 방식을 조정할 수 있습니다.
패키지 검색 경로 (pkg://):
- pkg:// 접두사는 Python 패키지 내부에서 설정 파일을 찾도록 지정합니다.
- 예를 들어, pkg://diffusion_planner.config는 diffusion_planner 패키지 내의 config 디렉토리를 의미합니다.

이와 같이 Hydra는 설정 파일의 위치를 지정하고, 기본 설정을 로드한 후 오버라이드 옵션을 통해 동적으로 설정을 변경할 수 있도록 해줍니다. 이를 통해 복잡한 애플리케이션의 구성 관리를 유연하게 처리할 수 있습니다.

1. 글로벌 Hydra 인스턴스 초기화 및 재설정

hydra.core.global_hydra.GlobalHydra.instance().clear()  # reinitialize hydra if already initialized

목적:
Hydra는 내부적으로 전역 상태(global state)를 유지합니다. 한 번 초기화된 후에는 재초기화하려고 하면 에러가 발생할 수 있습니다.
동작:
- GlobalHydra.instance()는 Hydra의 전역 인스턴스를 반환합니다.
- .clear() 메서드는 이미 초기화된 상태를 지워줍니다.
효과:
여러 번 Hydra를 호출하거나, 같은 Python 프로세스 내에서 Hydra 기반 설정을 여러 번 로드할 때 발생할 수 있는 충돌을 방지합니다.

2. Hydra 초기화

hydra.initialize(config_path=CONFIG_PATH)

CONFIG_PATH:
- CONFIG_PATH = '../nuplan-devkit/nuplan/planning/script/config/nuboard'
  이 경로는 nuBoard 관련 설정 파일(보통 YAML 파일들)이 위치한 디렉토리입니다.
역할:
- Hydra가 설정 파일들을 어디에서 찾을지 알려줍니다.
- 초기화 단계에서는 구성 파일들의 기본 위치를 지정해주며, 이후 설정을 합성(composition)할 때 이 경로에서 설정 파일을 읽어옵니다.

3. Hydra 구성 합성 (Compose)

cfg = hydra.compose(config_name=CONFIG_NAME, overrides=[
    'scenario_builder=nuplan',
    f'simulation_path={ml_planner_simulation_folder}',
    'hydra.searchpath=[pkg://diffusion_planner.config.scenario_filter, pkg://diffusion_planner.config, pkg://nuplan.planning.script.config.common, pkg://nuplan.planning.script.experiments]',
    'port_number=6599'
])

config_name:
- CONFIG_NAME = 'default_nuboard'
  Hydra는 지정된 CONFIG_PATH 내에서 'default_nuboard.yaml' 또는 이와 유사한 기본 설정 파일을 찾아서 로드합니다.
overrides:
오버라이드 리스트는 기본 설정 파일의 값을 덮어쓰거나 추가 설정을 할 때 사용됩니다.
1. 'scenario_builder=nuplan'
  - 설정 파일 내의 scenario_builder 키를 nuplan으로 설정합니다.
  - 예를 들어, 여러 데이터베이스나 시나리오 빌더 중 어떤 것을 사용할지 지정할 때 사용됩니다.
2. f'simulation_path={ml_planner_simulation_folder}'
  - simulation_path라는 설정 값을 nuBoard에서 사용할 시뮬레이션 결과 파일들의 경로 리스트로 지정합니다.
  - 여기서는 ml_planner_simulation_folder라는 리스트를 문자열로 변환하여 전달합니다.
3. 'hydra.searchpath=[pkg://diffusion_planner.config.scenario_filter, pkg://diffusion_planner.config, pkg://nuplan.planning.script.config.common, pkg://nuplan.planning.script.experiments]'
  - Hydra는 설정 파일을 찾기 위해 여러 "검색 경로(search path)"를 사용합니다.
  - pkg:// 접두사는 Python 패키지 내부에서 설정 파일을 찾도록 지시합니다.
  - 이 오버라이드는 기본 검색 경로에 추가적인 경로들을 지정해, 필요한 설정 파일들을 올바르게 찾을 수 있도록 합니다.
4. 'port_number=6599'
  - nuBoard가 실행될 때 사용할 포트 번호를 설정합니다.
결과:
위 오버라이드들은 기본 설정 파일(default_nuboard)에 정의된 값들을 변경하거나 추가하여 최종적인 구성 객체(cfg)를 만듭니다. 이 객체는 nuBoard 실행 시 모든 필요한 설정 정보를 담고 있게 됩니다.

ad_official