> ## 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.

> Metaflow와 W&B를 통합해 실험을 추적하고, 메트릭과 artifact를 자동으로 로깅하여 ML 워크플로를 관리합니다.

# Metaflow

<div id="overview">
  ## Overview
</div>

[Metaflow](https://docs.metaflow.org)는 Netflix에서 만든 ML 워크플로 생성 및 실행용 프레임워크입니다.

이 인테그레이션을 사용하면 Metaflow의 [step 및 플로우](https://docs.metaflow.org/metaflow/basics)에 데코레이터를 적용해 파라미터와 artifact를 W\&B에 자동으로 로깅할 수 있습니다.

* step에 데코레이터를 적용하면 해당 step 내 특정 유형에 대한 로깅을 켜거나 끌 수 있습니다.
* 플로우에 데코레이터를 적용하면 플로우의 모든 step에 대한 로깅을 켜거나 끌 수 있습니다.

<div id="quickstart">
  ## 퀵스타트
</div>

<div id="sign-up-and-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-the-wandb-library-and-log-in">
  ### `wandb` 라이브러리 설치 및 로그인
</div>

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

<Note>
  `wandb` 버전 0.19.8 이하에서는 `plum-dispatch` 대신 `fastcore` 버전 1.8.0 이하(`fastcore<1.8.0`)를 설치하세요.
</Note>

<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` 라이브러리를 설치하고 로그인합니다.

       ```shell theme={null}
       pip install -Uqqq metaflow "plum-dispatch<3.0.0" wandb

       wandb login
       ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install -Uqqq metaflow "plum-dispatch<3.0.0" wandb
    ```

    ```python theme={null}
    import wandb
    wandb.login()
    ```
  </Tab>

  <Tab title="Python notebook">
    ```notebook theme={null}
    !pip install -Uqqq metaflow "plum-dispatch<3.0.0" wandb

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

<div id="decorate-your-flows-and-steps">
  ### 플로우와 step에 데코레이터 적용하기
</div>

<Tabs>
  <Tab title="Step">
    step에 데코레이터를 적용하면 해당 step 내 특정 유형에 대한 로깅을 켜거나 끌 수 있습니다.

    이 예제에서는 `start`의 모든 데이터셋과 모델이 로깅됩니다.

    ```python theme={null}
    from wandb.integration.metaflow import wandb_log

    class WandbExampleFlow(FlowSpec):
        @wandb_log(datasets=True, models=True, settings=wandb.Settings(...))
        @step
        def start(self):
            self.raw_df = pd.read_csv(...).    # pd.DataFrame -> 데이터셋으로 업로드
            self.model_file = torch.load(...)  # nn.Module    -> 모델로 업로드
            self.next(self.transform)
    ```
  </Tab>

  <Tab title="Flow">
    플로우에 데코레이터를 적용하는 것은 플로우를 구성하는 모든 step에 기본값으로 데코레이터를 적용하는 것과 같습니다.

    이 경우 `WandbExampleFlow`의 모든 step은 기본적으로 데이터셋과 모델을 로깅하며, 이는 각 step에 `@wandb_log(datasets=True, models=True)`를 적용하는 것과 같습니다.

    ```python theme={null}
    from wandb.integration.metaflow import wandb_log

    @wandb_log(datasets=True, models=True)  # 모든 @step에 데코레이터 적용
    class WandbExampleFlow(FlowSpec):
        @step
        def start(self):
            self.raw_df = pd.read_csv(...).    # pd.DataFrame -> 데이터셋으로 업로드
            self.model_file = torch.load(...)  # nn.Module    -> 모델로 업로드
            self.next(self.transform)
    ```
  </Tab>

  <Tab title="Flow and Steps">
    플로우에 데코레이터를 적용하는 것은 모든 step에 기본값으로 데코레이터를 적용하는 것과 같습니다. 즉, 나중에 step에 다른 `@wandb_log`를 적용하면 플로우 수준 데코레이션을 재정의합니다.

    이 예제에서는 다음과 같습니다:

    * `start`와 `mid`는 데이터셋과 모델을 모두 로깅합니다.
    * `end`는 데이터셋과 모델을 모두 로깅하지 않습니다.

    ```python theme={null}
    from wandb.integration.metaflow import wandb_log

    @wandb_log(datasets=True, models=True)  # start와 mid에 데코레이터를 적용하는 것과 동일
    class WandbExampleFlow(FlowSpec):
      # 이 step은 데이터셋과 모델을 로깅합니다
      @step
      def start(self):
        self.raw_df = pd.read_csv(...).    # pd.DataFrame -> 데이터셋으로 업로드
        self.model_file = torch.load(...)  # nn.Module    -> 모델로 업로드
        self.next(self.mid)

      # 이 step도 데이터셋과 모델을 로깅합니다
      @step
      def mid(self):
        self.raw_df = pd.read_csv(...).    # pd.DataFrame -> 데이터셋으로 업로드
        self.model_file = torch.load(...)  # nn.Module    -> 모델로 업로드
        self.next(self.end)

      # 이 step은 재정의되어 데이터셋이나 모델을 로깅하지 않습니다
      @wandb_log(datasets=False, models=False)
      @step
      def end(self):
        self.raw_df = pd.read_csv(...).    
        self.model_file = torch.load(...)
    ```
  </Tab>
</Tabs>

<div id="access-your-data-programmatically">
  ## 프로그래밍 방식으로 데이터에 접근하기
</div>

캡처된 정보에는 세 가지 방법으로 접근할 수 있습니다. 로깅 중인 원래 Python 프로세스 내부에서 [`wandb` client library](/ko/models/ref/python/)를 사용하거나, [web app UI](/ko/models/track/workspaces/)를 사용하거나, [Public API](/ko/models/ref/python/public-api/)를 사용해 프로그래밍 방식으로 접근할 수 있습니다. `Parameter`는 W\&B의 [`config`](/ko/models/)에 저장되며 [Overview tab](/ko/models/runs/#overview-tab)에서 확인할 수 있습니다. `datasets`, `models`, `others`는 [W\&B Artifacts](/ko/models/artifacts/)에 저장되며 [Artifacts tab](/ko/models/runs/#artifacts-tab)에서 확인할 수 있습니다. 기본 Python 유형은 W\&B의 [`summary`](/ko/models/) dict에 저장되며 Overview tab에서 확인할 수 있습니다. 외부에서 API를 사용해 이 정보를 프로그래밍 방식으로 조회하는 방법에 대한 자세한 내용은 [Public API 가이드](/ko/models/track/public-api-guide/)를 참조하세요.

<div id="quick-reference">
  ### 빠른 레퍼런스
</div>

| 데이터                                    | 클라이언트 라이브러리                                   | UI                    |
| -------------------------------------- | --------------------------------------------- | --------------------- |
| `Parameter(...)`                       | `wandb.Run.config`                            | Overview tab, 설정      |
| `datasets`, `models`, `others`         | `wandb.Run.use_artifact("{var_name}:latest")` | Artifacts tab         |
| 기본 Python 유형 (`dict`, `list`, `str` 등) | `wandb.Run.summary`                           | Overview tab, Summary |

<div id="wandb_log-kwargs">
  ### `wandb_log` kwargs
</div>

| kwarg      | Options                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `datasets` | <ul><li><code>True</code>: 데이터셋인 인스턴스 변수를 기록합니다</li><li><code>False</code></li></ul>                                                                                                                                                                                                                                                                                                                                                  |
| `models`   | <ul><li><code>True</code>: 모델인 인스턴스 변수를 기록합니다</li><li><code>False</code></li></ul>                                                                                                                                                                                                                                                                                                                                                    |
| `others`   | <ul><li><code>True</code>: pickle로 직렬화할 수 있는 기타 모든 항목을 기록합니다</li><li><code>False</code></li></ul>                                                                                                                                                                                                                                                                                                                                     |
| `settings` | <ul><li><code>wandb.Settings(...)</code>: 이 step 또는 flow에 사용할 <code>wandb</code> 설정을 직접 지정합니다</li><li><code>None</code>: <code>wandb.Settings()</code>를 전달하는 것과 같습니다</li></ul><p>기본적으로:</p><ul><li><code>settings.run\_group</code>가 <code>None</code>이면 <code>\{flow\_name}/\{run\_id}</code>로 설정됩니다</li><li><code>settings.run\_job\_type</code>가 <code>None</code>이면 <code>\{run\_job\_type}/\{step\_name}</code>로 설정됩니다</li></ul> |

<div id="frequently-asked-questions">
  ## 자주 묻는 질문
</div>

<div id="what-exactly-do-you-log-do-you-log-all-instance-and-local-variables">
  ### 정확히 무엇을 로깅하나요? 모든 인스턴스 변수와 로컬 변수를 로깅하나요?
</div>

`wandb_log`는 인스턴스 변수만 로깅합니다. 로컬 변수는 절대 로깅되지 않습니다. 따라서 불필요한 데이터가 로깅되는 것을 방지할 수 있습니다.

<div id="which-data-types-get-logged">
  ### 어떤 데이터 유형이 로깅되나요?
</div>

현재는 다음 유형을 지원합니다:

| 로깅 설정      | 유형                                                                                                               |
| ---------- | ---------------------------------------------------------------------------------------------------------------- |
| 기본값(항상 켜짐) | <ul><li><code>dict, list, set, str, int, float, bool</code></li></ul>                                            |
| `datasets` | <ul><li><code>pd.DataFrame</code></li><li><code>pathlib.Path</code></li></ul>                                    |
| `models`   | <ul><li><code>nn.Module</code></li><li><code>sklearn.base.BaseEstimator</code></li></ul>                         |
| `others`   | <ul><li><a href="https://wiki.python.org/moin/UsingPickle">pickle로 직렬화 가능</a>하고 JSON으로 직렬화할 수 있는 모든 항목</li></ul> |

<div id="how-can-i-configure-logging-behavior">
  ### 로깅 동작은 어떻게 설정하나요?
</div>

| 변수 종류 | 동작                           | 예시              | 데이터 유형         |
| ----- | ---------------------------- | --------------- | -------------- |
| 인스턴스  | 자동으로 로깅됨                     | `self.accuracy` | `float`        |
| 인스턴스  | `datasets=True`인 경우 로깅됨      | `self.df`       | `pd.DataFrame` |
| 인스턴스  | `datasets=False`인 경우 로깅되지 않음 | `self.df`       | `pd.DataFrame` |
| 로컬    | 로깅되지 않음                      | `accuracy`      | `float`        |
| 로컬    | 로깅되지 않음                      | `df`            | `pd.DataFrame` |

<div id="is-artifact-lineage-tracked">
  ### artifact 리니지가 추적되나요?
</div>

예. step A의 출력이면서 동시에 step B의 입력인 artifact가 있으면, 리니지 DAG를 자동으로 생성합니다.

이 동작의 예시는 다음 [notebook](https://colab.research.google.com/drive/1wZG-jYzPelk8Rs2gIM3a71uEoG46u_nG#scrollTo=DQQVaKS0TmDU) 및 해당 [W\&B Artifacts 페이지](https://wandb.ai/megatruong/metaflow_integration/artifacts/dataset/raw_df/7d14e6578d3f1cfc72fe/graph)를 참조하세요.