使用 HyperPod CLI 和 SDK 管理 Amazon SageMaker HyperPod 集群-青云TOP-AI综合资源站平台|青云聚合API大模型调用平台|全网AI资源导航平台

📢 转载信息

原文链接：https://aws.amazon.com/blogs/machine-learning/manage-amazon-sagemaker-hyperpod-clusters-using-the-hyperpod-cli-and-sdk/

原文作者：Nicolas Jourdan, Andrew Brown, and Giuseppe Angelo Porcelli

训练和部署大型 AI 模型需要先进的分布式计算能力，但管理这些分布式系统不应该成为数据科学家和机器学习 (ML) 从业者的复杂负担。Amazon SageMaker HyperPod 搭配 Amazon Elastic Kubernetes Service (Amazon EKS) 编排的命令行界面 (CLI) 和软件开发工具包 (SDK) 简化了管理集群基础设施以及使用该服务的分布式训练和推理功能的方式。

SageMaker HyperPod CLI 为数据科学家提供了一个直观的命令行体验，抽象化了底层分布式系统的复杂性。CLI 构建在 SageMaker HyperPod SDK 之上，提供了用于管理 HyperPod 集群和常见工作流程的简单命令，例如启动训练或微调作业、部署推理端点以及监控集群性能。这使其非常适合快速实验和迭代。

简化的分层架构

HyperPod CLI 和 SDK 遵循多层、共享的架构。CLI 和 Python 模块作为面向用户的入口点，都构建在共同的 SDK 组件之上，以确保跨接口的一致行为。对于基础设施自动化，SDK 通过组合 AWS CloudFormation 堆栈配置和直接的 AWS API 交互来编排集群生命周期管理。训练和推理工作负载以及集成开发环境 (IDE)（Spaces）被表示为 Kubernetes 自定义资源定义 (CRD)，SDK 通过 Kubernetes API 来管理这些 CRD。

在本文中，我们将演示如何使用 CLI 和 SDK 在您的 AWS 账户中创建和管理 SageMaker HyperPod 集群。我们将逐步介绍一个实际示例，并深入探讨用户工作流程和参数选择。

本文重点关注集群的创建和管理。要深入了解如何使用 HyperPod CLI 和 SDK 提交训练作业和部署推理端点，请参阅我们的配套博文：使用新的 HyperPod CLI 和 SDK 在 Amazon SageMaker HyperPod 上训练和部署模型。

先决条件

要遵循本文中的示例，您必须具备以下先决条件：

一个有权访问 SageMaker HyperPod、Amazon Simple Storage Service (Amazon S3) 和 Amazon FSx for Lustre 的 AWS 账户。
创建 HyperPod 集群和实例组的足够的服务配额。
一个本地环境（您的本地机器或基于云的计算环境），用于运行 SageMaker HyperPod CLI 命令，配置如下：
- 基于 Linux 或 MacOS 的操作系统。
- 已安装 Python 3.8 或更高版本。
- 已配置了适当凭证以使用上述服务的AWS 命令行界面 (AWS CLI)。

安装 SageMaker HyperPod CLI

首先，安装最新版本的 SageMaker HyperPod CLI 和 SDK。本文中的示例基于版本 3.5.0。在您的本地环境中，运行以下命令；您也可以在 Python 虚拟环境中安装 CLI：

# 安装 HyperPod CLI 和 SDK
pip install sagemaker-hyperpod

此命令设置了与 SageMaker HyperPod 集群交互所需的工具。对于现有安装，请确保已安装最新版本的包（SageMaker HyperPod 3.5.0 或更高版本），以便能够使用本文描述的相关功能集。要验证 CLI 是否安装正确，运行 hyp 命令并检查输出：

# 检查 HyperPod CLI 是否正确安装
hyp

输出将类似于以下内容，其中包含有关如何使用 CLI 的说明：

