> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-weave-byob-note.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 튜토리얼: Vertex AI에서 W&B Launch 설정

> CustomJob 사양과 Artifact Registry를 사용하여 Google Cloud Vertex AI에서 ML 워크로드용 W&B Launch를 설정합니다.

이 튜토리얼에서는 W\&B Launch를 구성해 작업을 Vertex AI 트레이닝 작업으로 제출하고 실행하는 방법을 안내합니다. 이를 통해 트레이닝 워크로드를 Google Cloud의 관리형 인프라로 오프로드할 수 있습니다. Vertex AI 트레이닝 작업을 사용하면 Vertex AI 플랫폼에서 제공된 알고리즘 또는 맞춤형 알고리즘으로 머신 러닝 모델을 트레이닝할 수 있습니다. launch 작업을 시작하면 Vertex AI가 기본 인프라, 확장, 오케스트레이션을 관리합니다. 이 가이드는 이미 W\&B Launch를 사용하고 있으며 Google Cloud Vertex AI에서 작업을 실행하려는 ML 엔지니어와 플랫폼 관리자를 위한 것입니다.

W\&B Launch는 `google-cloud-aiplatform` SDK의 `CustomJob` 클래스를 통해 Vertex AI와 연동됩니다. launch 큐 설정을 사용해 `CustomJob`의 매개변수를 제어할 수 있습니다. Vertex AI가 Google Cloud 외부의 비공개 레지스트리에서 이미지를 가져오도록 설정할 수는 없습니다. 즉, Vertex AI를 W\&B Launch와 함께 사용하려면 container image를 Google Cloud 또는 공개 레지스트리에 저장해야 합니다. Vertex 작업이 container image에 액세스할 수 있도록 설정하는 방법에 대한 자세한 내용은 Vertex AI 문서를 참조하세요.

<div id="prerequisites">
  ## 사전 요구 사항
</div>

Launch 큐를 설정하기 전에 다음 Google Cloud 리소스와 권한이 준비되어 있는지 확인하세요.

