임의의 라이브러리에 wandb 추가하기

​

어떤 라이브러리에도 wandb 추가하기

이 가이드는 Python 라이브러리에 W&B를 통합하여 실험 추적(Experiment Tracking), GPU 및 시스템 모니터링, 모델 체크포인트(Model Checkpointing) 등 강력한 기능을 사용할 수 있도록 하는 방법과 모범 사례를 설명합니다.

아직 W&B 사용 방법을 익히는 중이라면, 이 문서의 Experiment Tracking과 같은 다른 W&B 가이드를 먼저 살펴볼 것을 권장합니다.

아래에서는 작업 중인 코드베이스가 단일 Python 학습 스크립트나 Jupyter 노트북보다 더 복잡할 때 적용할 수 있는 핵심 팁과 모범 사례를 다룹니다. 이 문서에서 다루는 주제는 다음과 같습니다:

• 설정 요구사항
• 사용자 로그인
• wandb 실행 시작하기
• 실행 Config 정의하기
• W&B로 로그 기록하기
• 분산 학습
• 모델 체크포인트와 기타 기능
• 하이퍼파라미터 튜닝
• 고급 통합

​

설정 요구 사항

시작하기 전에 라이브러리의 종속성에 W&B를 필수로 포함할지 여부를 먼저 결정하세요:

​

설치 시 W&B를 필수 의존성으로 설정하기

예를 들어 requirements.txt와 같은 종속성 파일에 W&B Python 라이브러리(wandb)를 추가하세요.

torch==1.8.0 
...
wandb==0.13.*

​

설치 시 W&B를 선택 사항으로 만들기

W&B SDK(wandb)를 선택 사항으로 두는 방법은 두 가지가 있습니다:

A. 사용자가 wandb를 수동으로 설치하지 않은 상태에서 wandb 기능을 사용하려고 할 때 오류를 발생시키고, 적절한 오류 메시지를 표시하도록 합니다:

try: 
    import wandb 
except ImportError: 
    raise ImportError(
        "You are trying to use wandb which is not currently installed."
        "Please install it using pip install wandb"
    ) 

B. Python 패키지를 빌드하는 경우 pyproject.toml 파일에 wandb를 선택적 의존성으로 추가합니다:

[project]
name = "my_awesome_lib"
version = "0.1.0"
dependencies = [
    "torch",
    "sklearn"
]

[project.optional-dependencies]
dev = [
    "wandb"
]

​

사용자 로그인하기

​

API key 생성

API key는 클라이언트나 머신을 W&B에 인증하는 데 사용됩니다. 사용자 프로필에서 API key를 생성할 수 있습니다.

보다 간편하게 설정하려면 User Settings로 바로 이동해 API key를 생성하세요. 새로 생성된 API key는 즉시 복사하여 비밀번호 관리자와 같은 안전한 위치에 저장하세요.

1. 오른쪽 상단의 사용자 프로필 아이콘을 클릭합니다.
2. User Settings를 선택한 다음, 아래로 스크롤하여 API Keys 섹션으로 이동합니다.

​

wandb 라이브러리를 설치하고 로그인하기

로컬 환경에 wandb 라이브러리를 설치하고 로그인하려면:

Command Line

1. WANDB_API_KEY 환경 변수를 API key로 설정합니다.

   export WANDB_API_KEY=<your_api_key>
   

2. wandb 라이브러리를 설치하고 로그인합니다.

   pip install wandb
   
   wandb login
   

Python

pip install wandb

import wandb
wandb.login()

Python notebook

!pip install wandb

import wandb
wandb.login()

위 단계들을 거치지 않고 처음으로 wandb를 사용하는 경우, 스크립트에서 wandb.init을 호출하면 자동으로 로그인 프롬프트가 표시됩니다.

​

실행 시작하기

W&B 실행은 W&B에 의해 기록되는 하나의 연산 단위입니다. 일반적으로 학습 실험 하나당 W&B 실행 하나를 사용합니다.

