# Amazon SageMaker HyperPod Essential コマンドガイド
<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>

インストールコマンドを実行する前に、レシピリポジトリのルートに移動します。

**Non Forge カスタマイズ手法を使用する場合は、Hyperpodrecipes リポジトリを使用します。Forge ベースのカスタマイズについては、Forge 固有のレシピリポジトリを参照してください。**  
以下のコマンドを実行して、SageMaker HyperPod CLI をインストールします。

**注記**  
conda / anaconda / miniconda 環境または別の仮想環境がアクティブになっていないことを確認します  
アクティブになっている場合は、以下を使用して環境を終了してください。  
conda / anaconda / miniconda 環境の場合は `conda deactivate`
Python 仮想環境の場合は `deactivate`

 Non 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\_forge) がプロンプトの先頭にされます
これにより、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>)
```

**ポッドのステータスについて**  
以下の表に、一般的なポッドのステータスを示します。


| ステータス | 説明 | 
| --- |--- |
| `Pending` | ポッドが受け入れられたが、まだノードにスケジュールされていないか、コンテナイメージがプルされるのを待っている | 
| `Running` | ポッドが少なくとも 1 つのコンテナが実行中または起動しているノードにバインドされた | 
| `Succeeded` | すべてのコンテナが正常に完了し、再起動しない | 
| `Failed` | すべてのコンテナが終了し、少なくとも 1 つが失敗した | 
| `Unknown` | ポッドの状態が判断できない (通常はノード通信の問題が原因) | 
| `CrashLoopBackOff` | コンテナが繰り返し失敗する。Kubernetes が再起動の試行からバックオフする | 
| `ImagePullBackOff` / `ErrImagePull` | レジストリからコンテナイメージをプルできない | 
| `OOMKilled` | メモリ制限を超えたために終了したコンテナ | 
| `Completed` | ジョブまたはポッドが正常に終了した (バッチジョブの完了) | 

**ヒント**  
`-w` フラグを使用して、ポッドのステータスの更新をリアルタイムで監視します。`Ctrl+C` を押して監視を停止します。

## ジョブログをモニタリングする
<a name="nova-hp-essential-commands-guide-logs"></a>

ログは、以下の 3 つの方法のいずれかで表示できます。

**CloudWatch の使用**  
ログは、CloudWatch の下の Hyperpodcluster を含む AWS アカウントで使用できます。ブラウザで表示するには、アカウントの CloudWatch ホームページに移動し、クラスター名を検索します。例えば、クラスターの名前が `my-hyperpod-rig` の場合、ロググループのプレフィックスは以下のようになります。
+ **ロググループ**: `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}`
+ ロググループに入ると、`hyperpod-i-00b3d8a1bf25714e4` などのノードインスタンス ID を使用して特定のログを見つけることができます。
  + ここで `i-00b3d8a1bf25714e4` は、トレーニングジョブが実行されている Hyperpodfriendly マシン名を表します。前のコマンド `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 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 パス

**コマンド**  
以下のコマンドを実行して、評価ジョブを開始します。

```
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` がインストールされている場所に基づいて `nemo_launcher` を Python パスに追加する必要がある場合があります。サンプルコマンド:

  ```
  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'` は、ハイパーポッド接続クラスターコマンドの実行を見逃したことを示します。
+ ジョブがスケジュールされていない場合は、SageMaker HyperPod CLI の出力にジョブ名やその他のメタデータを含むこのセクションがあるかどうかを再確認してください。ない場合は、以下を実行して Helm チャートを再インストールします。

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