Weights & Biases 실무 스터디 가이드

1. Weights & Biases란?

Weights & Biases (W&B)는 머신러닝 실험 추적, 모델 시각화, 하이퍼파라미터 최적화, 모델 및 데이터셋 버전 관리를 통합한 MLOps 플랫폼입니다. 단 몇 줄의 코드로 실험 메타데이터를 클라우드에 자동 기록하고, 대시보드에서 실시간으로 비교・분석할 수 있습니다.

3대 핵심 능력

📈 실험 추적

하이퍼파라미터, 메트릭, 아티팩트, 코드 스냅샷을 모든 실행에 자동 연결.

📊 시각화 & 대시보드

학습 곡선, confusion matrix, 3D 임베딩, 이미지/텍스트 로그를 대화형으로 탐색.

🔁 모델 & 데이터 버전 관리

데이터셋, 모델 가중치, 전처리 파이프라인을 추적 가능한 아티팩트로 관리.

2. 왜 써야 하는가?

기존 ML 실험 관리 방식(로컬 로그, 스프레드시트, TensorBoard)과 비교한 W&B의 주요 장점입니다.

비교 항목	TensorBoard	MLflow	W&B
설치 난이도	간단	중간	매우 간단 (pip install)
클라우드 대시보드	❌ (로컬 전용)	🟡 (유료 기능)	✅ 무료 티어 제공
하이퍼파라미터 스윕	❌	🟡 (수동 구성)	✅ 내장 Sweep API
아티팩트 버전 관리	❌	✅	✅ (모델+데이터)
협업 및 공유	❌	🟡 (서버 필요)	✅ 링크 공유 즉시

💡 추천 시나리오: 팀 단위 실험 추적, 하이퍼파라미터 최적화, 모델 리더보드가 필요하다면 W&B가 가장 생산적입니다. 소규모 개인 프로젝트에도 무료 티어로 충분합니다.

3. 핵심 개념

W&B의 주요 구성 요소는 Run, Project, Artifact, Sweep입니다. 아래 다이어그램은 기본 데이터 흐름을 보여줍니다.

╔══════════════════════════════════════════════════════════╗ ║ 사용자 환경 (Local/Cloud) ║ ║ ║ ║ ┌──────────────┐ ┌──────────────────┐ ║ ║ │ Python 코드 │────▶│ wandb.init() │ ║ ║ │ (train.py) │ │ - config │ ║ ║ └──────────────┘ │ - metrics │ ║ ║ │ - artifacts │ ║ ║ └────────┬─────────┘ ║ ║ ▼ ║ ║ ┌──────────────────┐ ║ ║ │ W&B 백엔드 서버 │ ║ ║ │ (cloud / on-prem)│ ║ ║ └────────┬─────────┘ ║ ║ ▼ ║ ║ ┌──────────────────┐ ║ ║ │ W&B 대시보드 │ ║ ║ │ - 실시간 차트 │ ║ ║ │ - 비교 뷰 │ ║ ║ │ - 아티팩트 탐색 │ ║ ║ └──────────────────┘ ║ ╚══════════════════════════════════════════════════════════╝

핵심 용어

용어	설명
Run	모델 학습 한 번의 실행. 메트릭, 파라미터, 출력이 모두 기록됨.
Project	관련 Run의 논리적 그룹. (예: "resnet-cifar10")
Artifact	데이터셋, 모델 가중치, 전처리 결과 등 파일 단위 버전 관리.
Sweep	하이퍼파라미터 자동 탐색. Bayesian, Grid, Random 등 전략 지원.

4. 퀵스타트

WandB를 처음 사용하는 경우 다음 3단계로 5분 안에 첫 실험을 추적할 수 있습니다.

1️⃣ 설치 & 로그인

pip install wandb
wandb login          # 브라우저에서 API 키 발급 후 입력

2️⃣ 기본 실험 코드

import wandb
import random

