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

이 가이드에서는 사용자가 여러분의 코드를 사용할 때 실험을 추적하고, 시스템 메트릭을 모니터링하며, 모델을 관리할 수 있도록 Python 라이브러리에 W&B를 통합하는 방법을 설명합니다. 자체 프레임워크, SDK 또는 재사용 가능한 트레이닝 코드를 통해 W&B 기능을 제공하려는 라이브러리 작성자와 유지 관리자를 위한 가이드입니다. 단일 Python 트레이닝 스크립트나 Jupyter notebook보다 더 복잡한 코드베이스(예: 트레이닝 프레임워크, SDK 또는 재사용 가능한 라이브러리)에 W&B를 통합하는 경우에는 다음 권장 사항을 따르세요.

W&B가 처음이라면 계속하기 전에 핵심 가이드(예: Experiment Tracking)를 먼저 검토하세요.

다음 섹션에서는 주요 인테그레이션 관련 결정을 순서대로 안내합니다. W&B 설치 방법, 인증 방법, Runs를 시작하고 설정하는 방법, 메트릭과 아티팩트를 로깅하는 방법, 그리고 분산 트레이닝과 하이퍼파라미터 스윕을 지원하는 방법을 차례로 다룹니다.

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

시작하기 전에 W&B를 필수 의존성으로 지정할지, 아니면 라이브러리의 선택 기능으로 제공할지 결정하세요. 이 선택은 W&B Python SDK(wandb)를 임포트하는 방식, 설치 관련 문서를 작성하는 방식, 그리고 wandb가 없는 환경을 처리하는 방식에 영향을 줍니다.

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

W&B가 라이브러리 기능의 핵심 요소라면, 라이브러리와 함께 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 키로 사용자와 머신을 인증합니다. 사용자가 라이브러리에서 run을 로깅하려면 먼저 API 키를 생성하고 wandb 클라이언트에서 이를 사용할 수 있게 해야 합니다.

API 키 생성

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

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

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

W&B 설치 및 로그인

API 키가 있으면 로컬 환경에 wandb 라이브러리를 설치하고 로그인하여 이후 run이 W&B에 인증할 수 있도록 하세요. 사용 중인 환경에 맞는 탭을 선택하세요.

명령줄
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에 로그인합니다. W&B에서 API 키를 입력하라는 메시지가 표시됩니다.
import wandb wandb.login()

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

!pip install wandb

import wandb
wandb.login()

run 시작하기

인증을 설정한 후 다음 단계는 라이브러리가 메트릭, 설정, 아티팩트를 로깅할 수 있도록 W&B 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()를 호출해야 합니다. run을 종료하면 process가 종료되기 전에 모든 메트릭, 설정, 아티팩트가 업로드되도록 보장됩니다.

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

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

런타임에 wandb를 선택 사항으로 만들어 사용자가 W&B run을 생성하지 않고도 라이브러리를 실행할 수 있게 하려면, 다음 접근 방식 중 하나를 사용하세요.

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

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

Python
Bash

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

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

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

Python
Bash

wandb.init(mode="disabled")

export WANDB_MODE=disabled

또는

wandb disabled

wandb를 오프라인으로 설정합니다.

Environment Variable
Bash

export WANDB_MODE=offline

또는

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

wandb offline

run config 정의하기

run을 초기화한 후에는 해당 run에 연결된 하이퍼파라미터와 기타 메타데이터를 기록하는 설정 딕셔너리를 첨부할 수 있습니다. config를 로깅하면 나중에 runs를 더 쉽게 비교하고, 필터링하고, 재현할 수 있습니다. run을 초기화할 때 설정 딕셔너리를 제공하면 하이퍼파라미터와 기타 메타데이터를 W&B에 로깅할 수 있습니다. W&B를 사용하면 config 파라미터를 기준으로 runs를 비교하고 Runs table에서 필터링할 수 있습니다. 또한 이러한 파라미터를 사용해 W&B에서 runs를 함께 그룹화할 수도 있습니다. 예를 들어, 다음 이미지에서는 batch size (batch_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.init()를 호출할 때는 아직 알 수 없을 수 있습니다. 초기화 시점에 값을 사용할 수 없는 경우, 나중에 wandb.Run.config.update로 config를 업데이트하세요. 예를 들어, 모델을 인스턴스화한 후 모델의 파라미터를 추가할 수 있습니다:

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

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

메트릭 및 데이터 로깅

run을 시작하고 설정한 후에는 메트릭과 기타 데이터 로깅을 시작할 수 있으며, 그러면 W&B가 이를 해당 run에 기록합니다.

메트릭 로깅

loss나 accuracy와 같은 스칼라 메트릭을 로깅하려면, 키가 메트릭 이름인 딕셔너리를 만드세요. 이 딕셔너리 객체를 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에서 관련 메트릭을 그룹화하세요. 일반적으로는 트레이닝 메트릭과 검증 메트릭에 각각 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 제어

기본적으로 W&B Python SDK는 자체 step 카운터를 관리하는데, 이 카운터는 트레이닝 루프의 step 의미와 일치하지 않을 수 있습니다. 같은 트레이닝 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을 사용할 수 없는 경우), W&B는 이전에 로깅된 global_step 값을 자동으로 사용합니다. 이 경우 필요할 때 해당 메트릭이 정의되어 있도록 메트릭의 초기값을 로깅해야 합니다.

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

