As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Usar o operador de treinamento para executar tarefas
<a name="sagemaker-eks-operator-usage"></a>

 Para usar o kubectl para executar a tarefa, você precisa criar um job.yaml para indicar as respectivas especificações e executar `kubectl apply -f job.yaml` para enviá-la. Nesse arquivo YAML, você pode especificar configurações personalizadas no argumento `logMonitoringConfiguration` para definir regras de monitoramento automatizadas que analisam as saídas de log da tarefa de treinamento distribuído para detectar problemas e executar a recuperação. 

```
apiVersion: sagemaker.amazonaws.com/v1
kind: HyperPodPyTorchJob
metadata:
  labels:
    app.kubernetes.io/name: HyperPod
    app.kubernetes.io/managed-by: kustomize
  name: &jobname xxx
  annotations:
    XXX: XXX
    ......
spec:
  nprocPerNode: "X"
  replicaSpecs:
    - name: 'XXX'
      replicas: 16
      template:
        spec:
          nodeSelector:
            beta.kubernetes.io/instance-type: ml.p5.48xlarge
          containers:
            - name: XXX
              image: XXX
              imagePullPolicy: Always
              ports:
                - containerPort: 8080 # This is the port that HyperPodElasticAgent listens to
              resources:
                limits:
                  nvidia.com/gpu: 8
                  hugepages-2Mi: 5120Mi
                requests:
                  nvidia.com/gpu: 8
                  hugepages-2Mi: 5120Mi
                  memory: 32000Mi
          ......        
  runPolicy:
    jobMaxRetryCount: 50
    restartPolicy:
      numRestartBeforeFullJobRestart: 3 
      evalPeriodSeconds: 21600 
      maxFullJobRestarts: 1
    cleanPodPolicy: "All"
    logMonitoringConfiguration: 
      - name: "JobStart"
        logPattern: ".*Experiment configuration.*" # This is the start of the training script
        expectedStartCutOffInSeconds: 120 # Expected match in the first 2 minutes
      - name: "JobHangingDetection"
        logPattern: ".*\\[Epoch 0 Batch \\d+.*'training_loss_step': (\\d+(\\.\\d+)?).*"
        expectedRecurringFrequencyInSeconds: 300 # If next batch is not printed within 5 minute, consider it hangs. Or if loss is not decimal (e.g. nan) for 2 minutes, mark it hang as well.
        expectedStartCutOffInSeconds: 600 # Allow 10 minutes of job startup time
      - name: "NoS3CheckpointingDetection"
        logPattern: ".*The checkpoint is finalized. All shards is written.*"
        expectedRecurringFrequencyInSeconds: 600 # If next checkpoint s3 upload doesn't happen within 10 mins, mark it hang.
        expectedStartCutOffInSeconds: 1800 # Allow 30 minutes for first checkpoint upload
      - name: "LowThroughputDetection"
        logPattern: ".*\\[Epoch 0 Batch \\d+.*'samples\\/sec': (\\d+(\\.\\d+)?).*"
        metricThreshold: 80 # 80 samples/sec
        operator: "lteq"
        metricEvaluationDataPoints: 25 # if throughput lower than threshold for 25 datapoints, kill the job
```

Se você quiser usar as opções de monitoramento de registros, certifique-se de emitir o registro de treinamento para o. `sys.stdout` HyperPod O agente elástico monitora os registros de treinamento em sys.stdout, que são salvos em. `/tmp/hyperpod/` Você pode usar o comando a seguir para emitir os logs de treinamento.

```
logging.basicConfig(format="%(asctime)s [%(levelname)s] %(name)s: %(message)s", level=logging.INFO, stream=sys.stdout)
```

 A seguinte tabela descreve todas as configurações possíveis de monitoramento de logs: 


