> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 실험 추적, 시스템 모니터링, 모델 관리를 위해 Python 라이브러리에 W&B를 통합하는 모범 사례입니다.

이 가이드에서는 W\&B를 Python 라이브러리, 프레임워크 또는 SDK에 통합하는 패턴을 설명합니다. 의존성 관리, 인증, 선택적 로깅, run 초기화, 아티팩트, 하이퍼파라미터 튜닝 및 분산 실행을 다룹니다.

단일 트레이닝 스크립트나 노트북이 아닌 재사용 가능한 라이브러리 코드에 인테그레이션을 구현할 때 이 가이드를 사용하세요. W\&B 소개는 [실험 추적](/ko/products/wandb/track)을 참조하세요.

<h2 id="design-the-integration">
  인테그레이션 설계
</h2>

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

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

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

<h2 id="decide-how-to-install-wb">
  W\&B 설치 방법 결정하기
</h2>

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

<h3 id="require-wb-as-a-dependency">
  W\&B를 필수 의존성으로 지정하기
</h3>

W\&B가 라이브러리의 핵심 요소라면 `wandb`를 라이브러리의 의존성에 추가하세요.

`requirements.txt` 파일의 경우:

```txt title="requirements.txt" type="text" theme={"system"}
torch
wandb
```

`pyproject.toml` 파일의 경우:

```toml title="pyproject.toml" type="toml" theme={"system"}
[project]
name = "my_awesome_lib"
version = "0.1.0"
dependencies = [
    "torch",
    "wandb",
]
```

인테그레이션에서 사용하는 W\&B 기능을 기준으로 호환되는 버전 범위를 지정하는 것을 고려하세요.

<h3 id="make-wb-an-optional-dependency">
  W\&B를 선택 종속성으로 설정하기
</h3>

W\&B가 선택 기능이라면 `wandb` 없이도 라이브러리를 설치할 수 있게 하세요.

`pyproject.toml`에서 W\&B를 선택 종속성으로 선언하세요.

```toml title="pyproject.toml" theme={"system"}
[project]
name = "my_awesome_lib"
version = "0.1.0"
dependencies = [
    "torch",
]

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

그런 다음 다음 명령으로 인테그레이션을 설치하세요:

```bash theme={"system"}
pip install "my_awesome_lib[wandb]"
```

<h2 id="authenticate-users">
  사용자 인증
</h2>

W\&B는 API 키를 사용하여 사용자와 머신을 인증합니다. 라이브러리에서 run을 로깅하려면 먼저 API 키를 생성하고 `wandb` 클라이언트에서 해당 키를 사용할 수 있도록 설정해야 합니다.

W\&B는 CLI, 환경 변수, `wandb.login()`을 통한 인증을 지원합니다.

<h3 id="create-an-api-key">
  API 키 생성
</h3>

<Note>
  더 간단한 방법으로 [User Settings](https://forge.coreweave.com/settings)로 이동해 API 키를 생성하세요. API 키를 즉시 복사한 후 비밀번호 관리자와 같은 안전한 위치에 저장하세요.
</Note>

<h3 id="authenticate-from-the-command-line">
  명령줄에서 인증하기
</h3>

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

```bash theme={"system"}
wandb login
```

W\&B에서 API 키를 입력하라는 메시지가 표시됩니다.

또는 `WANDB_API_KEY` 환경 변수를 설정하세요:

```bash theme={"system"}
export WANDB_API_KEY="<api_key>"
```

자세한 내용은 [환경 변수](/ko/products/wandb/track/environment-variables)를 참조하세요.

<h3 id="authenticate-from-python">
  Python에서 인증하기
</h3>

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

```python theme={"system"}
import wandb

wandb.login()
```

비대화형 워크플로를 중단시킬 수 있으므로 재사용 가능한 라이브러리 코드에서 [`wandb.login()`](/ko/products/wandb/ref/python/functions/login)을 자동으로 호출하지 마세요.

<h2 id="make-wb-logging-optional">
  W\&B 로깅을 선택 사항으로 설정하기
</h2>

W\&B가 run 데이터를 저장하거나 업로드할지 선택하세요.

| 모드 | 동작 |
| - | - |
| `disabled` | W\&B 로깅을 비활성화합니다. W\&B는 run 데이터를 저장하거나 업로드하지 않습니다. W\&B 방법을 호출해도 아무런 효과가 없습니다. |
| `offline` | run 데이터를 업로드하지 않고 로컬에 저장합니다. 나중에 [`wandb sync`](/ko/products/wandb/ref/cli/wandb-sync)로 run을 업로드할 수 있습니다. |

run 데이터를 저장하지 않으려면 `disabled`를 사용하세요. 나중에 업로드할 수 있도록 데이터를 로컬에 저장하려면 `offline`을 사용하세요.

<h3 id="use-disabled-mode">
  `disabled` 모드 사용
</h3>

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

```python theme={"system"}
with wandb.init(mode="disabled") as run:
    # 트레이닝 로직.