코드에서 W&B를 초기화하고 실행을 시작하려면 다음과 같이 합니다:

run = wandb.init()

선택적으로 사용자의 프로젝트 이름을 미리 지정하거나, 코드에서 wandb_project와 같은 파라미터를 사용해 사용자가 직접 설정하도록 할 수 있습니다. 이때 엔터티 파라미터에는 사용자 이름 또는 팀 이름을 wandb_entity와 같이 함께 전달합니다:

run = wandb.init(project=wandb_project, entity=wandb_entity)

run.finish()를 호출하여 실행을 종료해야 합니다. 이 방식이 사용 중인 통합의 설계와 잘 맞는다면, 실행을 컨텍스트 매니저로 사용하십시오:

# 이 블록이 종료되면 run.finish()가 자동으로 호출됩니다.
# 예외로 인해 종료될 경우 run.finish(exit_code=1)이 사용되며
# 실행이 실패로 표시됩니다.
with wandb.init() as run:
    ...

​

wandb.init는 언제 호출해야 하나요?

콘솔에 출력되는 모든 내용(오류 메시지를 포함한 모든 출력)이 W&B 실행의 일부로 로깅되므로, 라이브러리는 가능한 한 이른 시점에 W&B 실행을 생성해야 합니다. 이렇게 하면 디버깅이 더 쉬워집니다.

​

wandb를 선택적 의존성으로 사용하기

사용자가 라이브러리를 사용할 때 wandb를 옵션으로 두고 싶다면 다음 중 하나를 사용할 수 있습니다:

• 다음과 같이 wandb 플래그를 정의하거나:

Python

trainer = my_trainer(..., use_wandb=True)

Bash

python train.py ... --use-wandb

• 또는 wandb.init에서 wandb를 disabled로 설정하거나:

Python

wandb.init(mode="disabled")

Bash

export WANDB_MODE=disabled

or

wandb disabled

• 또는 wandb를 오프라인 모드로 설정합니다. 이 경우에도 wandb는 여전히 실행되지만, 인터넷을 통해 W&B와 통신을 시도하지는 않습니다:

Environment Variable

export WANDB_MODE=offline

or

os.environ['WANDB_MODE'] = 'offline'

Bash

wandb offline

​

실행 config 정의하기

wandb 실행 config를 사용하면 W&B 실행을 생성할 때 모델, 데이터셋 등의 메타데이터를 함께 지정할 수 있습니다. 이 정보는 서로 다른 실험을 비교하고 주요 차이점을 빠르게 파악하는 데 활용할 수 있습니다.

기록할 수 있는 일반적인 config 파라미터는 다음과 같습니다:

• 모델 이름, 버전, 아키텍처 파라미터 등
• 데이터셋 이름, 버전, train/val 예제 수 등
• 학습률, 배치 크기, 옵티마이저와 같은 학습 파라미터 등

다음 코드 스니펫은 config를 기록하는 방법을 보여줍니다:

config = {"batch_size": 32, ...}
wandb.init(..., config=config)

​

실행 config 업데이트

wandb.Run.config.update를 사용해 config를 업데이트합니다. 구성 딕셔너리는 딕셔너리가 정의된 이후에 파라미터를 얻게 되는 경우에 유용합니다. 예를 들어, 모델을 인스턴스화한 후 모델의 파라미터를 추가하고 싶을 수 있습니다.

run.config.update({"model_parameters": 3500})

구성 파일 정의 방법에 대한 자세한 내용은 실험 구성 문서를 참고하세요.

​

W&B로 로깅하기

​

메트릭 기록

키가 메트릭 이름이 되도록 딕셔너리를 생성합니다. 이 딕셔너리 객체를 run.log에 전달합니다:

for epoch in range(NUM_EPOCHS):
    for input, ground_truth in data: 
        prediction = model(input) 
        loss = loss_fn(prediction, ground_truth) 
        metrics = { "loss": loss } 
        run.log(metrics)

