本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 Amazon EKS 協作的 SageMaker HyperPod 叢集上執行任務
下列主題提供存取運算節點，以及在與 Amazon EKS 協作的佈建 SageMaker HyperPod 叢集上執行 ML 工作負載的程序和範例。根據您在 HyperPod 叢集上設定環境的方式，在 HyperPod 叢集上執行 ML 工作負載的方法有很多種。
**注意**
透過 SageMaker HyperPod CLI 或 kubectl 執行任務時，HyperPod 可以跨命名空間 (團隊) 追蹤運算使用率 (GPU/CPU 時數)。這些指標驅動用量報告，其中提供：
配置資源耗用量與借用資源耗用量的可見性
用於稽核的團隊資源使用率 (最多 180 天)
符合任務治理政策的成本歸因
若要使用用量報告，您必須安裝用量報告基礎設施。強烈建議設定[任務治理](sagemaker-hyperpod-eks-operate-console-ui-governance.md)以強制執行運算配額，並啟用精細的成本歸因。
如需設定和產生用量報告的詳細資訊，請參閱[在 HyperPod 中報告運算用量](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-usage-reporting.html)。
**提示**
如需有關如何設定和使用與 Amazon EKS 協作的 SageMaker HyperPod 叢集的實作體驗和指引，我們建議您參加 [SageMaker HyperPod 中的 Amazon EKS 支援](https://catalog.us-east-1.prod.workshops.aws/workshops/2433d39e-ccfe-4c00-9d3d-9917b729258e)工作坊。
資料科學家使用者可以使用已設定為 SageMaker HyperPod 叢集協調器的 EKS 叢集來訓練基礎模型。科學家利用 [SageMaker HyperPod CLI](https://github.com/aws/sagemaker-hyperpod-cli) 和原生 `kubectl` 命令，來尋找可用的 SageMaker HyperPod 叢集、提交訓練任務 (Pod)，以及管理其工作負載。SageMaker HyperPod CLI 使用訓練任務結構描述檔案啟用任務提交，並提供任務列示、描述、取消和執行的功能。科學家可以根據 HyperPod 管理的運算配額使用 [Kubeflow Training Operator](https://www.kubeflow.org/docs/components/training/overview/)，也可以使用 [SageMaker AI 管理的 MLflow](https://docs.aws.amazon.com/sagemaker/latest/dg/mlflow.html) 來管理 ML 實驗和訓練執行。
**Topics**
+ [安裝 SageMaker HyperPod CLI](sagemaker-hyperpod-eks-run-jobs-access-nodes.md)
+ [SageMaker HyperPod CLI 命令](sagemaker-hyperpod-eks-hyperpod-cli-reference.md)
+ [使用 SageMaker HyperPod CLI 執行任務](sagemaker-hyperpod-eks-run-jobs-hyperpod-cli.md)
+ [使用 `kubectl` 執行任務](sagemaker-hyperpod-eks-run-jobs-kubectl.md)
# 安裝 SageMaker HyperPod CLI
SageMaker HyperPod 提供 [SageMaker HyperPod 命令列介面](https://github.com/aws/sagemaker-hyperpod-cli) (CLI) 套件。
1. 檢查本機電腦上的 Python 版本是否介於 3.8 與 3.11 之間。
1. 檢查 [SageMaker HyperPod CLI](https://github.com/aws/sagemaker-hyperpod-cli) 套件中 `README` Markdown 檔案中的先決條件。
1. 從 GitHub 複製 SageMaker HyperPod CLI 套件。
```
git clone https://github.com/aws/sagemaker-hyperpod-cli.git
```
1. 安裝 SageMaker HyperPod CLI。
```
cd sagemaker-hyperpod-cli && pip install .
```
1. 執行下列命令，測試 SageMaker HyperPod CLI 是否已成功安裝。
```
hyperpod --help
```
**注意**
如果您是資料科學家且想要使用 SageMaker HyperPod CLI，請確定您的叢集管理員遵循[科學家的 IAM 使用者](sagemaker-hyperpod-prerequisites-iam.md#sagemaker-hyperpod-prerequisites-iam-cluster-user)和[設定 Kubernetes 角色型存取控制](sagemaker-hyperpod-eks-setup-rbac.md)中的指示正確設定 IAM 角色。
# SageMaker HyperPod CLI 命令
下表摘要說明 SageMaker HyperPod CLI 命令。
**注意**
如需完整的 CLI 參考，請參閱 [SageMaker HyperPod CLI GitHub 儲存庫](https://github.com/aws/sagemaker-hyperpod-cli)中的 [README](https://github.com/aws/sagemaker-hyperpod-cli?tab=readme-ov-file#sagemaker-hyperpod-command-line-interface)。
| SageMaker HyperPod CLI 命令 | 實體 | Description |
| --- | --- | --- |
| hyperpod get-clusters | 叢集/存取 | 列出具有 IAM 許可的使用者可將訓練工作負載提交至其中的所有叢集。提供整體可用執行個體的目前快照，以及最大容量，依運作狀態檢查狀態 (例如：BurnInPassed) 分組 |
| hyperpod connect-cluster | 叢集/存取 | 設定 kubectl 在指定的 HyperPod 叢集和命名空間上操作 |
| hyperpod start-job | job | 將任務提交至目標叢集 - 任務名稱在命名空間層級將是唯一的 - 使用者將能夠透過將它們當作 CLI 引數傳遞來覆寫 yaml 規格 |
| hyperpod get-job | job | 顯示所提交任務的中繼資料 |
| hyperpod list-jobs | job | 列出已連線叢集/命名空間中使用者已新增至其中的所有任務，而此使用者具有提交訓練工作負載的 IAM 許可 |
| hyperpod cancel-job | job | 停止和刪除任務，並放棄基礎運算資源。此任務無法重新繼續。如有需要，必須啟動新的任務。 |
| hyperpod list-pods | Pod | 列出命名空間中給定任務中的所有 Pod |
| hyperpod get-log | Pod | 擷取指定任務中特殊 Pod 的日誌 |
| hyperpod exec | Pod | 在指定 Pod 的 Shell 中執行 bash 命令並發佈輸出 |
| hyperpod --help | 公用程式 | 列出所有支援的命令 |
# 使用 SageMaker HyperPod CLI 執行任務
若要執行任務，請確定您已在 EKS 叢集中安裝 Kubeflow Training Operator。如需詳細資訊，請參閱[使用 Helm 在 Amazon EKS 叢集上安裝套件](sagemaker-hyperpod-eks-install-packages-using-helm-chart.md)。
執行 `hyperpod get-cluster` 命令以取得可用的 HyperPod 叢集清單。
```
hyperpod get-clusters
```
執行 `hyperpod connect-cluster` 以使用協作 HyperPod 叢集的 EKS 叢集來設定 SageMaker HyperPod CLI。
```
hyperpod connect-cluster --cluster-name
```
使用 `hyperpod start-job` 命令執行任務。下列命令顯示具有必要選項的命令。
```
hyperpod start-job \
--job-name
--image
--entry-script
--instance-type
--node-count
```
`hyperpod start-job` 命令也隨附各種選項，例如任務自動繼續和任務排程。
## 啟用任務自動繼續
`hyperpod start-job` 命令也有下列選項來指定任務自動繼續。若要讓任務自動繼續可以使用 SageMaker HyperPod 節點彈性功能，您必須將 `restart-policy` 選項的值設定為 `OnFailure`。任務必須在 `kubeflow` 命名空間或字首為 `hyperpod` 的命名空間下執行。
+ [--auto-resume ] \$1選用，失敗後啟用任務自動繼續，預設值為 false
+ [--max-retry ] \$1選用，如果 auto-resume 為 true，則 max-retry 預設值為 1，若未指定的話
+ [--restart-policy ] \$1選用， PyTorchJob 重新啟動政策。可用值為 `Always`、`OnFailure` 或 `Never` 或 `ExitCode`。預設值為 `OnFailure`。
```
hyperpod start-job \
... // required options \
--auto-resume true \
--max-retry 3 \
--restart-policy OnFailure
```
## 使用排程選項執行任務
`hyperpod start-job` 命令具有下列選項來設定具有佇列機制的任務。
**注意**
您需要在 EKS 叢集中安裝 [Kueue](https://kueue.sigs.k8s.io/docs/overview/)。如果您尚未安裝，請遵循 [SageMaker HyperPod 任務治理的設定](sagemaker-hyperpod-eks-operate-console-ui-governance-setup.md)中的指示。
+ [--scheduler-type ] \$1Optional，指定排程器類型。預設值為 `Kueue`。
+ [--queue-name ] \$1選用，指定要與任務一起提交的[本機佇列](https://kueue.sigs.k8s.io/docs/concepts/local_queue/)或[叢集佇列](https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/)名稱。叢集管理員應使用 `CreateComputeQuota` 建立佇列。
+ [--priority ] \$1選用，指定[工作負載優先順序類別](https://kueue.sigs.k8s.io/docs/concepts/workload_priority_class/)的名稱，此類別應由叢集管理員建立。
```
hyperpod start-job \
... // required options
--scheduler-type Kueue \
--queue-name high-priority-queue \
--priority high
```
## 從組態檔案執行任務
或者，您可以建立任務組態檔案，其中包含任務所需的所有參數，然後使用 --config-file 選項將此組態檔案傳遞至 `hyperpod start-job` 命令。在此案例中：
1. 使用必要的參數建立您的任務組態檔案。如需[基準組態檔案](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-eks-run-jobs-hyperpod-cli.html#sagemaker-hyperpod-eks-hyperpod-cli-from-config)，請參閱 SageMaker HyperPod CLI GitHub 儲存庫中的任務組態檔案。
1. 使用組態檔案啟動任務，如下所示。
```
hyperpod start-job --config-file /path/to/test_job.yaml
```
**提示**
如需 `hyperpod start-job` 命令的完整參數清單，請參閱 SageMaker HyperPod CLI GitHub 儲存庫 `README.md` 中的[提交任務](https://github.com/aws/sagemaker-hyperpod-cli?tab=readme-ov-file#submitting-a-job)一節。
# 使用 `kubectl` 執行任務
**注意**
訓練任務自動繼續需要 Kubeflow Training Operator 發行版本 `1.7.0`、`1.8.0` 或 `1.8.1`。
請注意，您應該使用 Helm Chart 在叢集中安裝 Kubeflow Training Operator。如需詳細資訊，請參閱[使用 Helm 在 Amazon EKS 叢集上安裝套件](sagemaker-hyperpod-eks-install-packages-using-helm-chart.md)。執行下列命令，驗證 Kubeflow Training Operator 控制平面是否已正確設定。
```
kubectl get pods -n kubeflow
```
此命令會傳回如下的輸出。
```
NAME READY STATUS RESTARTS AGE
training-operator-658c68d697-46zmn 1/1 Running 0 90s
```
**提交訓練任務**
若要執行訓練任務，請準備任務組態檔案並執行 [https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply) 命令，如下所示。
```
kubectl apply -f /path/to/training_job.yaml
```
**描述訓練任務**
若要擷取提交至 EKS 叢集的任務詳細資訊，請使用下列命令。它會傳回任務提交時間、完成時間、任務狀態、組態詳細資訊等任務資訊。
```
kubectl get -o yaml training-job -n kubeflow
```
**停止訓練任務並刪除 EKS 資源**
若要停止訓練任務，請使用 kubectl delete。以下是停止從組態檔案 `pytorch_job_simple.yaml` 建立之訓練任務的範例。
```
kubectl delete -f /path/to/training_job.yaml
```
這應該會傳回以下輸出。
```
pytorchjob.kubeflow.org "training-job" deleted
```
**啟用任務自動繼續**
SageMaker HyperPod 支援 Kubernetes 任務的任務自動繼續功能，其會與 Kubeflow Training Operator 控制平面整合。
確保叢集中有足夠的節點已通過 SageMaker HyperPod 運作狀態檢查。節點應該已將污點 `sagemaker.amazonaws.com/node-health-status` 設定為 `Schedulable`。建議在任務 YAML 檔案中包含節點選擇器，以選取具有適當組態的節點，如下所示。
```
sagemaker.amazonaws.com/node-health-status: Schedulable
```
下列程式碼片段範例說明如何修改 Kubeflow PyTorch 任務 YAML 組態，以啟用任務自動繼續功能。您需要新增兩個註釋，並將 `restartPolicy` 設定為 `OnFailure`，如下所示。
```
apiVersion: "kubeflow.org/v1"
kind: PyTorchJob
metadata:
name: pytorch-simple
namespace: kubeflow
annotations: { // config for job auto resume
sagemaker.amazonaws.com/enable-job-auto-resume: "true"
sagemaker.amazonaws.com/job-max-retry-count: "2"
}
spec:
pytorchReplicaSpecs:
......
Worker:
replicas: 10
restartPolicy: OnFailure
template:
spec:
nodeSelector:
sagemaker.amazonaws.com/node-health-status: Schedulable
```
**檢查任務自動繼續狀態**
執行以下命令來檢查任務自動繼續的狀態。
```
kubectl describe pytorchjob -n kubeflow
```
根據失敗模式，您可能會看到兩種模式的 Kubeflow 訓練任務重新啟動，如下所示。
**模式 1**：
```
Start Time: 2024-07-11T05:53:10Z
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal SuccessfulCreateService 9m45s pytorchjob-controller Created service: pt-job-1-worker-0
Normal SuccessfulCreateService 9m45s pytorchjob-controller Created service: pt-job-1-worker-1
Normal SuccessfulCreateService 9m45s pytorchjob-controller Created service: pt-job-1-master-0
Warning PyTorchJobRestarting 7m59s pytorchjob-controller PyTorchJob pt-job-1 is restarting because 1 Master replica(s) failed.
Normal SuccessfulCreatePod 7m58s (x2 over 9m45s) pytorchjob-controller Created pod: pt-job-1-worker-0
Normal SuccessfulCreatePod 7m58s (x2 over 9m45s) pytorchjob-controller Created pod: pt-job-1-worker-1
Normal SuccessfulCreatePod 7m58s (x2 over 9m45s) pytorchjob-controller Created pod: pt-job-1-master-0
Warning PyTorchJobRestarting 7m58s pytorchjob-controller PyTorchJob pt-job-1 is restarting because 1 Worker replica(s) failed.
```
**模式 2**：
```
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal SuccessfulCreatePod 19m pytorchjob-controller Created pod: pt-job-2-worker-0
Normal SuccessfulCreateService 19m pytorchjob-controller Created service: pt-job-2-worker-0
Normal SuccessfulCreatePod 19m pytorchjob-controller Created pod: pt-job-2-master-0
Normal SuccessfulCreateService 19m pytorchjob-controller Created service: pt-job-2-master-0
Normal SuccessfulCreatePod 4m48s pytorchjob-controller Created pod: pt-job-2-worker-0
Normal SuccessfulCreatePod 4m48s pytorchjob-controller Created pod: pt-job-2-master-0
```