> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-locadex-parallel-t9n-main-cs60c8p4o6ik99tylxgp3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

단일 트레이닝 스크립트나 notebook이 아닌 재사용 가능한 라이브러리 코드를 포괄하는 인테그레이션에 이 가이드를 사용하세요. W\&B 소개는 [Experiment Tracking](/ko/models/track)을 참조하세요.

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

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

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

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

<div id="decide-how-to-install-wb">
  ## W\&B 설치 방식 결정
</div>

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

<div id="require-wb-as-a-dependency">
  ### W\&B를 의존성으로 추가
</div>

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

`requirements.txt` 파일의 경우:

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

`pyproject.toml` 파일의 경우:

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

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

<div id="make-wb-an-optional-dependency">
  ### W\&B를 선택 종속성으로 지정
</div>

W\&B가 선택적 특성인 경우 `wandb` 없이도 라이브러리를 설치할 수 있게 하세요.

`pyproject.toml`에서 W\&B를 선택 종속성으로 선언합니다.

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

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

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

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

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

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

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

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

<Note>
  더 간편하게 하려면 [User Settings](https://wandb.ai/settings)로 이동해 API 키를 생성하세요. API 키는 즉시 복사해 비밀번호 관리자와 같은 안전한 위치에 저장하세요.
</Note>

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

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

```bash theme={null}
wandb login
```

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

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

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

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

<div id="authenticate-from-python">
  ### Python에서 인증
</div>

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

```python theme={null}
import wandb

wandb.login()
```

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

<div id="make-wb-logging-optional">
  ## W\&B 로깅을 선택적으로 사용
</div>

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

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

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

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

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

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

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

```bash theme={null}
export WANDB_MODE=disabled
```

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

```bash theme={null}
wandb disabled
```

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

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

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

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

```bash theme={null}
export WANDB_MODE=offline
```

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

```python theme={null}
import os

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

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

```bash theme={null}
wandb offline
```

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

```bash theme={null}
wandb sync <run_directory>
```

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

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

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

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

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

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

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

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

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

<div id="log-configuration-and-metrics">
  ## 설정 및 메트릭 로깅
</div>

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

<div id="log-configuration-values">
  ### 설정 값 기록
</div>

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

설명적인 키와 JSON 직렬화 가능한 값을 사용하세요:

```python theme={null}
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={null}
with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:
    # 트레이닝 로직.
```

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

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

자세한 내용은 [실험 구성](/ko/models/track/config)을 참조하세요.

<div id="log-metrics">
  ### 메트릭 로깅
</div>

트레이닝 중에 손실이나 정확도 등의 메트릭을 로깅합니다. 각 키는 메트릭 이름이고 각 값은 메트릭 값인 딕셔너리를 만듭니다. 이 딕셔너리를 [`wandb.Run.log()`](/ko/models/ref/python/experiments/run#method-run-log)에 전달합니다.

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

```python icon="python" title="Python" theme={null}
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/models/track/log)을 참조하세요.

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

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

기본적으로 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 title="Python" icon="python" theme={null}
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/models/track/log/customize-logging-axes)를 참조하세요.

<div id="track-models-and-datasets-with-artifacts">
  ## 아티팩트를 사용해 모델과 데이터셋 추적하기
</div>

메트릭 외에도, 본인과 팀 구성원이 Runs를 재현하고 비교할 수 있도록 라이브러리가 생성하거나 사용하는 모델과 데이터셋을 저장할 수 있습니다.

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

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

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

<div id="log-model-checkpoints">
  ### 모델 체크포인트 로깅
</div>

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

다음 예시는 10 에포크마다 체크포인트를 로깅합니다. run ID가 포함된 이름으로 아티팩트를 만들고, 로컬 디렉터리의 모델 가중치를 추가한 다음, [맞춤형 별칭](/ko/models/artifacts/create-a-custom-alias)과 함께 아티팩트를 로깅합니다.

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

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

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

아티팩트 이름과 선택적 별칭을 지정하여 해당 아티팩트의 특정 버전을 참조하세요. 아티팩트 이름은 `artifact_name:version` 또는 `artifact_name:alias` 형식입니다.

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

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

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

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

```python theme={null}
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/models/artifacts)를 참조하세요.

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

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

```python theme={null}
import wandb

api = wandb.Api()

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

local_path = artifact.download()
```

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

<div id="link-artifacts-to-the-wb-registry">
  ## 아티팩트를 W\&B 레지스트리에 연결하기
</div>

[W\&B Registry](/ko/models/registry)를 사용하여 여러 팀에서 아티팩트 버전을 공유하고 관리하세요.

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

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

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

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

```python theme={null}
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/models/registry/link_version)를 참조하세요.

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

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

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

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

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

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

일반적인 방법은 다음과 같습니다:

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

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