# Amazon SageMaker HyperPod 핵심 명령 가이드
<a name="nova-hp-essential-commands-guide"></a>

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

**사전 조건**  
이러한 명령을 사용하기 전에 다음 설정을 완료했는지 확인합니다.
+ RIG가 생성된 SageMaker HyperPod 클러스터(일반적으로 us-east-1)
+ 훈련 아티팩트용으로 생성된 출력 Amazon S3 버킷
+ 적절한 권한으로 구성된 IAM 역할
+ 올바른 JSONL 형식으로 업로드된 훈련 데이터
+ FSx for Lustre 동기화 완료(첫 번째 작업의 클러스터 로그에서 확인)

**Topics**
+ [레시피 CLI 설치](#nova-hp-essential-commands-guide-install)
+ [클러스터에 연결](#nova-hp-essential-commands-guide-connect)
+ [훈련 작업 시작](#nova-hp-essential-commands-guide-start-job)
+ [작업 상태 추적](#nova-hp-essential-commands-guide-status)
+ [작업 로그 모니터링](#nova-hp-essential-commands-guide-logs)
+ [활성 작업 나열](#nova-hp-essential-commands-guide-list-jobs)
+ [작업 취소](#nova-hp-essential-commands-guide-cancel-job)
+ [평가 작업 실행](#nova-hp-essential-commands-guide-evaluation)
+ [일반적인 문제](#nova-hp-essential-commands-guide-troubleshooting)

## 레시피 CLI 설치
<a name="nova-hp-essential-commands-guide-install"></a>

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

**비Forge 사용자 지정 기법을 사용하는 경우 Hyperpodrecipes 리포지토리를 사용합니다. Forge 기반 사용자 지정의 경우 Forge 특정 레시피 리포지토리를 참조하세요.**  
다음 명령을 실행하여 SageMaker HyperPod CLI를 설치합니다.

**참고**  
활성 conda/anaconda/miniconda 환경 또는 다른 가상 환경에 있지 않은지 확인합니다.  
d그렇다면 다음을 사용하여 환경을 종료하세요.  
conda/anaconda/miniconda 환경의 경우 `conda deactivate`
Python 가상 환경의 경우 `deactivate`

 비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 .`를 실행하기 전에 [새 가상 환경](https://docs.python.org/3/library/venv.html) 사용하려면 다음을 실행합니다.  
`python -m venv nova_forge`
`source nova_forge/bin/activate`
이제 명령줄에서 프롬프트 시작 위치에 (nova\$1forge)를 표시합니다.
이를 통해 CLI를 사용할 때 경쟁하는 종속 항목이 없도록 보장합니다.

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

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

## 클러스터에 연결
<a name="nova-hp-essential-commands-guide-connect"></a>

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

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

**중요**  
이 명령은 후속 명령에 필요한 컨텍스트 파일(`/tmp/hyperpod_context.json`)을 생성합니다. 이 파일을 찾을 수 없다는 오류가 표시되면 connect 명령을 다시 실행합니다.

**전문가 팁**: 다음과 같이 명령에 `--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`를 추가하지 않아도 됩니다.

## 훈련 작업 시작
<a name="nova-hp-essential-commands-guide-start-job"></a>

**참고**  
PPO/RFT 작업을 실행하는 경우 모든 포드가 동일한 노드에서 예약되도록 레이블 선택기 설정을 `src/hyperpod_cli/sagemaker_hyperpod_recipes/recipes_collection/cluster/k8s.yaml`에 추가해야 합니다.  

```
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>"
}
```

## 작업 상태 추적
<a name="nova-hp-essential-commands-guide-status"></a>

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

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

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


| Status | 설명 | 
| --- |--- |
| `Pending` | 수락되었지만 아직 노드에서 예약되지 않았거나 컨테이너 이미지가 풀링될 때까지 대기 중인 포드 | 
| `Running` | 하나 이상의 컨테이너가 실행 중이거나 시작 중 상태인 노드에 바인딩된 포드 | 
| `Succeeded` | 모든 컨테이너가 성공적으로 완료되었으며 다시 시작되지 않음 | 
| `Failed` | 모든 컨테이너가 종료되었지만 하나 이상의 컨테이너가 실패로 종료됨 | 
| `Unknown` | 포드 상태를 확인할 수 없음(일반적으로 노드 통신 문제로 인한 문제) | 
| `CrashLoopBackOff` | 컨테이너가 반복적으로 실패함, 재시작 시도에서 Kubernetes 백오프 | 
| `ImagePullBackOff` / `ErrImagePull` | 레지스트리에서 컨테이너 이미지를 가져올 수 없음 | 
| `OOMKilled` | 메모리 제한을 초과하여 컨테이너가 종료됨 | 
| `Completed` | 작업 또는 포드가 성공적으로 완료됨(배치 작업 완료) | 

**작은 정보**  
`-w` 플래그를 사용하여 포드 상태 업데이트를 실시간으로 감시합니다. `Ctrl+C`를 눌러 감시를 중지합니다.

## 작업 로그 모니터링
<a name="nova-hp-essential-commands-guide-logs"></a>

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

**CloudWatch 사용**  
로그는 CloudWatch 아래 Hyperpodcluster가 포함된 AWS 계정에서 사용할 수 있습니다. 브라우저에서 보려면 계정의 CloudWatch 홈페이지로 이동하여 클러스터 이름을 검색합니다. 예를 들어 `my-hyperpod-rig`라는 클러스터가 있으면 로그 그룹에 다음과 같은 접두사가 붙습니다.
+ **로그 그룹**: `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}`
+ 로그 그룹에 있으면 `hyperpod-i-00b3d8a1bf25714e4`와 같은 노드 인스턴스 ID를 사용하여 특정 로그를 찾을 수 있습니다.
  + 여기서, `i-00b3d8a1bf25714e4`는 훈련 작업이 실행 중인 Hyperpod 친화적인 시스템 이름을 나타냅니다. 이전 명령 `kubectl get pods -o wide -w -n kubeflow | (head -n1 ; grep my-cpt-run)` 출력에서 **NODE** 열을 캡처한 방법을 떠올려 보세요.
  + 이 경우에 '마스터' 노드 실행은 hyperpod-`i-00b3d8a1bf25714e4`에서 실행되었으므로 해당 문자열을 사용하여 보려는 로그 그룹을 선택합니다. `SagemakerHyperPodTrainingJob/rig-group/[NODE]`라고 표시된 항목을 선택합니다.

**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'이라고 표시된 결과를 선택할 수 있습니다. 마스터 노드가 되기 때문입니다.

**AWS AWS 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
```

## 활성 작업 나열
<a name="nova-hp-essential-commands-guide-list-jobs"></a>

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

```
hyperpod list-jobs -n kubeflow
```

**출력 예제:**

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

## 작업 취소
<a name="nova-hp-essential-commands-guide-cancel-job"></a>

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

```
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` 필드를 복사합니다.

## 평가 작업 실행
<a name="nova-hp-essential-commands-guide-evaluation"></a>

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

**사전 조건**  
평가 작업을 실행하기 전에 다음이 있는지 확인합니다.
+ 훈련 작업 `manifest.json` 파일의 체크포인트 Amazon S3 URI(훈련된 모델의 경우)
+ 올바른 형식으로 Amazon S3에 업로드된 평가 데이터세트
+ 평가 결과에 대한 출력 Amazon S3 경로

**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"
  }'
```

**파라미터 설명**:
+ `recipes.run.name`: 평가 작업의 고유 이름
+ `recipes.run.model_name_or_path`: `manifest.json` 또는 기본 모델 경로의 Amazon S3 URI(예: `nova-micro/prod`)
+ `recipes.run.output_s3_path`: 평가 결과의 Amazon S3 위치
+ `recipes.run.data_s3_path`: 평가 데이터세트의 Amazon S3 위치

**팁**:
+ **모델별 레시피**: 각 모델 크기(micro, lite, pro)에는 자체 평가 레시피가 있습니다.
+ **기본 모델 평가**: 체크포인트 URI 대신 기본 모델 경로(예: `nova-micro/prod`)를 사용하여 기본 모델 평가

**평가 데이터 형식**  
**입력 형식(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'}"
}
```

**필드 설명**:
+ `prompt`: 모델로 전송된 형식 지정된 입력
+ `inference`: 모델의 생성된 응답
+ `gold`: 입력 데이터세트의 예상되는 정답
+ `metadata`: 입력에서 전달되는 선택적 메타데이터

## 일반적인 문제
<a name="nova-hp-essential-commands-guide-troubleshooting"></a>
+ `ModuleNotFoundError: No module named 'nemo_launcher'`: `hyperpod_cli`가 설치된 위치에 따라 Python 경로에 `nemo_launcher`를 추가해야 할 수도 있습니다. 샘플 명령:

  ```
  export PYTHONPATH=<path_to_hyperpod_cli>/sagemaker-hyperpod-cli/src/hyperpod_cli/sagemaker_hyperpod_recipes/launcher/nemo/nemo_framework_launcher/launcher_scripts:$PYTHONPATH
  ```
+ `FileNotFoundError: [Errno 2] No such file or directory: '/tmp/hyperpod_current_context.json'`은 hyperpod connect cluster 명령을 실행하지 못했음을 나타냅니다.
+ 예약된 작업이 표시되지 않는 경우 SageMaker HyperPod CLI의 출력에 작업 이름 및 기타 메타데이터가 포함된 이 섹션이 있는지 다시 확인합니다. 그렇지 않은 경우 다음을 실행하여 헬름 차트를 다시 설치합니다.

  ```
  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
  ```