Amazon SageMaker HyperPod 핵심 명령 가이드

Amazon SageMaker HyperPod는 훈련 워크플로를 관리하기 위한 광범위한 명령줄 기능을 제공합니다. 이 가이드에서는 클러스터 연결부터 작업 진행 상황 모니터링에 이르기까지 일반적인 작업에 필요한 명령을 다룹니다.

사전 조건

이러한 명령을 사용하기 전에 다음 설정을 완료했는지 확인합니다.

레시피 CLI 설치

설치 명령을 실행하기 전에 레시피 리포지토리의 루트로 이동합니다.

비Forge 사용자 지정 기법을 사용하는 경우 Hyperpodrecipes 리포지토리를 사용합니다. Forge 기반 사용자 지정의 경우 Forge 특정 레시피 리포지토리를 참조하세요.

다음 명령을 실행하여 SageMaker HyperPod CLI를 설치합니다.

비Forge 사용자 지정 기법을 사용하는 경우 아래와 같이 sagemaker-hyperpod-recipes를 다운로드합니다.

git clone -b release_v2 https://github.com/aws/sagemaker-hyperpod-cli.git
cd sagemaker-hyperpod-cli
pip install -e .
cd ..
root_dir=$(pwd)
export PYTHONPATH=${root_dir}/sagemaker-hyperpod-cli/src/hyperpod_cli/sagemaker_hyperpod_recipes/launcher/nemo/nemo_framework_launcher/launcher_scripts:$PYTHONPATH
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh
rm -f ./get_helm.sh

Forge 구독자인 경우 아래 언급된 프로세스를 사용하여 레시피를 다운로드해야 합니다.

mkdir NovaForgeHyperpodCLI
cd NovaForgeHyperpodCLI
aws s3 cp s3://nova-forge-c7363-206080352451-us-east-1/v1/ ./ --recursive
pip install -e .

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh
rm -f ./get_helm.sh

목적: pip install -e .를 수행하는 이유는 무엇인가요?

이 명령은 SageMaker HyperPod CLI를 편집 가능한 모드로 설치하므로 매번 다시 설치하지 않고도 업데이트된 레시피를 사용할 수 있습니다. 또한 CLI가 자동으로 선택할 수 있는 새 레시피를 추가할 수 있습니다.

클러스터에 연결

작업을 실행하기 전에 SageMaker HyperPod CLI를 클러스터에 연결합니다.

export AWS_REGION=us-east-1 &&  SageMaker HyperPod  connect-cluster --cluster-name <your-cluster-name> --region us-east-1

전문가 팁: 다음과 같이 명령에 --namespace kubeflow 인수를 추가하여 항상 kubeflow 네임스페이스를 사용하도록 클러스터를 추가로 구성할 수 있습니다.

export AWS_REGION=us-east-1 && \
hyperpod connect-cluster \
--cluster-name <your-cluster-name> \
--region us-east-1 \
--namespace kubeflow

그러면 작업과 상호 작용할 때 모든 명령에 -n kubeflow를 추가하지 않아도 됩니다.

훈련 작업 시작

label_selector:
  required:
    sagemaker.amazonaws.com/instance-group-name:
      - <rig_group>

선택적 파라미터 재정의가 있는 레시피를 사용하여 훈련 작업을 시작합니다.

hyperpod start-job -n kubeflow \
--recipe fine-tuning/nova/nova_1_0/nova_micro/SFT/nova_micro_1_0_p5_p4d_gpu_lora_sft \
--override-parameters '{
"instance_type": "ml.p5.48xlarge",
    "container": "708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-fine-tune-repo:SM-HP-SFT-latest"
  }'

예상 결과:

Final command: python3 <path_to_your_installation>/NovaForgeHyperpodCLI/src/hyperpod_cli/sagemaker_hyperpod_recipes/main.py recipes=fine-tuning/nova/nova_micro_p5_gpu_sft cluster_type=k8s cluster=k8s base_results_dir=/local/home/<username>/results cluster.pullPolicy="IfNotPresent" cluster.restartPolicy="OnFailure" cluster.namespace="kubeflow" container="708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-fine-tune-repo:HP-SFT-DATAMIX-latest"

Prepared output directory at /local/home/<username>/results/<job-name>/k8s_templates
Found credentials in shared credentials file: ~/.aws/credentials
Helm script created at /local/home/<username>/results/<job-name>/<job-name>_launch.sh
Running Helm script: /local/home/<username>/results/<job-name>/<job-name>_launch.sh

NAME: <job-name>
LAST DEPLOYED: Mon Sep 15 20:56:50 2025
NAMESPACE: kubeflow
STATUS: deployed
REVISION: 1
TEST SUITE: None
Launcher successfully generated: <path_to_your_installation>/NovaForgeHyperpodCLI/src/hyperpod_cli/sagemaker_hyperpod_recipes/launcher/nova/k8s_templates/SFT