| Parâmetro | Usage | 
| --- | --- | 
| jobMaxRetryContagem | Número máximo de reinicializações em nível de processo. | 
| Política de reinicialização: numRestartBefore FullJobRestart | Número máximo de reinicializações em nível de processo antes que o operador reinicie em nível de tarefa. | 
| Política de reinicialização: evalPeriodSeconds | O período de avaliação do limite de reinicialização em segundos. | 
| Política de reinicialização: reinicia maxFullJob | Número máximo de reinicializações completas da tarefa antes que ela falhe. | 
| cleanPodPolicy | Especifica os pods que o operador deve limpar. Os valores aceitos são All, OnlyComplete e None. | 
| logMonitoringConfiguration | As regras de monitoramento de logs para detecção de tarefas lentas e interrompidas. | 
| expectedRecurringFrequencyInSeconds | Intervalo de tempo entre duas LogPattern partidas consecutivas após o qual a regra é avaliada como HANGING. Se não for especificado, não existe restrição de tempo entre LogPattern partidas consecutivas. | 
| expectedStartCutOffInSeconds | Hora da primeira LogPattern partida, após a qual a regra é avaliada como HANGING. Se não for especificado, não existe restrição de tempo para a primeira LogPattern partida. | 
| logPattern | Expressão regular que identifica as linhas de log às quais a regra se aplica quando a regra está ativa. | 
| metricEvaluationDataPontos | Número de vezes consecutivas em que uma regra deve ser avaliada como SLOW antes de marcar uma tarefa como SLOW. Se não especificado, o padrão será 1. | 
| metricThreshold | Limite para o valor extraído LogPattern com um grupo de captura. Quando não especificado, a avaliação da métrica não é executada. | 
| operador | A desigualdade a ser aplicada à configuração de monitoramento. Os valores aceitos são gt, gteq, lt, lteq e eq. | 
| stopPattern | Expressão regular para identificar a linha de log na qual desativar a regra. Se não especificado, a regra ficará sempre ativa. | 
| faultOnMatch | Indica se uma combinação de LogPattern deve acionar imediatamente uma falha no trabalho. Quando verdadeiro, o trabalho será marcado como defeituoso assim que LogPattern for correspondido, independentemente dos outros parâmetros da regra. Quando falsa ou não especificada, a regra será avaliada como SLOW ou HANGING com base em outros parâmetros. | 

 Para aumentar a resiliência do treinamento, especifique os detalhes da configuração do nó sobressalente. Se sua tarefa falhar, o operador trabalhará com o Kueue para usar os nós reservados com antecedência e continuar executando a tarefa. As configurações dos nós sobressalentes exigem o Kueue; portanto, se você tentar enviar uma tarefa com nós sobressalentes, mas não tiver o Kueue instalado, a tarefa falhará. O exemplo a seguir é um arquivo `job.yaml` de amostra que contém configurações de nós sobressalentes.

```
apiVersion: sagemaker.amazonaws.com/v1
kind: HyperPodPyTorchJob
metadata:
  labels:
    kueue.x-k8s.io/queue-name: user-queue # Specify the queue to run the job.
  name: hyperpodpytorchjob-sample
spec:
  nprocPerNode: "1"
  runPolicy:
    cleanPodPolicy: "None"
  replicaSpecs: 
    - name: pods
      replicas: 1
      spares: 1 # Specify how many spare nodes to reserve.
      template:
        spec:
          containers:
            - name: XXX
              image: XXX
              
              imagePullPolicy: Always
              ports:
                - containerPort: 8080
              resources:
                requests:
                  nvidia.com/gpu: "0"
                limits:
                  nvidia.com/gpu: "0"
```

## Monitoramento
<a name="sagemaker-eks-operator-usage-monitoring"></a>

A Amazon SageMaker HyperPod está integrada à [observabilidade com o Amazon Managed Grafana e o Amazon Managed Service for Prometheus, para](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-observability-addon.html) que você possa configurar o monitoramento para coletar e alimentar métricas nessas ferramentas de observabilidade.

Também é possível coletar métricas por meio do Amazon Managed Service for Prometheus sem a observabilidade gerenciada. Para isso, inclua as métricas que você deseja monitorar em seu arquivo `job.yaml` ao executar tarefas com o `kubectl`.

```
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: hyperpod-training-operator
  namespace: aws-hyperpod
spec:
  ......
  endpoints:
    - port: 8081
      path: /metrics
      interval: 15s
```

A seguir são apresentados os eventos que o operador de treinamento emite e que você pode inserir no Amazon Managed Service for Prometheus para monitorar tarefas de treinamento.


| Event | Description | 
| --- | --- | 
| hyperpod\_training\_operator\_jobs\_created\_total | Número total de tarefas que o operador de treinamento executou. | 
| hyperpod\_training\_operator\_jobs\_restart\_latency | Latência atual de reinicialização da tarefa. | 
| hyperpod\_training\_operator\_jobs\_fault\_detection\_latency | Latência de detecção de falhas. | 
| hyperpod\_training\_operator\_jobs\_deleted\_total | Número total de tarefas excluídas. | 
| hyperpod\_training\_operator\_jobs\_successful\_total | Número total de tarefas concluídas. | 
| hyperpod\_training\_operator\_jobs\_failed\_total | Número total de tarefas com falha. | 
| hyperpod\_training\_operator\_jobs\_restarted\_total | Número total de tarefas reiniciadas automaticamente. | 