Usage: hyp [OPTIONS] COMMAND [ARGS]... Options:
  --version    Show version information
  --help       Show this message and exit. Commands:
  configure    Update any subset of fields in ./config.yaml by passing --<field> flags.
  create       Create endpoints, pytorch jobs, cluster stacks, space, space access or space admin config.
  delete       Delete endpoints, pytorch jobs, space, space access or space template.
  describe     Describe endpoints, pytorch jobs or cluster stacks, spaces or space template.
  exec         Execute commands in pods for endpoints or pytorch jobs.
  get-cluster-context  Get context related to the current set cluster.
  get-logs     Get pod logs for endpoints, pytorch jobs or spaces.
  get-monitoring  Get monitoring configurations for Hyperpod cluster.
  get-operator-logs  Get operator logs for endpoints.
  init         Initialize a TEMPLATE scaffold in DIRECTORY.
  invoke       Invoke model endpoints.
  list         List endpoints, pytorch jobs, cluster stacks, spaces, and space templates.
  list-accelerator-partition-type
               List available accelerator partition types for an instance type.
  list-cluster   List SageMaker Hyperpod Clusters with metadata.
  list-pods    List pods for endpoints or pytorch jobs.
  reset        Reset the current directory's config.yaml to an "empty" scaffold: all schema keys set to default values (but keeping the...
  set-cluster-context  Connect to a HyperPod EKS cluster.
  start        Start space resources.
  stop         Stop space resources.
  update       Update an existing HyperPod cluster configuration, space, or space template.
  validate     Validate this directory's config.yaml against the appropriate schema.

有关 CLI 用法和可用命令及相应参数的更多信息，请参阅CLI 参考文档。

HyperPod CLI 提供用于管理 HyperPod 集群完整生命周期的命令。以下部分将解释如何创建新集群、监控其创建过程、修改实例组以及删除集群。

创建新的 HyperPod 集群

可以通过 AWS 管理控制台或 HyperPod CLI 创建 HyperPod 集群，两者都为集群创建提供了简化的体验。控制台提供了最简单、最指导性的方法，而 CLI 对于那些偏爱程序化体验的客户尤其有用——例如，用于实现可重复性或围绕集群创建构建自动化。这两种方法都使用相同的底层 CloudFormation 模板，该模板可在SageMaker HyperPod 集群设置 GitHub 存储库中找到。有关基于控制台的体验的演练，请参阅集群创建体验博文。

通过 HyperPod CLI 创建新集群遵循基于配置的工作流程：CLI 首先生成配置文件，然后编辑这些文件以匹配所需的集群规范。随后，这些文件作为 CloudFormation 堆栈提交，该堆栈创建 HyperPod 集群以及所需的资源，例如 VPC 和 FSx for Lustre 文件系统等。

要初始化新集群配置，请运行以下命令：hyp init cluster-stack

这将在当前目录中初始化一个新的集群配置，并生成一个 config.yaml 文件，您可以使用它来指定集群堆栈的配置。此外，它还会创建一个 README.md 文件，其中包含有关功能和工作流程的信息，以及 cfn_params.jinja 中 CloudFormation 堆栈参数的模板。

(base) xxxxxxxx@3c06303f9abb hyperpod % hyp init cluster-stack
Initializing new scaffold for 'cluster-stack'...
✔️ cluster-stack for schema version='1.0' is initialized in .
🚀 Welcome!
📘 See ./README.md for usage.

集群堆栈的配置变量定义在 config.yaml 中。以下是该文件的一个摘录：

...
# 将用于所有资源的前缀。提交时，将在前缀后添加一个 4 位 UUID
resource_name_prefix: hyp-eks-stack
# 布尔值，用于创建 HyperPod 集群堆栈
create_hyperpod_cluster_stack: True
# SageMaker HyperPod 集群的名称
hyperpod_cluster_name: hyperpod-cluster
# 布尔值，用于创建 EKS 集群堆栈
create_eks_cluster_stack: True
# Kubernetes 版本
kubernetes_version: 1.31
...

resource_name_prefix 参数充当部署期间创建的 AWS 资源的主要标识符。每次部署都必须使用唯一的资源名称前缀以避免冲突。前缀参数的值在集群创建期间会自动附加一个唯一的标识符，以确保资源唯一性。

可以通过打开您选择的编辑器中的 config.yaml 文件，或通过运行 hyp configure 命令来编辑配置。以下示例显示了如何指定将由堆栈创建的 Amazon EKS 集群的 Kubernetes 版本：

hyp configure --kubernetes-version 1.33

通过 CLI 命令更新变量，在将值设置到 config.yaml 之前根据定义的架构执行验证，从而增加了安全性。

除了 Kubernetes 版本和资源名称前缀之外，一些重要参数的示例如下：

# 包含实例组配置的字符串列表
instance_group_settings:
  - {'InstanceCount': 1, 'InstanceGroupName': 'default', 'InstanceType': 'ml.t3.medium', 'TargetAvailabilityZoneId': 'use2-az2', 'ThreadsPerCore': 1, 'InstanceStorageConfigs': [{'EbsVolumeConfig': {'VolumeSizeInGB': 500}}]} # 布尔值，用于创建 EKS 集群堆栈
create_eks_cluster_stack: True # 用于存储集群生命周期脚本的 S3 桶的名称
s3_bucket_name: amzn-s3-demo-bucket # FSx 文件系统的存储容量（以 GiB 为单位）
storage_capacity: 1200