{
 "Console URL": "https://us-east-1.console.aws.amazon.com/sagemaker/home?region=us-east-1#/cluster-management/<your-cluster-name>"
}

작업 상태 추적

kubectl을 사용하여 실행 중인 작업을 모니터링합니다.

kubectl get pods -o wide -w -n kubeflow | (head -n1 ; grep <your-job-name>)

포드 상태 이해

다음 표에서는 다음과 같은 일반적인 포드 상태를 설명합니다.

작업 로그 모니터링

다음과 같은 세 가지 방법 중 하나로 로그를 볼 수 있습니다.

CloudWatch 사용

로그는 CloudWatch 아래 Hyperpodcluster가 포함된 AWS 계정에서 사용할 수 있습니다. 브라우저에서 보려면 계정의 CloudWatch 홈페이지로 이동하여 클러스터 이름을 검색합니다. 예를 들어 my-hyperpod-rig라는 클러스터가 있으면 로그 그룹에 다음과 같은 접두사가 붙습니다.

CloudWatch Insights 사용

작업 이름이 유용하고 위의 모든 단계를 진행하지 않으려는 경우 /aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}에서 모든 로그를 쿼리하여 개별 로그를 찾을 수 있습니다.

CPT:

fields @timestamp, @message, @logStream, @log
| filter @message like /(?i)Starting CPT Job/
| sort @timestamp desc
| limit 100

작업 완료 시 Starting CPT Job을 CPT Job completed로 바꾸기

그런 다음 결과를 클릭하고 'Epoch 0'이라고 표시된 결과를 선택할 수 있습니다. 마스터 노드가 되기 때문입니다.

AWSAWS CLI 사용

AWS CLI를 사용하여 로그를 테일링하도록 선택할 수 있습니다. 이렇게 하기 전에 aws --version을 사용하여 aws cli 버전을 확인하세요. 또한 터미널에서 라이브 로그를 추적하는 데 도움이 되는 이 유틸리티 스크립트를 사용하는 것이 좋습니다.

V1의 경우:

aws logs get-log-events \
--log-group-name /aws/sagemaker/YourLogGroupName \
--log-stream-name YourLogStream \
--start-from-head | jq -r '.events[].message'

V2의 경우:

aws logs tail /aws/sagemaker/YourLogGroupName \
 --log-stream-name YourLogStream \
--since 10m \
--follow

활성 작업 나열

클러스터에서 실행 중인 모든 작업을 봅니다.

hyperpod list-jobs -n kubeflow

출력 예제:

{
  "jobs": [
    {
      "Name": "test-run-nhgza",
      "Namespace": "kubeflow",
      "CreationTime": "2025-10-29T16:50:57Z",
      "State": "Running"
    }
  ]
}

작업 취소

언제든지 실행 중인 작업을 중지합니다.

hyperpod cancel-job --job-name <job-name> -n kubeflow

작업 이름 찾기

옵션 1: 사용자 레시피에서

작업 이름은 레시피의 run 블록에 지정됩니다.

run:
  name: "my-test-run"                        # This is your job name
  model_type: "amazon.nova-micro-v1:0:128k"
  ...

옵션 2: list-jobs 명령에서

hyperpod list-jobs -n kubeflow를 사용하고 출력에서 Name 필드를 복사합니다.

평가 작업 실행

평가 레시피를 사용하여 훈련된 모델 또는 기본 모델을 평가합니다.

사전 조건

평가 작업을 실행하기 전에 다음이 있는지 확인합니다.

Command

다음 명령을 실행하여 평가 작업을 시작합니다.

hyperpod start-job -n kubeflow \
  --recipe evaluation/nova/nova_2_0/nova_lite/nova_lite_2_0_p5_48xl_gpu_bring_your_own_dataset_eval \
  --override-parameters '{
    "instance_type": "p5.48xlarge",
    "container": "708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-evaluation-repo:SM-HP-Eval-latest",
    "recipes.run.name": "<your-eval-job-name>",
    "recipes.run.model_name_or_path": "<checkpoint-s3-uri>",
    "recipes.run.output_s3_path": "s3://<your-bucket>/eval-results/",
    "recipes.run.data_s3_path": "s3://<your-bucket>/eval-data.jsonl"
  }'

파라미터 설명:

팁:

평가 데이터 형식

입력 형식(JSONL):

{
  "metadata": "{key:4, category:'apple'}",
  "system": "arithmetic-patterns, please answer the following with no other words: ",
  "query": "What is the next number in this series? 1, 2, 4, 8, 16, ?",
  "response": "32"
}

출력 형식:

{
  "prompt": "[{'role': 'system', 'content': 'arithmetic-patterns, please answer the following with no other words: '}, {'role': 'user', 'content': 'What is the next number in this series? 1, 2, 4, 8, 16, ?'}]",
  "inference": "['32']",
  "gold": "32",
  "metadata": "{key:4, category:'apple'}"
}

필드 설명:

일반적인 문제