이 가이드는 Python 라이브러리에 Weights & Biases (W&B)를 통합하는 방법을 설명합니다.
트레이닝 프레임워크, SDK, 또는 재사용 가능한 라이브러리 같은 복잡한 코드베이스에 W&B를 통합하는 경우에는 다음 권장 사항을 따르세요.
여기서는 단일 Python 트레이닝 스크립트나 Jupyter 노트북보다 더 복잡한 코드베이스에서 작업할 때 유용한 핵심 팁과 모범 사례를 다룹니다.
시작하기 전에 W&B를 라이브러리의 필수 의존성으로 사용할지, 선택적 기능으로 제공할지 결정하세요.
W&B가 라이브러리의 핵심 기능에 필수적이라면, 의존성 목록에 W&B Python SDK(wandb)를 추가하세요:
torch==1.8.0
...
wandb==0.13.*
wandb를 조건부로 임포트하거나, 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"
]
더 간편한 방법을 원한다면 User Settings에서 직접 API 키를 생성하세요. 새로 생성된 API 키를 즉시 복사하여 비밀번호 관리자와 같은 안전한 위치에 저장하세요.
- 오른쪽 상단에 있는 사용자 프로필 아이콘을 클릭합니다.
- User Settings를 선택한 다음, 아래로 스크롤하여 API Keys 섹션으로 이동합니다.
로컬 환경에 wandb 라이브러리를 설치하고 로그인하려면:
-
WANDB_API_KEY 환경 변수를 API 키로 설정합니다:
export WANDB_API_KEY=<your_api_key>
-
wandb 라이브러리를 설치하고 로그인합니다:
pip install wandb
wandb login
-
터미널에서 다음 명령을 실행해 Python SDK를 설치합니다.
-
Python 스크립트나 노트북에서 W&B에 로그인합니다. 그러면 API 키 입력을 요청하는 프롬프트가 표시됩니다.
import wandb
wandb.login()
다음 코드 스니펫을 Jupyter 노트북의 셀에 복사해 붙여넣은 뒤 실행합니다. 그러면 API 키를 입력하라는 프롬프트가 표시됩니다.!pip install wandb
import wandb
wandb.login()
wandb.init()으로 run을 초기화하고, 프로젝트 이름과 팀 엔티티(팀 이름)를 지정하세요. 프로젝트를 지정하지 않으면 W&B는 run을 “uncategorized”라는 기본 프로젝트에 저장합니다.
with wandb.init(project="<project_name>", entity="<entity>") as run:
...
run.finish()를 호출하여 run을 종료하고 모든 데이터를 W&B에 로깅해야 합니다.
wandb.init은 언제 호출해야 하나요가능한 한 이른 시점에 wandb.init()을 호출하세요. W&B는 stdout, stderr, 오류 메시지를 캡처하여 디버깅을 더 쉽게 해 줍니다.모든 관련 정보가 run에 캡처되도록 전체 트레이닝 루프를 wandb.init 컨텍스트 매니저로 감싸세요. 여기에는 디버깅에 매우 중요할 수 있는 오류 메시지도 모두 포함됩니다.
wandb를 선택적으로 사용할 수 있게 하려면 다음 중 하나를 사용할 수 있습니다.
- 예를 들어 다음과 같이
wandb 플래그를 정의하거나:
trainer = my_trainer(..., use_wandb=True)
python train.py ... --use-wandb
- 또는
wandb.init에서 wandb를 disabled로 설정하거나:
wandb.init(mode="disabled")
export WANDB_MODE=disabled
- 또는
wandb를 오프라인 모드로 설정합니다. 이 경우에도 wandb는 여전히 실행되지만, 인터넷을 통해 W&B와 통신을 시도하지는 않습니다:
Environment Variable
Bash
export WANDB_MODE=offline
os.environ['WANDB_MODE'] = 'offline'
- 모델 이름, 버전, 아키텍처 파라미터, 하이퍼파라미터
- 데이터셋 이름, 버전, 트레이닝 또는 검증 예제 수
- 학습률, 배치 크기, 옵티마이저와 같은 트레이닝 파라미터
다음 코드 스니펫은 config를 로깅하는 방법을 보여줍니다:
config = {"batch_size": 32, ...}
with wandb.init(..., config=config) as run:
...
wandb.Run.config.update를 사용해 config를 업데이트하세요. 예를 들어, 모델이 인스턴스화된 후에 해당 모델의 파라미터를 추가하고 싶을 수 있습니다:
with wandb.init(...) as run:
model = MyModel(...)
run.config.update({"model_parameters": 3500})
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)
train/, 검증 메트릭에는 val/ 같은 접두사를 사용하지만, 사용 사례에 맞는 어떤 접두사든 사용할 수 있습니다.
이렇게 하면 프로젝트 워크스페이스에서 트레이닝 및 검증 메트릭, 또는 따로 구분해서 보고 싶은 다른 유형의 메트릭에 대해 각각 별도의 섹션이 생성됩니다:
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()를 참조하세요.
동일한 트레이닝 스텝에 대해 wandb.Run.log()를 여러 번 호출하면, wandb SDK는 wandb.Run.log()가 호출될 때마다 내부 스텝 카운터를 증가시킵니다. 이 카운터는 트레이닝 루프의 트레이닝 스텝과 일치하지 않을 수 있습니다.
이 상황을 피하려면, wandb.init을 호출한 직후에 run.define_metric을 사용해 x축에 사용할 스텝을 한 번만 명시적으로 정의하세요:
with wandb.init(...) as run:
run.define_metric("*", step_metric="global_step")
*은 모든 메트릭이 차트에서 global_step을 x축으로 사용한다는 의미입니다. 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})
- 메트릭은 얼마나 자주 로깅해야 할까요? 반드시 로깅해야 할까요, 선택적으로 둘까요?
- 시각화에 어떤 유형의 데이터가 도움이 될까요?
- 이미지의 경우, 시간에 따른 변화를 확인하기 위해 샘플 예측값, 세그멘테이션 마스크 등을 로깅할 수 있습니다.
- 텍스트의 경우, 나중에 탐색할 수 있도록 샘플 예측값을 테이블 형태로 로깅할 수 있습니다.
예시는 Log objects and media를 참고하세요.
분산 환경을 지원하는 프레임워크의 경우, 다음 워크플로 중 하나를 사용할 수 있습니다:
- 메인 프로세스에서만 로그를 남깁니다(권장).
- 모든 프로세스에서 로그를 남기고, 공통
group 이름을 사용해 run을 그룹화합니다.
자세한 내용은 Log Distributed Training Experiments를 참고하세요.
W&B Artifacts를 사용해 모델과 데이터셋을 추적하고 버전 관리를 수행합니다. Artifacts는 머신 러닝 자산에 대한 저장소와 버전 관리를 제공하며, 데이터와 모델이 어떻게 서로 연관되어 있는지 보여 주는 계보(lineage)를 자동으로 추적합니다.
라이브러리에 Artifacts를 통합할 때는 다음 사항을 고려하십시오.
- (옵션으로 제공하고 싶다면) 모델 체크포인트와 데이터셋 중 무엇을 아티팩트로 로깅할지.
- 아티팩트 입력 참조값(예:
entity/project/artifact).
- 모델 체크포인트 또는 데이터셋을 로깅하는 빈도. 예를 들어, 매 에포크마다, 500 스텝마다 등.
모델 체크포인트를 W&B에 기록합니다. 일반적으로는 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)
dataset = wandb.Artifact(name="flowers", type="dataset")
dataset.add_file("flowers.npy")
run.use_artifact(dataset)
run.use_artifact()을 사용해 해당 아티팩트를 현재 run에 연결하여, W&B가 run에서 사용된 데이터셋의 lineage를 추적할 수 있도록 합니다.
W&B에 이미 로깅해 둔 아티팩트를 다운로드하여 트레이닝 또는 추론 코드에서 사용합니다.
run 컨텍스트가 있는 경우 wandb.Run.use_artifact()를 사용해 W&B의 아티팩트를 참조한 다음 wandb.Artifact.download()를 호출해 로컬 디렉터리에 다운로드합니다.
with wandb.init(...) as run:
artifact = run.use_artifact("user/project/artifact:latest")
local_path = artifact.download()
import wandb
artifact = wandb.Api().artifact("user/project/artifact:latest")
local_path = artifact.download()
플랫폼
W&B Models
W&B Weave
W&B Inference
W&B 트레이닝
릴리스 노트