通过 hyp configure 命令更新配置值时，有两个重要的细微差别：

config.yaml 中变量名中的下划线 (_) 在 CLI 命令中变为连字符 (-)。因此，config.yaml 中的 kubernetes_version 是通过 CLI 中的 hyp configure --kubernetes-version 进行配置的。
config.yaml 中包含条目列表的变量作为 JSON 列表在 CLI 命令中配置。例如，多个实例组在 config.yaml 中配置如下：

instance_group_settings:
  - {'InstanceCount': 1, 'InstanceGroupName': 'default', 'InstanceType': 'ml.t3.medium', 'TargetAvailabilityZoneId': 'use2-az2', 'ThreadsPerCore': 1, 'InstanceStorageConfigs': [{'EbsVolumeConfig': {'VolumeSizeInGB': 500}}]}
  - {'InstanceCount': 2, 'InstanceGroupName': 'worker', 'InstanceType': 'ml.t3.large', 'TargetAvailabilityZoneId': 'use2-az2', 'ThreadsPerCore': 1, 'InstanceStorageConfigs': [{'EbsVolumeConfig': {'VolumeSizeInGB': 1000}}]}

这会转换为以下 CLI 命令：

hyp configure —instance-group-settings "[{'InstanceCount': 1, 'InstanceGroupName': 'default', 'InstanceType': 'ml.t3.medium', 'TargetAvailabilityZoneId': 'use2-az2', 'ThreadsPerCore': 1, 'InstanceStorageConfigs': [{'EbsVolumeConfig': {'VolumeSizeInGB': 500}}]}, {'InstanceCount': 2, 'InstanceGroupName': 'worker', 'InstanceType': 'ml.t3.large', 'TargetAvailabilityZoneId': 'use2-az2', 'ThreadsPerCore': 1, 'InstanceStorageConfigs': [{'EbsVolumeConfig': {'VolumeSizeInGB': 1000}}]}]"

在完成所需的更改后，通过运行以下命令验证您的配置文件：hyp validate

这将根据定义的架构验证 config.yaml 中的参数。如果成功，CLI 将输出以下内容：

(base) xxxxxxxx@3c06303f9abb hyperpod % hyp validate
✔️  config.yaml is valid!

可以通过运行以下命令将集群创建堆栈提交给 CloudFormation：hyp create --region <region>

hyp create 命令执行验证并将 config.yaml 中的值注入到 cfn_params.jinja 模板中。如果未明确提供 AWS 区域，该命令将使用 AWS 凭证配置中的默认区域。解析后的配置文件和 CloudFormation 模板值将保存到 ./run/ 目录下时间戳子目录中，提供了一种轻量级的本地版本控制机制，用于跟踪在特定时间点使用何种配置创建了集群。您也可以选择将这些工件提交到您的版本控制系统中，以提高可重复性和可审计性。如果成功，该命令将输出 CloudFormation 堆栈 ID：

(base) xxxxxxxx@3c06303f9abb dev % hyp create
✔️ config.yaml is valid!
✔️ Submitted! Files written to run/20251118T101501
Submitting to default region: us-east-1.
Stack creation initiated. Stack ID: arn:aws:cloudformation:us-east-1:xxxxxxxxxxx:stack/HyperpodClusterStack-d5351/5b83ed40-c491-11f0-a31f-1234073395a1

监控 HyperPod 集群创建过程

您可以通过运行以下命令来列出现有的 CloudFormation 堆栈：hyp list cluster-stack --region <region>

您可以通过添加以下标志来选择按堆栈状态过滤输出：--status "['CREATE_COMPLETE', 'UPDATE_COMPLETE']"。

此命令的输出将类似于以下内容：

(base) xxxxxxxx@3c06303f9abb dev % hyp list cluster-stack
📋 HyperPod Cluster Stacks (94 found) [1] Stack Details: Field | Value
---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------- StackId | arn:aws:cloudformation:us-east-1:xxxxxxxxxxx:stack/HyperpodClusterStack-d5351-S3EndpointStack-10JBD25F965A8/e2898250-c491-11f0-bf25-0afff7e082cf StackName | HyperpodClusterStack-d5351-S3EndpointStack-10JBD25F965A8 TemplateDescription | S3 Endpoint Stack
 CreationTime | :18:50 StackStatus | CREATE_COMPLETE ParentId | arn:aws:cloudformation:us-east-1:xxxxxxxxxxx:stack/HyperpodClusterStack-d5351/5b83ed40-c491-11f0-a31f-1234073395a1 RootId | arn:aws:cloudformation:us-east-1:xxxxxxxxxxx:stack/HyperpodClusterStack-d5351/5b83ed40-c491-11f0-a31f-1234073395a1 DriftInformation | {'StackDriftStatus': 'NOT_CHECKED'}

