Python 라이브러리에 W&B 추가하기 - Weights & Biases Documentation

이 가이드에서는 Python 라이브러리에 Weights & Biases (W&B)를 통합하는 방법을 설명합니다. 트레이닝 프레임워크, SDK 또는 재사용 가능한 라이브러리처럼 복잡한 코드베이스에 W&B를 통합하는 경우에는 다음 권장 사항을 따르세요.

W&B를 처음 사용한다면 계속하기 전에 핵심 가이드(예: 실험 추적)를 먼저 검토하세요.

아래에서는 작업 중인 코드베이스가 단일 Python 트레이닝 스크립트나 Jupyter 노트북보다 더 복잡할 때 유용한 팁과 모범 사례를 다룹니다.

사용자의 W&B 설치 방식을 결정합니다

시작하기 전에 W&B를 필수 의존성으로 지정할지, 아니면 라이브러리의 선택 기능으로 제공할지 결정하세요.

W&B를 필수 의존성으로 지정하기

W&B가 라이브러리 기능의 핵심 요소라면, W&B Python SDK(wandb)를 의존성에 추가하세요:

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

설치 시 W&B를 선택 사항으로 설정하기

W&B가 선택적 기능이라면, 설치되어 있지 않아도 라이브러리가 실행될 수 있게 하세요. Python에서 wandb를 조건부로 임포트하거나 pyproject.toml에서 선택적 의존성으로 선언할 수 있습니다.

Python
pyproject.toml

wandb를 사용할 수 있는지 확인하고, 사용자가 W&B 기능을 활성화했지만 이를 설치하지 않은 경우 명확한 오류를 발생시키세요:

try:
    import wandb
    _WANDB_AVAILABLE = True
except ImportError:
    _WANDB_AVAILABLE = False

pyproject.toml 파일에서 wandb를 선택적 의존성으로 선언하세요:

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

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

사용자 인증

W&B는 API 키로 사용자와 머신을 인증합니다.

API 키 생성

API 키는 클라이언트나 머신이 W&B에 인증되도록 합니다. 사용자 프로필에서 API 키를 생성할 수 있습니다.

더 간편하게 하려면 User Settings로 이동해 API 키를 생성하세요. API 키는 즉시 복사해 비밀번호 관리자와 같은 안전한 위치에 저장하세요.

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

W&B 설치 및 로그인

로컬 환경에 wandb 라이브러리를 설치하고 로그인하려면 다음 단계를 따르세요.

명령줄
Python
Python 노트북

WANDB_API_KEY 환경 변수를 API 키로 설정합니다.
export WANDB_API_KEY=<your_api_key>
wandb 라이브러리를 설치하고 로그인합니다.
pip install wandb wandb login

터미널을 열고 Python SDK를 설치합니다.
pip install wandb
Python 스크립트 또는 노트북에서 W&B에 로그인합니다. API 키를 입력하라는 메시지가 표시됩니다.
import wandb wandb.login()

다음 코드 스니펫을 Jupyter 노트북의 셀에 복사해 붙여넣고 실행합니다. API 키를 입력하라는 메시지가 표시됩니다.

!pip install wandb

import wandb
wandb.login()

run 시작하기

run은 트레이닝 실험과 같은 단일 계산 작업 단위를 의미합니다. 대부분의 라이브러리는 트레이닝 작업마다 run 하나를 생성합니다. run에 대한 자세한 내용은 W&B Runs를 참조하세요. wandb.init()으로 run을 초기화하고 프로젝트 이름과 team entity(팀 이름)를 지정하세요. 프로젝트를 지정하지 않으면 W&B는 run을 “uncategorized”라는 기본 프로젝트에 저장합니다.:

with wandb.init(project="<project_name>", entity="<entity>") as run:
    ...

W&B는 오류가 발생하더라도 run이 제대로 종료되도록 컨텍스트 관리자를 사용하는 것을 권장합니다. 컨텍스트 관리자를 사용하지 않는 경우에는 run을 종료하고 모든 데이터를 W&B에 로깅하기 위해 run.finish()를 호출해야 합니다.

wandb.init()를 호출하는 시점wandb.init()은 가능한 한 빨리 호출하세요. W&B는 stdout, stderr, 오류 메시지를 캡처하므로 디버깅이 쉬워집니다.관련된 모든 정보가 run에 캡처되도록 전체 트레이닝 루프를 wandb.init() 컨텍스트 관리자 안에서 감싸세요. 여기에는 디버깅에 매우 중요한 오류 메시지도 포함됩니다.

`wandb`를 선택적 의존성으로 설정하기

라이브러리 사용자가 wandb를 선택적으로 사용하게 하려면, 다음 중 한 가지 방법을 사용할 수 있습니다.

