# Guía de comandos esenciales de Amazon SageMaker HyperPod
<a name="nova-hp-essential-commands-guide"></a>

Amazon SageMaker HyperPod dispone de muchas herramientas de línea de comandos para administrar los flujos de trabajo de entrenamiento. En esta guía se describen los comandos esenciales para las operaciones habituales, desde la conexión al clúster hasta la supervisión del progreso del trabajo.

**Requisitos previos**  
Antes de usar estos comandos, asegúrese de haber realizado la siguiente configuración:
+ Clúster de SageMaker HyperPod creado con RIG (normalmente en us-east-1)
+ Bucket de Amazon S3 de salida creado para artefactos de entrenamiento
+ Roles de IAM con los permisos adecuados
+ Datos de entrenamiento cargados en el formato JSONL correcto
+ Sincronización con FSx para Lustre completada (compruébelo en los registros del clúster en el primer trabajo)

**Topics**
+ [Instalación de la CLI de la fórmula](#nova-hp-essential-commands-guide-install)
+ [Conexión al clúster](#nova-hp-essential-commands-guide-connect)
+ [Inicio de un trabajo de entrenamiento](#nova-hp-essential-commands-guide-start-job)
+ [Seguimiento del estado del trabajo](#nova-hp-essential-commands-guide-status)
+ [Supervisión de los registros de trabajo](#nova-hp-essential-commands-guide-logs)
+ [Listado de los trabajos activos](#nova-hp-essential-commands-guide-list-jobs)
+ [Cancelar una tarea](#nova-hp-essential-commands-guide-cancel-job)
+ [Puesta en marcha de un trabajo de evaluación](#nova-hp-essential-commands-guide-evaluation)
+ [Problemas comunes](#nova-hp-essential-commands-guide-troubleshooting)

## Instalación de la CLI de la fórmula
<a name="nova-hp-essential-commands-guide-install"></a>

Desplácese hasta la raíz del repositorio de fórmulas antes de usar el comando de instalación.

**Utilice el repositorio de fórmulas de HyperPod si utiliza técnicas de personalización que no sean de Forge. Para la personalización basada en Forge, consulte el repositorio de fórmulas específico de Forge.**  
Use los siguientes comandos para instalar la CLI de SageMaker HyperPod:

**nota**  
Asegúrese de no estar en un entorno conda, anaconda o miniconda activo o en algún otro entorno virtual  
Si es así, salga del entorno mediante:  
`conda deactivate` para entornos conda, anaconda o miniconda
`deactivate` para entornos virtuales de Python

 Si está utilizando una técnica de personalización que no sea de Forge, descargue las fórmulas de sagemaker-hyperpod como se muestra a continuación:

```
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 cuenta con una **suscripción a Forge,** debería poder descargar las fórmulas mediante el proceso mencionado a continuación.

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

**sugerencia**  
Para usar un [nuevo entorno virtual](https://docs.python.org/3/library/venv.html) antes de poner en marcha `pip install -e .`, use:  
`python -m venv nova_forge`
`source nova_forge/bin/activate`
La línea de comandos ahora mostrará (nova\_forge) al principio de la petición.
Esto garantiza que las dependencias no compitan cuando se use la CLI.

**Propósito**: ¿por qué usamos `pip install -e .`?

Este comando instala la CLI de SageMaker HyperPod en modo editable, lo que le permite utilizar fórmulas actualizadas sin tener que volver a instalarlas cada vez que quiera usarlas. También le permite agregar nuevas fórmulas que la CLI puede usar automáticamente.

## Conexión al clúster
<a name="nova-hp-essential-commands-guide-connect"></a>

Conecte la CLI de SageMaker HyperPod a su clúster antes de llevar a cabo cualquier trabajo:

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

**importante**  
Este comando crea un archivo de contexto (`/tmp/hyperpod_context.json`) necesario para los comandos que se usarán a continuación. Si ve un error indicando que no se puede encontrar el archivo, vuelva a usar el comando connect.

**Consejo profesional**: si quiere configurar el clúster para que utilice siempre el espacio de nombres `kubeflow`, agregue el argumento `--namespace kubeflow` al comando de la siguiente manera:

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

De esta forma no tendrá que agregar `-n kubeflow` en todos los comandos al interactuar con sus tareas.

## Inicio de un trabajo de entrenamiento
<a name="nova-hp-essential-commands-guide-start-job"></a>

**nota**  
Si lleva a cabo trabajos de PPO o RFT, asegúrese de agregar los ajustes del selector de etiquetas para `src/hyperpod_cli/sagemaker_hyperpod_recipes/recipes_collection/cluster/k8s.yaml` de forma que todos los pods estén programados en el mismo nodo.  

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

Lanzamiento de un trabajo de entrenamiento mediante una fórmula con modificaciones de parámetros opcionales:

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

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

## Seguimiento del estado del trabajo
<a name="nova-hp-essential-commands-guide-status"></a>

Supervise los trabajos en marcha con kubectl:

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

**Explicación de los estados de los pods**  
En la siguiente tabla se explican los estados comunes de los pods:


| Estado | Descripción | 
| --- |--- |
| `Pending` | Se acepta el pod, pero aún no se ha programado en un nodo o se está esperando a que se extraigan las imágenes del contenedor | 
| `Running` | El pod está enlazado a un nodo con al menos un contenedor en marcha o iniciándose. | 
| `Succeeded` | Todos los contenedores se completaron correctamente y no se reiniciarán. | 
| `Failed` | Todos los contenedores terminaron con al menos uno de ellos devolviendo un error. | 
| `Unknown` | No se puede determinar el estado del pod (normalmente debido a problemas de comunicación entre los nodos). | 
| `CrashLoopBackOff` | El contenedor falla repetidamente; Kubernetes se retrasa ante los intentos de reinicio. | 
| `ImagePullBackOff` / `ErrImagePull` | No se pudo extraer la imagen del contenedor del registro. | 
| `OOMKilled` | El contenedor se canceló por superar los límites de memoria. | 
| `Completed` | El trabajo o el pod finalizaron correctamente (finalización del trabajo por lotes). | 

**sugerencia**  
Use el indicador `-w` para ver las actualizaciones del estado del pod en tiempo real. Pulse `Ctrl+C` para dejar de ver.

## Supervisión de los registros de trabajo
<a name="nova-hp-essential-commands-guide-logs"></a>

Puede ver los registros de tres maneras:

**Uso de CloudWatch**  
Los registros están disponibles en la cuenta de AWS que contiene el clúster de HyperPod en CloudWatch. Para verlos en su navegador, vaya a la página de inicio de CloudWatch en su cuenta y busque el nombre del clúster. Por ejemplo, si su clúster se llamara `my-hyperpod-rig`, el grupo de registro tendría el prefijo:
+ **Grupo de registro**: `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}`
+ Una vez en el grupo de registro, podrá encontrar el registro específico mediante el ID de la instancia del nodo, como - `hyperpod-i-00b3d8a1bf25714e4`.
  + `i-00b3d8a1bf25714e4` aquí representa el nombre de la máquina compatible con HyperPod en la que se está poniendo en marcha el trabajo de entrenamiento. Recuerde que en el resultado del comando `kubectl get pods -o wide -w -n kubeflow | (head -n1 ; grep my-cpt-run)` anterior capturamos una columna llamada **NODE**.
  + En este caso, el nodo maestro se ponía en marcha en hyperpod-`i-00b3d8a1bf25714e4` y, por lo tanto, utilizaremos esa cadena para seleccionar el grupo de registro que queremos ver. Seleccione el que dice `SagemakerHyperPodTrainingJob/rig-group/[NODE]`.

**Uso de Información de CloudWatch**  
Si tiene a mano el nombre de su trabajo y no desea seguir todos los pasos anteriores, simplemente consulte todos los registros en `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}` para encontrar el registro individual.

CPT:

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

Para completar el trabajo, sustituya `Starting CPT Job` por `CPT Job completed`.

Luego, puede hacer clic en los resultados y elegir el que diga “Epoch 0”, ya que ese será el nodo maestro.

**Uso de AWS CLI**  
Puede optar por rastrear los registros mediante AWS CLI AWS CLI. Antes de hacerlo, compruebe su versión de AWS CLI utilizando `aws --version`. También se recomienda usar este script de utilidad que ayuda a rastrear los registros en tiempo real en su terminal.

**Para V1**:

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

**Para V2**:

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

## Listado de los trabajos activos
<a name="nova-hp-essential-commands-guide-list-jobs"></a>

Vea todos los trabajos que están en marcha en el clúster:

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

**Ejemplo de código de salida**:

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

## Cancelar una tarea
<a name="nova-hp-essential-commands-guide-cancel-job"></a>

Detenga el trabajo en marcha en cualquier momento:

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

**Búsqueda del nombre del trabajo**  
**Opción 1: a partir de una fórmula**

El nombre del trabajo se especifica en el bloque `run` de la fórmula:

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

**Opción 2: a partir del comando list-jobs**

Use `hyperpod list-jobs -n kubeflow` y copie el campo `Name` de la salida.

## Puesta en marcha de un trabajo de evaluación
<a name="nova-hp-essential-commands-guide-evaluation"></a>

Evalúe un modelo entrenado o un modelo base mediante una fórmula de evaluación.

**Requisitos previos**  
Antes de poner en marcha trabajos de evaluación, asegúrese de que dispone de lo siguiente:
+ URI del punto de control de Amazon S3 del archivo `manifest.json` de su trabajo de entrenamiento (para modelos entrenados)
+ Conjunto de datos de evaluación cargado en Amazon S3 en el formato correcto
+ Ruta de Amazon S3 para ver los resultados de la evaluación

**Comando**  
Use el siguiente comando para iniciar un trabajo de evaluación:

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

**Descripciones de los parámetros**:
+ `recipes.run.name`: nombre único del trabajo de evaluación
+ `recipes.run.model_name_or_path`: URI de Amazon S3 de `manifest.json` o de la ruta del modelo base (por ejemplo, `nova-micro/prod`)
+ `recipes.run.output_s3_path`: ubicación de Amazon S3 para los resultados de la evaluación
+ `recipes.run.data_s3_path`: ubicación en Amazon S3 del conjunto de datos de evaluación

**Consejos**:
+ **Fórmulas específicas para cada modelo**: cada tamaño de modelo (micro, lite, pro) tiene su propia fórmula de evaluación.
+ **Evaluación del modelo base**: utilice las rutas del modelo base (por ejemplo, `nova-micro/prod`) en lugar de los URI de puntos de control para evaluar los modelos base.

**Formato de los datos de evaluación**  
**Formato de entrada (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 de salida**:

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

**Descripción de campos**:
+ `prompt`: entrada formateada enviada al modelo
+ `inference`: respuesta generada por el modelo
+ `gold`: respuesta correcta esperada del conjunto de datos de entrada
+ `metadata`: metadatos opcionales transferidos desde la entrada

## Problemas comunes
<a name="nova-hp-essential-commands-guide-troubleshooting"></a>
+ `ModuleNotFoundError: No module named 'nemo_launcher'`, puede que tenga que agregar `nemo_launcher` a su ruta de Python en función del lugar donde se haya instalado `hyperpod_cli`. Comando de ejemplo

  ```
  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 que no puso en marcha el comando hyperpod connect cluster.
+ Si no ve el trabajo programado, compruebe si la salida de la CLI de SageMaker HyperPod incluye esta sección con los nombres de los trabajos y otros metadatos. Si no es así, vuelva a instalar el gráfico de Helm usando:

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