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

이 가이드에서는 Python 라이브러리, 프레임워크 또는 SDK에 W&B를 통합하는 패턴을 설명합니다. 의존성 관리, 인증, 선택적 로깅, run 초기화, 아티팩트, 하이퍼파라미터 튜닝 및 분산 실행을 다룹니다. 단일 트레이닝 스크립트나 notebook이 아닌 재사용 가능한 라이브러리 코드를 포괄하는 인테그레이션에 이 가이드를 사용하세요. W&B 소개는 Experiment Tracking을 참조하세요.

인테그레이션 설계

라이브러리에 W&B를 추가하기 전에 다음 사항을 결정하세요.

wandb를 필수 종속성으로 할지 선택 종속성으로 할지
사용자가 W&B 데이터를 저장하거나 업로드하지 않고도 라이브러리를 실행할 수 있도록 할지
라이브러리에서 로깅할 설정 값, 메트릭, 아티팩트
W&B Sweeps를 사용한 하이퍼파라미터 튜닝을 지원할지
모델 및 데이터셋 같은 아티팩트를 조직의 W&B 레지스트리를 통해 공유할지
라이브러리에서 분산 트레이닝과 여러 프로세스를 처리하는 방식

이러한 결정에 따라 라이브러리에서 W&B를 임포트하는 방식, run 라이프사이클을 관리하는 방식, W&B를 사용할 수 없을 때의 동작이 결정됩니다.

W&B 설치 방식 결정

라이브러리와 함께 W&B를 자동으로 설치할지, 선택 기능으로 제공할지 결정하세요.

W&B를 의존성으로 추가

W&B가 라이브러리의 핵심인 경우 wandb를 의존성에 추가하세요. requirements.txt 파일의 경우:

requirements.txt

torch
wandb

pyproject.toml 파일의 경우:

pyproject.toml

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

인테그레이션에서 사용하는 W&B 특성에 따라 호환되는 버전 범위를 지정하는 것이 좋습니다.

W&B를 선택 종속성으로 지정

W&B가 선택적 특성인 경우 wandb 없이도 라이브러리를 설치할 수 있게 하세요. pyproject.toml에서 W&B를 선택 종속성으로 선언합니다.

pyproject.toml

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

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

그런 다음 다음 명령을 사용하여 인테그레이션을 설치합니다:

pip install "my_awesome_lib[wandb]"

사용자 인증

W&B는 API 키로 사용자와 머신을 인증합니다. 라이브러리에서 run을 로깅하려면 먼저 API 키를 생성하고 wandb 클라이언트에서 이를 사용할 수 있게 해야 합니다. W&B는 CLI, 환경 변수 및 wandb.login()을 통한 인증을 지원합니다.

API 키 생성

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

명령줄에서 인증하기

터미널에서 다음을 실행하세요:

wandb login

W&B에서 API 키를 입력하라는 메시지가 표시됩니다. 또는 WANDB_API_KEY 환경 변수를 설정하세요:

export WANDB_API_KEY="<api_key>"

자세한 내용은 환경 변수를 참조하세요.

Python에서 인증

대화형 Python 환경 또는 노트북에서 다음을 호출하세요:

import wandb

wandb.login()

재사용 가능한 라이브러리 코드에서 wandb.login()을 자동으로 호출하면 비대화형 워크플로가 중단될 수 있으므로 피하세요.

W&B 로깅을 선택적으로 사용

W&B에서 run 데이터를 저장하거나 업로드할지 선택합니다.

모드	동작
`disabled`	W&B 로깅을 비활성화합니다. W&B는 run 데이터를 저장하거나 업로드하지 않습니다. W&B 메서드를 호출해도 아무런 효과가 없습니다.
`offline`	run 데이터를 업로드하지 않고 로컬에 저장합니다. 나중에 `wandb sync`를 사용하여 run을 업로드할 수 있습니다.

run 데이터를 저장하지 않으려면 disabled를 사용합니다. 나중에 업로드할 데이터를 로컬에 저장하려면 offline를 사용합니다.

`disabled` 모드 사용

wandb.init()에 mode="disabled"를 전달하세요:

with wandb.init(mode="disabled") as run:
    # 트레이닝 로직.

또는 환경에서 WANDB_MODE를 설정합니다:

export WANDB_MODE=disabled

W&B CLI로도 모드를 설정할 수 있습니다:

wandb disabled

`offline` 모드 사용

wandb.init()에 mode="offline"을 전달하세요:

with wandb.init(mode="offline") as run:
    # 트레이닝 로직.

또는 환경에서 WANDB_MODE를 설정하세요:

export WANDB_MODE=offline

Python에서 wandb.init()를 호출하기 전에 환경 변수를 설정하세요:

import os

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

W&B CLI에서도 모드를 설정할 수 있습니다:

wandb offline