根据 config.yaml 中的配置，会创建几个嵌套堆栈，涵盖 HyperPod 集群设置的不同方面，例如 EKSClusterStack、FsxStack 和 VPCStack。

您可以使用 describe 命令查看任何单个堆栈的详细信息：hyp describe cluster-stack <stack-name> --region <region>

一个示例子堆栈 S3EndpointStack 的输出将类似于以下内容：

(base) xxxxxxxx@3c06303f9abb dev % hyp describe cluster-stack HyperpodClusterStack-d5351-S3EndpointStack-10JBD25F965A8
📋 Stack Details for: HyperpodClusterStack-d5351-S3EndpointStack-10JBD25F965A8
Status: CREATE_COMPLETE Field | Value -----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------- StackId | arn:aws:cloudformation:us-east-1:xxxxxxxxxxx:stack/HyperpodClusterStack-d5351-S3EndpointStack-10JBD25F965A8/e2898250-c491-11f0-bf25-0afff7e082cf StackName | HyperpodClusterStack-d5351-S3EndpointStack-10JBD25F965A8 Description | S3 Endpoint Stack Parameters | [ | { | "ParameterKey": "ResourceNamePrefix", | "ParameterValue": "hyp-eks-demo-stack" | }, | { | "ParameterKey": "VpcId", | "ParameterValue": "vpc-XXXXXXXXXXXXXX" | }, | { | "ParameterKey": "EksPrivateRouteTableIds", | "ParameterValue": "rtb-XXXXXXXXXXXXXX,rtb-XXXXXXXXXXXXXX" | }, | { | "ParameterKey": "PrivateRouteTableIds", | "ParameterValue": "rtb-XXXXXXXXXXXXXX,rtb-XXXXXXXXXXXXXX" | } | ]
 CreationTime | :18:50.007000+00:00 RollbackConfiguration | {} StackStatus | CREATE_COMPLETE DisableRollback | True NotificationARNs | [] Capabilities | [ | "CAPABILITY_AUTO_EXPAND", | "CAPABILITY_IAM", | "CAPABILITY_NAMED_IAM" | ] Tags | [] EnableTerminationProtection | False ParentId | arn:aws:cloudformation:us-east-1:xxxxxxxxxxx:stack/HyperpodClusterStack-d5351/5b83ed40-c491-11f0-a31f-1234073395a1 RootId | arn:aws:cloudformation:us-east-1:xxxxxxxxxxx:stack/HyperpodClusterStack-d5351/5b83ed40-c491-11f0-a31f-1234073395a1 DriftInformation | { | "StackDriftStatus": "NOT_CHECKED"

如果任何堆栈显示 CREATE_FAILED、ROLLBACK_* 或 DELETE_*，请在控制台中打开 CloudFormation 页面以调查根本原因。集群创建堆栈失败通常与集群本身、实例组或 VPC 或 NAT 网关等网络组件的不足的服务配额有关。请查看相应的SageMaker HyperPod 配额以了解 SageMaker HyperPod 所需的配额详情。

连接到集群

在集群堆栈成功创建所需资源并将状态更改为 CREATE_COMPLETE 后，您可以配置 CLI 和本地 Kubernetes 环境以与 HyperPod 集群交互。

hyp set-cluster-context --cluster-name <cluster-name> —region <region>

--cluster-name 选项指定要连接的 HyperPod 集群的名称，--region 选项指定创建集群的区域。可以选择使用 --namespace 参数配置特定命名空间。该命令会更新本地 ./kube/config 中的 Kubernetes 配置，以便您可以使用 HyperPod CLI 和 kubectl 等 Kubernetes 工具来管理 HyperPod 集群中的资源。

有关如何使用 CLI 向新创建的 HyperPod 集群提交训练作业和推理部署的更多信息，请参阅我们的配套博文：使用新的 HyperPod CLI 和 SDK 在 Amazon SageMaker HyperPod 上训练和部署模型。

修改现有的 HyperPod 集群

HyperPod CLI 通过 hyp update cluster 命令提供了一个命令来修改现有 HyperPod 集群的实例组和节点恢复模式。如果您需要通过添加或删除工作节点来扩展集群，或者想要更改节点组使用的实例类型，这会很有用。

要更新实例组，请运行以下命令，并根据您的集群名称和所需的实例组设置进行调整：

hyp update cluster --cluster-name  --region \
 --instance-groups '[{ 
         "instance_count": 2, 
         "instance_group_name": "worker-nodes", 
         "instance_type": "ml.m5.large", 
         "execution_role": "arn:aws:iam:::role/", 
         "life_cycle_config": { 
                 "source_s3_uri": "s3:///amzn-s3-demo-source-bucket/", 
                 "on_create": "on_create.sh" 
         }
   }]'