1. **Vertex AI API가 사용 설정된 Google Cloud 프로젝트를 생성하거나 액세스합니다.** API 사용 설정에 대한 자세한 내용은 [Google Cloud API Console docs](https://support.google.com/googleapi/answer/6158841?hl=en)를 참고하세요.
2. **Vertex에서 실행할 이미지를 저장할 Google Cloud Artifact Registry 저장소를 생성합니다.** 자세한 내용은 [Google Cloud Artifact Registry documentation](https://cloud.google.com/artifact-registry/docs/overview)을 참고하세요.
3. **Vertex AI가 메타데이터를 저장할 스테이징 GCS 버킷을 생성합니다.** 이 버킷은 스테이징 버킷으로 사용되므로 Vertex AI 워크로드와 동일한 리전에 있어야 합니다. 스테이징과 build 컨텍스트에 동일한 버킷을 사용할 수 있습니다.
4. **서비스 계정을 생성합니다.** 이 서비스 계정에는 Vertex AI 작업을 시작하는 데 필요한 권한이 있어야 합니다. 서비스 계정에 권한을 부여하는 방법에 대한 자세한 내용은 [Google Cloud IAM documentation](https://cloud.google.com/iam/docs/creating-managing-service-accounts)을 참고하세요.
5. **다음 표와 같이 서비스 계정에 Vertex 작업을 관리할 권한을 부여합니다.**

| Permission                     | Resource Scope                 | Description                        |
| ------------------------------ | ------------------------------ | ---------------------------------- |
| `aiplatform.customJobs.create` | Specified Google Cloud Project | 프로젝트 내에서 새 머신러닝 작업을 생성할 수 있습니다.    |
| `aiplatform.customJobs.list`   | Specified Google Cloud Project | 프로젝트 내의 머신러닝 작업 목록을 조회할 수 있습니다.    |
| `aiplatform.customJobs.get`    | Specified Google Cloud Project | 프로젝트 내의 특정 머신러닝 작업 정보를 조회할 수 있습니다. |

<Note>
  Vertex AI 워크로드가 기본이 아닌 서비스 계정의 ID를 사용하도록 하려면, 서비스 계정 생성 방법과 필요한 권한에 대한 안내는 Vertex AI 문서를 참고하세요. W\&B run에 맞춤형 서비스 계정을 선택하려면 Launch 큐 설정의 `spec.service_account` 필드를 사용하세요.
</Note>

<div id="configure-a-queue-for-vertex-ai">
  ## Vertex AI용 큐 설정
</div>

Google Cloud 사전 요구 사항을 갖추었다면, 다음 단계는 W\&B Launch가 Vertex AI 작업을 제출할 때 사용할 큐 설정을 계획하는 것입니다. Vertex AI 리소스용 큐 설정은 Vertex AI Python SDK의 `CustomJob` 생성자와 `CustomJob`의 `run` 메서드에 전달할 입력값을 지정합니다. 리소스 설정은 `spec` 및 `run` 키 아래에 저장됩니다.

* `spec` 키에는 Vertex AI Python SDK의 [`CustomJob` 생성자](https://cloud.google.com/vertex-ai/docs/pipelines/customjob-component)에 전달하는 키워드 인자 값이 들어 있습니다.
* `run` 키에는 Vertex AI Python SDK의 `CustomJob` 클래스에 있는 `run` 메서드에 전달하는 키워드 인자 값이 들어 있습니다.

실행 환경 사용자 지정은 `spec.worker_pool_specs` 목록에서 이루어집니다. worker pool spec은 작업을 실행할 워커 그룹을 정의합니다. 기본 설정의 worker spec은 가속기 없이 `n1-standard-4` 머신 1대를 요청합니다. 필요에 맞게 머신 유형, 가속기 유형, 개수를 변경할 수 있습니다.

사용 가능한 머신 유형과 가속기 유형에 대한 자세한 내용은 [Vertex AI documentation](https://cloud.google.com/vertex-ai/docs/reference/rest/v1/MachineSpec)을 참조하세요.

<div id="create-a-queue">
  ## 큐 만들기
</div>

이제 큐 설정을 계획했으므로, Vertex AI를 컴퓨팅 리소스로 사용하는 큐를 W\&B App에서 만드세요.

1. [Launch 페이지](https://wandb.ai/launch)로 이동합니다.

2. **Create Queue** 버튼을 클릭합니다.

3. 큐를 생성할 **Entity**를 선택합니다.

4. **Name** 필드에 큐 이름을 입력합니다.

5. **Resource**로 **Google Cloud Vertex AI**를 선택합니다.

6. **Configuration** 필드에 [Configure a queue for Vertex AI](#configure-a-queue-for-vertex-ai)에서 정의한 Vertex AI `CustomJob` 정보를 입력합니다. 기본적으로 W\&B는 다음과 유사한 YAML 및 JSON 요청 본문을 자동으로 채웁니다.

   ```yaml theme={null}
   spec:
     worker_pool_specs:
       - machine_spec:
           machine_type: n1-standard-4
           accelerator_type: ACCELERATOR_TYPE_UNSPECIFIED
           accelerator_count: 0
         replica_count: 1
         container_spec:
           image_uri: ${image_uri}
     staging_bucket: [STAGING-BUCKET]
   run:
     restart_job_on_worker_restart: false
   ```

7. 큐 설정을 마친 후 **Create Queue** 버튼을 클릭합니다.

최소한 다음 필드는 지정해야 합니다.

* `spec.worker_pool_specs`: 비어 있지 않은 워커 풀 사양 목록
* `spec.staging_bucket`: Vertex AI 애셋과 메타데이터를 스테이징하기 위한 GCS 버킷

<Warning>
  일부 Vertex AI 문서에서는 워커 풀 사양의 모든 키를 카멜 케이스로 표시합니다. 예를 들어 `workerPoolSpecs`가 있습니다. Vertex AI Python SDK는 이러한 키에 스네이크 케이스를 사용합니다. 예를 들어 `worker_pool_specs`가 있습니다.

  Launch 큐 설정의 모든 키는 스네이크 케이스를 사용해야 합니다.
</Warning>

<div id="configure-a-launch-agent">
  ## Launch 에이전트 구성하기
</div>

큐를 만들었으면 Launch 에이전트가 큐를 폴링하여 작업을 Vertex AI로 전달하도록 구성하세요. Launch 에이전트는 설정 파일로 구성할 수 있으며, 기본 설정 파일 경로는 `~/.config/wandb/launch-config.yaml`입니다.

```yaml theme={null}
max_jobs: [N-CONCURRENT-JOBS]
queues:
  - [QUEUE-NAME]
```

Vertex AI에서 실행할 이미지를 Launch 에이전트가 빌드하도록 하려면 [고급 에이전트 설정](./setup-agent-advanced)을 참조하세요.

<div id="set-up-agent-permissions">
  ## 에이전트 권한 설정
</div>

마지막으로, Launch 에이전트가 사전 요구 사항에서 만든 서비스 계정으로 작동하는 데 필요한 사용자 인증 정보를 제공하세요. 이 서비스 계정으로 인증하는 방법은 여러 가지가 있습니다. Workload Identity, 다운로드한 서비스 계정 JSON, 환경 변수, Google Cloud Platform 명령줄 도구 또는 이 방법들을 조합해 인증할 수 있습니다.