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

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

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

이 가이드에서는 Python 라이브러리에 Weights & Biases (W\&B)를 통합하는 방법을 설명합니다.

트레이닝 프레임워크, SDK 또는 재사용 가능한 라이브러리처럼 복잡한 코드베이스에 W\&B를 통합하는 경우에는 다음 권장 사항을 따르세요.

<Tip>
  W\&B를 처음 사용한다면 계속하기 전에 핵심 가이드(예: [실험 추적](/ko/models/track/))를 먼저 검토하세요.
</Tip>

아래에서는 작업 중인 코드베이스가 단일 Python 트레이닝 스크립트나 Jupyter 노트북보다 더 복잡할 때 유용한 팁과 모범 사례를 다룹니다.

<div id="decide-how-users-install-wb">
  ## 사용자의 W\&B 설치 방식을 결정합니다
</div>

시작하기 전에 W\&B를 필수 의존성으로 지정할지, 아니면 라이브러리의 선택 기능으로 제공할지 결정하세요.

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

W\&B가 라이브러리 기능의 핵심 요소라면, W\&B Python SDK(`wandb`)를 의존성에 추가하세요:

```txt theme={null}
torch==1.8.0 
...
wandb==0.13.*
```

<div id="make-wb-optional-on-installation">
  ### 설치 시 W\&B를 선택 사항으로 설정하기
</div>

W\&B가 선택적 기능이라면, 설치되어 있지 않아도 라이브러리가 실행될 수 있게 하세요.

Python에서 `wandb`를 조건부로 임포트하거나 `pyproject.toml`에서 선택적 의존성으로 선언할 수 있습니다.

<Tabs>
  <Tab title="Python">
    `wandb`를 사용할 수 있는지 확인하고, 사용자가 W\&B 기능을 활성화했지만 이를 설치하지 않은 경우 명확한 오류를 발생시키세요:

    ```python theme={null}
    try:
        import wandb
        _WANDB_AVAILABLE = True
    except ImportError:
        _WANDB_AVAILABLE = False
    ```
  </Tab>

  <Tab title="pyproject.toml">
    `pyproject.toml` 파일에서 `wandb`를 선택적 의존성으로 선언하세요:

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

    [project.optional-dependencies]
    dev = [
        "wandb"
    ]
    ```
  </Tab>
</Tabs>

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

W\&B는 API 키로 사용자와 머신을 인증합니다.

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

API 키는 클라이언트나 머신이 W\&B에 인증되도록 합니다. 사용자 프로필에서 API 키를 생성할 수 있습니다.

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

1. 오른쪽 상단의 사용자 프로필 아이콘을 클릭합니다.
2. **User Settings**를 선택한 다음 **API Keys** 섹션으로 스크롤합니다.

<div id="install-and-log-in-to-wb">
  ### W\&B 설치 및 로그인
</div>

로컬 환경에 `wandb` 라이브러리를 설치하고 로그인하려면 다음 단계를 따르세요.

<Tabs>
  <Tab title="명령줄">
    1. `WANDB_API_KEY` [환경 변수](/ko/models/track/environment-variables/)를 API 키로 설정합니다.

       ```bash theme={null}
       export WANDB_API_KEY=<your_api_key>
       ```

    2. `wandb` 라이브러리를 설치하고 로그인합니다.

       ```bash theme={null}
       pip install wandb

       wandb login
       ```
  </Tab>

  <Tab title="Python">
    1. 터미널을 열고 Python SDK를 설치합니다.
       ```bash theme={null}
       pip install wandb
       ```

    2. Python 스크립트 또는 노트북에서 W\&B에 로그인합니다. API 키를 입력하라는 메시지가 표시됩니다.
       ```python theme={null}
       import wandb
       wandb.login()
       ```
  </Tab>

  <Tab title="Python 노트북">
    다음 코드 스니펫을 Jupyter 노트북의 셀에 복사해 붙여넣고 실행합니다. API 키를 입력하라는 메시지가 표시됩니다.

    ```notebook theme={null}
    !pip install wandb

    import wandb
    wandb.login()
    ```
  </Tab>
</Tabs>

<div id="start-a-run">
  ## run 시작하기
</div>

*run*은 트레이닝 실험과 같은 단일 계산 작업 단위를 의미합니다. 대부분의 라이브러리는 트레이닝 작업마다 run 하나를 생성합니다. run에 대한 자세한 내용은 [W\&B Runs](/ko/models/runs/)를 참조하세요.

[`wandb.init()`](/ko/models/ref/python/functions/init)으로 run을 초기화하고 프로젝트 이름과 team entity(팀 이름)를 지정하세요. 프로젝트를 지정하지 않으면 W\&B는 run을 "uncategorized"라는 기본 프로젝트에 저장합니다.:

```python theme={null}
with wandb.init(project="<project_name>", entity="<entity>") as run:
    ...