다음과 같이 wandb 플래그를 정의합니다.

Python
Bash

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

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

또는 wandb.init()에서 wandb를 disabled로 설정합니다.

Python
Bash

wandb.init(mode="disabled")

export WANDB_MODE=disabled

또는

wandb disabled

또는 wandb를 오프라인으로 설정합니다. 이 경우에도 wandb는 계속 실행되지만, 인터넷을 통해 W&B와 통신을 시도하지 않을 뿐입니다.

Environment Variable
Bash

export WANDB_MODE=offline

또는

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

wandb offline

run config 정의하기

run을 초기화할 때 설정 딕셔너리를 제공하면 하이퍼파라미터와 기타 메타데이터를 W&B에 로깅할 수 있습니다. W&B App을 사용하면 config 파라미터를 기준으로 runs를 비교하고 Runs table에서 필터링할 수 있습니다. 또한 이러한 파라미터를 사용해 W&B App에서 runs를 함께 그룹화할 수도 있습니다. 예를 들어, 다음 이미지에서는 batch size (bathch_size)가 config 파라미터로 정의되어 있으며 Runs table에 표시됩니다(첫 번째 column 참조). 이를 통해 사용자는 batch size를 기준으로 runs를 필터링하고 비교할 수 있습니다:

일반적인 config 파라미터 값의 예시는 다음과 같습니다:

모델 이름, 버전, 아키텍처 파라미터, 하이퍼파라미터
데이터셋 이름, 버전, 트레이닝 또는 검증 예제 수
학습률, batch size, optimizer와 같은 트레이닝 파라미터

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

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

run config 업데이트

초기화 시점에 값을 사용할 수 없는 경우, 나중에 wandb.Run.config.update로 config를 업데이트하세요. 예를 들어, 모델을 인스턴스화한 후 모델의 파라미터를 추가할 수 있습니다:

with wandb.init(...) as run:
    model = MyModel(...)
    run.config.update({"model_parameters": 3500})

자세한 내용은 Experiments 설정을 참조하세요.

메트릭 및 데이터 로깅

메트릭 로깅

키가 메트릭 이름인 딕셔너리를 만드세요. 이 딕셔너리 객체를 wandb.Run.log()에 전달해 W&B에 로깅하세요:

NUM_EPOCHS = 10

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)

메트릭 이름 접두사를 사용해 W&B App에서 관련 메트릭을 그룹화하세요. 일반적으로는 트레이닝 메트릭과 검증 메트릭에 각각 train/과 val/를 사용하지만, 사용 사례에 맞는 접두사라면 무엇이든 사용할 수 있습니다. 이렇게 하면 프로젝트의 Workspace에서 트레이닝 및 검증 메트릭이나, 따로 구분하려는 다른 메트릭 유형별로 별도의 섹션이 생성됩니다:

with wandb.init(...) as run:
    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-axis 제어

같은 트레이닝 step에 대해 wandb.Run.log()를 여러 번 호출하면 wandb SDK는 wandb.Run.log()를 호출할 때마다 내부 step 카운터를 증가시킵니다. 이 카운터는 트레이닝 루프의 트레이닝 step과 맞지 않을 수 있습니다. 이 문제를 방지하려면 wandb.init()를 호출한 직후 wandb.Run.define_metric()를 사용해 x-axis step을 한 번만 명시적으로 정의하세요:

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

glob 패턴 *은 모든 메트릭이 차트에서 x축으로 global_step을 사용한다는 뜻입니다. 특정 메트릭만 global_step을 기준으로 로깅하려면, 대신 해당 메트릭을 지정할 수 있습니다:

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

이제 wandb.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” 값을 자동으로 사용합니다. 이 경우 필요할 때 해당 메트릭이 정의되어 있도록 메트릭의 초기값을 로깅해야 합니다.

미디어 및 구조화 데이터 로깅

스칼라 외에도 이미지, 테이블, 텍스트, 오디오, 비디오 등을 로깅할 수 있습니다. 데이터를 로깅할 때 고려할 사항은 다음과 같습니다.

메트릭을 얼마나 자주 로깅해야 하나요? 선택 사항으로 둘 수 있나요?
시각화하는 데 어떤 유형의 데이터가 도움이 될 수 있나요?
- 이미지의 경우 시간에 따른 변화를 확인할 수 있도록 샘플 예측 결과, 세그멘테이션 마스크 등을 로깅할 수 있습니다.
- 텍스트의 경우 나중에 탐색할 수 있도록 샘플 예측 결과를 담은 테이블을 로깅할 수 있습니다.

예시는 객체 및 미디어 로깅을 참조하세요.