메트릭이 많다면 메트릭 이름에 train/..., val/... 같은 접두사를 사용해 UI에서 자동으로 그룹화할 수 있습니다. 이렇게 하면 학습 및 검증 메트릭(또는 분리해서 보고 싶은 다른 유형의 메트릭)을 위해 W&B 워크스페이스 내에 각각 별도의 섹션이 생성됩니다:

metrics = {
    "train/loss": 0.4,
    "train/learning_rate": 0.4,
    "val/loss": 0.5, 
    "val/accuracy": 0.7
}
run.log(metrics)

wandb.Run.log() 참고 문서를 참조하세요.

​

x축 불일치 방지

동일한 학습 스텝에 대해 run.log를 여러 번 호출하면, wandb SDK는 run.log가 호출될 때마다 내부 스텝 카운터를 증가시킵니다. 이 카운터는 학습 루프의 학습 스텝과 일치하지 않을 수 있습니다.

이러한 불일치를 피하려면, wandb.init을 호출한 직후에 한 번만 run.define_metric을 사용해 x축 스텝을 명시적으로 정의하세요:

with wandb.init(...) as run:
    run.define_metric("*", step_metric="global_step")

glob 패턴 *는 모든 메트릭이 차트에서 global_step을 x축으로 사용한다는 뜻입니다. 특정 메트릭만 global_step 기준으로 기록하고 싶다면, 대신 해당 메트릭들을 명시하면 됩니다:

run.define_metric("train/loss", step_metric="global_step")

이제 run.log를 호출할 때마다 지표와 step 메트릭, global_step을 함께 기록하세요:

for step, (input, ground_truth) in enumerate(data):
    ...
    run.log({"global_step": step, "train/loss": 0.1})
    run.log({"global_step": step, "eval/loss": 0.2})

별도의 step 변수에 접근할 수 없는 경우, 예를 들어 검증 루프 동안 “global_step”을(를) 사용할 수 없다면, wandb는 이전에 기록된 “global_step” 값을 자동으로 사용합니다. 이때 필요한 시점에 이미 정의되어 있도록, 해당 지표의 초기 값을 먼저 기록해 두십시오.

​

이미지, 테이블, 오디오 등 로깅하기

메트릭뿐만 아니라 플롯, 히스토그램, 테이블, 텍스트, 이미지, 비디오, 오디오, 3D 등의 미디어도 함께 로깅할 수 있습니다.

데이터를 로깅할 때는 다음 사항을 고려하십시오.

• 메트릭은 어느 정도 간격으로 로깅해야 할까요? 선택적으로 로깅해도 될까요?
• 시각화에 어떤 유형의 데이터가 도움이 될까요?
  • 이미지의 경우 샘플 예측값, 세그멘테이션 마스크 등을 로깅하여 시간 경과에 따른 변화를 확인할 수 있습니다.
  • 텍스트의 경우 나중에 분석할 수 있도록 샘플 예측값을 테이블 형태로 로깅할 수 있습니다.

미디어, 객체, 플롯 등에 대한 자세한 내용은 로깅 가이드를 참조하십시오.

​

분산 학습

분산 환경을 지원하는 프레임워크의 경우, 다음 워크플로 중 하나를 사용할 수 있습니다:

• 어떤 프로세스가 “메인” 프로세스인지 감지한 뒤, 해당 프로세스에서만 wandb를 사용합니다. 다른 프로세스에서 오는 필요한 데이터는 먼저 메인 프로세스로 전달해야 합니다. (이 워크플로를 권장합니다.)
• 모든 프로세스에서 wandb를 호출하고, 모두에게 동일한 고유 group 이름을 부여해 자동으로 하나의 그룹으로 묶이도록 합니다.

자세한 내용은 분산 학습 실험 로깅을 참고하세요.

​

모델 체크포인트와 기타 항목 로깅

