이 가이드에서는 Python 라이브러리에 Weights & Biases (W&B)를 통합하는 방법을 설명합니다.
트레이닝 프레임워크, SDK 또는 재사용 가능한 라이브러리처럼 복잡한 코드베이스에 W&B를 통합하는 경우에는 다음 권장 사항을 따르세요.
W&B를 처음 사용한다면 계속하기 전에 핵심 가이드(예: 실험 추적)를 먼저 검토하세요. 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을 초기화하고 프로젝트 이름과 team entity(팀 이름)를 지정하세요. 프로젝트를 지정하지 않으면 W&B는 run을 “uncategorized”라는 기본 프로젝트에 저장합니다.:
with wandb.init(project="<project_name>", entity="<entity>") as run:
...
run.finish()를 호출해야 합니다.
wandb.init()를 호출하는 시점wandb.init()은 가능한 한 빨리 호출하세요. W&B는 stdout, stderr, 오류 메시지를 캡처하므로 디버깅이 쉬워집니다.관련된 모든 정보가 run에 캡처되도록 전체 트레이닝 루프를 wandb.init() 컨텍스트 관리자 안에서 감싸세요. 여기에는 디버깅에 매우 중요한 오류 메시지도 포함됩니다.
wandb를 선택적으로 사용하게 하려면, 다음 중 한 가지 방법을 사용할 수 있습니다.
python trainer = my_trainer(..., use_wandb=True)
bash 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'
- 모델 이름, 버전, 아키텍처 파라미터, 하이퍼파라미터
- 데이터셋 이름, 버전, 트레이닝 또는 검증 예제 수
- 학습률, batch size, optimizer와 같은 트레이닝 파라미터
다음 코드 스니펫은 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/를 사용하지만, 사용 사례에 맞는 접두사라면 무엇이든 사용할 수 있습니다.
이렇게 하면 프로젝트의 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()를 참조하세요.
같은 트레이닝 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")
*은 모든 메트릭이 차트에서 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})
- 메트릭을 얼마나 자주 로깅해야 하나요? 선택 사항으로 둘 수 있나요?
- 시각화하는 데 어떤 유형의 데이터가 도움이 될 수 있나요?
- 이미지의 경우 시간에 따른 변화를 확인할 수 있도록 샘플 예측 결과, 세그멘테이션 마스크 등을 로깅할 수 있습니다.
- 텍스트의 경우 나중에 탐색할 수 있도록 샘플 예측 결과를 담은 테이블을 로깅할 수 있습니다.
예시는 객체 및 미디어 로깅을 참조하세요.
분산 환경을 지원하는 프레임워크에서는 다음 워크플로 중 하나를 적용할 수 있습니다:
- 메인 프로세스에서만 로깅합니다(권장).
- 모든 프로세스에서 로깅하고, 공유
group 이름을 사용해 run을 그룹화합니다.
자세한 내용은 분산 트레이닝 Experiments 로깅을 참조하세요.
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)
dataset = wandb.Artifact(name="flowers", type="dataset")
dataset.add_file("flowers.npy")
run.use_artifact(dataset)
run.use_artifact()를 사용해 이 artifact를 현재 run에 연결하며, 이를 통해 W&B는 run에서 사용된 데이터셋의 리니지를 추적할 수 있습니다.
트레이닝 또는 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()
import wandb
artifact = wandb.Api().artifact("user/project/artifact:latest")
local_path = artifact.download()
