翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# トレーニングオペレーターを使用してジョブを実行する
<a name="sagemaker-eks-operator-usage"></a>

 kubectl を使用してジョブを実行するには、job.yaml を作成してジョブ仕様を指定し、`kubectl apply -f job.yaml` を実行してジョブを送信する必要があります。この YAML ファイルでは、`logMonitoringConfiguration` 引数でカスタム設定を指定して、分散トレーニングジョブからのログ出力を分析し、問題を検出して復旧する自動モニタリングルールを定義できます。

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

ログモニタリングオプションを使用する場合は、トレーニングログを `sys.stdout` に出力していることを確認してください。HyperPod Elastic Agent は、`/tmp/hyperpod/` に保存されている sys.stdout のトレーニングログをモニタリングします。次のコマンドを使用して、トレーニングログを出力できます。

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

 想定可能なすべてのログモニタリング設定は、次の表のとおりです。


| パラメータ | 使用方法 | 
| --- | --- | 
| jobMaxRetryCount | プロセスレベルでの再起動の最大数 | 
| restartPolicy: numRestartBeforeFullJobRestart | オペレーターがジョブレベルで再起動するまでのプロセスレベルでの再起動の最大数 | 
| restartPolicy: evalPeriodSeconds | 再起動制限を秒単位で評価する期間 | 
| restartPolicy: maxFullJobRestarts | ジョブが失敗するまでのフルジョブの再起動の最大数 | 
| cleanPodPolicy | オペレータがクリーンアップするポッドを指定します。許容される値は、All、OnlyComplete、None です。 | 
| logMonitoringConfiguration | 遅いジョブやハングしたジョブを検出するためのログモニタリングルール | 
| expectedRecurringFrequencyInSeconds | ルールが HANGING と評価されるまでの 2 つの LogPattern 一致の時間間隔。指定しない場合、連続する LogPattern 一致の間に時間制約はありません。 | 
| expectedStartCutOffInSeconds | ルールが HANGING と評価される場合の最初の LogPattern 一致までの時間。指定しない場合、最初の LogPattern 一致に時間制約はありません。 | 
| logPattern | ルールがアクティブな場合にルールが適用されるログ行を識別する正規表現 | 
| metricEvaluationDataPoints | ジョブを SLOW としてマークする前に、ルールが SLOW に評価する必要がある連続回数。指定されなかった場合、デフォルト値は 1 です。 | 
| metricThreshold | キャプチャグループを持つ LogPattern によって抽出された値のしきい値。指定しない場合、メトリクス評価は実行されません。 | 
| オペレーター | モニタリング設定に適用する不等式。許容される値は、gt、gteq、lt、lteq、eq です。 | 
| stopPattern | ルールを非アクティブ化するログ行を識別するための定期的な説明。指定しない場合、ルールは常にアクティブになります。 | 
| faultOnMatch | LogPattern の一致がジョブの障害をすぐにトリガーするかどうかを示します。true の場合、他のルールパラメータに関係なく、LogPattern が一致するとすぐにジョブは障害としてマークされます。false または指定しない場合、ルールは他のパラメータに基づいて SLOW または HANGING に評価されます。 | 

 トレーニングの耐障害性を向上するには、予備のノード設定の詳細を指定します。ジョブが失敗した場合、オペレーターは Kueue と連携して、事前に予約されたノードを使用してジョブの実行を続行します。スペアノード設定には Kueue が必要なため、スペアノードを持つジョブを送信しようとしても Kueue がインストールされていない場合、ジョブは失敗します。次の例は、予備のノード設定を含むサンプル `job.yaml` ファイルです。

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

## モニタリング
<a name="sagemaker-eks-operator-usage-monitoring"></a>

Amazon SageMaker HyperPod は、[Amazon Managed Grafana および Amazon Managed Service for Prometheus とのオブザーバビリティ](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-observability-addon.html)と統合されているため、これらのオブザーバビリティツールにメトリクスを収集して供給するためのモニタリングを設定できます。

または、マネージドオブザーバビリティを使用せずに、Amazon Managed Service for Prometheus を介してメトリクスをスクレイプすることもできます。これを行うには、`kubectl` でジョブを実行する際に、モニタリングするメトリクスを `job.yaml` ファイルに含めます。

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

以下は、トレーニングオペレーターが Amazon Managed Service for Prometheus にフィードしてトレーニングジョブをモニタリングできるイベントです。


| [Event] (イベント) | 説明 | 
| --- | --- | 
| hyperpod\_training\_operator\_jobs\_created\_total | トレーニングオペレーターが実行したジョブの合計数 | 
| hyperpod\_training\_operator\_jobs\_restart\_latency | 現在のジョブの再起動レイテンシー | 
| hyperpod\_training\_operator\_jobs\_fault\_detection\_latency | 障害検出のレイテンシー | 
| hyperpod\_training\_operator\_jobs\_deleted\_total | 削除されたジョブの合計数 | 
| hyperpod\_training\_operator\_jobs\_successful\_total | 完了したジョブの合計数 | 
| hyperpod\_training\_operator\_jobs\_failed\_total | 失敗したジョブの合計数 | 
| hyperpod\_training\_operator\_jobs\_restarted\_total | 自動再起動されたジョブの合計数 | 

## サンプル Docker 設定
<a name="sagemaker-eks-operator-usage-docker"></a>

以下は、`hyperpod run` コマンドで実行できるサンプル docker ファイルです。

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

## ログモニタリング設定例
<a name="sagemaker-eks-operator-usage-log-monitoring"></a>

**ジョブのハング検出**

ハングしたジョブを検出するには、次の設定を使用します。以下のパラメータを使用します。
+ expectedStartCutOffInSeconds – モニターが最初のログを予期するまで待機する時間
+ expectedRecurringFrequencyInSeconds – ログの次のバッチを待機する時間間隔

これらの設定の場合、ログモニターはトレーニングジョブの開始から 60 秒以内に正規表現パターン `.*Train Epoch.*` に一致するログ行を認識することを期待します。最初の表示後、モニターは 10 秒ごとに一致するログ行を認識することを期待します。最初のログが 60 秒以内に現れない場合、または後続のログが 10 秒ごとに現れない場合、HyperPod Elastic Agent はコンテナをスタックとして扱い、トレーニングオペレーターと連携してジョブを再開します。

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

**トレーニングロスのスパイク**

次のモニタリング設定は、パターン `xxx training_loss_step xx` を使用してトレーニングログを出力します。パラメータ `metricEvaluationDataPoints` を使用します。これにより、オペレータがジョブを再起動する前にデータポイントのしきい値を指定できます。トレーニング損失値が 2.0 を超える場合、オペレーターはジョブを再起動します。

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

**低 TFLOP 検出**

次のモニタリング設定は、パターン `xx TFLOPs xx` を使用して、5 秒ごとにトレーニングログを出力します。5 つのデータポイントで TFLOP が 100 未満の場合、オペレーターはトレーニングジョブを再起動します。

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

**トレーニングスクリプトのエラーログ検出**

次のモニタリング設定は、 で指定されたパターン`logPattern`がトレーニングログに存在するかどうかを検出します。トレーニングオペレーターがエラーパターンに遭遇するとすぐに、トレーニングオペレーターはそれを障害として扱い、ジョブを再起動します。

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