사용 중인 프레임워크가 모델이나 데이터셋을 사용하거나 생성한다면, wandb로 이를 로깅하여 완전한 추적 가능성을 확보하고, W&B 아티팩트를 통해 wandb가 전체 파이프라인을 자동으로 모니터링하도록 할 수 있습니다.

아티팩트를 사용할 때, 다음과 같이 일부 설정을 사용자가 정의하도록 하면 유용할 수 있지만 필수는 아닙니다:

• 모델 체크포인트나 데이터셋을 로깅할지 여부(옵션으로 두고 싶은 경우).
• (있는 경우) 입력으로 사용되는 아티팩트의 경로나 참조값. 예: user/project/artifact.
• 아티팩트를 로깅하는 빈도.

​

모델 체크포인트 기록하기

Model Checkpoints를 W&B에 기록할 수 있습니다. 고유한 wandb 실행 ID를 활용해 출력되는 Model Checkpoints의 이름을 지정하면 실행 간 체크포인트를 구분하는 데 유용합니다. 또한 유용한 메타데이터를 추가할 수도 있습니다. 아래 예시와 같이 각 모델에 별칭(alias)을 추가할 수도 있습니다:

metadata = {"eval/accuracy": 0.8, "train/steps": 800} 

artifact = wandb.Artifact(
                name=f"model-{run.id}", 
                metadata=metadata, 
                type="model"
                ) 
artifact.add_dir("output_model") # 모델 가중치가 저장되는 로컬 디렉토리

aliases = ["best", "epoch_10"] 
run.log_artifact(artifact, aliases=aliases)

사용자 지정 별칭을 만드는 방법에 대한 자세한 내용은 사용자 지정 별칭 만들기를 참조하세요.

출력 아티팩트는 원하는 빈도(예: 매 에포크마다, 500 스텝마다 등)로 로깅할 수 있으며, 자동으로 버전이 관리됩니다.

​

사전 학습된 모델 또는 데이터셋을 로깅하고 추적하기

사전 학습된 모델이나 데이터셋처럼 학습의 입력으로 사용하는 아티팩트를 로깅할 수 있습니다. 다음 코드 스니펫은 아티팩트를 로깅하고, 위 그래프에 표시된 것처럼 현재 실행의 입력으로 추가하는 방법을 보여줍니다.

artifact_input_data = wandb.Artifact(name="flowers", type="dataset")
artifact_input_data.add_file("flowers.npy")
run.use_artifact(artifact_input_data)

​

아티팩트 다운로드

아티팩트(데이터셋, 모델 등)를 다시 사용하면 wandb가 로컬에 사본을 다운로드하여 캐시합니다:

artifact = run.use_artifact("user/project/artifact:latest")
local_path = artifact.download("./tmp")

아티팩트는 W&B의 Artifacts 섹션에서 찾을 수 있으며, 자동으로 생성되는 별칭(latest, v2, v3)이나 로깅 시 수동으로 지정한 별칭(best_accuracy 등)을 사용해 참조할 수 있습니다.

분산 환경이나 단순 추론과 같이 wandb.init을 통해 wandb 실행을 생성하지 않고 아티팩트를 다운로드하려는 경우, 대신 wandb API를 사용해 아티팩트를 참조할 수 있습니다:

artifact = wandb.Api().artifact("user/project/artifact:latest")
local_path = artifact.download()

자세한 내용은 아티팩트 다운로드 및 사용 문서를 참고하세요.

​

하이퍼파라미터 튜닝

라이브러리에서 W&B 하이퍼파라미터 튜닝 기능을 활용하려면, W&B Sweeps를 라이브러리에 추가할 수도 있습니다.

​

고급 통합

다음 통합 예시를 통해 고급 수준의 W&B 통합이 어떻게 구현되는지 확인할 수 있습니다. 대부분의 통합은 아래 예시만큼 복잡하지 않다는 점에 유의하세요.

• Hugging Face Transformers WandbCallback
• PyTorch Lightning WandbLogger