분산 트레이닝 지원

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

메인 프로세스에서만 로깅합니다(권장).
모든 프로세스에서 로깅하고, 공유 group 이름을 사용해 run을 그룹화합니다.

자세한 내용은 분산 트레이닝 Experiments 로깅을 참조하세요.

Artifacts를 사용해 모델과 데이터셋 추적하기

W&B Artifacts를 사용해 모델과 데이터셋을 추적하고 버전 관리하세요. Artifacts는 머신 러닝 자산을 위한 저장소와 버전 관리를 제공하며, 데이터와 모델이 어떻게 연결되어 있는지 보여주도록 리니지를 자동으로 추적합니다.

라이브러리에 Artifacts를 인테그레이션할 때는 다음 사항을 고려하세요:

모델 체크포인트 또는 데이터셋을 Artifacts로 log할지 여부(선택 사항으로 제공하려는 경우).
Artifact 입력 레퍼런스(예: entity/project/artifact).
모델 체크포인트 또는 데이터셋의 logging 빈도. 예를 들어 매 에포크마다, 500 step마다 등입니다.

모델 체크포인트 로깅

모델 체크포인트를 W&B에 로깅하세요. 일반적으로 체크포인트는 W&B에서 생성한 고유한 run ID를 artifact 이름의 일부로 사용해 artifact로 로깅합니다.

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)

이전 코드 스니펫은 모델 체크포인트를 artifact로 로깅하고, evaluation accuracy 및 트레이닝 step과 같은 메타데이터를 추가하는 방법을 보여줍니다. 이 artifact에는 고유한 run ID가 포함된 이름이 지정되며, 쉽게 참조할 수 있도록 맞춤형 alias가 태그됩니다.

입력 artifact 로깅하기

입력으로 사용된 데이터셋 또는 사전 학습된 모델을 로깅합니다:

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

이전 코드 스니펫은 “flowers”라는 데이터셋용 artifact를 생성하고 여기에 파일을 추가합니다. 그런 다음 run.use_artifact()를 사용해 이 artifact를 현재 run에 연결하며, 이를 통해 W&B는 run에서 사용된 데이터셋의 리니지를 추적할 수 있습니다.

Artifacts 다운로드

트레이닝 또는 Inference 코드에서 사용하려면, 이전에 W&B에 로깅한 Artifacts를 다운로드하세요. run 컨텍스트가 있으면 wandb.Run.use_artifact()를 사용해 W&B의 artifact를 참조한 다음, wandb.Artifact.download()를 호출해 로컬 디렉터리로 다운로드합니다.

with wandb.init(...) as run:
    artifact = run.use_artifact("user/project/artifact:latest")
    local_path = artifact.download()

W&B Public API를 사용하면 run을 초기화하지 않고도 artifact를 참조하고 다운로드할 수 있습니다. 이는 분산 환경이나 Inference 수행처럼 새 run을 만들고 싶지 않은 시나리오에서 유용합니다.

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

자세한 내용은 Artifacts 다운로드 및 사용하기를 참조하세요.

하이퍼파라미터 조정

라이브러리가 하이퍼파라미터 튜닝을 지원하는 경우, W&B Sweeps를 통합해 실험을 관리하고 시각화할 수 있습니다.

​사용자의 W&B 설치 방식을 결정합니다

​W&B를 필수 의존성으로 지정하기

​설치 시 W&B를 선택 사항으로 설정하기

​사용자 인증

​API 키 생성

​W&B 설치 및 로그인

​run 시작하기

​wandb를 선택적 의존성으로 설정하기

​run config 정의하기

​run config 업데이트

​메트릭 및 데이터 로깅

​메트릭 로깅

​x-axis 제어

​미디어 및 구조화 데이터 로깅

​분산 트레이닝 지원

​Artifacts를 사용해 모델과 데이터셋 추적하기

​모델 체크포인트 로깅

​입력 artifact 로깅하기

​Artifacts 다운로드

​하이퍼파라미터 조정

사용자의 W&B 설치 방식을 결정합니다

W&B를 필수 의존성으로 지정하기

설치 시 W&B를 선택 사항으로 설정하기

사용자 인증

API 키 생성

W&B 설치 및 로그인

run 시작하기

`wandb`를 선택적 의존성으로 설정하기

run config 정의하기

run config 업데이트

메트릭 및 데이터 로깅

메트릭 로깅

x-axis 제어

미디어 및 구조화 데이터 로깅

분산 트레이닝 지원

Artifacts를 사용해 모델과 데이터셋 추적하기

모델 체크포인트 로깅

입력 artifact 로깅하기

Artifacts 다운로드

하이퍼파라미터 조정