오프라인 run을 나중에 업로드하려면 다음을 사용하세요:

wandb sync <run_directory>

run 초기화

인증 후 run을 초기화하여 라이브러리의 메트릭, 설정 값, 아티팩트를 로깅합니다. wandb.init()을 호출하고 프로젝트와 팀 entity를 지정합니다. 프로젝트를 생략하면 W&B는 기본 "uncategorized" 프로젝트에 run을 저장합니다. 트레이닝 루프를 wandb.init() 컨텍스트 관리자 안에서 사용합니다. 블록을 벗어나면 프로세스가 종료되기 전에 W&B가 run을 종료하고 보류 중인 데이터를 처리합니다. 예를 들어, 라이브러리에 다음 트레이닝 루프가 있다고 가정합니다.

Python

import random # 데이터 시뮬레이션용

def model(training_data: int) -> int:
    """Model simulation for demonstration purposes."""
    return training_data * 2 + random.randint(-1, 1)  

# 가중치와 노이즈 시뮬레이션
weights = random.random() # 무작위 가중치 초기화
noise = random.random() / 5  # 노이즈를 시뮬레이션하기 위한 작은 무작위 값

for epoch in range(epochs):
    xb = weights + noise  # 시뮬레이션된 입력 트레이닝 데이터
    yb = weights + noise * 2  # 시뮬레이션된 목표 출력(입력 노이즈의 2배)
    
    y_pred = model(xb)  # 모델 예측
    loss = (yb - y_pred) ** 2  # 평균 제곱 오차 손실

    print(f"epoch={epoch}, loss={loss}")

W&B를 통합하려면 컨텍스트 관리자를 사용하여 run을 초기화하고, 설정 값을 wandb.init()에 전달한 다음, wandb.Run.log()로 메트릭을 로깅하세요:

Python

import random # 데이터 시뮬레이션용
import wandb

def model(training_data: int) -> int:
    """Model simulation for demonstration purposes."""
    return training_data * 2 + random.randint(-1, 1)  

# 가중치와 노이즈 시뮬레이션
weights = random.random() # 가중치를 무작위로 초기화
noise = random.random() / 5  # 노이즈를 흉내 내는 작은 무작위 값

# 하이퍼파라미터 및 설정
config = {
    "epochs": 10,  # 트레이닝할 에포크 수
    "learning_rate": 0.01,  # optimizer의 학습률
}

# 컨텍스트 매니저를 사용해 W&B run을 초기화하고 종료합니다
with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:    
    # 트레이닝 루프 시뮬레이션
    for epoch in range(config["epochs"]):
        xb = weights + noise  # 시뮬레이션한 입력 트레이닝 데이터
        yb = weights + noise * 2  # 시뮬레이션한 목표 출력(입력 노이즈의 두 배)
        
        y_pred = model(xb)  # 모델 예측
        loss = (yb - y_pred) ** 2  # 평균 제곱 오차 손실

        print(f"epoch={epoch}, loss={loss}")
        # 에포크와 손실을 W&B에 로깅
        run.log({
            "epoch": epoch,
            "loss": loss,
        })

wandb.init() 호출 시점W&B에서 모니터링할 작업을 시작하기 전에 wandb.init()를 호출하세요. 전체 트레이닝 루프를 컨텍스트 관리자로 감싸면 run에서 디버깅에 필요한 표준 출력, 표준 오류 및 오류 메시지를 캡처합니다.

다음 섹션에서는 라이브러리에서 설정 값과 메트릭을 로깅하는 방법을 자세히 설명합니다.

설정 및 메트릭 로깅

설정 값과 메트릭을 W&B에 로깅하면 본인과 팀 구성원이 실험을 비교, 필터링, 그룹화, 재현할 수 있습니다.

설정 값 기록

하이퍼파라미터와 기타 메타데이터를 기록하려면 설정 딕셔너리를 wandb.init()에 전달하세요. 설명적인 키와 JSON 직렬화 가능한 값을 사용하세요:

config = {
    "batch_size": 32,
    "learning_rate": 0.001,
    "optimizer": "adam",
    "model": {
        "type": "resnet",
        "depth": 50,
    },
    "dataset": {
        "name": "CIFAR-10",
        "num_classes": 10,
    },
}

딕셔너리를 wandb.init()에 전달하세요:

with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:
    # 트레이닝 로직.

일부 값은 run 시작 시 사용할 수 없을 수 있습니다. 나중에 wandb.Run.config.update()를 사용해 추가하세요:

run.config.update(
    {
        "model_parameters": 3500,
    }
)

자세한 내용은 실험 구성을 참조하세요.

메트릭 로깅