```

W\&B는 오류가 발생하더라도 run이 제대로 종료되도록 컨텍스트 관리자를 사용하는 것을 권장합니다. 컨텍스트 관리자를 사용하지 않는 경우에는 run을 종료하고 모든 데이터를 W\&B에 로깅하기 위해 `run.finish()`를 호출해야 합니다.

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

  `wandb.init()`은 가능한 한 빨리 호출하세요. W\&B는 stdout, stderr, 오류 메시지를 캡처하므로 디버깅이 쉬워집니다.

  관련된 모든 정보가 run에 캡처되도록 전체 트레이닝 루프를 `wandb.init()` 컨텍스트 관리자 안에서 감싸세요. 여기에는 디버깅에 매우 중요한 오류 메시지도 포함됩니다.
</Tip>

<div id="set-wandb-as-an-optional-dependency">
  ### `wandb`를 선택적 의존성으로 설정하기
</div>

라이브러리 사용자가 `wandb`를 선택적으로 사용하게 하려면, 다음 중 한 가지 방법을 사용할 수 있습니다.

* 다음과 같이 `wandb` 플래그를 정의합니다.

<Tabs>
  <Tab title="Python">`python trainer = my_trainer(..., use_wandb=True) `</Tab>
  <Tab title="Bash">`bash python train.py ... --use-wandb `</Tab>
</Tabs>

* 또는 `wandb.init()`에서 `wandb`를 `disabled`로 설정합니다.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    wandb.init(mode="disabled")
    ```
  </Tab>

  <Tab title="Bash">
    ```bash theme={null}
    export WANDB_MODE=disabled
    ```

    또는

    ```bash theme={null}
    wandb disabled
    ```
  </Tab>
</Tabs>

* 또는 `wandb`를 오프라인으로 설정합니다. 이 경우에도 `wandb`는 계속 실행되지만, 인터넷을 통해 W\&B와 통신을 시도하지 않을 뿐입니다.

<Tabs>
  <Tab title="Environment Variable">
    ```bash theme={null}
    export WANDB_MODE=offline
    ```

    또는

    ```python theme={null}
    os.environ['WANDB_MODE'] = 'offline'
    ```
  </Tab>

  <Tab title="Bash">
    ```bash theme={null}
    wandb offline
    ```
  </Tab>
</Tabs>

<div id="define-a-run-config">
  ## run config 정의하기
</div>

run을 초기화할 때 설정 딕셔너리를 제공하면 하이퍼파라미터와 기타 메타데이터를 W\&B에 로깅할 수 있습니다.

W\&B App을 사용하면 config 파라미터를 기준으로 runs를 비교하고 Runs table에서 필터링할 수 있습니다. 또한 이러한 파라미터를 사용해 W\&B App에서 runs를 함께 그룹화할 수도 있습니다.

예를 들어, 다음 이미지에서는 batch size (bathch\_size)가 config 파라미터로 정의되어 있으며 Runs table에 표시됩니다(첫 번째 column 참조). 이를 통해 사용자는 batch size를 기준으로 runs를 필터링하고 비교할 수 있습니다:

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mVjDwbx0mC8gYx-b/images/integrations/integrations_add_any_lib_runs_page.png?fit=max&auto=format&n=mVjDwbx0mC8gYx-b&q=85&s=a059dd2d4101adf87649438ea957b35c" alt="W&B Runs table" width="1820" height="768" data-path="images/integrations/integrations_add_any_lib_runs_page.png" />
</Frame>

일반적인 config 파라미터 값의 예시는 다음과 같습니다:

* 모델 이름, 버전, 아키텍처 파라미터, 하이퍼파라미터
* 데이터셋 이름, 버전, 트레이닝 또는 검증 예제 수
* 학습률, batch size, optimizer와 같은 트레이닝 파라미터

다음 코드 스니펫은 config를 로깅하는 방법을 보여줍니다:

```python theme={null}
config = {"batch_size": 32, ...}
with wandb.init(..., config=config) as run:
    ...
```