## Configuração de exemplo do Docker
<a name="sagemaker-eks-operator-usage-docker"></a>

Veja a seguir um exemplo de arquivo do Docker que você pode executar com o comando `hyperpod run`.

```
export AGENT_CMD="--backend=nccl"
exec hyperpodrun --server-host=${AGENT_HOST} --server-port=${AGENT_PORT} \
    --tee=3 --log_dir=/tmp/hyperpod \
    --nnodes=${NNODES} --nproc-per-node=${NPROC_PER_NODE} \
    --pre-train-script=/workspace/echo.sh --pre-train-args='Pre-training script' \
    --post-train-script=/workspace/echo.sh --post-train-args='Post-training script' \
    /workspace/mnist.py --epochs=1000 ${AGENT_CMD}
```

## Exemplo de configurações de monitoramento de logs
<a name="sagemaker-eks-operator-usage-log-monitoring"></a>

**Detecção de suspensão de tarefas**

Para detectar trabalhos suspensos, use as configurações a seguir. São usados os seguintes parâmetros:
+ expectedStartCutOffInSeconds — quanto tempo o monitor deve esperar antes de esperar os primeiros registros
+ expectedRecurringFrequencyInSeconds — o intervalo de tempo de espera pelo próximo lote de registros

Com essas configurações, o monitor de logs espera ver uma linha de log correspondente ao padrão regex `.*Train Epoch.*` em 60 segundos após o início da tarefa de treinamento. Após a primeira aparição, o monitor espera ver linhas de log correspondentes a cada 10 segundos. Se os primeiros registros não aparecerem em 60 segundos ou os registros subsequentes não aparecerem a cada 10 segundos, o agente HyperPod elástico tratará o contêiner como preso e coordenará com o operador de treinamento a reinicialização do trabalho.

```
runPolicy:
    jobMaxRetryCount: 10
    cleanPodPolicy: "None"
    logMonitoringConfiguration:
      - name: "JobStartGracePeriod"
        # Sample log line: [default0]:2025-06-17 05:51:29,300 [INFO] __main__: Train Epoch: 5 [0/60000 (0%)]       loss=0.8470
        logPattern: ".*Train Epoch.*"  
        expectedStartCutOffInSeconds: 60 
      - name: "JobHangingDetection"
        logPattern: ".*Train Epoch.*"
        expectedRecurringFrequencyInSeconds: 10 # if the next batch is not printed within 10 seconds
```

**Picos de perda de treinamento**

A configuração de monitoramento a seguir emite logs de treinamento com o padrão `xxx training_loss_step xx`. Ela usa o parâmetro `metricEvaluationDataPoints`, que permite especificar um limite de pontos de dados antes que o operador reinicie a tarefa. Se o valor da perda de treinamento for maior que 2,0, o operador reiniciará a tarefa.

```
runPolicy:
  jobMaxRetryCount: 10
  cleanPodPolicy: "None"
  logMonitoringConfiguration:
    - name: "LossSpikeDetection"
      logPattern: ".*training_loss_step (\\d+(?:\\.\\d+)?).*"   # training_loss_step 5.0
      metricThreshold: 2.0
      operator: "gt"
      metricEvaluationDataPoints: 5 # if loss higher than threshold for 5 data points, restart the job
```

** TFLOPs Detecção baixa**

A configuração de monitoramento a seguir emite logs de treinamento com o padrão `xx TFLOPs xx` a cada 5 segundos. Se TFLOPs for menor que 100 para 5 pontos de dados, o operador reinicia o trabalho de treinamento.

```
runPolicy:
  jobMaxRetryCount: 10
  cleanPodPolicy: "None"
  logMonitoringConfiguration:
    - name: "TFLOPs"
      logPattern: ".* (.+)TFLOPs.*"    # Training model, speed: X TFLOPs...
      expectedRecurringFrequencyInSeconds: 5        
      metricThreshold: 100       # if Tflops is less than 100 for 5 data points, restart the job       
      operator: "lt"
      metricEvaluationDataPoints: 5
```

**Detecção do registro de erros do script de treinamento**

A configuração de monitoramento a seguir detecta se o padrão especificado em `logPattern` está presente nos registros de treinamento. Assim que o operador de treinamento encontra o padrão de erro, ele o trata como uma falha e reinicia o trabalho.

```
runPolicy:
  jobMaxRetryCount: 10
  cleanPodPolicy: "None"
  logMonitoringConfiguration:
    - name: "GPU Error"
      logPattern: ".*RuntimeError.*out of memory.*"
      faultOnMatch: true
```