Guía de comandos esenciales de Amazon SageMaker HyperPod

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:

Instalación de la CLI de la fórmula

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:

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

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

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

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

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

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

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:

Supervisión de los registros de trabajo

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:

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 la AWSAWS CLI

Puede optar por rastrear los registros mediante 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

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

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

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:

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:

Consejos:

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:

Problemas comunes