# Guia de comandos essenciais do Amazon SageMaker HyperPod
<a name="nova-hp-essential-commands-guide"></a>

O Amazon SageMaker HyperPod fornece uma ampla funcionalidade de linha de comando para gerenciar fluxos de trabalho de treinamento. Este guia aborda os comandos essenciais para operações comuns, desde a conexão com seu cluster até o monitoramento do progresso da tarefa.

**Pré-requisitos**  
Antes de usar esses comandos, conclua a seguinte configuração:
+ Cluster do SageMaker HyperPod com o RIG criado (normalmente em us-east-1)
+ Saída do bucket do Amazon S3 criado para artefatos de treinamento
+ Perfis do IAM configurados com as permissões apropriadas
+ Dados de treinamento enviados no formato JSONL correto
+ Sincronização do FSx para Lustre concluída (verifique nos logs do cluster no primeiro trabalho)

**Topics**
+ [Instalação da CLI para fórmulas](#nova-hp-essential-commands-guide-install)
+ [Conectar-se a um cluster](#nova-hp-essential-commands-guide-connect)
+ [Início de uma tarefa de treinamento](#nova-hp-essential-commands-guide-start-job)
+ [Monitoramento do status da tarefa](#nova-hp-essential-commands-guide-status)
+ [Monitoramento dos logs de tarefas](#nova-hp-essential-commands-guide-logs)
+ [Listagem das tarefas ativas](#nova-hp-essential-commands-guide-list-jobs)
+ [Cancelar uma tarefa](#nova-hp-essential-commands-guide-cancel-job)
+ [Execução de uma tarefa de avaliação](#nova-hp-essential-commands-guide-evaluation)
+ [Problemas comuns](#nova-hp-essential-commands-guide-troubleshooting)

## Instalação da CLI para fórmulas
<a name="nova-hp-essential-commands-guide-install"></a>

Navegue até a raiz do repositório de fórmulas antes de executar o comando de instalação.

**Use o repositório Hyperpodrecipes se estiver usando técnicas de personalização que não sejam do Forge. Para personalização baseada no Forge, consulte o repositório de fórmulas específico do Forge.**  
Execute os seguintes comandos para instalar a CLI do SageMaker HyperPod:

**nota**  
Verifique se você não está em um ambiente conda/anaconda/miniconda ativo ou em outro ambiente virtual  
Se estiver, saia do ambiente usando:  
`conda deactivate` para ambientes conda/anaconda/miniconda
`deactivate` para ambientes virtuais Python

 Se você estiver usando uma técnica de personalização que não seja do Forge, faça o download de sagemaker-hyperpod-recipes, conforme mostrado abaixo:

```
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 você é **assinante do Forge,** deve fazer o download das fórmulas usando o processo mencionado abaixo.

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

**dica**  
Para usar um [novo ambiente virtual](https://docs.python.org/3/library/venv.html) antes de executar `pip install -e .`, execute:  
`python -m venv nova_forge`
`source nova_forge/bin/activate`
Sua linha de comando agora será exibida (nova\_forge) no início do seu prompt
Isso garante que não haja dependências concorrentes ao usar a CLI

**Objetivo**: por que executamos `pip install -e .`?

Esse comando instala a CLI do SageMaker HyperPod no modo editável, permitindo que você use fórmulas atualizadas sem precisar reinstalá-las todas as vezes. Ele também permite que você adicione novas fórmulas que a CLI pode coletar automaticamente.

## Conectar-se a um cluster
<a name="nova-hp-essential-commands-guide-connect"></a>

Conecte a CLI do SageMaker HyperPod ao seu cluster antes de executar qualquer tarefa:

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

**Importante**  
Esse comando cria um arquivo de contexto (`/tmp/hyperpod_context.json`) que os comandos subsequentes exigem. Se você vir um erro informando que esse arquivo não foi encontrado, execute novamente o comando connect.

**Dica profissional**: você pode configurar ainda mais seu cluster para sempre usar o namespace `kubeflow` adicionando o argumento `--namespace kubeflow` ao seu comando da seguinte forma:

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

Isso elimina a necessidade de adicionar o `-n kubeflow` em cada comando ao interagir com suas tarefas.

## Início de uma tarefa de treinamento
<a name="nova-hp-essential-commands-guide-start-job"></a>

**nota**  
Se estiver executando tarefas de PPO/RFT, certifique-se de adicionar as configurações do seletor de rótulos a `src/hyperpod_cli/sagemaker_hyperpod_recipes/recipes_collection/cluster/k8s.yaml` para que todos os pods sejam programados no mesmo nó.  

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

Inicie uma tarefa de treinamento usando uma fórmula com substituições de parâmetros opcionais:

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

**Saída esperada**:

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

## Monitoramento do status da tarefa
<a name="nova-hp-essential-commands-guide-status"></a>

Monitore suas tarefas em execução usando o kubectl:

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

**Noções básicas sobre os status de pods**  
A tabela abaixo explica os status comuns de pods:


| Status | Descrição | 
| --- |--- |
| `Pending` | O pod foi aceito, mas ainda não foi programado para um nó, ou está aguardando a extração das imagens do contêiner | 
| `Running` | Pod vinculado a um nó com pelo menos um contêiner em execução ou iniciando | 
| `Succeeded` | Todos os contêineres foram concluídos com sucesso e não serão reiniciados | 
| `Failed` | Todos os contêineres foram encerrados, com pelo menos um apresentando falha | 
| `Unknown` | O estado do pod não pode ser determinado (geralmente devido a problemas de comunicação dos nós) | 
| `CrashLoopBackOff` | O contêiner falha repetidamente; o Kubernetes está suspendendo novas tentativas de reinicialização | 
| `ImagePullBackOff` / `ErrImagePull` | Não é possível extrair a imagem do contêiner do registro | 
| `OOMKilled` | Contêiner encerrado por exceder os limites de memória | 
| `Completed` | Tarefa ou pod concluído com êxito (conclusão das tarefas em lote) | 

**dica**  
Use o sinalizador `-w` para acompanhar as atualizações de status dos pods em tempo real. Pressione `Ctrl+C` para parar de acompanhar.

## Monitoramento dos logs de tarefas
<a name="nova-hp-essential-commands-guide-logs"></a>

Você pode visualizar seus logs de três maneiras:

**Usar o CloudWatch**  
Seus logs estão disponíveis em sua conta da AWS que contém o Hyperpodcluster no CloudWatch. Para visualizá-los em seu navegador, navegue até a página inicial do CloudWatch em sua conta e pesquise o nome do seu cluster. Por exemplo, se seu cluster se chamasse `my-hyperpod-rig`, o grupo de logs teria o prefixo:
+ **Grupo de logs**: `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}`
+ Quando estiver no grupo de logs, você poderá encontrar seu log específico usando o ID da instância do nó, como `hyperpod-i-00b3d8a1bf25714e4`.
  + `i-00b3d8a1bf25714e4` aqui representa o nome da máquina compatível com Hyperpod em que sua tarefa de treinamento está sendo executada. Lembre-se de como, na saída anterior do comando `kubectl get pods -o wide -w -n kubeflow | (head -n1 ; grep my-cpt-run)`, capturamos uma coluna chamada **NODE**.
  + Nesse caso, a execução do nó “principal” estava sendo realizada em hyperpod-`i-00b3d8a1bf25714e4` e, portanto, usaremos essa string para selecionar o grupo de logs a ser visualizado. Selecione a que diz `SagemakerHyperPodTrainingJob/rig-group/[NODE]`

**Uso do CloudWatch Insights**  
Se você souber o nome da sua tarefa e não quiser seguir todas as etapas acima, basta consultar todos os logs em `/aws/sagemaker/Clusters/my-hyperpod-rig/{UUID}` para encontrar o log individual.

CPT:

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

Para concluir a tarefa, substitua `Starting CPT Job` por `CPT Job completed`

Em seguida, você pode clicar nos resultados e escolher aquele que diz “Epoch 0”, pois este será seu nó principal.

**Como usar o AWS CLI**  
Você pode optar por rastrear seus logs usando a CLI AWS CLI. Antes de fazer isso, verifique sua AWS CLI versão da AWS CLI em uso `aws --version`. Também é recomendável usar esse script utilitário que ajuda no rastreamento de logs em tempo real em seu 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
```

## Listagem das tarefas ativas
<a name="nova-hp-essential-commands-guide-list-jobs"></a>

Veja todas as tarefas em execução no seu cluster:

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

**Resultado do exemplo**:

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

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

Interrompa uma tarefa em execução a qualquer momento:

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

**Localização do nome da sua tarefa**  
**Opção 1: da sua fórmula**

O nome da tarefa é especificado no bloco `run` da sua fórmula:

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

**Opção 2: do comando list-jobs**

Use `hyperpod list-jobs -n kubeflow` e copie o campo `Name` da saída.

## Execução de uma tarefa de avaliação
<a name="nova-hp-essential-commands-guide-evaluation"></a>

Avalie um modelo treinado ou modelo de base usando uma fórmula de avaliação.

**Pré-requisitos**  
Antes de executar tarefas de avaliação, verifique se você tem:
+ O URI do ponto de verificação do Amazon S3 do arquivo `manifest.json` da tarefa de treinamento (para modelos treinados)
+ O conjunto de dados de avaliação carregado para o Amazon S3 no formato correto
+ O caminho da saída do Amazon S3 para obter os resultados da avaliação

**Command**  
Execute o seguinte comando para iniciar uma tarefa de avaliação:

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

**Descrições dos parâmetros**:
+ `recipes.run.name`: o nome exclusivo para sua tarefa de avaliação
+ `recipes.run.model_name_or_path`: o URI do Amazon S3 de `manifest.json` ou o caminho do modelo base (p. ex., `nova-micro/prod`)
+ `recipes.run.output_s3_path`: o local do Amazon S3 para obter os resultados da avaliação
+ `recipes.run.data_s3_path`: o local do seu conjunto de dados de avaliação no Amazon S3

**Dicas**:
+ **Fórmulas específicas de modelos**: cada tamanho de modelo (micro, lite, pro) tem sua própria fórmula de avaliação
+ **Avaliação de modelos de base**: use caminhos de modelos de base (p. ex., `nova-micro/prod`) em vez de URIs de ponto de verificação para avaliar modelos de base

**Formato dos dados de avaliação**  
**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 saída**:

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

**Descrições dos campos**:
+ `prompt`: entrada formatada enviada ao modelo
+ `inference`: resposta gerada do modelo
+ `gold`: resposta correta esperada do conjunto de dados de entrada
+ `metadata`: metadados opcionais transmitidos da entrada

## Problemas comuns
<a name="nova-hp-essential-commands-guide-troubleshooting"></a>
+ `ModuleNotFoundError: No module named 'nemo_launcher'`, talvez seja necessário adicionar `nemo_launcher` ao seu caminho Python com base em onde `hyperpod_cli` está instalado. Exemplo de comando:

  ```
  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 você não executou o comando hyperpod connect cluster.
+ Caso sua tarefa não apareça como agendada, verifique se a saída da CLI do SageMaker HyperPod tem essa seção com os nomes de tarefas e outros metadados. Caso contrário, reinstale o chart do Helm executando:

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