本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 安装训练操作符
请参阅以下各部分，了解如何安装训练操作符。
## 先决条件
在使用 HyperPod 训练操作员之前，您必须满足以下先决条件：
+ [使用 Amazon EKS 编排创建了一个 HyperPod 集群](https://docs.amazonaws.cn/sagemaker/latest/dg/sagemaker-hyperpod-eks-operate-console-ui-create-cluster.html)。
+ 在您的 HyperPod 集群上安装了最新的 AMI。有关更多信息，请参阅 [SageMaker HyperPod 亚马逊 EKS 的 AMI 发布](sagemaker-hyperpod-release-ami-eks.md)。
+ [已安装 cert-manager](https://cert-manager.io/docs/installation/)。
+ [使用控制台设置 EKS 容器组身份代理](https://docs.amazonaws.cn/eks/latest/userguide/pod-id-agent-setup.html)。如果要使用 Amazon CLI，请使用以下命令：
```
aws eks create-addon \
--cluster-name my-eks-cluster \
--addon-name eks-pod-identity-agent \
--region Amazon Web Services 区域
```
+ （可选）如果您在私有 VPC 中运行 HyperPod 集群节点，则必须为亚马逊 AI AP SageMaker I (`com.amazonaws.aws-region.sagemaker.api`) 和亚马逊 EKS 身份验证服务 (com.amazonaws) 设置 PrivateLinks VPC 终端节点。 *aws-region*.eks-auth）。您还必须确保您的集群节点运行的子网位于安全组中，该安全组允许流量通过 VPC 终端节点进行路由，以便与 SageMaker AI 和 Amazon EKS 通信。如果这些设置不正确，插件安装可能会失败。要了解有关设置 VPC 终端节点的更多信息，请参阅[创建 VPC 终端节点](https://docs.amazonaws.cn/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws)。
## 安装训练操作符
现在，您可以通过 SageMaker AI 控制台、Amazon EKS 控制台或使用控制台方法安装 HyperPod 培训操作员，这些方法提供了可帮助您安装操作员的简化体验。 Amazon CLI Amazon CLI 提供了一种编程方法，可让您自定义更多安装内容。
在这两种控制台体验之间， SageMaker AI 提供一键安装，创建 IAM 执行角色，创建 pod 身份关联并安装操作员。Amazon EKS 控制台安装与此类似，但此方法不会自动创建 IAM 执行角色。在此过程中，您可以选择利用控制台预填充的信息创建新的 IAM 执行角色。默认情况下，这些创建的角色只能访问要在其中安装操作符的当前集群。除非您编辑该角色的权限以包含其他集群，否则，如果您移除并重新安装操作符，则必须创建一个新角色。
------
#### [ SageMaker AI console (recommended) ]
1. 打开 Amazon A SageMaker I 控制台，网址为[https://console.aws.amazon.com/sagemaker/](https://console.amazonaws.cn/sagemaker/)。
1. 转到集群的详细信息页面。
1. 在 “**控制面板**” 选项卡上，找到名为 **Amazon SageMaker HyperPod 培训操作员**的插件，然后选择**安装**。在安装过程中，A SageMaker I 会创建一个 IAM 执行角色，其权限与[ AmazonSageMakerHyperPodTrainingOperatorAccess](https://docs.amazonaws.cn/aws-managed-policy/latest/reference/AmazonSageMakerHyperPodTrainingOperatorAccess.html)托管策略类似，并在您的 Amazon EKS 集群和新的执行角色之间创建 Pod 身份关联。
------
#### [ Amazon EKS console ]
**注意**
如果您通过 Amazon EKS 集群安装附加组件，请首先确保已使用键值对标记您的 HyperPod 集群。`SageMaker:true`否则，安装将失败。
1. 在 [https://console.aws.amazon.com/eks/home\$1/](https://console.amazonaws.cn/eks/home#/clusters) clusters 中打开 Amazon EKS 控制台。
1. 转至您的 EKS 集群，选择**附加组件**，然后选择**获取更多插件**。
1. 选择 Amazon SageMaker HyperPod 培训运营商，然后选择**下一步**。
1. 在**版本**下，控制台默认显示最新版本，建议您使用该版本。
1. 在**插件访问权限**下，选择要与训练操作符附加组件结合使用的容器组身份 IAM 角色。如果您还没有角色，请选择**创建推荐的角色**以创建一个角色。
1. 在此角色创建过程中，IAM 控制台会预先填充所有必要的信息，例如用例、[ AmazonSageMakerHyperPodTrainingOperatorAccess](https://docs.amazonaws.cn/aws-managed-policy/latest/reference/AmazonSageMakerHyperPodTrainingOperatorAccess.html)托管策略和其他所需权限、角色名称和描述。在完成这些步骤时，请查看信息，然后选择**创建角色**。
1. 在 EKS 控制台中，查看附加组件的设置，然后选择**创建**。
------
#### [ CLI ]
1. 确保 HyperPod 集群的 IAM 执行角色具有信任关系，允许 EKS Pod Identity 使用以下信任策略代入[角色或创建新的 IAM 角色](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_create.html)。或者，您可以使用 Amazon EKS 控制台安装该附加组件，从而创建推荐的角色。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowEksAuthToAssumeRoleForPodIdentity",
"Effect": "Allow",
"Principal": {
"Service": "pods.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession",
"eks-auth:AssumeRoleForPodIdentity"
]
}
]
}
```
------
1. 将[ AmazonSageMakerHyperPodTrainingOperatorAccess 托管策略](https://docs.amazonaws.cn/aws-managed-policy/latest/reference/AmazonSageMakerHyperPodTrainingOperatorAccess.html)附加到您创建的角色。
1. [随后，在您的 EKS 集群、IAM 角色和新 IAM 角色之间创建容器组身份关联](https://docs.amazonaws.cn/eks/latest/userguide/pod-identities.html)。
```
aws eks create-pod-identity-association \
--cluster-name my-eks-cluster \
--role-arn ARN of your execution role \
--namespace aws-hyperpod \
--service-account hp-training-operator-controller-manager \
--region Amazon Web Services 区域
```
1. 完成该过程后，您可以使用 ListPodIdentityAssociations 操作来查看您创建的关联。以下是其内容的示例响应。
```
aws eks list-pod-identity-associations --cluster-name my-eks-cluster
{
"associations": [{
"clusterName": "my-eks-cluster",
"namespace": "aws-hyperpod",
"serviceAccount": "hp-training-operator-controller-manager",
"associationArn": "arn:aws:eks:us-east-2:123456789012:podidentityassociation/my-hyperpod-cluster/a-1a2b3c4d5e6f7g8h9",
"associationId": "a-1a2b3c4d5e6f7g8h9"
}]
}
```
1. 要安装训练操作符，请使用 `create-addon` 操作。`--addon-version` 参数是可选的。如果您不提供版本，则默认为最新版本。要获取可能的版本，请使用[ DescribeAddonVersions](https://docs.amazonaws.cn/eks/latest/APIReference/API_DescribeAddonVersions.html)操作。
```
aws eks create-addon \
--cluster-name my-eks-cluster \
--addon-name amazon-sagemaker-hyperpod-training-operator \
--resolve-conflicts OVERWRITE
```
------
如果您的 HyperPod 集群上已经安装了培训操作员，则可以将 EKS 插件更新到所需的版本。如果你想使用[无检查点训练或[弹性训练](https://docs.amazonaws.cn/sagemaker/latest/dg/sagemaker-eks-elastic-training.html)](https://docs.amazonaws.cn/sagemaker/latest/dg/sagemaker-eks-checkpointless.html)，请考虑以下几点：
+ 无检查点训练和弹性训练都要求 EKS 插件必须在 1.2.0 或更高版本上。
+ Amazon SageMaker HyperPod 培训运营商保持对任何 EKS 附加版本的向后兼容性，因此您可以从任何附加版本升级到 1.2.0 或更高版本。
+ 如果您从 1.2.0 或更高版本降级到较低版本，则必须在降级之前先删除现有作业，并在降级完成后重新提交作业。
------
#### [ Amazon EKS Console ]
1. 在 [https://console.aws.amazon.com/eks/home\$1/](https://console.amazonaws.cn/eks/home#/clusters) clusters 中打开 Amazon EKS 控制台。
1. 前往您的 EKS 集群，然后选择**附加组件。**然后，选择 Amazon SageMaker HyperPod 培训操作员附加组件，然后选择 “**编辑”**。
1. 在 “**版本**” 菜单中，选择所需的插件版本，然后选择 “**保存更改**”。
------
#### [ CLI ]
1. 首先获取您的集群支持的插件版本列表。
```
aws eks describe-addon-versions \
--kubernetes-version $(aws eks describe-cluster --name my-eks-cluster --query 'cluster.version' --output text) \
--addon-name amazon-sagemaker-hyperpod-training-operator \
--query 'addons[0].addonVersions[].addonVersion' \
--output table
```
1. 然后将插件更新到你想要的版本。
```
aws eks update-addon \
--cluster-name my-eks-cluster \
--addon-name amazon-sagemaker-hyperpod-training-operator \
--addon-version target-version
--resolve-conflicts OVERWRITE
```
------
训练操作符提供了大量带默认值的选项，这些选项可能适合您的使用案例。我们建议您在更改训练操作符之前，先尝试使用默认值运行训练操作符。下表描述了所有参数，以及您可能需要配置每个参数的场景示例。
| 参数 | 说明 | 默认 |
| --- | --- | --- |
| hpTrainingControllermanager.manager.resources.reques | 要为控制器分配的处理器数 | 1 |
| hpTrainingControllermanager.manager.resources.reques | 要为控制器分配的内存量 | 2Gi |
| hpTrainingControllermanager.manager.resources.limits | 控制器的 CPU 限制 | 2 |
| hpTrainingControllermanager.manager.resources.Limits | 控制器的内存限制 | 4Gi |
| hpTrainingController管理员.nodeSelector | 控制器容器组（pod）的节点选择器 | 默认行为是选择带标签 sagemaker.amazonaws.com/compute-type: "HyperPod" 的节点 |
## HyperPod 弹性剂
HyperPod 弹性剂是 [PyTorch's](https://docs.pytorch.org/docs/stable/elastic/agent.html) 的延伸 ElasticAgent。它协调每个容器上培训工作人员的生命周期，并与培训操作员进行沟通。 HyperPod 要使用 HyperPod 训练操作员，必须先将 HyperPod 弹性代理安装到训练图像中，然后才能使用操作员提交和运行作业。以下是一个 docker 文件，用于安装弹性代理并使用 `hyperpodrun` 创建作业启动器。
**注意**
[无检查点训练和弹性训练](https://docs.amazonaws.cn/sagemaker/latest/dg/sagemaker-eks-checkpointless.html)[都要求您使用 HyperPod 弹性](https://docs.amazonaws.cn/sagemaker/latest/dg/sagemaker-eks-elastic-training.html)代理版本 1.1.0 或更高版本。
```
RUN pip install hyperpod-elastic-agent
ENTRYPOINT ["entrypoint.sh"]
# entrypoint.sh
...
hyperpodrun --nnodes=node_count --nproc-per-node=proc_count \
--rdzv-backend hyperpod \ # Optional
--inprocess-restart \ # Optional (in-process fault recovery with checkpointless training)
... # Other torchrun args
# pre-traing arg_group
--pre-train-script pre.sh --pre-train-args "pre_1 pre_2 pre_3" \
# post-train arg_group
--post-train-script post.sh --post-train-args "post_1 post_2 post_3" \
training.py --script-args
```
现在，您可以使用 `kubectl` 提交作业。
### HyperPod 弹性剂论点
HyperPod 弹性代理支持所有原始参数，并添加了一些其他参数。以下是 HyperPod 弹性代理中可用的所有参数。有关 PyTorch的 Elastic 代理的更多信息，请参阅其[官方文档](https://docs.pytorch.org/docs/stable/elastic/agent.html)。
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| --shutdown-signal | 发送给工作线程以执行关闭操作的信号（SIGTERM 或 SIGKILL） | “SIGKILL” |
| --shutdown-timeout | 关机信号和 SIGKILL 信号之间的超时时间（以秒为单位） | 15 |
| --server-host | 代理服务器地址 | “0.0.0.0” |
| --server-port | 代理服务器端口 | 8080 |
| --server-log-level | 代理服务器日志级别 | “info” |
| --server-shutdown-timeout | 服务器关闭超时时间（以秒为单位） | 300 |
| --pre-train-script | 预训练脚本的路径 | 无 |
| --pre-train-args | 预训练脚本的参数 | 无 |
| --post-train-script | 训练后脚本的路径 | 无 |
| --post-train-args | 训练后脚本的参数 | 无 |
| --进程中重启 | 指定是否使用 inprocess\$1restart 功能的标志 | FALSE |
| --处理中超时 | 代理在触发进程级重启之前等待工作人员到达同步屏障的时间（以秒为单位）。 | 无 |
## 任务治理（可选）
培训操作员与[ HyperPod 任务管理集成，任务管理](https://docs.amazonaws.cn/sagemaker/latest/dg/sagemaker-hyperpod-eks-operate-console-ui-governance)是一个强大的管理系统，旨在简化资源分配，并确保在 Amazon EKS 集群中跨团队和项目高效利用计算资源。要设置 HyperPod 任务管理，请参阅[SageMaker HyperPod 任务管理设置](sagemaker-hyperpod-eks-operate-console-ui-governance-setup.md)。
**注意**
安装 HyperPod 任务管理插件时，必须使用 v1.3.0-eksbuild.1 或更高版本。
提交作业时，请务必包含队列名称与优先级类标签 `hyperpod-ns-team-name-localqueue` 和 `priority-class-name-priority`。例如，如果您使用的是 Kueue，则标签会变为以下内容：
+ kueue.x-k8s.io/queue-name：hypod-ns-localqueue *team-name*
+ kuee.x-k8s.io/priority-class：-name-priority *priority-class*
配置文件可能类似于如下示例：
```
apiVersion: sagemaker.amazonaws.com/v1
kind: HyperPodPytorchJob
metadata:
name: hp-task-governance-sample
namespace: hyperpod-ns-team-name
labels:
kueue.x-k8s.io/queue-name: hyperpod-ns-team-name-localqueue
kueue.x-k8s.io/priority-class: priority-class-priority
spec:
nprocPerNode: "1"
runPolicy:
cleanPodPolicy: "None"
replicaSpecs:
- name: pods
replicas: 4
spares: 2
template:
spec:
containers:
- name: ptjob
image: XXXX
imagePullPolicy: Always
ports:
- containerPort: 8080
resources:
requests:
cpu: "2"
```
然后使用以下 kubectl 命令来应用 YAML 文件。
```
kubectl apply -f task-governance-job.yaml
```
## Kueue（可选）
您可以直接运行作业，您的组织也可以将训练操作符与 Kueue 集成来分配资源和调度作业。按照以下步骤将 Kueue 安装到您的 HyperPod 集群中。
1. 按照 [Kueue 官方文档](https://kueue.sigs.k8s.io/docs/installation/#install-a-custom-configured-released-version)中的安装指南进行操作。当您进行到配置 `controller_manager_config.yaml` 的步骤时，请添加以下配置：
```
externalFrameworks:
- "HyperPodPytorchJob.v1.sagemaker.amazonaws.com"
```
1. 按照官方安装指南中的其余步骤操作。安装完 Kueue 后，您可以使用 `kubectl apply -f sample-queues.yaml` 命令创建一些示例队列。使用以下 YAML 文件。
```
apiVersion: kueue.x-k8s.io/v1beta1
kind: ClusterQueue
metadata:
name: cluster-queue
spec:
namespaceSelector: {}
preemption:
withinClusterQueue: LowerPriority
resourceGroups:
- coveredResources:
- cpu
- nvidia.com/gpu
- pods
flavors:
- name: default-flavor
resources:
- name: cpu
nominalQuota: 16
- name: nvidia.com/gpu
nominalQuota: 16
- name: pods
nominalQuota: 16
---
apiVersion: kueue.x-k8s.io/v1beta1
kind: LocalQueue
metadata:
name: user-queue
namespace: default
spec:
clusterQueue: cluster-queue
---
apiVersion: kueue.x-k8s.io/v1beta1
kind: ResourceFlavor
metadata:
name: default-flavor
---
apiVersion: kueue.x-k8s.io/v1beta1
description: High priority
kind: WorkloadPriorityClass
metadata:
name: high-priority-class
value: 1000
---
apiVersion: kueue.x-k8s.io/v1beta1
description: Low Priority
kind: WorkloadPriorityClass
metadata:
name: low-priority-class
value: 500
```