Amazon SageMaker HyperPod 核心命令指南

Amazon SageMaker HyperPod 提供丰富的命令行功能，用于管理训练工作流。本指南涵盖常见操作的核心命令，包括连接集群、监控作业进度。

先决条件

使用这些命令前，请确保已完成以下配置：

安装配方 CLI

执行安装命令前，请先导航到配方存储库根目录。

若使用非 Forge 自定义方案，请使用 Hyperpodrecipes 存储库；若基于 Forge 进行自定义，请参考专属 Forge 的配方存储库。

执行以下命令安装 SageMaker HyperPod CLI：

若使用的是非 Forge 自定义技术，请按如下方式下载 sagemaker-hyperpod-recipes 存储库：

git clone -b release_v2 https://github.com/aws/sagemaker-hyperpod-cli.git
cd sagemaker-hyperpod-cli
pip install -e .
cd ..
root_dir=$(pwd)
export PYTHONPATH=${root_dir}/sagemaker-hyperpod-cli/src/hyperpod_cli/sagemaker_hyperpod_recipes/launcher/nemo/nemo_framework_launcher/launcher_scripts:$PYTHONPATH
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh
rm -f ./get_helm.sh

若为 Forge 订阅用户，您应按照如下流程下载配方。

mkdir NovaForgeHyperpodCLI
cd NovaForgeHyperpodCLI
aws s3 cp s3://nova-forge-c7363-206080352451-us-east-1/v1/ ./ --recursive
pip install -e .

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh
rm -f ./get_helm.sh

目的：为何要执行 pip install -e .？

该命令以可编辑模式安装 SageMaker HyperPod CLI，无需您每次重新安装，即可使用更新后的配方。其同时支持新增配方并被 CLI 自动识别。

连接到集群

运行任何任务前，请先使用 SageMaker HyperPod CLI 连接集群：

export AWS_REGION=us-east-1 &&  SageMaker HyperPod  connect-cluster --cluster-name <your-cluster-name> --region us-east-1

专业提示：您可以通过在命令中添加 --namespace kubeflow 参数，进一步将集群配置为始终使用 kubeflow 命名空间，示例如下：

export AWS_REGION=us-east-1 && \
hyperpod connect-cluster \
--cluster-name <your-cluster-name> \
--region us-east-1 \
--namespace kubeflow

这样就无需在每条任务命令中都添加 -n kubeflow。

启动训练作业

label_selector:
  required:
    sagemaker.amazonaws.com/instance-group-name:
      - <rig_group>

通过配方启动训练作业（支持可选参数覆盖）：

hyperpod start-job -n kubeflow \
--recipe fine-tuning/nova/nova_1_0/nova_micro/SFT/nova_micro_1_0_p5_p4d_gpu_lora_sft \
--override-parameters '{
"instance_type": "ml.p5.48xlarge",
    "container": "708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-fine-tune-repo:SM-HP-SFT-latest"
  }'

预期输出：

Final command: python3 <path_to_your_installation>/NovaForgeHyperpodCLI/src/hyperpod_cli/sagemaker_hyperpod_recipes/main.py recipes=fine-tuning/nova/nova_micro_p5_gpu_sft cluster_type=k8s cluster=k8s base_results_dir=/local/home/<username>/results cluster.pullPolicy="IfNotPresent" cluster.restartPolicy="OnFailure" cluster.namespace="kubeflow" container="708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-fine-tune-repo:HP-SFT-DATAMIX-latest"

Prepared output directory at /local/home/<username>/results/<job-name>/k8s_templates
Found credentials in shared credentials file: ~/.aws/credentials
Helm script created at /local/home/<username>/results/<job-name>/<job-name>_launch.sh
Running Helm script: /local/home/<username>/results/<job-name>/<job-name>_launch.sh

NAME: <job-name>
LAST DEPLOYED: Mon Sep 15 20:56:50 2025
NAMESPACE: kubeflow
STATUS: deployed
REVISION: 1
TEST SUITE: None
Launcher successfully generated: <path_to_your_installation>/NovaForgeHyperpodCLI/src/hyperpod_cli/sagemaker_hyperpod_recipes/launcher/nova/k8s_templates/SFT