请注意，上一个命令中的所有字段都是运行更新命令所必需的，即使您只修改了实例计数。您可以通过运行 hyp describe cluster <cluster-name> --region <region> 命令来列出当前的集群和实例组配置以获取所需的值。

更新命令的输出将类似于以下内容：

[11/18/25 13:21:57] Update Params: {'instance_groups': [ClusterInstanceGroupSpecification(instance_count=2, instance_group_name='worker-nodes', instance_type='ml.m5.large', life_cycle_config=ClusterLifeCycleConfig(source_s3_uri='s3://amzn-s3-demo-source-bucket2', on_create='on_create.sh'), execution_role='arn:aws:iam::037065979077:role/hyp-eks-stack-4e5aExecRole', threads_per_core=<sagemaker_core.main.utils.Unassigned object at 0x106637810>, instance_storage_configs=<sagemaker_core.main.utils.Unassigned object at 0x106637810>, on_start_deep_health_checks=<sagemaker_core.main.utils.Unassigned object at 0x106637810>, training_plan_arn=<sagemaker_core.main.utils.Unassigned object at 0x106637810>, override_vpc_config=<sagemaker_core.main.utils.Unassigned object at 0x106637810>, scheduled_update_config=<sagemaker_core.main.utils.Unassigned object at 0x106637810>, image_id=<sagemaker_core.main.utils.Unassigned object at 0x106637810>)], 'node_recovery': 'Automatic'}
[11/18/25 13:21:58] Updating cluster resource. resources.py:3506
INFO:sagemaker_core.main.resources:Updating cluster resource.
Cluster has been updated
Cluster hyperpod-cluster has been updated

--node-recovery 选项允许您配置节点恢复行为，可以设置为 Automatic 或 None。有关 SageMaker HyperPod 自动节点恢复功能的更多信息，请参阅自动节点恢复。

删除现有的 HyperPod 集群

要删除现有的 HyperPod 集群，请运行以下命令。请注意，此操作不可逆：

hyp delete cluster-stack <stack-name> --region <region>

此命令将删除指定的 CloudFormation 堆栈和相关的 AWS 资源。您可以使用可选的 --retain-resources 标志来指定一个逗号分隔的逻辑资源 ID 列表，以便在删除过程中保留这些资源。仔细考虑需要保留哪些资源非常重要，因为删除操作无法撤销。

此命令的输出将类似于以下内容，提示您确认资源删除：

⚠ WARNING: This will delete the following 12 resources: Other (12): - EKSClusterStack - FsxStack - HelmChartStack - HyperPodClusterStack - HyperPodParamClusterStack - LifeCycleScriptStack - PrivateSubnetStack - S3BucketStack - S3EndpointStack - SageMakerIAMRoleStack - SecurityGroupStack - VPCStack Continue? [y/N]: y
✓ Stack 'HyperpodClusterStack-d5351' deletion initiated successfully

SageMaker HyperPod SDK

SageMaker HyperPod 还包含一个用于对上述功能进行编程访问的 Python SDK。Python SDK 被 CLI 命令使用，在安装 sagemaker-hyperpod Python 包（如本文开头所述）时会被安装。HyperPod CLI 最适合那些偏爱简化、交互式体验来执行常见 HyperPod 管理任务（如创建和监控集群、训练作业和推理端点）的用户。它对于快速原型设计、实验以及通过脚本或持续集成和交付 (CI/CD) 管道实现重复性 HyperPod 工作流程自动化特别有用。相比之下，HyperPod SDK 提供了更多的编程控制和灵活性，使其成为需要将 HyperPod 功能直接嵌入应用程序、与其他 AWS 或第三方服务集成或构建复杂的、定制化的 HyperPod 管理工作流程时的首选。请根据您用例的复杂性、对自动化和集成的需求来选择... [内容被截断]

🚀 想要体验更好更全面的AI调用？

欢迎使用青云聚合API，约为官网价格的十分之一，支持300+全球最新模型，以及全球各种生图生视频模型，无需翻墙高速稳定，文档丰富，小白也可以简单操作。

目录CONTENT

使用 HyperPod CLI 和 SDK 管理 Amazon SageMaker HyperPod 集群