> ## 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.
# 튜토리얼: SageMaker에서 W&B Launch 설정하기
> ECR, S3, IAM 설정 지침에 따라 Amazon SageMaker에 트레이닝 작업을 제출하도록 W&B Launch를 구성하세요.
이 튜토리얼에서는 ML 엔지니어와 플랫폼 관리자가 Amazon SageMaker에 트레이닝 작업을 제출할 수 있도록 W\&B Launch를 설정하는 방법을 설명합니다. 이 튜토리얼을 마치면 W\&B에서 SageMaker 트레이닝 작업을 실행하는 데 필요한 AWS 리소스, IAM 역할, 큐 설정, Launch 에이전트를 갖추게 됩니다.
W\&B Launch를 사용하면 Amazon SageMaker에 Launch 작업을 제출하여 SageMaker 플랫폼에서 기본 제공 알고리즘 또는 맞춤형 알고리즘으로 머신 러닝 모델을 트레이닝할 수 있습니다. SageMaker는 컴퓨팅 리소스의 프로비저닝과 해제를 처리하므로, EKS 클러스터가 없는 팀에도 적합한 선택이 될 수 있습니다.
Amazon SageMaker에 연결된 W\&B Launch 큐는 [CreateTrainingJob API](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html)를 사용해 Launch 작업을 SageMaker Training Jobs로 실행합니다. Launch 큐 설정을 사용하여 `CreateTrainingJob` API로 전송되는 인수를 제어하세요.
Amazon SageMaker는 [트레이닝 작업을 실행하기 위해 도커 이미지를 사용합니다](https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-training-algo-dockerfile.html). SageMaker가 가져와 사용하는 이미지는 Amazon Elastic Container Registry(ECR)에 저장되어 있어야 합니다. 즉, 트레이닝에 사용할 이미지를 ECR에 저장해야 합니다.
이 가이드에서는 SageMaker Training Jobs를 실행하는 방법을 안내합니다. Amazon SageMaker에서 Inference용 모델을 배포하는 방법에 대한 정보는 [이 예제 Launch 작업](https://github.com/wandb/launch-jobs/tree/main/jobs/deploy_to_sagemaker_endpoints)을 참조하세요.
## 사전 요구 사항
시작하기 전에 다음 사전 요구 사항을 충족해야 합니다:
* [Launch 에이전트가 도커 이미지를 대신 빌드하도록 할지 결정합니다](#decide-if-you-want-the-launch-agent-to-build-a-docker-image).
* [AWS 리소스를 설정하고 S3, ECR, SageMaker IAM 역할에 대한 정보를 수집합니다](#set-up-aws-resources).
* [Launch 에이전트용 IAM 역할을 생성합니다](#create-an-iam-role-for-the-launch-agent).
다음 섹션에서는 각 사전 요구 사항을 완료하는 방법을 설명합니다.
### Launch 에이전트가 도커 이미지를 빌드할지 결정합니다
W\&B Launch 에이전트가 사용자를 대신해 도커 이미지를 빌드하도록 할지 결정합니다. 선택할 수 있는 옵션은 두 가지입니다:
* Launch 에이전트가 도커 이미지를 빌드하고, 이미지를 Amazon ECR에 푸시한 다음, [SageMaker Training](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html) 작업을 제출하도록 허용합니다. 이 옵션은 트레이닝 코드를 빠르게 반복 개선하는 ML 엔지니어에게 더 간편한 방법이 될 수 있습니다.
* 트레이닝 또는 Inference 스크립트가 포함된 기존 도커 이미지를 사용합니다. 이 옵션은 기존 CI 시스템과 잘 맞습니다. 이 옵션을 선택하면 Amazon ECR의 컨테이너 레지스트리에 도커 이미지를 직접 업로드해야 합니다.
### AWS 리소스 설정
선호하는 AWS 리전에 다음 AWS 리소스가 반드시 구성되어 있어야 합니다.
1. 컨테이너 이미지를 저장할 [ECR 저장소](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html)
2. SageMaker 트레이닝 작업의 입력과 출력을 저장할 하나 이상의 [S3 버킷](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)
3. SageMaker가 트레이닝 작업을 실행하고 Amazon ECR 및 Amazon S3와 상호 작용할 수 있도록 허용하는 Amazon SageMaker용 IAM 역할
이 리소스의 ARN을 기록해 두세요. [Launch 큐 설정](#configure-launch-queue-for-sagemaker)을 정의할 때 ARN이 필요합니다.
### Launch 에이전트용 IAM 정책 만들기
Launch 에이전트가 SageMaker 트레이닝 작업을 제출하고, 선택적으로 ECR에 이미지를 푸시하는 데 필요한 권한을 부여하는 IAM 정책이 필요합니다. 정책을 생성하려면 다음 단계를 따르세요.
1. AWS의 IAM 화면에서 새 정책을 만드세요.
2. JSON 정책 편집기로 전환한 다음, 사용 사례에 맞는 다음 정책을 붙여넣으세요. `[BRACKETS]`의 자리 표시자는 사용자의 값으로 바꾸세요.
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:DescribeLogStreams",
"SageMaker:AddTags",
"SageMaker:CreateTrainingJob",
"SageMaker:DescribeTrainingJob"
],
"Resource": "arn:aws:sagemaker:[REGION]:[ACCOUNT-ID]:*"
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::[ACCOUNT-ID]:role/[ROLE-ARN-FROM-QUEUE-CONFIG]"
},
{
"Effect": "Allow",
"Action": "kms:CreateGrant",
"Resource": "[ARN-OF-KMS-KEY]",
"Condition": {
"StringEquals": {
"kms:ViaService": "SageMaker.[REGION].amazonaws.com",
"kms:GrantIsForAWSResource": "true"
}
}
}
]
}
```
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:DescribeLogStreams",
"SageMaker:AddTags",
"SageMaker:CreateTrainingJob",
"SageMaker:DescribeTrainingJob"
],
"Resource": "arn:aws:sagemaker:[REGION]:[ACCOUNT-ID]:*"
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::[ACCOUNT-ID]:role/[ROLE-ARN-FROM-QUEUE-CONFIG]"
},
{
"Effect": "Allow",
"Action": [
"ecr:CreateRepository",
"ecr:UploadLayerPart",
"ecr:PutImage",
"ecr:CompleteLayerUpload",
"ecr:InitiateLayerUpload",
"ecr:DescribeRepositories",
"ecr:DescribeImages",
"ecr:BatchCheckLayerAvailability",
"ecr:BatchDeleteImage"
],
"Resource": "arn:aws:ecr:[REGION]:[ACCOUNT-ID]:repository/[REPOSITORY]"
},
{
"Effect": "Allow",
"Action": "ecr:GetAuthorizationToken",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "kms:CreateGrant",
"Resource": "[ARN-OF-KMS-KEY]",
"Condition": {
"StringEquals": {
"kms:ViaService": "SageMaker.[REGION].amazonaws.com",
"kms:GrantIsForAWSResource": "true"
}
}
}
]
}
```
3. **Next**를 클릭하세요.
4. 정책 이름과 설명을 입력하세요.
5. **Create policy**를 클릭하세요.
이제 다음 섹션에서 Launch 에이전트 역할에 연결할 수 있는 IAM 정책이 준비되었습니다.
### Launch 에이전트용 IAM 역할 생성
Launch 에이전트가 Amazon SageMaker 트레이닝 작업을 생성하려면 권한이 필요합니다. 앞선 섹션에서 생성한 정책을 전용 역할에 연결하면 에이전트가 런타임에 해당 권한을 수임할 수 있습니다. IAM 역할을 생성하려면 아래 절차를 따르세요.
1. AWS의 IAM 화면에서 새 역할을 생성합니다.
2. **Trusted Entity**에서 **AWS Account**를 선택합니다(또는 조직의 정책에 맞는 다른 옵션을 선택합니다).
3. 권한 화면에서 스크롤하여 앞선 섹션에서 생성한 정책 이름을 선택합니다.
4. 역할의 이름과 설명을 입력합니다.
5. **Create role**을 선택합니다.
6. 역할의 ARN을 기록해 둡니다. Launch 에이전트를 설정할 때 이 ARN을 지정합니다.
IAM 역할 생성에 대한 자세한 내용은 [AWS Identity and Access Management Documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)을 참조하세요.
* Launch 에이전트가 이미지를 빌드해야 하는 경우, 추가로 필요한 권한은 [Advanced agent set up](./setup-agent-advanced)을 참조하세요.
* SageMaker 큐의 `kms:CreateGrant` 권한은 연결된 `ResourceConfig`에 `VolumeKmsKeyId`가 지정되어 있고, 연결된 역할에 이 작업을 허용하는 정책이 없는 경우에만 필요합니다.
## SageMaker용 Launch 큐 설정
AWS 사전 요구 사항을 충족했다면 작업을 SageMaker로 라우팅하는 W\&B Launch 큐를 만들 수 있습니다. W\&B App에서 SageMaker를 컴퓨팅 리소스로 사용하는 큐를 생성하세요.
1. [Launch App](https://wandb.ai/launch)으로 이동합니다.
2. **Create Queue**를 클릭합니다.
3. 큐를 생성할 **Entity**를 선택합니다.
4. **Name** 필드에 큐 이름을 입력합니다.
5. **Resource**로 **SageMaker**를 선택합니다.
6. **Configuration** 필드에서 SageMaker 작업에 대한 정보를 입력합니다. 기본적으로 W\&B는 YAML 및 JSON `CreateTrainingJob` 요청 본문을 미리 채웁니다.
```json theme={null}
{
"RoleArn": "[REQUIRED]",
"ResourceConfig": {
"InstanceType": "ml.m4.xlarge",
"InstanceCount": 1,
"VolumeSizeInGB": 2
},
"OutputDataConfig": {
"S3OutputPath": "[REQUIRED]"
},
"StoppingCondition": {
"MaxRuntimeInSeconds": 3600
}
}
```
최소한 다음 항목은 지정해야 합니다.
* `RoleArn`: SageMaker 실행 IAM 역할의 ARN입니다([사전 요구 사항](#prerequisites) 참고). Launch **에이전트** IAM 역할과 혼동하지 마세요.
* `OutputDataConfig.S3OutputPath`: SageMaker가 출력을 저장할 위치를 지정하는 Amazon S3 URI입니다.
* `ResourceConfig`: 필수 리소스 설정 사양입니다. 리소스 설정 옵션은 [AWS `ResourceConfig` documentation](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ResourceConfig.html)을 참조하세요.
* `StoppingCondition`: 트레이닝 작업의 중지 조건에 대한 필수 사양입니다. 옵션은 [AWS `StoppingCondition` documentation](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StoppingCondition.html)을 참조하세요.
7. **Create Queue**를 클릭합니다.
큐를 폴링하도록 Launch 에이전트를 설정하면 큐가 생성되고 작업을 받을 준비가 완료됩니다.
## Launch 에이전트 설정
다음 섹션에서는 에이전트를 배포할 수 있는 위치와, 에이전트를 배포하는 위치에 따라 에이전트를 설정하는 방법을 설명합니다.
Amazon SageMaker [큐](#decide-where-to-run-the-launch-agent)용 Launch 에이전트는 로컬 머신, EC2 인스턴스 또는 EKS 클러스터에 배포할 수 있습니다. 에이전트를 배포하는 위치에 따라 [Launch 에이전트를 설정하세요](#configure-a-launch-agent).
### Launch 에이전트를 어디에서 실행할지 결정하세요
프로덕션 워크로드이면서 이미 EKS 클러스터를 보유한 고객의 경우, W\&B는 이 Helm chart를 사용해 EKS 클러스터에 Launch 에이전트를 배포할 것을 권장합니다.
현재 EKS 클러스터가 없는 프로덕션 워크로드의 경우에는 EC2 인스턴스가 좋은 선택입니다. Launch 에이전트 인스턴스는 항상 실행 상태를 유지하지만, 에이전트에는 `t2.micro` 크기의 EC2 인스턴스면 충분하므로 비용 부담이 크지 않습니다.
실험용 또는 개인 사용 사례에서는 빠르게 시작하는 방법으로 로컬 머신에서 Launch 에이전트를 실행할 수 있습니다.
사용 사례에 따라 다음 탭의 안내를 따라 Launch 에이전트를 설정하세요:
W\&B는 [W\&B managed Helm chart](https://github.com/wandb/helm-charts/tree/main/charts/launch-agent)를 사용해 EKS 클러스터에 에이전트를 설치할 것을 권장합니다.
Amazon EC2 Dashboard로 이동한 후 다음 단계를 완료하세요:
1. **Launch instance**를 클릭합니다.
2. **Name** 필드에 이름을 입력합니다. 필요하면 태그를 추가합니다.
3. **Instance type**에서 EC2 컨테이너용 인스턴스 유형을 선택합니다. 1 vCPU와 1 GiB 메모리면 충분합니다(예: `t2.micro`).
4. **Key pair (login)** 필드에서 조직용 키 페어를 생성합니다. 이 키 페어는 이후 단계에서 SSH client를 사용해 [EC2 인스턴스에 연결](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect.html)할 때 사용합니다.
5. **Network settings**에서 조직의 보안 그룹을 선택합니다.
6. **Advanced details**를 펼칩니다. **IAM instance profile**에서 이전 섹션에서 생성한 Launch 에이전트 IAM 역할을 선택합니다.
7. **Summary** 필드를 검토합니다. 내용이 올바르면 **Launch instance**를 선택합니다.
AWS의 EC2 Dashboard 왼쪽 패널에서 **Instances**로 이동합니다. 생성한 EC2 인스턴스가 실행 중인지 확인합니다(**Instance state** 열 참조). EC2 인스턴스가 실행 중임을 확인한 후, 로컬 머신의 터미널에서 다음 작업을 수행하세요:
1. **Connect**를 선택합니다.
2. **SSH client** 탭을 선택하고 안내에 따라 EC2 인스턴스에 연결합니다.
3. EC2 인스턴스에서 다음 패키지를 설치합니다:
```bash theme={null}
sudo yum install python311 -y && python3 -m ensurepip --upgrade && pip3 install wandb && pip3 install wandb[launch]
```
4. 다음으로, EC2 인스턴스에서 Docker를 설치하고 시작합니다:
```bash theme={null}
sudo yum update -y && \
sudo yum install -y docker python3 && \
sudo systemctl start docker && \
sudo systemctl enable docker && \
sudo usermod -a -G docker ec2-user
newgrp docker
```
이제 Launch 에이전트 설정을 구성할 수 있습니다.
로컬 머신에서 폴링하는 에이전트에 역할을 연결하려면 `~/.aws/config` 및 `~/.aws/credentials`에 있는 AWS 설정 파일을 사용합니다. 이전 단계에서 Launch 에이전트용으로 생성한 IAM 역할 ARN을 입력하세요.
```yaml title="~/.aws/config" theme={null}
[profile SageMaker-agent]
role_arn = arn:aws:iam::[ACCOUNT-ID]:role/[AGENT-ROLE-NAME]
source_profile = default
```
```yaml title="~/.aws/credentials" theme={null}
[default]
aws_access_key_id=[ACCESS-KEY-ID]
aws_secret_access_key=[SECRET-ACCESS-KEY]
aws_session_token=[SESSION-TOKEN]
```
세션 토큰의 [최대 길이](https://docs.aws.amazon.com/cli/latest/reference/sts/get-session-token.html#description)는 연결된 주체에 따라 1시간 또는 3일입니다.
### Launch 에이전트 설정
에이전트를 어디에서 실행할지 결정한 후에는 SageMaker 큐를 폴링하고 AWS에 인증할 수 있도록 에이전트를 설정합니다. `launch-config.yaml`이라는 이름의 YAML 설정 파일로 Launch 에이전트를 설정합니다.
기본적으로 W\&B는 `~/.config/wandb/launch-config.yaml`에서 설정 파일을 찾습니다. `-c` 플래그를 사용해 Launch 에이전트를 활성화할 때 다른 디렉터리를 선택적으로 지정할 수 있습니다.
다음 YAML 스니펫은 핵심 에이전트 설정 옵션을 지정하는 방법을 보여줍니다:
```yaml title="launch-config.yaml" theme={null}
max_jobs: -1
queues:
- [QUEUE-NAME]
environment:
type: aws
region: [YOUR-REGION]
registry:
type: ecr
uri: [ECR-REPO-ARN]
builder:
type: docker
```
이제 `wandb launch-agent`로 에이전트를 시작하세요.
이제 Launch 에이전트가 실행 중이며 SageMaker 큐를 폴링하여 작업을 확인합니다.
## 선택 사항: Launch 작업 도커 이미지를 Amazon ECR에 푸시
이 섹션은 Launch 에이전트가 트레이닝 또는 Inference 로직이 포함된 기존 도커 이미지를 사용하는 경우에만 적용됩니다. [Launch 에이전트는 두 가지 동작 옵션을 지원합니다.](#decide-if-you-want-the-launch-agent-to-build-a-docker-image)
Launch 작업이 포함된 도커 이미지를 Amazon ECR 리포지토리에 업로드하세요. 이미지 기반 작업을 사용하는 경우, 새 Launch 작업을 제출하기 전에 해당 도커 이미지가 ECR 레지스트리에 있어야 합니다.
{/* ## W&B에서 Launch 작업 실행하기
W&B GUI로 이동하면 이제 SageMaker Launch 큐가 활성화되어 있습니다. UI 또는 CLI에서 여기에 작업을 보낼 수 있습니다. */}