> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

> W&B를 Hydra와 통합하여 ML 실험의 복잡한 설정을 관리하고 하이퍼파라미터를 자동으로 로깅하세요.

# Hydra

> [Hydra](https://hydra.cc)는 연구용 애플리케이션을 비롯한 복잡한 애플리케이션의 개발을 간소화하는 오픈 소스 Python 프레임워크입니다. 핵심 기능은 여러 설정을 조합(composition)하여 계층적 설정을 동적으로 생성하고, 설정 파일과 명령줄에서 이를 재정의할 수 있다는 점입니다.

이 페이지에서는 Hydra 기반 설정 관리와 W\&B 실험 추적을 함께 사용하는 방법을 설명합니다. 이를 통해 Hydra의 조합 가능한 설정은 그대로 유지하면서 W\&B의 시각화, 하이퍼파라미터 최적화, run 비교 기능을 활용할 수 있습니다. 다음 섹션에서는 메트릭 추적, Hydra 설정의 하이퍼파라미터 로깅, 멀티프로세싱 문제 해결, W\&B Sweeps를 사용한 하이퍼파라미터 최적화를 다룹니다.

<h2 id="track-metrics">
  메트릭 추적
</h2>

Hydra로 설정한 run에서 W\&B로 메트릭을 보내려면 평소처럼 `wandb.init()`과 `wandb.Run.log()`를 사용하세요. 다음 예시에서는 Hydra 설정 파일에 `wandb.entity`와 `wandb.project`를 정의하여 하나의 설정으로 Hydra와 W\&B를 함께 제어합니다.

```python theme={"system"}
import wandb


@hydra.main(config_path="configs/", config_name="defaults")
def run_experiment(cfg):

    with wandb.init(entity=cfg.wandb.entity, project=cfg.wandb.project) as run:
      run.log({"loss": loss})
```

<h2 id="track-hyperparameters">
  하이퍼파라미터 추적
</h2>

Hydra의 설정을 W\&B에 로깅하면 모든 하이퍼파라미터를 run의 메트릭과 함께 확인할 수 있어 실험을 더 쉽게 비교하고 재현할 수 있습니다.

Hydra는 설정 딕셔너리를 처리하는 기본 인터페이스로 [OmegaConf](https://omegaconf.readthedocs.io/en/2.1_branch/)를 사용합니다. OmegaConf 설정 객체(예: `omegaconf.DictConfig`)는 일반 Python `dict` 인스턴스가 아닙니다.

`wandb.Run.config`는 읽기 전용 속성이므로, OmegaConf 설정 객체를 전달하려고 하면 `wandb.Run.config = ...`에서 `AttributeError`가 발생합니다.

`OmegaConf.to_container()`로 `cfg`를 일반 `dict`로 변환한 다음 `wandb.init(config=...)`에 전달하세요(또는 `wandb.Run.config.update(...)`를 호출하세요).

```python theme={"system"}
import hydra
import omegaconf
import wandb


@hydra.main(version_base=None, config_path="configs/", config_name="defaults")
def run_experiment(cfg):
    cfg_dict = omegaconf.OmegaConf.to_container(
        cfg, resolve=True, throw_on_missing=True
    )
    # 선택 사항: W&B 메타데이터(entity, 프로젝트 등)가 run 설정에 함께 로깅되지 않도록 합니다
    cfg_dict.pop("wandb", None)
    with wandb.init(
        entity=cfg.wandb.entity,
        project=cfg.wandb.project,
        config=cfg_dict,
    ) as run:
        run.log({"loss": loss})
        model = Model(**run.config["model"]["configs"])
```

<h2 id="troubleshoot-multiprocessing">
  멀티프로세싱 문제 해결
</h2>

프로세스가 시작된 후 응답하지 않는다면 [분산 트레이닝에서 알려진 멀티프로세싱 문제](/ko/products/wandb/track/log/distributed-training)가 원인일 수 있습니다. 이 문제를 해결하려면 W\&B의 멀티프로세싱 프로토콜을 변경하세요. 다음과 같이 `wandb.init()`에 settings 매개변수를 추가로 지정하거나:

```python theme={"system"}
wandb.init(settings=wandb.Settings(start_method="thread"))
```

또는 셸에서 전역 환경 변수를 설정해도 됩니다:

```bash theme={"system"}
export WANDB_START_METHOD=thread
```

<h2 id="optimize-hyperparameters">
  하이퍼파라미터 최적화
</h2>

[W\&B Sweeps](/ko/products/wandb/sweeps)는 최소한의 코드만으로 W\&B 실험에 대한 인사이트와 시각화를 제공하는 하이퍼파라미터 검색 플랫폼입니다. Sweeps는 코드를 변경하지 않고도 Hydra 프로젝트와 통합됩니다. 스윕할 매개변수를 정의한 설정 파일만 있으면 됩니다.

다음은 `sweep.yaml` 파일의 예시입니다.

```yaml theme={"system"}
program: main.py
method: bayes
metric:
  goal: maximize
  name: test/accuracy
parameters:
  dataset:
    values: [mnist, cifar10]

command:
  - ${env}
  - python
  - ${program}
  - ${args_no_hyphens}
```

스윕을 실행하세요:

```bash theme={"system"}
wandb sweep sweep.yaml
```

W\&B는 프로젝트에 스윕을 자동으로 생성하고 `wandb agent` 명령을 반환합니다. 스윕을 실행할 각 머신에서 이 명령을 실행하세요.

<h3 id="pass-parameters-not-present-in-hydra-defaults">
  Hydra 기본값에 없는 매개변수 전달하기
</h3>

<a id="pitfall-3-sweep-passing-parameters-not-present-in-defaults" aria-label="Hydra 기본값에 없는 매개변수 전달하기" />

Hydra에서는 명령 앞에 `+`를 붙여 기본 설정 파일에 없는 추가 매개변수를 명령줄로 전달할 수 있습니다. 예를 들어 다음과 같이 호출하면 추가 매개변수에 원하는 값을 지정해 전달할 수 있습니다.

```bash theme={"system"}
python program.py +experiment=some_experiment
```

[Hydra Experiments](https://hydra.cc/docs/patterns/configuring_experiments/)를 설정할 때와 같은 방식으로는 이러한 `+` 설정에 대해 스윕을 실행할 수 없습니다. 이 문제를 해결하려면 experiment 매개변수를 비어 있는 기본 파일로 초기화한 다음, W\&B Sweep을 사용해 호출할 때마다 해당 빈 설정을 재정의하세요. 자세한 내용은 W\&B 리포트 [Configuring W\&B Projects with Hydra](https://forge.coreweave.com/wandb/adrishd/hydra-example/reports/Configuring-W-B-Projects-with-Hydra--VmlldzoxNTA2MzQw?galleryTag=posts\&utm_source=fully_connected\&utm_medium=blog\&utm_campaign=hydra)를 참조하세요.


## Related topics

- [Why does my process stop responding when using Hydra with Weights & Biases?](/support/models/articles/process-hangs-when-using-hydra-with-wan.md)