트레이닝 중에 손실이나 정확도 등의 메트릭을 로깅합니다. 각 키는 메트릭 이름이고 각 값은 메트릭 값인 딕셔너리를 만듭니다. 이 딕셔너리를 wandb.Run.log()에 전달합니다. 다음 코드 스니펫은 트레이닝 및 검증 메트릭을 W&B에 로깅합니다:

Python

import wandb

with wandb.init(entity="your-entity", project="your-project-name") as run:
    metrics = {
        "train/loss": 0.4,
        "train/learning_rate": 0.4,
        "val/loss": 0.5, 
        "val/accuracy": 0.7
    }
    run.log(metrics)

train/, val/과 같은 접두사를 사용하여 관련 메트릭을 그룹화하세요. 지원되는 데이터 유형 로깅, 자동 추적되는 데이터 및 권장 사항에 대한 자세한 내용은 메트릭 및 데이터 로깅을 참조하세요. 모델과 데이터셋을 추적하려면 아티팩트로 모델 및 데이터셋 추적 섹션을 참조하세요.

맞춤형 로깅 축 정의

기본적으로 W&B는 로깅된 메트릭을 자동으로 증가하는 step을 기준으로 플롯합니다. wandb.Run.log()를 호출할 때마다 step이 증가합니다. wandb.Run.define_metric()을 사용하면 에포크나 전역 step과 같은 다른 값을 기준으로 메트릭을 플롯할 수 있습니다. 다음 예시에서는 validation_loss의 x축으로 x_axis_squared를 정의합니다. 각 루프 반복에서 x_axis_squared는 인덱스 i의 제곱이며, validation_loss는 무작위로 생성된 값입니다:

Python

import wandb
import random

with wandb.init() as run:
    run.define_metric(step_metric = "x_axis_squared", name = "validation_loss")

    for i in range(10):
        log_dict = {
            "x_axis_squared": i**2,
            "validation_loss": random.random(),
        }
        run.log(log_dict)

자세한 내용은 맞춤형 로깅 축 정의를 참조하세요.

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

메트릭 외에도, 본인과 팀 구성원이 Runs를 재현하고 비교할 수 있도록 라이브러리가 생성하거나 사용하는 모델과 데이터셋을 저장할 수 있습니다. W&B Artifacts를 사용해 라이브러리가 생성하거나 사용하는 모델, 데이터셋 및 기타 파일을 버전 관리하세요. 아티팩트 지원을 추가하기 전에 다음을 결정하세요:

로깅할 파일
아티팩트 로깅을 선택 사항으로 제공할지 여부
체크포인트를 로깅할 빈도
아티팩트와 별칭의 이름을 지정하는 방법
어떤 아티팩트가 run 입력 및 출력을 나타내는지

모델 체크포인트 로깅

모델 체크포인트를 아티팩트로 로깅하면 학습된 가중치를 복구하고, 버전을 관리하고, 공유할 수 있습니다. 각 체크포인트를 해당 원본 run과 연결하려면 아티팩트 이름에 run ID를 포함하세요. 다음 예시는 10 에포크마다 체크포인트를 로깅합니다. run ID가 포함된 이름으로 아티팩트를 만들고, 로컬 디렉터리의 모델 가중치를 추가한 다음, 맞춤형 별칭과 함께 아티팩트를 로깅합니다.

Python

import wandb
with wandb.init(entity="your-entity", project="your-project-name") as run:

    # 여기에 트레이닝 데이터 및 모델 트레이닝 로직 작성

    if epoch % 10 == 0: # 10 에포크마다 모델 checkpoint 로깅

        metadata = {"eval/accuracy": 0.8, "train/steps": 800} 

        artifact = wandb.Artifact(
                        name=f"model-{run.id}", 
                        metadata=metadata, 
                        type="model"
                        )
        artifact.add_dir("./models/output_model") # 모델 가중치가 저장된 로컬 디렉토리

        run.log_artifact(artifact, aliases=f"epoch_{epoch}")

run 입력 추적

데이터셋이나 모델 체크포인트처럼 run에서 아티팩트를 사용할 때는 wandb.Run.use_artifact()를 사용하세요. W&B는 해당 아티팩트를 run의 입력으로 기록합니다. 아티팩트 이름과 선택적 별칭을 지정하여 해당 아티팩트의 특정 버전을 참조하세요. 아티팩트 이름은 artifact_name:version 또는 artifact_name:alias 형식입니다.

Python

import wandb

# run 초기화
with wandb.init(entity="your-entity", project="your-project") as run:
  # 아티팩트를 조회하고 종속성으로 표시
  artifact = run.use_artifact(artifact_or_name="artifact_name:alias_or_version")

run 출력 추적

wandb.Run.log_artifact()를 사용하여 아티팩트를 run의 출력으로 로깅하세요.

wandb.Artifact()로 아티팩트를 생성합니다.
아티팩트에 하나 이상의 파일을 추가합니다.
wandb.Run.log_artifact()로 아티팩트를 로깅합니다.