<div id="update-the-run-config">
  ### run config 업데이트
</div>

초기화 시점에 값을 사용할 수 없는 경우, 나중에 `wandb.Run.config.update`로 config를 업데이트하세요. 예를 들어, 모델을 인스턴스화한 후 모델의 파라미터를 추가할 수 있습니다:

```python theme={null}
with wandb.init(...) as run:
    model = MyModel(...)
    run.config.update({"model_parameters": 3500})
```

자세한 내용은 [Experiments 설정](/ko/models/track/config/)을 참조하세요.

<div id="log-metrics-and-data">
  ## 메트릭 및 데이터 로깅
</div>

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

키가 메트릭 이름인 딕셔너리를 만드세요. 이 딕셔너리 객체를 [`wandb.Run.log()`](/ko/models/ref/python/experiments/run#method-run-log)에 전달해 W\&B에 로깅하세요:

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

메트릭 이름 접두사를 사용해 W\&B App에서 관련 메트릭을 그룹화하세요. 일반적으로는 트레이닝 메트릭과 검증 메트릭에 각각 `train/`과 `val/`를 사용하지만, 사용 사례에 맞는 접두사라면 무엇이든 사용할 수 있습니다.

이렇게 하면 프로젝트의 Workspace에서 트레이닝 및 검증 메트릭이나, 따로 구분하려는 다른 메트릭 유형별로 별도의 섹션이 생성됩니다:

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

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mVjDwbx0mC8gYx-b/images/integrations/integrations_add_any_lib_log.png?fit=max&auto=format&n=mVjDwbx0mC8gYx-b&q=85&s=da8be42cd29aef0849aa301423982676" alt="W&B Workspace" width="1236" height="738" data-path="images/integrations/integrations_add_any_lib_log.png" />
</Frame>

자세한 내용은 [`wandb.Run.log()`](/ko/models/ref/python/experiments/run#method-run-log)를 참조하세요.

<div id="control-the-x-axis">
  ### x-axis 제어
</div>

같은 트레이닝 step에 대해 `wandb.Run.log()`를 여러 번 호출하면 wandb SDK는 `wandb.Run.log()`를 호출할 때마다 내부 step 카운터를 증가시킵니다. 이 카운터는 트레이닝 루프의 트레이닝 step과 맞지 않을 수 있습니다.

이 문제를 방지하려면 `wandb.init()`를 호출한 직후 `wandb.Run.define_metric()`를 사용해 x-axis step을 한 번만 명시적으로 정의하세요:

```python theme={null}
with wandb.init(...) as run:
    run.define_metric("*", step_metric="global_step")
```

glob 패턴 `*`은 모든 메트릭이 차트에서 x축으로 `global_step`을 사용한다는 뜻입니다. 특정 메트릭만 `global_step`을 기준으로 로깅하려면, 대신 해당 메트릭을 지정할 수 있습니다:

```python theme={null}
run.define_metric("train/loss", step_metric="global_step")
```

이제 `wandb.Run.log()`를 호출할 때마다 메트릭과 `step` 메트릭, `global_step`를 로깅하세요:

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

독립적인 step 변수에 액세스할 수 없는 경우(예를 들어 검증 루프 중에 "global\_step"을 사용할 수 없는 경우), wandb는 이전에 로깅된 "global\_step" 값을 자동으로 사용합니다. 이 경우 필요할 때 해당 메트릭이 정의되어 있도록 메트릭의 초기값을 로깅해야 합니다.

<div id="log-media-and-structured-data">
  ### 미디어 및 구조화 데이터 로깅
</div>

스칼라 외에도 이미지, 테이블, 텍스트, 오디오, 비디오 등을 로깅할 수 있습니다.

데이터를 로깅할 때 고려할 사항은 다음과 같습니다.

* 메트릭을 얼마나 자주 로깅해야 하나요? 선택 사항으로 둘 수 있나요?
* 시각화하는 데 어떤 유형의 데이터가 도움이 될 수 있나요?
  * 이미지의 경우 시간에 따른 변화를 확인할 수 있도록 샘플 예측 결과, 세그멘테이션 마스크 등을 로깅할 수 있습니다.
  * 텍스트의 경우 나중에 탐색할 수 있도록 샘플 예측 결과를 담은 테이블을 로깅할 수 있습니다.

예시는 [객체 및 미디어 로깅](/ko/models/track/log)을 참조하세요.

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

분산 환경을 지원하는 프레임워크에서는 다음 워크플로 중 하나를 적용할 수 있습니다:

* 메인 프로세스에서만 로깅합니다(권장).
* 모든 프로세스에서 로깅하고, 공유 `group` 이름을 사용해 run을 그룹화합니다.

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

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

[W\&B Artifacts](/ko/models/artifacts/)를 사용해 모델과 데이터셋을 추적하고 버전 관리하세요. Artifacts는 머신 러닝 자산을 위한 저장소와 버전 관리를 제공하며, 데이터와 모델이 어떻게 연결되어 있는지 보여주도록 리니지를 자동으로 추적합니다.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mVjDwbx0mC8gYx-b/images/integrations/integrations_add_any_lib_dag.png?fit=max&auto=format&n=mVjDwbx0mC8gYx-b&q=85&s=e3d7cd8e279f640b8f1a442dc83e1a8c" alt="W&B에 저장된 Datasets 및 모델 체크포인트" width="1622" height="324" data-path="images/integrations/integrations_add_any_lib_dag.png" />
</Frame>

라이브러리에 Artifacts를 인테그레이션할 때는 다음 사항을 고려하세요:

* 모델 체크포인트 또는 데이터셋을 Artifacts로 log할지 여부(선택 사항으로 제공하려는 경우).
* Artifact 입력 레퍼런스(예: `entity/project/artifact`).
* 모델 체크포인트 또는 데이터셋의 logging 빈도. 예를 들어 매 에포크마다, 500 step마다 등입니다.

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

모델 체크포인트를 W\&B에 로깅하세요. 일반적으로 체크포인트는 W\&B에서 생성한 고유한 run ID를 artifact 이름의 일부로 사용해 artifact로 로깅합니다.

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

이전 코드 스니펫은 모델 체크포인트를 artifact로 로깅하고, evaluation accuracy 및 트레이닝 step과 같은 메타데이터를 추가하는 방법을 보여줍니다. 이 artifact에는 고유한 run ID가 포함된 이름이 지정되며, 쉽게 참조할 수 있도록 [맞춤형 alias](/ko/models/artifacts/create-a-custom-alias/)가 태그됩니다.

<div id="log-input-artifacts">
  ### 입력 artifact 로깅하기
</div>

입력으로 사용된 데이터셋 또는 사전 학습된 모델을 로깅합니다:

```python theme={null}
dataset = wandb.Artifact(name="flowers", type="dataset")
dataset.add_file("flowers.npy")
run.use_artifact(dataset)
```

이전 코드 스니펫은 "flowers"라는 데이터셋용 artifact를 생성하고 여기에 파일을 추가합니다. 그런 다음 `run.use_artifact()`를 사용해 이 artifact를 현재 run에 연결하며, 이를 통해 W\&B는 run에서 사용된 데이터셋의 리니지를 추적할 수 있습니다.

<div id="download-artifacts">
  ### Artifacts 다운로드
</div>

트레이닝 또는 Inference 코드에서 사용하려면, 이전에 W\&B에 로깅한 Artifacts를 다운로드하세요.

run 컨텍스트가 있으면 [`wandb.Run.use_artifact()`](/ko/models/ref/python/experiments/run)를 사용해 W\&B의 artifact를 참조한 다음, [`wandb.Artifact.download()`](/ko/models/ref/python/experiments/artifact)를 호출해 로컬 디렉터리로 다운로드합니다.

```python theme={null}
with wandb.init(...) as run:
    artifact = run.use_artifact("user/project/artifact:latest")
    local_path = artifact.download()
```

[W\&B Public API](/ko/models/ref/python/public-api/)를 사용하면 run을 초기화하지 않고도 artifact를 참조하고 다운로드할 수 있습니다. 이는 분산 환경이나 Inference 수행처럼 새 run을 만들고 싶지 않은 시나리오에서 유용합니다.

```python theme={null}
import wandb
artifact = wandb.Api().artifact("user/project/artifact:latest")
local_path = artifact.download()
```

자세한 내용은 [Artifacts 다운로드 및 사용하기](/ko/models/artifacts/download-and-use-an-artifact/)를 참조하세요.

<div id="tune-hyper-parameters">
  ## 하이퍼파라미터 조정
</div>

라이브러리가 하이퍼파라미터 튜닝을 지원하는 경우, [W\&B Sweeps](/ko/models/sweeps/)를 통합해 실험을 관리하고 시각화할 수 있습니다.