```

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

```bash theme={"system"}
export WANDB_MODE=disabled
```

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

```bash theme={"system"}
wandb disabled
```

<h3 id="use-offline-mode">
  `offline` 모드 사용
</h3>

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

```python theme={"system"}
with wandb.init(mode="offline") as run:
    # 트레이닝 로직.
```

또는 환경 변수로 `WANDB_MODE`를 설정하세요.

```bash theme={"system"}
export WANDB_MODE=offline
```

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

```python theme={"system"}
import os

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

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

```bash theme={"system"}
wandb offline
```

나중에 다음 명령으로 오프라인 run을 업로드하세요:

```bash theme={"system"}
wandb sync <run_directory>
```

<h2 id="initialize-a-run">
  run 초기화
</h2>

인증 후 [run](/ko/products/wandb/runs)을 초기화하여 라이브러리의 메트릭, [설정](/ko/products/wandb/track/config) 값, [아티팩트](/ko/products/wandb/artifacts)를 로깅하세요.

[`wandb.init()`](/ko/products/wandb/ref/python/functions/init)을 호출하고 프로젝트와 팀 entity를 지정하세요. 프로젝트를 생략하면 W\&B는 기본 `"uncategorized"` 프로젝트에 run을 저장합니다.

트레이닝 루프를 감싸는 컨텍스트 관리자로 `wandb.init()`을 사용하세요. 블록을 벗어나면 W\&B는 run을 종료하고 프로세스가 끝나기 전에 대기 중인 데이터를 처리합니다.

예를 들어 라이브러리에 다음과 같은 트레이닝 루프가 있다고 가정합니다.

```python icon="python" title="Python" theme={"system"}
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 icon="python" title="Python" highlight={2,13-16,19,30-33} theme={"system"}
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,
        })
```

<Tip>
  **`wandb.init()` 호출 시점**

  W\&B로 모니터링하려는 작업 전에 `wandb.init()`을 호출하세요. 전체 트레이닝 루프를 감싸는 컨텍스트 관리자로 사용하면 run이 디버깅에 필요한 표준 출력, 표준 오류, 오류 메시지를 캡처합니다.
</Tip>