import wandb

# run 초기화
with wandb.init(entity="your-entity", project="project-name") as run:
  
  # 아티팩트 생성
  artifact = wandb.Artifact(name = "artifact-name", type = "artifact-type")
  artifact.add_file(local_path = "path/to/file", name="optional-filename") # 아티팩트에 파일 추가

  # 아티팩트를 run의 출력으로 로깅
  run.log_artifact(artifact_or_path = artifact)

아티팩트 생성, 관리 및 사용에 대한 자세한 내용은 Artifacts를 참조하세요.

아티팩트 다운로드

W&B Public API를 사용하여 run을 생성하거나 run 입력 관계를 기록하지 않고 아티팩트를 다운로드할 수 있습니다.

import wandb

api = wandb.Api()

artifact = api.artifact(
    "<entity>/<project>/<artifact_name>:<alias_or_version>"
)

local_path = artifact.download()

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

아티팩트를 W&B 레지스트리에 연결하기

W&B Registry를 사용하여 여러 팀에서 아티팩트 버전을 공유하고 관리하세요. 아티팩트 버전을 연결하기 전에 다음을 결정하세요.

공유할 아티팩트 버전
연결할 컬렉션
게시할 레지스트리

대상 레지스트리가 이미 존재해야 합니다.

다음 예시에서는 아티팩트를 로깅하고 레지스트리의 컬렉션에 연결합니다.

import wandb
import random

# 아티팩트를 게시할 컬렉션과 레지스트리의
# 이름을 지정합니다
COLLECTION_NAME = "collection-name"
REGISTRY_NAME = "registry-name"

# 아티팩트를 추적할 W&B Run을 초기화합니다
with wandb.init(project="project-name") as run:
    # 로깅할 수 있도록 가상의 모델 파일을 생성합니다
    with open("my_model.txt", "w") as f:
        f.write("Model: " + str(random.random()))

    # 아티팩트를 W&B에 로깅합니다
    logged_artifact = run.log_artifact(
        artifact_or_path="./my_model.txt", 
        name="artifact-name",
        type="artifact-type" # 아티팩트 유형을 지정합니다
    )

    # 아티팩트를 레지스트리에 연결합니다
    run.link_artifact(
        artifact=logged_artifact, 
        target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"
    )

자세한 내용은 아티팩트 버전을 컬렉션에 연결하기를 참조하세요.

하이퍼파라미터 튜닝

라이브러리에서 하이퍼파라미터 튜닝을 지원하는 경우 W&B Sweeps를 통합하여 그리드, 무작위 또는 베이지안 탐색을 실행하세요.

W&B는 스윕 설정을 기본 트레이닝 로직과 분리해 둘 것을 권장합니다. 트레이닝 함수는 스윕별 로직에 직접 의존하지 말고 wandb.Run.config에서 매개변수를 조회해야 합니다.

자세한 내용은 Sweeps를 참조하세요.

분산 트레이닝 지원

라이브러리가 여러 프로세스 또는 머신을 지원하는 경우, 어떤 프로세스에서 run을 생성하고 데이터를 로깅할지 정의하세요. 일반적인 방법은 다음과 같습니다:

메인 프로세스에서만 로깅합니다. 이 방법은 중복된 메트릭과 아티팩트를 방지합니다.
각 프로세스에 대해 하나의 run을 생성하고 공유 group 값으로 run을 그룹화합니다.

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

​인테그레이션 설계

​W&B 설치 방식 결정

​W&B를 의존성으로 추가

​W&B를 선택 종속성으로 지정

​사용자 인증

​API 키 생성

​명령줄에서 인증하기

​Python에서 인증

​W&B 로깅을 선택적으로 사용

​disabled 모드 사용

​offline 모드 사용

​run 초기화

​설정 및 메트릭 로깅

​설정 값 기록

​메트릭 로깅

​맞춤형 로깅 축 정의

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

​모델 체크포인트 로깅

​run 입력 추적

​run 출력 추적

​아티팩트 다운로드

​아티팩트를 W&B 레지스트리에 연결하기

​하이퍼파라미터 튜닝

​분산 트레이닝 지원

인테그레이션 설계

W&B 설치 방식 결정

W&B를 의존성으로 추가

W&B를 선택 종속성으로 지정

사용자 인증

API 키 생성

명령줄에서 인증하기

Python에서 인증

W&B 로깅을 선택적으로 사용

`disabled` 모드 사용

`offline` 모드 사용

run 초기화

설정 및 메트릭 로깅

설정 값 기록

메트릭 로깅

맞춤형 로깅 축 정의

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

모델 체크포인트 로깅

run 입력 추적

run 출력 추적

아티팩트 다운로드

아티팩트를 W&B 레지스트리에 연결하기

하이퍼파라미터 튜닝

분산 트레이닝 지원