Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Guida ai comandi SageMaker HyperPod essenziali di Amazon
<a name="nova-hp-essential-commands-guide"></a>

Amazon SageMaker HyperPod offre ampie funzionalità da riga di comando per la gestione dei flussi di lavoro di formazione. Questa guida descrive i comandi essenziali per le operazioni più comuni, dalla connessione al cluster al monitoraggio dell'avanzamento dei lavori.

**Prerequisiti**  
Prima di utilizzare questi comandi, assicuratevi di aver completato la seguente configurazione:
+ SageMaker HyperPod cluster con RIG creato (tipicamente in us-east-1)
+ Output: bucket Amazon S3 creato per gli artefatti di addestramento
+ Ruoli IAM configurati con autorizzazioni appropriate
+ Dati di allenamento caricati nel formato JSONL corretto
+ FSx per Lustre sync completata (verifica nei log del cluster al primo processo)

**Topics**
+ [Installazione della CLI di Recipe](#nova-hp-essential-commands-guide-install)
+ [Connessione al cluster](#nova-hp-essential-commands-guide-connect)
+ [Avvio di un lavoro di formazione](#nova-hp-essential-commands-guide-start-job)
+ [Verifica dello stato del lavoro](#nova-hp-essential-commands-guide-status)
+ [Monitoraggio dei registri dei lavori](#nova-hp-essential-commands-guide-logs)
+ [Elenco delle offerte di lavoro attive](#nova-hp-essential-commands-guide-list-jobs)
+ [Annullare un lavoro](#nova-hp-essential-commands-guide-cancel-job)
+ [Esecuzione di un processo di valutazione](#nova-hp-essential-commands-guide-evaluation)
+ [Problemi comuni](#nova-hp-essential-commands-guide-troubleshooting)

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

Vai alla directory principale del tuo repository di ricette prima di eseguire il comando di installazione.

**Usa il repository Hyperpodrecipes se utilizzi tecniche di personalizzazione Non Forge, per la personalizzazione basata su Forge fai riferimento al repository di ricette specifico di forge.**  
Esegui i seguenti comandi per installare la SageMaker HyperPod CLI:

**Nota**  
Assicurati di non trovarti in un ambiente conda /anaconda/miniconda attivo o in un altro ambiente virtuale  
Se lo sei, esci dall'ambiente usando:  
`conda deactivate`per ambienti conda/anaconda/miniconda
`deactivate`per ambienti virtuali Python

 Se utilizzi una tecnica di personalizzazione Non Forge, scaricala sagemaker-hyperpod-recipes come mostrato di seguito:

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

Se sei un **abbonato a Forge,** dovresti scaricare le ricette utilizzando la procedura indicata di seguito.

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

**Suggerimento**  
Per utilizzare un [nuovo ambiente virtuale prima dell'](https://docs.python.org/3/library/venv.html)esecuzione`pip install -e .`, esegui:  
`python -m venv nova_forge`
`source nova_forge/bin/activate`
La riga di comando verrà ora visualizzata (nova\$1forge) all'inizio del prompt
Ciò garantisce che non vi siano dipendenze concorrenti quando si utilizza la CLI

**Scopo**: perché lo facciamo? `pip install -e .`

Questo comando installa la SageMaker HyperPod CLI in modalità modificabile, che consente di utilizzare ricette aggiornate senza reinstallarle ogni volta. Consente inoltre di aggiungere nuove ricette che la CLI può selezionare automaticamente.

## Connessione al cluster
<a name="nova-hp-essential-commands-guide-connect"></a>

Connect la SageMaker HyperPod CLI al cluster prima di eseguire qualsiasi job:

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

**Importante**  
Questo comando crea un file di contesto (`/tmp/hyperpod_context.json`) richiesto dai comandi successivi. Se visualizzi un errore relativo a questo file non trovato, esegui nuovamente il comando connect.

**Suggerimento**: puoi configurare ulteriormente il cluster in modo che utilizzi sempre lo spazio dei `kubeflow` nomi aggiungendo l'`--namespace kubeflow`argomento al comando come segue:

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

Ciò consente di risparmiare la fatica di aggiungere il comando `-n kubeflow` in ogni comando quando si interagisce con i job.

## Avvio di un lavoro di formazione
<a name="nova-hp-essential-commands-guide-start-job"></a>

**Nota**  
Se state eseguendo dei PPO/RFT lavori, assicuratevi di aggiungere le impostazioni del selettore di etichette `src/hyperpod_cli/sagemaker_hyperpod_recipes/recipes_collection/cluster/k8s.yaml` in modo che tutti i pod siano programmati sullo stesso nodo.  

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

Avvia un processo di formazione utilizzando una ricetta con sostituzioni facoltative dei parametri:

```
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 previsto**:

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

## Verifica dello stato del lavoro
<a name="nova-hp-essential-commands-guide-status"></a>

Monitora i tuoi lavori in esecuzione usando kubectl:

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

**Comprensione degli stati dei pod**  
La tabella seguente illustra gli stati comuni dei pod:


| Stato | Description | 
| --- |--- |
| `Pending` | Pod accettato ma non ancora programmato su un nodo o in attesa che le immagini del contenitore vengano estratte | 
| `Running` | Pod associato a un nodo con almeno un contenitore in esecuzione o in fase di avvio | 
| `Succeeded` | Tutti i contenitori sono stati completati correttamente e non verranno riavviati | 
| `Failed` | Tutti i contenitori sono terminati e almeno uno è terminato con un errore | 
| `Unknown` | Lo stato del pod non può essere determinato (in genere a causa di problemi di comunicazione tra i nodi) | 
| `CrashLoopBackOff` | Errore ripetuto del container; Kubernetes si ritira dai tentativi di riavvio | 
| `ImagePullBackOff` / `ErrImagePull` | Impossibile estrarre l'immagine del contenitore dal registro | 
| `OOMKilled` | Contenitore terminato per superamento dei limiti di memoria | 
| `Completed` | Job o Pod completato correttamente (completamento del lavoro in batch) | 

**Suggerimento**  
Usa il `-w` flag per guardare gli aggiornamenti sullo stato del pod in tempo reale. Premi `Ctrl+C` per interrompere la visione.

## Monitoraggio dei registri dei lavori
<a name="nova-hp-essential-commands-guide-logs"></a>

È possibile visualizzare i registri in tre modi:

**Usando CloudWatch**  
I tuoi log sono disponibili nel tuo AWS account che contiene Hyperpodcluster in. CloudWatch Per visualizzarli nel browser, vai alla CloudWatch home page del tuo account e cerca il nome del cluster. Ad esempio, se il cluster fosse chiamato, `my-hyperpod-rig` il gruppo di log avrebbe il prefisso:
+ **Gruppo di log**: `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}`
+ Una volta entrato nel gruppo di log, puoi trovare il tuo registro specifico utilizzando l'ID dell'istanza del nodo, ad esempio -`hyperpod-i-00b3d8a1bf25714e4`.
  + `i-00b3d8a1bf25714e4`here rappresenta il nome del computer Hyperpodfriendly su cui è in esecuzione il processo di formazione. **Ricordiamo come nell'`kubectl get pods -o wide -w -n kubeflow | (head -n1 ; grep my-cpt-run)`output del comando precedente abbiamo catturato una colonna chiamata NODE.**
  + L'esecuzione del nodo «master» in questo caso era in esecuzione su hyperpod `i-00b3d8a1bf25714e4` e quindi useremo quella stringa per selezionare il gruppo di log da visualizzare. Seleziona quello che dice `SagemakerHyperPodTrainingJob/rig-group/[NODE]`

**Utilizzo di CloudWatch Insights**  
Se hai il nome del tuo lavoro a portata di mano e non desideri seguire tutti i passaggi precedenti, puoi semplicemente interrogare tutti i log sottostanti `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}` per trovare il registro individuale.

CPT:

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

Per completare il lavoro, sostituire con `Starting CPT Job` `CPT Job completed`

Quindi puoi fare clic sui risultati e scegliere quello che dice «Epoch 0" poiché sarà il tuo nodo principale.

**Usando il AWS CLI**  
Puoi scegliere di seguire i tuoi tronchi usando il AWS CLI. Prima di farlo, controlla che la tua AWS CLI versione utilizzi`aws --version`. Si consiglia inoltre di utilizzare questo script di utilità che aiuta a tracciare i log in tempo reale nel terminale

**per V1:**

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

**per V2:**

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

## Elenco delle offerte di lavoro attive
<a name="nova-hp-essential-commands-guide-list-jobs"></a>

Visualizza tutti i lavori in esecuzione nel tuo cluster:

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

**Output di esempio:**

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

## Annullare un lavoro
<a name="nova-hp-essential-commands-guide-cancel-job"></a>

Interrompi un processo in esecuzione in qualsiasi momento:

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

**Trovare il nome del lavoro**  
**Opzione 1: dalla tua ricetta**

Il nome del lavoro è specificato nel `run` blocco della ricetta:

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

**Opzione 2: dal comando list-jobs**

Usa `hyperpod list-jobs -n kubeflow` e copia il `Name` campo dall'output.

## Esecuzione di un processo di valutazione
<a name="nova-hp-essential-commands-guide-evaluation"></a>

Valuta un modello addestrato o un modello base utilizzando una ricetta di valutazione.

**Prerequisiti**  
Prima di eseguire i lavori di valutazione, assicuratevi di disporre di:
+ Controlla l'URI di Amazon S3 dal file `manifest.json` del tuo processo di formazione (per i modelli addestrati)
+ Set di dati di valutazione caricato su Amazon S3 nel formato corretto
+ Percorso di output Amazon S3 per i risultati della valutazione

**Comando**  
Esegui il comando seguente per avviare un processo di valutazione:

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

**Descrizioni dei parametri**:
+ `recipes.run.name`: nome univoco per il lavoro di valutazione
+ `recipes.run.model_name_or_path`: URI Amazon S3 da `manifest.json` o percorso del modello base (ad es.) `nova-micro/prod`
+ `recipes.run.output_s3_path`: posizione Amazon S3 per i risultati della valutazione
+ `recipes.run.data_s3_path`: posizione Amazon S3 del set di dati di valutazione

**Suggerimenti:**
+ **Ricette specifiche per ogni modello**: ogni modello di taglia (micro, lite, pro) ha una propria ricetta di valutazione
+ **Valutazione del modello di base**: utilizza i percorsi del modello di base (ad esempio`nova-micro/prod`) anziché il checkpoint URIs per valutare i modelli di base

**Formato dei dati di valutazione**  
**Formato di input (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"
}
```

**Formato di output:**

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

**Descrizioni dei campi**:
+ `prompt`: input formattato inviato al modello
+ `inference`: risposta generata dal modello
+ `gold`: Risposta corretta prevista dal set di dati di input
+ `metadata`: metadati opzionali trasmessi dall'input

## Problemi comuni
<a name="nova-hp-essential-commands-guide-troubleshooting"></a>
+ `ModuleNotFoundError: No module named 'nemo_launcher'`, potresti dover aggiungere `nemo_launcher` al tuo percorso Python in base a dove `hyperpod_cli` è installato. Comando di esempio:

  ```
  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'`indica che non hai eseguito il comando hyperpod connect cluster.
+ Se non vedi il tuo lavoro pianificato, ricontrolla se l'output della tua SageMaker HyperPod CLI contiene questa sezione con i nomi dei lavori e altri metadati. In caso contrario, reinstalla Helm Chart eseguendo:

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