Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Guide des commandes Amazon SageMaker HyperPod Essential
<a name="nova-hp-essential-commands-guide"></a>

Amazon SageMaker HyperPod fournit des fonctionnalités de ligne de commande étendues pour gérer les flux de travail de formation. Ce guide couvre les commandes essentielles pour les opérations courantes, de la connexion à votre cluster au suivi de l'avancement des tâches.

**Conditions préalables**  
Avant d'utiliser ces commandes, assurez-vous d'avoir effectué la configuration suivante :
+ SageMaker HyperPod cluster avec RIG créé (généralement dans us-east-1)
+ Compartiment de sortie Amazon S3 créé pour les artefacts d'entraînement
+ Rôles IAM configurés avec les autorisations appropriées
+ Données d'entraînement téléchargées au format JSONL correct
+ FSx pour que la synchronisation avec Lustre soit terminée (vérifiez dans les journaux du cluster lors de la première tâche)

**Topics**
+ [Installation de Recipe CLI](#nova-hp-essential-commands-guide-install)
+ [Connexion à votre cluster](#nova-hp-essential-commands-guide-connect)
+ [Commencer un poste de formation](#nova-hp-essential-commands-guide-start-job)
+ [Vérification de l'état du travail](#nova-hp-essential-commands-guide-status)
+ [Surveillance des journaux des tâches](#nova-hp-essential-commands-guide-logs)
+ [Lister les offres d'emploi actives](#nova-hp-essential-commands-guide-list-jobs)
+ [Annulation d'une tâche](#nova-hp-essential-commands-guide-cancel-job)
+ [Exécution d'une tâche d'évaluation](#nova-hp-essential-commands-guide-evaluation)
+ [Problèmes courants](#nova-hp-essential-commands-guide-troubleshooting)

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

Accédez à la racine de votre référentiel de recettes avant d'exécuter la commande d'installation.

**Utilisez le référentiel Hyperpodrerecipes si vous utilisez des techniques de personnalisation autres que Forge. Pour la personnalisation basée sur Forge, reportez-vous au référentiel de recettes spécifique à la forge.**  
Exécutez les commandes suivantes pour installer la SageMaker HyperPod CLI :

**Note**  
Assurez-vous que vous n'êtes pas dans un environnement conda, anaconda, miniconda actif ou dans un autre environnement virtuel  
Si c'est le cas, veuillez quitter l'environnement en utilisant :  
`conda deactivate`pour les environnements conda, anaconda et miniconda
`deactivate`pour les environnements virtuels Python

 Si vous utilisez une technique de personnalisation autre que Forge, sagemaker-hyperpod-recipes téléchargez-la comme indiqué ci-dessous :

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

Si vous êtes **abonné à Forge,** vous devriez télécharger les recettes en utilisant le processus mentionné ci-dessous.

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

**Astuce**  
Pour utiliser un [nouvel environnement virtuel](https://docs.python.org/3/library/venv.html) avant de l'exécuter`pip install -e .`, exécutez :  
`python -m venv nova_forge`
`source nova_forge/bin/activate`
Votre ligne de commande s'affichera désormais (nova\$1forge) au début de votre invite
Cela garantit qu'il n'y a pas de dépendances concurrentes lors de l'utilisation de la CLI

**Objectif** : Pourquoi le faisons-nous `pip install -e .` ?

Cette commande installe la SageMaker HyperPod CLI en mode modifiable, ce qui vous permet d'utiliser des recettes mises à jour sans avoir à les réinstaller à chaque fois. Cela vous permet également d'ajouter de nouvelles recettes que la CLI peut automatiquement récupérer.

## Connexion à votre cluster
<a name="nova-hp-essential-commands-guide-connect"></a>

Connectez la SageMaker HyperPod CLI à votre cluster avant d'exécuter des tâches :

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

**Important**  
Cette commande crée un fichier de contexte (`/tmp/hyperpod_context.json`) requis par les commandes suivantes. Si vous voyez un message d'erreur concernant ce fichier introuvable, réexécutez la commande connect.

**Conseil de pro** : Vous pouvez configurer davantage votre cluster pour qu'il utilise toujours l'`kubeflow`espace de noms en ajoutant l'`--namespace kubeflow`argument à votre commande comme suit :

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

Cela vous évite d'avoir à ajouter la commande `-n kubeflow` dans chaque commande lorsque vous interagissez avec vos tâches.

## Commencer un poste de formation
<a name="nova-hp-essential-commands-guide-start-job"></a>

**Note**  
Si vous exécutez PPO/RFT des tâches, assurez-vous d'ajouter des paramètres de sélection d'étiquettes `src/hyperpod_cli/sagemaker_hyperpod_recipes/recipes_collection/cluster/k8s.yaml` afin que tous les modules soient planifiés sur le même nœud.  

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

Lancez une tâche de formation à l'aide d'une recette avec des remplacements de paramètres facultatifs :

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

**Résultat attendu** :

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

## Vérification de l'état du travail
<a name="nova-hp-essential-commands-guide-status"></a>

Surveillez vos tâches en cours à l'aide de kubectl :

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

**Comprendre le statut des pods**  
Le tableau suivant explique les statuts courants des pods :


| Statut | Description | 
| --- |--- |
| `Pending` | Pod accepté mais pas encore programmé sur un nœud, ou en attente d'extraction des images du conteneur | 
| `Running` | Pod lié à un nœud avec au moins un conteneur en cours d'exécution ou en cours de démarrage | 
| `Succeeded` | Tous les conteneurs ont été terminés avec succès et ne redémarreront pas | 
| `Failed` | Tous les conteneurs ont été interrompus et au moins l'un d'entre eux s'est terminé par un échec | 
| `Unknown` | L'état du pod ne peut pas être déterminé (généralement en raison de problèmes de communication entre nœuds) | 
| `CrashLoopBackOff` | Défaillance répétée du conteneur ; Kubernetes recule après les tentatives de redémarrage | 
| `ImagePullBackOff` / `ErrImagePull` | Impossible d'extraire l'image du conteneur du registre | 
| `OOMKilled` | Conteneur fermé pour dépassement des limites de mémoire | 
| `Completed` | Job ou pod terminé avec succès (fin du travail par lots) | 

**Astuce**  
Utilisez le `-w` drapeau pour suivre les mises à jour de l'état du pod en temps réel. Appuyez `Ctrl+C` pour arrêter de regarder.

## Surveillance des journaux des tâches
<a name="nova-hp-essential-commands-guide-logs"></a>

Vous pouvez consulter vos journaux de trois manières :

**En utilisant CloudWatch**  
Vos journaux sont disponibles dans votre AWS compte qui contient l'Hyperpodcluster sous. CloudWatch Pour les consulter dans votre navigateur, rendez-vous sur la CloudWatch page d'accueil de votre compte et recherchez le nom de votre cluster. Par exemple, si votre cluster était appelé, `my-hyperpod-rig` le groupe de journaux aurait le préfixe suivant :
+ **Groupe de journaux** : `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}`
+ Une fois que vous êtes dans le groupe de journaux, vous pouvez trouver votre journal spécifique à l'aide de l'ID d'instance du nœud, tel que -`hyperpod-i-00b3d8a1bf25714e4`.
  + `i-00b3d8a1bf25714e4`ici représente le nom de la machine Hyperpodfriendly sur laquelle s'exécute votre tâche de formation. Rappelez-vous comment, dans la `kubectl get pods -o wide -w -n kubeflow | (head -n1 ; grep my-cpt-run)` sortie de commande précédente, nous avons capturé une colonne appelée **NODE**.
  + Le nœud « maître » exécuté était dans ce cas exécuté sur hyperpod- `i-00b3d8a1bf25714e4` et nous allons donc utiliser cette chaîne pour sélectionner le groupe de journaux à afficher. Sélectionnez celui qui dit `SagemakerHyperPodTrainingJob/rig-group/[NODE]`

**Utilisation d' CloudWatch Insights**  
Si vous avez le nom de votre poste à portée de main et que vous ne souhaitez pas suivre toutes les étapes ci-dessus, vous pouvez simplement rechercher tous les journaux `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}` ci-dessous pour trouver le journal individuel.

CPT :

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

Pour terminer le travail, remplacer `Starting CPT Job` par `CPT Job completed`

Ensuite, vous pouvez cliquer sur les résultats et choisir celui qui indique « Epoch 0 », car ce sera votre nœud principal.

**En utilisant le AWS CLI**  
Vous pouvez choisir de suivre vos journaux à l'aide du AWS CLI. Avant de le faire, veuillez vérifier votre AWS CLI version à l'aide de`aws --version`. Il est également recommandé d'utiliser ce script utilitaire qui facilite le suivi des journaux en direct sur votre terminal

**pour V1** :

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

**pour V2** :

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

## Lister les offres d'emploi actives
<a name="nova-hp-essential-commands-guide-list-jobs"></a>

Afficher toutes les tâches exécutées dans votre cluster :

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

**Exemple de sortie :**

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

## Annulation d'une tâche
<a name="nova-hp-essential-commands-guide-cancel-job"></a>

Arrêtez une tâche en cours d'exécution à tout moment :

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

**Trouver le nom de votre poste**  
**Option 1 : À partir de votre recette**

Le nom de la tâche est spécifié dans le `run` bloc de votre recette :

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

**Option 2 : depuis la commande list-jobs**

Utilisez `hyperpod list-jobs -n kubeflow` et copiez le `Name` champ à partir de la sortie.

## Exécution d'une tâche d'évaluation
<a name="nova-hp-essential-commands-guide-evaluation"></a>

Évaluez un modèle entraîné ou un modèle de base à l'aide d'une recette d'évaluation.

**Conditions préalables**  
Avant d'exécuter des tâches d'évaluation, assurez-vous d'avoir :
+ Vérifiez l'URI Amazon S3 depuis le `manifest.json` fichier de votre tâche de formation (pour les modèles entraînés)
+ Ensemble de données d'évaluation chargé sur Amazon S3 dans le bon format
+ Afficher le chemin Amazon S3 pour les résultats de l'évaluation

**Commande**  
Exécutez la commande suivante pour démarrer une tâche d'évaluation :

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

**Descriptions des paramètres** :
+ `recipes.run.name`: nom unique pour votre tâche d'évaluation
+ `recipes.run.model_name_or_path`: URI Amazon S3 depuis `manifest.json` ou chemin du modèle de base (par exemple,`nova-micro/prod`)
+ `recipes.run.output_s3_path`: emplacement Amazon S3 pour les résultats de l'évaluation
+ `recipes.run.data_s3_path`: emplacement de votre ensemble de données d'évaluation sur Amazon S3

**Conseils** :
+ **Recettes spécifiques au modèle** : chaque taille de modèle (micro, lite, pro) possède sa propre recette d'évaluation
+ **Évaluation du modèle de base** : utilisez les chemins du modèle de base (par exemple,`nova-micro/prod`) au lieu du point de contrôle URIs pour évaluer les modèles de base

**Format des données d'évaluation**  
**Format d'entrée (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 de sortie** :

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

**Descriptions des champs** :
+ `prompt`: entrée formatée envoyée au modèle
+ `inference`: réponse générée par le modèle
+ `gold`: réponse correcte attendue de la part du jeu de données en entrée
+ `metadata`: métadonnées facultatives transmises depuis l'entrée

## Problèmes courants
<a name="nova-hp-essential-commands-guide-troubleshooting"></a>
+ `ModuleNotFoundError: No module named 'nemo_launcher'`, vous devrez peut-être ajouter des éléments `nemo_launcher` à votre chemin python en fonction de l'endroit où `hyperpod_cli` il est installé. Exemple de commande :

  ```
  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'`indique que vous n'avez pas exécuté la commande Hyperpod Connect Cluster.
+ Si votre tâche n'est pas planifiée, vérifiez si la sortie de votre SageMaker HyperPod CLI contient cette section avec les noms des tâches et d'autres métadonnées. Sinon, réinstallez helm chart en exécutant :

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