[다음 섹션](#log-configuration-and-metrics)에서는 라이브러리의 설정 값과 메트릭을 로깅하는 방법을 자세히 설명합니다.

<h2 id="log-configuration-and-metrics">
  설정과 메트릭 로깅하기
</h2>

설정 값과 메트릭을 W\&B에 로깅하면 팀 구성원과 함께 실험을 [비교](/ko/products/wandb/runs/compare-runs), [필터링](/ko/products/wandb/runs/filter-runs#example-filter-run-configuration-values-with-contains), [그룹화](/ko/products/wandb/runs/grouping), [재현](/ko/products/wandb/track/reproduce_experiments)할 수 있습니다.

<h3 id="log-configuration-values">
  설정 값 로깅하기
</h3>

하이퍼파라미터와 기타 메타데이터를 기록하려면 `wandb.init()`에 [설정](/ko/products/wandb/track/config) 딕셔너리를 전달하세요.

의미를 명확히 나타내는 키와 JSON으로 직렬화할 수 있는 값을 사용하세요:

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

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

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

run이 시작될 때 일부 값은 사용 가능하지 않을 수 있습니다. 나중에 `wandb.Run.config.update()`로 추가하세요:

```python theme={"system"}
run.config.update(
    {
        "model_parameters": 3500,
    }
)
```

자세한 내용은 [실험 설정](/ko/products/wandb/track/config)을 참조하세요.

<h3 id="log-metrics">
  메트릭 로깅하기
</h3>

트레이닝 중에 손실이나 정확도 같은 메트릭을 로깅하세요. 각 키가 메트릭 이름이고 값이 메트릭 값인 딕셔너리를 만든 다음, 이 딕셔너리를 [`wandb.Run.log()`](/ko/products/wandb/ref/python/experiments/run#method-run-log)에 전달하세요.

다음 코드 스니펫은 트레이닝 및 검증 메트릭을 W\&B에 로깅합니다.

```python icon="python" title="Python" theme={"system"}
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/` 같은 접두사를 사용하여 관련 메트릭을 그룹화하세요.

지원되는 데이터 유형의 로깅, 자동으로 추적되는 데이터, 모범 사례에 대한 안내는 [메트릭 및 데이터 로깅하기](/ko/products/wandb/track/log)를 참조하세요.

모델과 데이터셋을 추적하려면 [아티팩트로 모델 및 데이터셋 추적하기](#track-models-and-datasets-with-artifacts) 섹션을 참조하세요.

<h3 id="define-a-custom-log-axis">
  맞춤형 로깅 축 정의
</h3>

기본적으로 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 title="Python" icon="python" theme={"system"}
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)
```

자세한 내용은 [맞춤형 로깅 축 정의](/ko/products/wandb/track/log/customize-logging-axes)를 참조하세요.

<h2 id="track-models-and-datasets-with-artifacts">
  아티팩트로 모델과 데이터셋 추적하기
</h2>

메트릭 외에도 라이브러리가 생성하거나 사용하는 모델과 데이터셋을 보존하여 사용자와 팀 구성원이 run을 재현하고 비교할 수 있습니다.

[W\&B Artifacts](/ko/products/wandb/artifacts)를 사용하여 라이브러리가 생성하거나 사용하는 모델, 데이터셋 및 기타 파일의 버전을 관리하세요.

아티팩트 지원을 추가하기 전에 다음을 결정하세요:

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

<h3 id="log-model-checkpoints">
  모델 체크포인트 로깅하기
</h3>

모델 체크포인트를 아티팩트로 로깅하여 트레이닝된 가중치를 복구하고, 버전을 관리하고, 공유할 수 있습니다. 각 체크포인트를 원본 run과 연결하려면 아티팩트 이름에 run ID를 포함하세요.

다음 예시는 10에포크마다 체크포인트를 로깅합니다. 이름에 run ID가 포함된 아티팩트를 생성하고, 로컬 디렉터리에서 모델 가중치를 추가한 다음, [맞춤형 별칭](/ko/products/wandb/artifacts/create-a-custom-alias)을 지정하여 아티팩트를 로깅합니다.

```python title="Python" icon="python" theme={"system"}
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}")
```

<h3 id="track-run-inputs">
  run 입력 추적
</h3>

run이 데이터셋이나 모델 체크포인트 같은 아티팩트를 사용할 때는 [`wandb.Run.use_artifact()`](/ko/products/wandb/ref/python/experiments/run#method-run-use_artifact)를 사용하세요. W\&B는 해당 아티팩트를 run의 입력으로 기록합니다.

아티팩트의 특정 버전을 참조하려면 아티팩트 이름과 별칭(선택 사항)을 지정하세요. 아티팩트 이름은 `artifact_name:version` 또는 `artifact_name:alias` 형식입니다.

```python title="Python" icon="python" theme={"system"}
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")
```

<h3 id="track-run-outputs">
  run 출력 추적
</h3>

run의 출력으로 아티팩트를 로깅하려면 [`wandb.Run.log_artifact()`](/ko/products/wandb/ref/python/experiments/run#method-run-log_artifact)를 사용하세요.

1. `wandb.Artifact()`로 아티팩트를 생성하세요.
2. 아티팩트에 하나 이상의 파일을 추가하세요.
3. `wandb.Run.log_artifact()`로 아티팩트를 로깅하세요.

```python theme={"system"}
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](/ko/products/wandb/artifacts)를 참조하세요.

<h3 id="download-artifacts">
  아티팩트 다운로드
</h3>

[W\&B Public API](/ko/products/wandb/ref/python/public-api)를 사용하면 run을 생성하거나 run 입력 관계를 기록하지 않고 아티팩트를 다운로드할 수 있습니다.

```python theme={"system"}
import wandb

api = wandb.Api()

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

local_path = artifact.download()
```

자세한 내용은 [아티팩트 다운로드 및 사용](/ko/products/registry/download_use_artifact)을 참조하세요.

<h2 id="link-artifacts-to-the-registry">
  아티팩트를 레지스트리에 연결하기
</h2>

[레지스트리](/ko/products/registry)를 사용하여 팀 간에 아티팩트 버전을 공유하고 관리하세요.

아티팩트 버전을 연결하기 전에 다음을 결정하세요.

* 공유할 아티팩트 버전
* 아티팩트 버전을 연결할 [컬렉션](/ko/products/registry/create_collection)
* 아티팩트 버전을 게시할 [레지스트리](/ko/products/registry)

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

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

```python theme={"system"}
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}"
    )
```

자세한 내용은 [아티팩트 버전을 컬렉션에 연결하기](/ko/products/registry/link_version)를 참조하세요.

<h2 id="tune-hyperparameters">
  하이퍼파라미터 튜닝
</h2>

라이브러리가 하이퍼파라미터 튜닝을 지원한다면 [W\&B Sweeps](/ko/products/wandb/sweeps)를 통합하여 그리드, 무작위 또는 베이지안 탐색을 실행하세요.

<Tip>
  W\&B는 스윕 설정을 기본 트레이닝 로직과 분리할 것을 권장합니다. 트레이닝 함수는 스윕 전용 로직에 직접 의존하는 대신 `wandb.Run.config`에서 매개변수를 조회해야 합니다.
</Tip>

자세한 내용은 [Sweeps](/ko/products/wandb/sweeps)를 참조하세요.

<h2 id="support-distributed-training">
  분산 트레이닝 지원
</h2>

라이브러리가 여러 프로세스나 머신을 지원하는 경우, run을 생성하고 데이터를 로깅할 프로세스를 정의하세요.

일반적인 접근 방식은 다음과 같습니다:

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

자세한 내용은 [분산 트레이닝 실험 로깅](/ko/products/wandb/track/log/distributed-training)을 참조하세요.