# 프로젝트 생성 및 실행 시작
wandb.init(project="my-first-project", config={
    "learning_rate": 0.01,
    "epochs": 10,
    "batch_size": 32
})

for epoch in range(wandb.config.epochs):
    loss = random.random() * (1.0 - epoch/10)   # 가상의 loss
    acc = 0.5 + 0.4 * (epoch / 10)             # 가상의 accuracy

    # 메트릭 기록
    wandb.log({"loss": loss, "accuracy": acc})

# 실행 종료 (자동으로도 종료됨)
wandb.finish()

위 코드를 실행하면 my-first-project 프로젝트가 생성되고 대시보드에서 실시간으로 메트릭을 확인할 수 있습니다.

3️⃣ CLI로 Sweep 실행하기

# sweep config 파일 (sweep.yaml)
wandb sweep --project my-sweep sweep.yaml

# sweep agent 실행 (여러 병렬 실행 가능)
wandb agent <sweep_id>

⚠️ 주의: wandb.init()은 중첩해서 호출하지 마세요. 새 Run이 필요하면 명시적으로 wandb.init(reinit=True)를 사용하거나 이전 Run을 finish() 하세요.

5. 핵심 설정 레퍼런스

자주 사용하는 wandb.init() 및 wandb.log() 파라미터를 정리했습니다.

파라미터	타입	설명
`project`	str	프로젝트 이름. 없으면 "Uncategorized"
`config`	dict	하이퍼파라미터 등 설정 값 (wandb.config 로 접근)
`name`	str	Run 이름. 미지정 시 자동 생성
`tags`	list[str]	Run에 태그 추가 (예: ["baseline", "v2"])
`group`	str	여러 Run을 하나의 실험 그룹으로 묶음
`job_type`	str	"train", "eval" 등 작업 유형
`wandb.log(dict)`	dict	메트릭, 이미지, 텍스트 등을 키-값으로 전송
`wandb.log({}, step=)`	int	명시적 step 지정 (기본은 자동 증가)

6. 실무 팁 & 트러블슈팅

자주 겪는 문제와 해결책

문제	원인 / 해결
`wandb: Network error`	방화벽/프록시 차단. `wandb offline` 모드로 먼저 기록 후 `wandb sync`로 업로드.
대시보드에 메트릭이 안 보임	`wandb.log()` 호출 간격이 너무 김. 또는 `wandb.finish()` 누락. 종료 시 자동 flush.
API 키 오류	`wandb login --relogin` 으로 재설정. 환경변수 `WANDB_API_KEY` 도 활용.
멀티 GPU / 분산 학습	각 프로세스에 `wandb.init(settings=wandb.Settings(_service_wait=300))` 추가. 또는 `wandb.finish()` 확실히 호출.
아티팩트 업로드 실패	파일 경로 확인. 대용량 파일은 `wandb.Artifact`의 `add_dir()` 대신 `add_reference()`로 외부 스토리지 링크 권장.

💡 꿀팁: wandb.init(magic=True) 또는 wandb.magic을 사용하면 코드 수정 없이 자동 로깅이 가능합니다 (Fast.ai, PyTorch Lightning 등 일부 프레임워크). 하지만 프로덕션에서는 명시적 로깅을 권장합니다.

오프라인 모드

import os
os.environ["WANDB_MODE"] = "offline"   # 네트워크 없이 로컬에 저장
# ... 학습 후 ...
wandb sync --sync-all              # 나중에 한 번에 업로드

7. 참고 자료

W&B 공식 문서 – 전체 API 레퍼런스 및 가이드
W&B 예제 갤러리 – PyTorch, TensorFlow, JAX 등 다양한 프레임워크 예제
GitHub 예제 리포지토리 – 커뮤니티 기여 예제
W&B Reports – 팀 공유용 리포트 기능
Sweep 문서 – 하이퍼파라미터 최적화 상세