Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Panduan Per SageMaker HyperPod intah Esensial Amazon
<a name="nova-hp-essential-commands-guide"></a>

Amazon SageMaker HyperPod menyediakan fungsionalitas baris perintah yang luas untuk mengelola alur kerja pelatihan. Panduan ini mencakup perintah penting untuk operasi umum, mulai dari menghubungkan ke cluster Anda hingga memantau kemajuan pekerjaan.

**Prasyarat**  
Sebelum menggunakan perintah ini, pastikan Anda telah menyelesaikan pengaturan berikut:
+ SageMaker HyperPod cluster dengan RIG dibuat (biasanya di us-east-1)
+ Buket keluaran Amazon S3 dibuat untuk artefak pelatihan
+ Peran IAM dikonfigurasi dengan izin yang sesuai
+ Data pelatihan diunggah dalam format JSONL yang benar
+ FSx untuk sinkronisasi Lustre selesai (verifikasi dalam log cluster pada pekerjaan pertama)

**Topics**
+ [Menginstal Recipe CLI](#nova-hp-essential-commands-guide-install)
+ [Menghubungkan ke cluster Anda](#nova-hp-essential-commands-guide-connect)
+ [Memulai pekerjaan pelatihan](#nova-hp-essential-commands-guide-start-job)
+ [Memeriksa status pekerjaan](#nova-hp-essential-commands-guide-status)
+ [Memantau log pekerjaan](#nova-hp-essential-commands-guide-logs)
+ [Mendaftarkan pekerjaan aktif](#nova-hp-essential-commands-guide-list-jobs)
+ [Membatalkan pekerjaan](#nova-hp-essential-commands-guide-cancel-job)
+ [Menjalankan pekerjaan evaluasi](#nova-hp-essential-commands-guide-evaluation)
+ [Masalah umum](#nova-hp-essential-commands-guide-troubleshooting)

## Menginstal Recipe CLI
<a name="nova-hp-essential-commands-guide-install"></a>

Arahkan ke root repositori resep Anda sebelum menjalankan perintah instalasi.

**Gunakan repositori Hyperpodrecipes jika menggunakan teknik penyesuaian Non Forge, untuk kustomisasi berbasis Forge lihat repositori resep khusus forge.**  
Jalankan perintah berikut untuk menginstal SageMaker HyperPod CLI:

**catatan**  
Pastikan Anda tidak berada di lingkungan conda/anaconda/miniconda aktif atau lingkungan virtual lainnya  
Jika ya, silakan keluar dari lingkungan menggunakan:  
`conda deactivate`untuk lingkungan conda/anaconda/miniconda
`deactivate`untuk lingkungan virtual python

 Jika Anda menggunakan teknik kustomisasi Non Forge, unduh sagemaker-hyperpod-recipes-seperti yang ditunjukkan di bawah ini:

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

Jika Anda adalah Pelang ** gan Forge, ** Anda harus mengunduh resep menggunakan proses yang disebutkan di bawah ini.

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

**Tip**  
Untuk menggunakan lingkungan virtual [ baru ](https://docs.python.org/3/library/venv.html) sebelum menjalankan`pip install -e .`, jalankan:  
`python -m venv nova_forge`
`source nova_forge/bin/activate`
Baris perintah Anda sekarang akan ditampilkan (nova\_forge) di awal prompt Anda
Ini memastikan tidak ada dependensi yang bersaing saat menggunakan CLI

**Tujuan**: Mengapa kita melakukannya`pip install -e .`?

Perintah ini menginstal SageMaker HyperPod CLI dalam mode yang dapat diedit, memungkinkan Anda untuk menggunakan resep yang diperbarui tanpa menginstal ulang setiap kali. Ini juga memungkinkan Anda untuk menambahkan resep baru yang dapat diambil CLI secara otomatis.

## Menghubungkan ke cluster Anda
<a name="nova-hp-essential-commands-guide-connect"></a>

Hubungkan SageMaker HyperPod CLI ke cluster Anda sebelum menjalankan pekerjaan apa pun:

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

**penting**  
Perintah ini membuat file konteks (`/tmp/hyperpod_context.json`) yang diperlukan perintah berikutnya. Jika Anda melihat kesalahan tentang file ini tidak ditemukan, jalankan kembali perintah connect.

**Kiat pro**: Anda dapat lebih lanjut mengkonfigurasi cluster Anda untuk selalu menggunakan `kubeflow` namespace dengan menambahkan `--namespace kubeflow` argumen ke perintah Anda sebagai berikut:

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

Ini menghemat upaya menambahkan perintah `-n kubeflow` di setiap saat berinteraksi dengan pekerjaan Anda.

## Memulai pekerjaan pelatihan
<a name="nova-hp-essential-commands-guide-start-job"></a>

**catatan**  
Jika menjalankan PPO/RFT pekerjaan, pastikan Anda menambahkan pengaturan pemilih label `src/hyperpod_cli/sagemaker_hyperpod_recipes/recipes_collection/cluster/k8s.yaml` agar semua pod dijadwalkan pada node yang sama.  

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

Luncurkan pekerjaan pelatihan menggunakan resep dengan penggantian parameter opsional:

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

**Output yang diharapkan**:

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

## Memeriksa status pekerjaan
<a name="nova-hp-essential-commands-guide-status"></a>

Pantau pekerjaan berjalan Anda menggunakan kubectl:

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

**Memahami status pod**  
Tabel berikut menjelaskan status pod umum:


| Status | Deskripsi | 
| --- |--- |
| `Pending` | Pod diterima tetapi belum dijadwalkan ke node, atau menunggu gambar kontainer ditarik | 
| `Running` | Pod terikat ke node dengan setidaknya satu kontainer berjalan atau dimulai | 
| `Succeeded` | Semua kontainer berhasil diselesaikan dan tidak akan restart | 
| `Failed` | Semua kontainer dihentikan dengan setidaknya satu berakhir dengan kegagalan | 
| `Unknown` | Status pod tidak dapat ditentukan (biasanya karena masalah komunikasi node) | 
| `CrashLoopBackOff` | Kontainer berulang kali gagal; Kubernetes mundur dari upaya restart | 
| `ImagePullBackOff` / `ErrImagePull` | Tidak dapat menarik gambar kontainer dari registri | 
| `OOMKilled` | Wadah dihentikan karena melebihi batas memori | 
| `Completed` | Pekerjaan atau Pod berhasil diselesaikan (penyelesaian tugas batch) | 

**Tip**  
Gunakan ben `-w` dera untuk menonton pembaruan status pod secara real-time. Tek `Ctrl+C` an untuk berhenti menonton.

## Memantau log pekerjaan
<a name="nova-hp-essential-commands-guide-logs"></a>

Anda dapat melihat log Anda salah satu dari tiga cara:

**Menggunakan CloudWatch**  
Log Anda tersedia di AWS akun Anda yang berisi Hyperpodcluster di bawah. CloudWatch Untuk melihatnya di browser Anda, navigasikan ke CloudWatch beranda di akun Anda dan cari nama cluster Anda. Misalnya, jika cluster Anda di `my-hyperpod-rig` panggil grup log akan memiliki awalan:
+ **Grup log**: `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}`
+ Setelah Anda berada di grup log, Anda dapat menemukan log spesifik Anda menggunakan ID instance node seperti -`hyperpod-i-00b3d8a1bf25714e4`.
  + `i-00b3d8a1bf25714e4`di sini mewakili nama mesin Hyperpodfriendly tempat pekerjaan pelatihan Anda berjalan. Ingat bagaimana pada `kubectl get pods -o wide -w -n kubeflow | (head -n1 ; grep my-cpt-run)` output perintah sebelumnya kita menangkap kolom yang disebut ** NODE**.
  + Node “master” yang dijalankan dalam hal ini berjalan pada hyperpod- `i-00b3d8a1bf25714e4` dan dengan demikian kita akan menggunakan string itu untuk memilih grup log untuk dilihat. Pilih salah satu yang mengatakan `SagemakerHyperPodTrainingJob/rig-group/[NODE]`

**Menggunakan CloudWatch Wawasan**  
Jika Anda memiliki nama pekerjaan Anda dan tidak ingin melalui semua langkah di atas, Anda cukup menanyakan semua log di bawah `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}` untuk menemukan log individu.

CPT:

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

Untuk penyelesaian pekerjaan ganti `Starting CPT Job` dengan `CPT Job completed`

Kemudian Anda dapat mengklik hasil dan memilih salah satu yang mengatakan “Epoch 0" karena itu akan menjadi node master Anda.

**Menggunakan AWS CLI**  
Anda dapat memilih untuk mengekor log Anda menggunakan AWS CLI. Sebelum melakukannya, silakan periksa AWS CLI versi Anda menggunakan`aws --version`. Disarankan juga untuk menggunakan skrip utilitas ini yang membantu dalam pelacakan log langsung di terminal Anda

**untuk V1**:

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

**untuk V2**:

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

## Mendaftarkan pekerjaan aktif
<a name="nova-hp-essential-commands-guide-list-jobs"></a>

Lihat semua pekerjaan yang berjalan di cluster Anda:

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

**Contoh keluaran**:

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

## Membatalkan pekerjaan
<a name="nova-hp-essential-commands-guide-cancel-job"></a>

Hentikan pekerjaan yang sedang berjalan kapan saja:

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

**Menemukan nama pekerjaan Anda**  
**Opsi 1: Dari resep Anda **

Nama pekerjaan ditentukan di `run` blok resep Anda:

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

**Opsi 2: Dari perintah list-jobs **

Gunakan `hyperpod list-jobs -n kubeflow` dan salin `Name` bidang dari output.

## Menjalankan pekerjaan evaluasi
<a name="nova-hp-essential-commands-guide-evaluation"></a>

Evaluasi model terlatih atau model dasar menggunakan resep evaluasi.

**Prasyarat**  
Sebelum menjalankan pekerjaan evaluasi, pastikan Anda memiliki:
+ Pos pemeriksaan Amazon S3 URI dari `manifest.json` file pekerjaan pelatihan Anda (untuk model terlatih)
+ Dataset evaluasi diunggah ke Amazon S3 dalam format yang benar
+ Jalur keluaran Amazon S3 untuk hasil evaluasi

**Perintah**  
Jalankan perintah berikut untuk memulai pekerjaan evaluasi:

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

**Deskripsi parameter**:
+ `recipes.run.name`: Nama unik untuk pekerjaan evaluasi Anda
+ `recipes.run.model_name_or_path`: URI Amazon S3 dari `manifest.json` atau jalur model dasar (mis.,`nova-micro/prod`)
+ `recipes.run.output_s3_path`: Lokasi Amazon S3 untuk hasil evaluasi
+ `recipes.run.data_s3_path`: Lokasi Amazon S3 dari kumpulan data evaluasi Anda

**Tips**:
+ **Model-specific resep**: Setiap ukuran model (mikro, lite, pro) memiliki resep evaluasi sendiri
+ **Evaluasi model dasar**: Gunakan jalur model dasar (misalnya,`nova-micro/prod`) alih-alih URI pos pemeriksaan untuk mengevaluasi model dasar

**Format data evaluasi**  
**Format masukan (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"
}
```

**Format keluaran**:

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

**Deskripsi bidang**:
+ `prompt`: Input yang diformat dikirim ke model
+ `inference`: Respon yang dihasilkan model
+ `gold`: Diharapkan jawaban benar dari kumpulan data input
+ `metadata`: Metadata opsional dilewatkan dari input

## Masalah umum
<a name="nova-hp-essential-commands-guide-troubleshooting"></a>
+ `ModuleNotFoundError: No module named 'nemo_launcher'`, Anda mungkin harus menambahkan `nemo_launcher` ke jalur python Anda berdasarkan di `hyperpod_cli` mana diinstal. Perintah sampel:

  ```
  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'`menunjukkan Anda melewatkan menjalankan perintah cluster hyperpod connect.
+ Jika Anda tidak melihat pekerjaan Anda dijadwalkan, periksa kembali apakah output SageMaker HyperPod CLI Anda memiliki bagian ini dengan nama pekerjaan dan metadata lainnya. Jika tidak, instal ulang bagan helm dengan menjalankan:

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