本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Kubernetes 集群预训练教程（GPU）
<a name="sagemaker-hyperpod-gpu-kubernetes-cluster-pretrain-tutorial"></a>

可通过两种方法在 GPU Kubernetes 集群中启动训练作业：
+ （推荐）[HyperPod 命令行工具](https://github.com/aws/sagemaker-hyperpod-cli)
+  NeMo 风格启动器

**先决条件**  
在开始设置环境之前，请确保您：  
 HyperPod GPU Kubernetes 集群设置正确。
拥有一个共享存储位置。它可以是可从群集节点访问的 Amazon FSx 文件系统或 NFS 系统。
拥有采用以下格式之一的数据：  
JSON
JSONGZ（压缩 JSON）
ARROW
（可选）如果您使用中的模型权重进行预训练或微调，则必须获得 HuggingFace 代币。 HuggingFace 有关获取令牌的更多信息，请参阅[用户访问令牌](https://huggingface.co/docs/hub/en/security-tokens)。

## GPU Kubernetes 环境设置
<a name="sagemaker-hyperpod-gpu-kubernetes-environment-setup"></a>

要设置 GPU Kubernetes 环境，请执行以下操作：
+ 设置虚拟环境。确保您使用 Python 3.9 或更高版本。

  ```
  python3 -m venv ${PWD}/venv
  source venv/bin/activate
  ```
+ 使用下列方法之一安装依赖项：
  + （推荐）：[HyperPod 命令行工具方法](https://github.com/aws/sagemaker-hyperpod-cli)：

    ```
    # 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
    ```
+ [设置 kubectl 和 eksctl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html)
+ [安装 Helm](https://helm.sh/docs/intro/install/)
+ 连接到 Kubernetes 集群

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

## 使用 SageMaker HyperPod CLI 启动训练作业
<a name="sagemaker-hyperpod-gpu-kubernetes-launch-training-job-cli"></a>

我们建议使用 SageMaker HyperPod 命令行界面 (CLI) 工具提交带有配置的训练作业。以下示例为 `hf_llama3_8b_seq16k_gpu_p5x16_pretrain` 模型提交训练作业。
+ `your_training_container`：深度学习容器。要查找最新版本的 SMP 容器，请参阅 [SageMaker 模型并行度库的发行说明](model-parallel-release-notes.md)。
+ （可选）如果您需要预先训练的权重，则 HuggingFace 可以通过设置以下键值对来提供 HuggingFace 标记：

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

```
hyperpod start-job --recipe training/llama/hf_llama3_8b_seq16k_gpu_p5x16_pretrain \
--persistent-volume-claims fsx-claim:data \
--override-parameters \
'{
"recipes.run.name": "hf-llama3-8b",
"recipes.exp_manager.exp_dir": "/data/<your_exp_dir>",
"container": "658645717510.dkr.ecr.<region>.amazonaws.com/smdistributed-modelparallel:2.4.1-gpu-py311-cu121",
"recipes.model.data.train_dir": "<your_train_data_dir>",
"recipes.model.data.val_dir": "<your_val_data_dir>",
"cluster": "k8s",
"cluster_type": "k8s"
}'
```

提交训练作业后，可使用以下命令来验证您是否已成功提交该作业。

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

在运行 `kubectl get pods` 时，`STATUS` 会变为 `Completed`。

## 使用配方启动程序启动训练作业
<a name="sagemaker-hyperpod-gpu-kubernetes-launch-training-job-recipes"></a>

或者，您可以使用 SageMaker HyperPod 食谱来提交您的训练作业。使用配方需更新 `k8s.yaml`、`config.yaml` 以及运行启动脚本。
+ 在 `k8s.yaml` 中，更新 `persistent_volume_claims`。它会将 Amazon FSx 声明挂载到每个计算单元的`/data`目录中

  ```
  persistent_volume_claims:
    - claimName: fsx-claim
      mountPath: data
  ```
+ 在 `config.yaml` 中，更新 `git` 下的 `repo_url_or_path`。

  ```
  git:
    repo_url_or_path: <training_adapter_repo>
    branch: null
    commit: null
    entry_script: null
    token: null
  ```
+ 更新 `launcher_scripts/llama/run_hf_llama3_8b_seq16k_gpu_p5x16_pretrain.sh`
  + `your_contrainer`：深度学习容器。要查找最新版本的 SMP 容器，请参阅 [SageMaker 模型并行度库的发行说明](model-parallel-release-notes.md)。
  + （可选）如果您需要预先训练的权重，则 HuggingFace 可以通过设置以下键值对来提供 HuggingFace 标记：

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

  ```
  #!/bin/bash
  #Users should setup their cluster type in /recipes_collection/config.yaml
  REGION="<region>"
  IMAGE="658645717510.dkr.ecr.${REGION}.amazonaws.com/smdistributed-modelparallel:2.4.1-gpu-py311-cu121"
  SAGEMAKER_TRAINING_LAUNCHER_DIR=${SAGEMAKER_TRAINING_LAUNCHER_DIR:-"$(pwd)"}
  EXP_DIR="<your_exp_dir>" # Location to save experiment info including logging, checkpoints, ect
  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_gpu_p5x16_pretrain \
      base_results_dir="${SAGEMAKER_TRAINING_LAUNCHER_DIR}/results" \
      recipes.run.name="hf-llama3" \
      recipes.exp_manager.exp_dir="$EXP_DIR" \
      cluster=k8s \
      cluster_type=k8s \
      container="${IMAGE}" \
      recipes.model.data.train_dir=$TRAIN_DIR \
      recipes.model.data.val_dir=$VAL_DIR
  ```
+ 启动训练作业

  ```
  bash launcher_scripts/llama/run_hf_llama3_8b_seq16k_gpu_p5x16_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` 更改为 `Running` 后，可使用以下命令检查日志。

```
kubectl logs name_of_pod
```

在运行 `kubectl get pods` 时，`STATUS` 会变成 `Completed`。

有关 k8s 集群配置的更多信息，请参阅[在 HyperPod k8s 上运行训练作业](cluster-specific-configurations-run-training-job-hyperpod-k8s.md)。