스칼라 외에도 이미지, 테이블, 텍스트, 오디오, 비디오 등을 로깅할 수 있습니다. 메트릭과 함께 미디어를 로깅하면 사용자가 시간 경과에 따른 모델의 정성적 동작을 살펴보는 데 도움이 됩니다. 데이터를 로깅할 때 고려할 사항은 다음과 같습니다.

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

자세한 내용은 객체 및 미디어 로깅을 참조하세요.

분산 트레이닝 지원

라이브러리가 여러 프로세스나 여러 머신에서 트레이닝을 실행할 수 있다면, 로그가 일관성을 유지하고 중복되지 않도록 해당 환경에서 W&B가 어떻게 동작해야 하는지 결정하세요. 분산 환경을 지원하는 프레임워크에서는 다음 워크플로 중 하나를 적용할 수 있습니다:

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

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

아티팩트를 사용해 모델과 데이터셋 추적하기

메트릭 외에도, 사용자가 Runs를 재현하고 비교할 수 있도록 라이브러리가 생성하거나 사용하는 모델과 데이터셋을 저장할 수 있습니다. W&B 아티팩트를 사용해 모델과 데이터셋을 추적하고 버전 관리하세요. 아티팩트는 머신 러닝 자산을 위한 저장소와 버전 관리를 제공하며, 데이터와 모델이 어떻게 연결되어 있는지 보여주도록 리니지를 자동으로 추적합니다.

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

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

모델 체크포인트 로깅

모델 체크포인트를 아티팩트로 로깅하면 사용자가 학습된 가중치를 복구하고, 버전을 관리하고, 공유할 수 있습니다. 일반적으로 체크포인트는 W&B에서 생성한 고유한 run ID를 아티팩트 이름의 일부로 사용해 아티팩트로 로깅합니다.

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)

이전 스니펫은 모델 체크포인트를 아티팩트로 로깅하고, evaluation accuracy 및 트레이닝 step과 같은 메타데이터를 포함합니다. 이 아티팩트의 이름에는 고유한 run ID가 포함되며, 빠르게 참조할 수 있도록 맞춤형 alias가 태그됩니다.

입력 아티팩트 로깅하기

데이터와 모델 간의 리니지를 캡처하려면 run이 입력으로 사용하는 데이터셋 또는 사전 학습된 모델을 로깅합니다:

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

이전 코드 스니펫은 “flowers”라는 데이터셋용 아티팩트를 생성하고 여기에 파일을 추가합니다. wandb.Run.use_artifact() 호출은 이 아티팩트를 현재 run에 연결하므로 W&B는 run에서 사용된 데이터셋의 리니지를 추적할 수 있습니다.

아티팩트 다운로드

아티팩트를 로깅한 후에는 트레이닝 또는 Inference 코드에서 사용하기 위해 이전에 W&B에 로깅한 아티팩트를 다운로드할 수 있습니다. 적절한 방법은 이미 활성 run이 있는지에 따라 달라집니다. run 컨텍스트가 있으면 wandb.Run.use_artifact()를 사용해 W&B의 아티팩트를 참조한 다음, wandb.Artifact.download()를 호출해 로컬 디렉터리로 다운로드합니다. wandb.Run.use_artifact()를 사용하면 아티팩트가 현재 run의 입력으로도 기록되어 리니지가 유지됩니다.

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

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

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

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

하이퍼파라미터 조정

라이브러리가 하이퍼파라미터 튜닝을 지원하는 경우, W&B Sweeps를 통합해 실험을 관리하고 시각화할 수 있습니다. 스윕은 정의된 검색 공간에서 여러 run을 조율하고, 사용자가 설정을 나란히 비교할 수 있도록 결과를 W&B에 표시합니다.

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

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

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

​사용자 인증

​API 키 생성

​W&B 설치 및 로그인

​run 시작하기

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

​run config 정의하기

​run config 업데이트

​메트릭 및 데이터 로깅

​메트릭 로깅

​x-axis 제어

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

​분산 트레이닝 지원

​아티팩트를 사용해 모델과 데이터셋 추적하기

​모델 체크포인트 로깅

​입력 아티팩트 로깅하기

​아티팩트 다운로드

​하이퍼파라미터 조정

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

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

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

사용자 인증

API 키 생성

W&B 설치 및 로그인

run 시작하기

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

run config 정의하기

run config 업데이트

메트릭 및 데이터 로깅

메트릭 로깅

x-axis 제어

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

분산 트레이닝 지원

아티팩트를 사용해 모델과 데이터셋 추적하기

모델 체크포인트 로깅

입력 아티팩트 로깅하기

아티팩트 다운로드

하이퍼파라미터 조정