Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

# Leitfaden SageMaker HyperPod für Amazon Essential Commands
<a name="nova-hp-essential-commands-guide"></a>

Amazon SageMaker HyperPod bietet umfangreiche Befehlszeilenfunktionen für die Verwaltung von Schulungsabläufen. Dieses Handbuch behandelt grundlegende Befehle für allgemeine Operationen, von der Verbindung mit Ihrem Cluster bis hin zur Überwachung des Auftragsfortschritts.

**Voraussetzungen**  
Bevor Sie diese Befehle verwenden, stellen Sie sicher, dass Sie die folgende Einrichtung abgeschlossen haben:
+ SageMaker HyperPod Cluster mit erstelltem RIG (normalerweise in us-east-1)
+ Ausgabe eines Amazon S3 S3-Buckets, der für Trainingsartefakte erstellt wurde
+ Mit entsprechenden Berechtigungen konfigurierte IAM-Rollen
+ Trainingsdaten wurden im richtigen JSONL-Format hochgeladen
+ FSx Die Lustre-Synchronisierung ist abgeschlossen (beim ersten Job in den Clusterprotokollen überprüfen)

**Topics**
+ [Recipe CLI installieren](#nova-hp-essential-commands-guide-install)
+ [Verbindungsaufbau mit Ihrem Cluster](#nova-hp-essential-commands-guide-connect)
+ [Einen Ausbildungsjob beginnen](#nova-hp-essential-commands-guide-start-job)
+ [Jobstatus wird überprüft](#nova-hp-essential-commands-guide-status)
+ [Job-Logs überwachen](#nova-hp-essential-commands-guide-logs)
+ [Aktive Jobs auflisten](#nova-hp-essential-commands-guide-list-jobs)
+ [Stornieren eines Auftrags](#nova-hp-essential-commands-guide-cancel-job)
+ [Einen Evaluierungsjob ausführen](#nova-hp-essential-commands-guide-evaluation)
+ [Häufige Probleme](#nova-hp-essential-commands-guide-troubleshooting)

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

Navigieren Sie zum Stammverzeichnis Ihres Rezept-Repositorys, bevor Sie den Installationsbefehl ausführen.

**Verwenden Sie das Hyperpodrecipes-Repository, wenn Sie Anpassungstechniken verwenden, die nicht von Forge stammen. Informationen zur Forge-basierten Anpassung finden Sie im Forge-spezifischen Rezept-Repository.**  
Führen Sie die folgenden Befehle aus, um die SageMaker HyperPod CLI zu installieren:

**Anmerkung**  
Stellen Sie sicher, dass Sie sich nicht in einer aktiven Conda/Anaconda/Miniconda-Umgebung oder einer anderen virtuellen Umgebung befinden  
Wenn ja, verlassen Sie die Umgebung bitte mit:  
`conda deactivate`für Conda/Anaconda/Miniconda-Umgebungen
`deactivate`für virtuelle Python-Umgebungen

 Wenn Sie eine Technik zur Anpassung verwenden, die nicht von Forge stammt, laden Sie sagemaker-hyperpod-recipes sie wie folgt herunter:

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

Wenn Sie ein **Forge-Abonnent sind,** sollten Sie die Rezepte mithilfe des unten genannten Verfahrens herunterladen.

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

**Tipp**  
Um vor der Ausführung eine [neue virtuelle Umgebung](https://docs.python.org/3/library/venv.html) zu verwenden`pip install -e .`, führen Sie folgenden Befehl aus:  
`python -m venv nova_forge`
`source nova_forge/bin/activate`
In Ihrer Befehlszeile wird nun (nova\$1forge) am Anfang Ihrer Eingabeaufforderung angezeigt
Dadurch wird sichergestellt, dass bei der Verwendung der CLI keine konkurrierenden Abhängigkeiten bestehen

**Zweck**: Warum tun wir das`pip install -e .`?

Dieser Befehl installiert die SageMaker HyperPod CLI im bearbeitbaren Modus, sodass Sie aktualisierte Rezepte verwenden können, ohne sie jedes Mal neu installieren zu müssen. Außerdem können Sie neue Rezepte hinzufügen, die von der CLI automatisch abgerufen werden können.

## Verbindungsaufbau mit Ihrem Cluster
<a name="nova-hp-essential-commands-guide-connect"></a>

Connect die SageMaker HyperPod CLI mit Ihrem Cluster, bevor Sie Jobs ausführen:

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

**Wichtig**  
Dieser Befehl erstellt eine Kontextdatei (`/tmp/hyperpod_context.json`), die für nachfolgende Befehle erforderlich ist. Wenn Sie eine Fehlermeldung darüber erhalten, dass diese Datei nicht gefunden wurde, führen Sie den Befehl connect erneut aus.

**Profi-Tipp**: Sie können Ihren Cluster weiter so konfigurieren, dass er immer den `kubeflow` Namespace verwendet, indem Sie das `--namespace kubeflow` Argument wie folgt zu Ihrem Befehl hinzufügen:

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

Dies erspart Ihnen den Aufwand, das `-n kubeflow` bei der Interaktion mit Ihren Jobs in jedem Befehl hinzufügen zu müssen.

## Einen Ausbildungsjob beginnen
<a name="nova-hp-essential-commands-guide-start-job"></a>

**Anmerkung**  
Wenn Sie PPO/RFT Jobs ausführen, stellen Sie sicher, dass Sie Labelauswahl-Einstellungen hinzufügen, `src/hyperpod_cli/sagemaker_hyperpod_recipes/recipes_collection/cluster/k8s.yaml` sodass alle Pods auf demselben Knoten geplant sind.  

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

Starten Sie einen Trainingsjob mithilfe eines Rezepts mit optionalen Parameterüberschreibungen:

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

**Erwartete Ausgabe**:

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

## Jobstatus wird überprüft
<a name="nova-hp-essential-commands-guide-status"></a>

Überwachen Sie Ihre laufenden Jobs mit kubectl:

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

**Pod-Status verstehen**  
In der folgenden Tabelle werden die häufigsten Pod-Status erklärt:


| Status | Description | 
| --- |--- |
| `Pending` | Der Pod wurde akzeptiert, aber noch nicht für einen Knoten geplant oder wartet darauf, dass Container-Images abgerufen werden | 
| `Running` | Pod, der an einen Knoten gebunden ist, auf dem mindestens ein Container läuft oder gestartet wird | 
| `Succeeded` | Alle Container wurden erfolgreich abgeschlossen und werden nicht neu gestartet | 
| `Failed` | Alle Container wurden beendet, wobei mindestens einer mit einem Fehler endete | 
| `Unknown` | Der Pod-Status kann nicht bestimmt werden (normalerweise aufgrund von Problemen mit der Knotenkommunikation) | 
| `CrashLoopBackOff` | Container schlägt wiederholt fehl; Kubernetes zieht sich von Neustartversuchen zurück | 
| `ImagePullBackOff` / `ErrImagePull` | Das Container-Image konnte nicht aus der Registrierung abgerufen werden | 
| `OOMKilled` | Der Container wurde wegen Überschreitung der Speichergrenzen beendet | 
| `Completed` | Job oder Pod erfolgreich abgeschlossen (Batch-Job-Abschluss) | 

**Tipp**  
Verwenden Sie die `-w` Flagge, um sich die Aktualisierungen des Pod-Status in Echtzeit anzusehen. Drücken Sie`Ctrl+C`, um die Wiedergabe zu beenden.

## Job-Logs überwachen
<a name="nova-hp-essential-commands-guide-logs"></a>

Sie können Ihre Protokolle auf drei Arten anzeigen:

**Verwenden CloudWatch**  
Ihre Protokolle sind in Ihrem AWS Konto verfügbar, das den Hyperpodcluster unter enthält. CloudWatch Um sie in Ihrem Browser anzuzeigen, navigieren Sie in Ihrem Konto zur CloudWatch Startseite und suchen Sie nach Ihrem Clusternamen. Wenn Ihr Cluster beispielsweise aufgerufen würde, hätte `my-hyperpod-rig` die Protokollgruppe das Präfix:
+ **Protokollgruppe**: `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}`
+ Sobald Sie in der Protokollgruppe sind, können Sie Ihr spezifisches Protokoll anhand der Knoteninstanz-ID wie - finden`hyperpod-i-00b3d8a1bf25714e4`.
  + `i-00b3d8a1bf25714e4`steht hier für den Hyperpod-freundlichen Computernamen, auf dem Ihr Trainingsjob ausgeführt wird. **Erinnern Sie sich, wie wir in der vorherigen `kubectl get pods -o wide -w -n kubeflow | (head -n1 ; grep my-cpt-run)` Befehlsausgabe eine Spalte namens NODE erfasst haben.**
  + Der „Master“ -Knoten wurde in diesem Fall auf Hyperpod `i-00b3d8a1bf25714e4` - ausgeführt. Daher verwenden wir diese Zeichenfolge, um die anzuzeigende Protokollgruppe auszuwählen. Wählen Sie den aus, der sagt `SagemakerHyperPodTrainingJob/rig-group/[NODE]`

**CloudWatch Insights verwenden**  
Wenn Sie Ihren Jobnamen griffbereit haben und nicht alle oben genannten Schritte durchführen möchten, können Sie einfach alle Logs unter abfragen, `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}` um das individuelle Protokoll zu finden.

CPT:

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

Um den Auftrag abzuschließen, ersetzen Sie ihn durch `Starting CPT Job` `CPT Job completed`

Dann können Sie sich durch die Ergebnisse klicken und diejenige mit der Aufschrift „Epoche 0" auswählen, da dies Ihr Masternode sein wird.

**Mit dem AWS CLI**  
Sie können wählen, ob Sie Ihre Protokolle mit dem verfolgen möchten AWS CLI. Bevor Sie dies tun, überprüfen Sie bitte Ihre AWS CLI Version mit`aws --version`. Es wird auch empfohlen, dieses Utility-Skript zu verwenden, das bei der Live-Protokollverfolgung in Ihrem Terminal hilft

**für V1**:

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

**für V2**:

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

## Aktive Jobs auflisten
<a name="nova-hp-essential-commands-guide-list-jobs"></a>

Alle Jobs anzeigen, die in Ihrem Cluster ausgeführt werden:

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

**Beispielausgabe:**

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

## Stornieren eines Auftrags
<a name="nova-hp-essential-commands-guide-cancel-job"></a>

Stoppen Sie einen laufenden Job jederzeit:

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

**Finden Sie Ihren Jobnamen**  
**Option 1: Aus deinem Rezept**

Der Jobname ist im `run` Block Ihres Rezepts angegeben:

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

**Option 2: Aus dem Befehl list-jobs**

Verwenden `hyperpod list-jobs -n kubeflow` und kopieren Sie das `Name` Feld aus der Ausgabe.

## Einen Evaluierungsjob ausführen
<a name="nova-hp-essential-commands-guide-evaluation"></a>

Evaluieren Sie ein trainiertes Modell oder Basismodell anhand eines Bewertungsrezepts.

**Voraussetzungen**  
Bevor Sie Evaluierungsjobs ausführen, stellen Sie sicher, dass Sie über Folgendes verfügen:
+ Checkpoint Amazon S3 S3-URI aus der `manifest.json` Datei Ihres Trainingsjobs (für trainierte Modelle)
+ Bewertungsdatensatz wurde im richtigen Format auf Amazon S3 hochgeladen
+ Amazon S3-Pfad für Evaluierungsergebnisse ausgeben

**Befehl**  
Führen Sie den folgenden Befehl aus, um einen Evaluierungsjob zu starten:

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

**Beschreibungen der Parameter**:
+ `recipes.run.name`: Eindeutiger Name für Ihren Bewertungsjob
+ `recipes.run.model_name_or_path`: Amazon S3 S3-URI von `manifest.json` oder Basismodellpfad (z. B.`nova-micro/prod`)
+ `recipes.run.output_s3_path`: Amazon S3 S3-Standort für Evaluierungsergebnisse
+ `recipes.run.data_s3_path`: Amazon S3 S3-Speicherort Ihres Bewertungsdatensatzes

**Tipps**:
+ **Modellspezifische Rezepte**: Für jede Modellgröße (Micro, Lite, Pro) gibt es ein eigenes Bewertungsrezept
+ **Bewertung des Basismodells**: Verwenden Sie Basismodellpfade (z. B.`nova-micro/prod`) anstelle von Checkpoints, um Basismodelle URIs zu bewerten

**Format der Bewertungsdaten**  
**Eingabeformat (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"
}
```

**Ausgabeformat**:

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

**Feldbeschreibungen**:
+ `prompt`: Formatierte Eingabe, die an das Modell gesendet wurde
+ `inference`: Die generierte Antwort des Modells
+ `gold`: Richtige Antwort aus dem Eingabedatensatz erwartet
+ `metadata`: Optionale Metadaten, die von der Eingabe übergeben wurden

## Häufige Probleme
<a name="nova-hp-essential-commands-guide-troubleshooting"></a>
+ `ModuleNotFoundError: No module named 'nemo_launcher'`, je nachdem, wo es installiert `hyperpod_cli` ist`nemo_launcher`, müssen Sie möglicherweise zu Ihrem Python-Pfad etwas hinzufügen. Beispielbefehl:

  ```
  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'`weist darauf hin, dass Sie den Befehl hyperpod connect cluster nicht ausgeführt haben.
+ Wenn Ihr Job nicht geplant ist, überprüfen Sie noch einmal, ob die Ausgabe Ihrer SageMaker HyperPod CLI diesen Abschnitt mit Jobnamen und anderen Metadaten enthält. Wenn nicht, installieren Sie helm chart erneut, indem Sie Folgendes ausführen:

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