Python 라이브러리에 W&B 추가하기

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

인테그레이션 설계

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

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

이러한 결정에 따라 라이브러리가 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  # 시뮬레이션된 목표 출력 (입력 노이즈의 두 배)
    
    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,  # 옵티마이저의 학습률
}

# 컨텍스트 관리자를 사용하여 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과 같은 다른 값을 기준으로 메트릭을 표시하세요. 다음 예시는 x_axis_squared를 validation_loss의 x축으로 정의합니다. 루프가 반복될 때마다 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)

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

아티팩트로 모델과 데이터셋 추적하기

메트릭 외에도 라이브러리가 생성하거나 사용하는 모델과 데이터셋을 보존하여 사용자와 팀 구성원이 run을 재현하고 비교할 수 있습니다. 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에포크마다 모델 체크포인트 로깅

        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 출력 추적

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

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()

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

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

레지스트리를 사용하여 팀 간에 아티팩트 버전을 공유하고 관리하세요. 아티팩트 버전을 연결하기 전에 다음을 결정하세요.

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

대상 레지스트리가 미리 생성되어 있어야 합니다.

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

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를 선택 종속성으로 설정하기

사용자 인증

API 키 생성

명령줄에서 인증하기

Python에서 인증하기

W&B 로깅을 선택 사항으로 설정하기

`disabled` 모드 사용

`offline` 모드 사용

run 초기화

설정과 메트릭 로깅하기

설정 값 로깅하기

메트릭 로깅하기

맞춤형 로깅 축 정의

아티팩트로 모델과 데이터셋 추적하기

모델 체크포인트 로깅하기

run 입력 추적

run 출력 추적

아티팩트 다운로드

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

하이퍼파라미터 튜닝

분산 트레이닝 지원