本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Trainium Kubernetes 叢集預先訓練教學課程
<a name="sagemaker-hyperpod-trainium-kubernetes-cluster-pretrain-tutorial"></a>

您可以使用下列其中一種方法，在 Trainium Kubernetes 叢集中啟動訓練任務。
+ (建議) [HyperPod 命令列工具](https://github.com/aws/sagemaker-hyperpod-cli)
+ NeMo 樣式啟動器

**先決條件**  
開始設定環境之前，請確定您具有下列先決條件：  
設定 HyperPod Trainium Kubernetes 叢集
共用儲存位置，其可以是可從叢集節點存取的 Amazon FSx 檔案系統或 NFS 系統。
採用下列其中一種格式的資料：  
JSON
JSONGZ (壓縮 JSON)
ARROW
(選用) 如果您要使用來自 HuggingFace 的模型權重進行預先訓練或微調，則必須取得 HuggingFace 權杖。如需取得權杖的詳細資訊，請參閱[使用者存取權杖](https://huggingface.co/docs/hub/en/security-tokens)。

## 設定您的 Trainium Kubernetes 環境
<a name="sagemaker-hyperpod-trainium-setup-trainium-kubernetes-environment"></a>

若要設定 Trainium Kubernetes 環境，請執行下列動作：

1. 完成下列教學課程中的步驟：從**下載資料集**開始的 [HuggingFace Llama3-8B 預先訓練](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/libraries/nxd-training/tutorials/hf_llama3_8B_pretraining.html#download-the-dataset)。

1. 準備模型組態。它們可在 Neuron 儲存庫中取得。針對本教學課程，您可以使用 llama3 8b 模型組態。

1. 虛擬環境設定。請確定您使用的是 Python 3.9 或更新版本。

   ```
   python3 -m venv ${PWD}/venv
   source venv/bin/activate
   ```

1. 安裝相依性
   + (建議) 使用下列 HyperPod 命令列工具

     ```
     # install HyperPod command line tools
     git clone https://github.com/aws/sagemaker-hyperpod-cli
     cd sagemaker-hyperpod-cli
     pip3 install .
     ```
   + 如果您使用的是 SageMaker HyperPod 配方，請指定下列內容

     ```
     # install SageMaker HyperPod Recipes.
     git clone --recursive git@github.com:aws/sagemaker-hyperpod-recipes.git
     cd sagemaker-hyperpod-recipes
     pip3 install -r requirements.txt
     ```

1. [設定 kubectl 和 eksctl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html)

1. [安裝 Helm](https://helm.sh/docs/intro/install/)

1. 連線至您的 Kubernetes 叢集

   ```
   aws eks update-kubeconfig --region "${CLUSTER_REGION}" --name "${CLUSTER_NAME}"
   hyperpod connect-cluster --cluster-name "${CLUSTER_NAME}" [--region "${CLUSTER_REGION}"] [--namespace <namespace>]
   ```

1. 容器：[Neuron 容器](https://github.com/aws-neuron/deep-learning-containers?tab=readme-ov-file#pytorch-training-neuronx)

## 使用 SageMaker HyperPod CLI 啟動訓練任務
<a name="sagemaker-hyperpod-trainium-launch-training-job-cli"></a>

建議使用 SageMaker HyperPod 命令列介面 (CLI) 工具，搭配您的組態提交訓練任務。下列範例會提交 `hf_llama3_8b_seq8k_trn1x4_pretrain` Trainium 模型的訓練任務。
+ `your_neuron_container`：[Neuron 容器](https://github.com/aws-neuron/deep-learning-containers?tab=readme-ov-file#pytorch-training-neuronx)。
+ `your_model_config`：來自環境設定區段的模型組態
+ (選用) 如果您需要來自 HuggingFace 的預先訓練權重，您可以設定下列金鑰/值對，以提供 HuggingFace 權杖：

  ```
  "recipes.model.hf_access_token": "<your_hf_token>"
  ```

```
hyperpod start-job --recipe training/llama/hf_llama3_8b_seq8k_trn1x4_pretrain \
--persistent-volume-claims fsx-claim:data \
--override-parameters \
'{
 "cluster": "k8s",
 "cluster_type": "k8s",
 "container": "<your_neuron_contrainer>",
 "recipes.run.name": "hf-llama3",
 "recipes.run.compile": 0,
 "recipes.model.model_config": "<your_model_config>",
 "instance_type": "trn1.32xlarge",
 "recipes.data.train_dir": "<your_train_data_dir>"
}'
```

在提交了訓練任務之後，您可以使用下列命令來驗證是否已成功提交。

```
kubectl get pods
NAME                              READY   STATUS             RESTARTS        AGE
hf-llama3-<your-alias>-worker-0   0/1     running         0               36s
```

如果 `STATUS` 是 `PENDING` 或 `ContainerCreating`，請執行下列命令以取得詳細資訊。

```
kubectl describe pod name_of_pod
```

在任務 `STATUS` 變更為 `Running` 之後，您可以使用下列命令來檢查日誌。

```
kubectl logs name_of_pod
```

當您執行 `Completed` 時，`STATUS` 會變成 `kubectl get pods`。

## 使用配方啟動器啟動訓練任務
<a name="sagemaker-hyperpod-trainium-launch-training-job-recipes"></a>

或者，使用 SageMaker HyperPod 配方來提交您的訓練任務。若要使用配方提交訓練任務，請更新 `k8s.yaml` 和 `config.yaml`。為模型執行 bash 指令碼以啟動該模型。
+ 在 `k8s.yaml` 中，更新 persistent\$1volume\$1claims，將 Amazon FSx 宣告掛載到運算節點中的 /data 目錄

  ```
  persistent_volume_claims:
    - claimName: fsx-claim
      mountPath: data
  ```
+ 更新 launcher\$1scripts/llama/run\$1hf\$1llama3\$18b\$1seq8k\$1trn1x4\$1pretrain.sh
  + `your_neuron_contrainer`：來自環境設定區段的容器
  + `your_model_config`：來自環境設定區段的模型組態

  (選用) 如果您需要來自 HuggingFace 的預先訓練權重，您可以設定下列金鑰/值對，以提供 HuggingFace 權杖：

  ```
  recipes.model.hf_access_token=<your_hf_token>
  ```

  ```
   #!/bin/bash
  #Users should set up their cluster type in /recipes_collection/config.yaml
  IMAGE="<your_neuron_contrainer>"
  MODEL_CONFIG="<your_model_config>"
  SAGEMAKER_TRAINING_LAUNCHER_DIR=${SAGEMAKER_TRAINING_LAUNCHER_DIR:-"$(pwd)"}
  TRAIN_DIR="<your_training_data_dir>" # Location of training dataset
  VAL_DIR="<your_val_data_dir>" # Location of talidation dataset
  
  HYDRA_FULL_ERROR=1 python3 "${SAGEMAKER_TRAINING_LAUNCHER_DIR}/main.py" \
    recipes=training/llama/hf_llama3_8b_seq8k_trn1x4_pretrain \
    base_results_dir="${SAGEMAKER_TRAINING_LAUNCHER_DIR}/results" \
    recipes.run.name="hf-llama3-8b" \
    instance_type=trn1.32xlarge \
    recipes.model.model_config="$MODEL_CONFIG" \
    cluster=k8s \
    cluster_type=k8s \
    container="${IMAGE}" \
    recipes.data.train_dir=$TRAIN_DIR \
    recipes.data.val_dir=$VAL_DIR
  ```
+ 啟動任務

  ```
  bash launcher_scripts/llama/run_hf_llama3_8b_seq8k_trn1x4_pretrain.sh
  ```

在提交了訓練任務之後，您可以使用下列命令來驗證是否已成功提交。

```
kubectl get pods
NAME                             READY   STATUS             RESTARTS        AGE
hf-llama3-<your-alias>-worker-0   0/1     running         0               36s
```

如果 `STATUS` 位於 `PENDING` 或 `ContainerCreating`，請執行下列命令以取得更多詳細資訊。

```
kubectl describe pod name_of_pod
```

在任務 STATUS 變更為執行中之後，您可以使用下列命令來檢查日誌。

```
kubectl logs name_of_pod
```

當您執行 `Completed` 時，`STATUS` 會變成 `kubectl get pods`。

如需 k8s 叢集組態的詳細資訊，請參閱 [Trainium Kubernetes 叢集預先訓練教學課程](#sagemaker-hyperpod-trainium-kubernetes-cluster-pretrain-tutorial)。