{
 "Console URL": "https://us-east-1.console.aws.amazon.com/sagemaker/home?region=us-east-1#/cluster-management/<your-cluster-name>"
}

查看作业状态

使用 kubectl 监控运行中的作业：

kubectl get pods -o wide -w -n kubeflow | (head -n1 ; grep <your-job-name>)

容器组（pod）状态说明

下表说明常见的容器组（pod）状态：

监控作业日志

您可通过以下三种方式之一查看日志：

使用 CloudWatch

日志存储在包含 HyperPod 集群的 AWS 账户对应的 CloudWatch 中。如需在浏览器中查看，请导航到账户中的 CloudWatch 主页，然后搜索集群名称。例如，若集群名为 my-hyperpod-rig，则日志组的前缀为：

使用 CloudWatch Insights

若已掌握作业名称，且不想执行上述全部步骤，可直接在 /aws/sagemaker/Clusters/my-hyperpod-rig/{UUID} 下查询所有日志，以定位对应日志。

CPT：

fields @timestamp, @message, @logStream, @log
| filter @message like /(?i)Starting CPT Job/
| sort @timestamp desc
| limit 100

如需查询作业完成状态，可将 Starting CPT Job 替换为 CPT Job completed

然后，您可以单击结果，并选择显示“Epoch 0”的结果，因为那将是主节点。

使用 AWSAWS CLI

您也可以通过 AWS CLI 实时跟踪日志。操作前，请先使用 aws --version 检查 AWS CLI 版本。建议使用提供的工具脚本，以便在终端中实时跟踪日志

V1：

aws logs get-log-events \
--log-group-name /aws/sagemaker/YourLogGroupName \
--log-stream-name YourLogStream \
--start-from-head | jq -r '.events[].message'

V2：

aws logs tail /aws/sagemaker/YourLogGroupName \
 --log-stream-name YourLogStream \
--since 10m \
--follow

列出所有活跃作业

查看集群中所有正在运行的作业：

hyperpod list-jobs -n kubeflow

输出示例：

{
  "jobs": [
    {
      "Name": "test-run-nhgza",
      "Namespace": "kubeflow",
      "CreationTime": "2025-10-29T16:50:57Z",
      "State": "Running"
    }
  ]
}

取消作业

随时停止正在运行的作业：

hyperpod cancel-job --job-name <job-name> -n kubeflow

查找作业名称

选项 1：从配方中获取

作业名称已在配方的 run 代码块中指定：

run:
  name: "my-test-run"                        # This is your job name
  model_type: "amazon.nova-micro-v1:0:128k"
  ...

选项 2：通过 list-jobs 命令获取

执行 hyperpod list-jobs -n kubeflow 命令，复制输出结果中的 Name 字段即可。

运行评估作业

使用评估配方对已训练模型或基础模型进行评估。

先决条件

运行评估作业前，确保已准备好以下内容：

命令

执行以下命令启动评估作业：

hyperpod start-job -n kubeflow \
  --recipe evaluation/nova/nova_2_0/nova_lite/nova_lite_2_0_p5_48xl_gpu_bring_your_own_dataset_eval \
  --override-parameters '{
    "instance_type": "p5.48xlarge",
    "container": "708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-evaluation-repo:SM-HP-Eval-latest",
    "recipes.run.name": "<your-eval-job-name>",
    "recipes.run.model_name_or_path": "<checkpoint-s3-uri>",
    "recipes.run.output_s3_path": "s3://<your-bucket>/eval-results/",
    "recipes.run.data_s3_path": "s3://<your-bucket>/eval-data.jsonl"
  }'

参数描述：

提示：

评估数据格式

输入格式（JSONL）：

{
  "metadata": "{key:4, category:'apple'}",
  "system": "arithmetic-patterns, please answer the following with no other words: ",
  "query": "What is the next number in this series? 1, 2, 4, 8, 16, ?",
  "response": "32"
}

输出格式：

{
  "prompt": "[{'role': 'system', 'content': 'arithmetic-patterns, please answer the following with no other words: '}, {'role': 'user', 'content': 'What is the next number in this series? 1, 2, 4, 8, 16, ?'}]",
  "inference": "['32']",
  "gold": "32",
  "metadata": "{key:4, category:'apple'}"
}

字段描述：

常见问题