本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 SageMaker API 建立 SageMaker 訓練計畫，或 AWS CLI SageMaker 訓練計畫支援透過其 API 以程式設計方式建立訓練計畫。您可以使用 AWS CLI 或 SageMaker SDKs與訓練計畫 API 互動。 SageMaker 訓練計畫的 API 動作提供以程式設計方式管理訓練計畫的全方位工作流程： + **`SearchTrainingPlanOfferings`：**可讓使用者透過指定執行個體類型、計數和所需時段等參數來查詢和探索可用的運算資源。API 會傳回最符合使用者要求的訓練計劃方案排名清單。 + **`CreateTrainingPlan`：**允許保留特定的訓練計畫方案，使用唯一的訓練計畫 ARN 將潛在的運算容量轉換為排程的預留容量。 + **`ListTrainingPlans`：**提供擷取和檢閱使用者帳戶中所有現有訓練計劃的方法 AWS ，以及選用的篩選和排序功能。 + **`DescribeTrainingPlan`：**提供特定訓練計畫的詳細洞見，包括其從 `Pending` 到 `Active` 再到 `Expired` 的生命週期階段。 + **`ExtendTrainingPlan`：**透過購買 延伸產品來擴展現有的訓練計劃。如需詳細資訊，請參閱[訓練計畫延伸](training-plan-extension.md)。 + **`DescribeTrainingPlanExtensionHistory`：**擷取訓練計畫的延伸歷史記錄。如需詳細資訊，請參閱[訓練計畫延伸](training-plan-extension.md)。 **Topics** + [搜尋訓練計畫供應項目](search-training-plan-offerings-api-cli-sdk.md) + [保留最佳訓練計畫](choose-best-training-plan-using-api-cli-sdk.md) + [列出訓練計畫](list-training-plans-using-api-cli-sdk.md) + [檢視訓練計畫詳細資訊](training-plan-details-using-api-cli-sdk.md) # 搜尋訓練計畫供應項目 若要建立訓練計畫，請先呼叫 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html) API 操作，將您的計劃要求 (例如執行個體類型、計數和所需時段) 做為輸入參數傳遞。訓練計畫專屬於其目標資源。確定您指定計畫將用於哪些目標資源 (`training-job` 或 `hyperpod-cluster`)。API 會傳回符合您要求的可用方案清單。如果找不到合適的方案，您可能需要調整要求並再次搜尋。 此 API 呼叫會擷取最符合您容量需求的訓練計畫方案。回應中傳回的每個 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanOffering.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanOffering.html) 都會以唯一的方案 ID 識別。清單中的第一個方案代表其最符合您的要求。如果在您指定的日期內沒有可用的訓練計畫，則清單為空白。調整您的搜尋條件並尋找一組新的方案。 + 保留持續時間從 1 天到 182 天，增量單位為 1 天。 + 保留執行個體數量選項為 1、2、4、8、16、32 或 64 個執行個體。 若要了解 SageMaker 訓練計畫支援的可用執行個體清單，請參閱 [支援的執行個體類型 AWS 區域和定價](reserve-capacity-with-training-plans.md#training-plans-supported-instances-and-regions)。 下列範例使用 AWS CLI 命令來請求具有指定執行個體類型、計數和時間資訊的培訓計劃方案。 ``` # List training plan offerings with instance type, instance count, duration in hours, start time after, and end time before. aws sagemaker search-training-plan-offerings \ --target-resources "training-job" \ --instance-type "ml.p4d.24xlarge" \ --instance-count 1 \ --duration-hours 15 \ --start-time-after "1737484800" --end-time-before "1737657600" ``` 此 JSON 文件是來自 SageMaker 訓練計畫 API 的範例回應。回應提供符合所指定容量要求的多個可用訓練計畫方案的相關資訊。它包含三種不同的方案，其中具有不同的持續時間、預付費用和開始/結束時間，全部都使用相同的執行個體類型並將訓練任務設為目標。 ``` { "TrainingPlanOfferings": [ { "TrainingPlanOfferingId": "tpo-SHA-256-hash-value", "TargetResources": [ "training-job" ], "RequestedStartTimeAfter": "2025-01-21T11:08:27.704000-08:00", "DurationHours": 15, "DurationMinutes": 51, "UpfrontFee": "xxxx.xx", "CurrencyCode": "USD", "ReservedCapacityOfferings": [ { "InstanceType": "ml.p4d.24xlarge", "InstanceCount": 1, "AvailabilityZone": "us-west-2a", "DurationHours": 15, "DurationMinutes": 51, "StartTime": "2025-01-21T11:39:00-08:00", "EndTime": "2025-01-22T03:30:00-08:00" } ] }, { "TrainingPlanOfferingId": "tpo-SHA-256-hash-value", "TargetResources": [ "training-job" ], "RequestedStartTimeAfter": "2025-01-21T11:08:27.704000-08:00", "DurationHours": 39, "DurationMinutes": 51, "UpfrontFee": "xxxx.xx", "CurrencyCode": "USD", "ReservedCapacityOfferings": [ { "InstanceType": "ml.p4d.24xlarge", "InstanceCount": 1, "AvailabilityZone": "us-west-2a", "DurationHours": 39, "DurationMinutes": 51, "StartTime": "2025-01-21T11:39:00-08:00", "EndTime": "2025-01-23T03:30:00-08:00" } ] }, { "TrainingPlanOfferingId": "tpo-SHA-256-hash-value", "TargetResources": [ "training-job" ], "RequestedStartTimeAfter": "2025-01-21T11:08:27.704000-08:00", "DurationHours": 24, "DurationMinutes": 0, "UpfrontFee": "xxxx.xx", "CurrencyCode": "USD", "ReservedCapacityOfferings": [ { "InstanceType": "ml.p4d.24xlarge", "InstanceCount": 1, "AvailabilityZone": "us-west-2a", "DurationHours": 24, "DurationMinutes": 0, "StartTime": "2025-01-22T03:30:00-08:00", "EndTime": "2025-01-23T03:30:00-08:00" } ] } ] } ``` 以下是如何使用 AWS CLI 搜尋包含 UltraServers 之訓練計劃方案的範例命令。 ``` aws sagemaker search-training-plan-offerings \ --ultra-server-type ml.c6i-32xlargesc \ --ultra-server-count 1 \ --duration-hours 24 \ --target-resources hyperpod-cluster --start-time-after "1737484800" \ --end-time-before "1737657600" ``` ``` { "TrainingPlanOfferings": [ { "TrainingPlanOfferingId": "tpo-SHA-256-hash-value", "TargetResources": [ "training-job" ], "RequestedStartTimeAfter": "2025-07-21T16:59:25.760000+00:00", "DurationHours": 24, "DurationMinutes": 0, "UpfrontFee": "0.24", "CurrencyCode": "USD", "ReservedCapacityOfferings": [ { "ReservedCapacityType": "UltraServer", "UltraServerType": "ml.u-p6e-gb200x72", "UltraServerCount": 1, "InstanceType": "ml.p6e-gb200.36xlarge", "InstanceCount": 18, "AvailabilityZone": "us-east-2a", "DurationHours": 24, "DurationMinutes": 0, "StartTime": "2025-07-22T11:30:00+00:00", "EndTime": "2025-07-23T11:30:00+00:00" } ] } ] } ``` 下列各節會針對 `SearchTrainingPlanOfferings` API 操作定義必要和選用的輸入請求參數。 ## 必要參數 呼叫 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html) API 列出符合您要求的訓練計畫方案時，您必須提供下列值： + `TargetResources`：將使用計畫的目標資源 (`training-job` 或 `hyperpod-cluster`)。預設值為 `training-job`。訓練計畫專屬於其目標資源。 + 專為 SageMaker 訓練任務設計的訓練計畫只能用來排程和執行訓練任務。 + HyperPod 叢集的訓練計畫專門用來將運算資源提供給叢集的執行個體群組。 + `InstanceType`：要佈建的執行個體類型。`InstanceType` 必須屬於支援的類型。 若要了解 SageMaker 訓練計畫支援的可用執行個體清單，請參閱 [支援的執行個體類型 AWS 區域和定價](reserve-capacity-with-training-plans.md#training-plans-supported-instances-and-regions)。 + `InstanceCount`：要佈建的執行個體數量。如果執行個體數量大於 1，則應該是 2 的次方。 + `DurationHour`：所請求計畫的總持續時間，以小時為單位。`DurationHour` 會四捨五入至最接近的 24 倍數。 ## 選用的參數 下列各節提供一些選用參數的詳細資訊，您可以將這些參數傳給 `SearchTrainingPlanOfferings` API 請求。 + `StartTimeAfter`：指定計畫的請求開始時間。`StartTimeAfter` 未來應該是 `timestamp` 或 `ISO 8601 date/time` 值。 + `EndTimeBefore`：以 `timestamp` 或 `ISO 8601 date/time` 格式指定計畫的請求結束時間。`EndTimeBefore` 應距開始時間至少 24 小時。 + `UltraServerType`：指定要搜尋的 UltraServer 類型。如需 UltraServer 的詳細資訊，請參閱 [SageMaker AI 中的 UltraServer](reserve-capacity-with-training-plans.md#training-plans-ultraservers)。 + `UltraServerCount`：指定要搜尋的 UltraServer 數量。 # 保留最佳訓練計畫 在檢閱最符合您要求的可用訓練計劃方案之後，您可以透過呼叫 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html) API 操作來保留特定計畫。建立時，計畫一開始會進入 `Pending` 狀態，並保留到預留程序完成為止。API 呼叫的回應會傳回訓練計畫 Amazon Resource Name (ARN)。請記下此 ARN，以供稍後追蹤和監控之用。訓練計畫保留會在後端以非同步方式完成。總金額的付款會在履行過程中自動收取。一旦完成付款交易並保護請求的預留容量，訓練計畫就會設定為 `Scheduled` 狀態，並準備好進行排程。 **重要** 訓練計畫一旦購買就無法修改。 訓練計劃無法跨 AWS 帳戶或在您的 AWS 組織內共用。 下列範例使用 AWS CLI 命令來請求特定的訓練計劃，並將計劃 ID 做為參數傳遞。 ``` aws sagemaker create-training-plan \ --training-plan-offering-id "tpo-SHA-256-hash-value" \ --training-plan-name "name" \ ``` 此 JSON 文件是來自 SageMaker 訓練計畫 API 的範例回應。回應包含已成功建立之訓練計畫的 Amazon Resource Name (ARN)。 **注意** 訓練計畫會保持 `Pending` 狀態，直到履行程序完成為止。 ``` { "TrainingPlanArn":"arn:aws:sagemaker:us-east-1:123456789123:training-plan/large-models-fine-tuning" } ``` 下列各節會針對 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html) API 操作定義必要和選用的輸入請求參數。 ## 必要參數 呼叫 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html) API 以保留特定訓練計畫時，您必須提供下列值： + `TrainingPlanOfferingId`：您要選擇的計畫 ID。您可以在 `SearchTrainingPlanOfferings` API 呼叫的回應中擷取計畫方案的 ID。其格式應以 `pto-*` 開頭。 + `TrainingPlanName`：您正要建立的計畫名稱。 # 列出訓練計畫 您可以呼叫 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListTrainingPlans.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListTrainingPlans.html) API，列出在 AWS 您的帳戶和區域中建立的所有訓練計畫。 下列範例使用 AWS CLI 命令來擷取訓練計畫的清單。 ``` aws sagemaker list-training-plans \ --start-time-after "2024-09-26T00:00:01.000Z" ``` 此 JSON 文件是來自 SageMaker 訓練計畫 API 的範例回應。回應提供已成功建立和保留之訓練計畫的詳細資訊。 ``` { "[TrainingPlanSummaries](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanSummary.html)": [ { "AvailableInstanceCount": 2, "CurrencyCode": "USD", "DurationHours": 48, "DurationMinutes": 0, "EndTime": "2024-09-28T04:30:00-07:00", "InUseInstanceCount": 2, "[ReservedCapacitySummaries](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ReservedCapacitySummary.html)": [ { "AvailabilityZone": "string", "DurationHours": 48, "DurationMinutes": 0, "EndTime": "2024-09-28T04:30:00-07:00", "InstanceType": "ml.p5.48xlarge", "ReservedCapacityArn": "arn:aws:sagemaker:us-east-1:123456789123:reserved-capacity/large-models-fine-tuning-rc1", "StartTime": "2024-09-26T04:30:00-07:00", "Status": "Scheduled", "TotalInstanceCount": 4, "UltraServerCount": 4, "UltraServerType": "ml.p6e-gb200.36xlarge" } ], "StartTime": "2024-09-26T04:30:00-07:00", "Status": "Scheduled", "StatusMessage": "Payment confirmed, training plan scheduled." "TargetResources": [ "training-job" ], "TotalInstanceCount": 4, "TotalUltraServerCount": 4, "TrainingPlanArn": "arn:aws:sagemaker:us-east-1:123456789123:training-plan/large-models-fine-tuning", "TrainingPlanName": "large-models-fine-tuning", "UpfrontFee": "xxxx.xx" } ] } ``` 下列各節提供一些選用參數的詳細資訊，您可以將這些參數傳給 `ListTrainingPlans` API 請求。 ## 選用的參數 下列各節提供一些選用參數的詳細資訊，您可以將這些參數傳給 `ListTrainingPlans` API 請求。 + `StartTimeAfter`：所列計畫實際時間範圍的開始時間，指定為 `timestamp` 或 `ISO 8601 date/time`。 + `StartTimeBefore`：所列計劃實際時間範圍的結束時間，指定為 `timestamp` 或 `ISO 8601 date/time`。 + `Filters`：用來篩選結果的條件，最多 5 個名稱/值對，其中 "Name" 是 [TrainingPlanSummary](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanSummary.html) 欄位的名稱，而 "Value" 是篩選條件要考慮的值。例如 `Name=Status,Value=Active`。 下列範例使用 AWS CLI 命令，使用上述一些選用參數來擷取訓練計畫清單。 ``` aws sagemaker list-training-plans --max-results 10 --sort-by StartTime --sort-order Descending --start-time-after 13000000 --filters Name=Status,Value=Active ``` # 檢視訓練計畫詳細資訊 若要監控狀態或擷取訓練計畫的詳細資訊，您可以使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingPlan.html) API。API 回應包含 `Status` 欄位，其中反映訓練計畫的目前狀態： + 如果計畫購買失敗，狀態會設定為 `Failed`。 + 成功付款後，狀態會根據計畫的開始日期從 `Pending` 轉換為 `Scheduled`。 + 當計畫來到其開始日期時，狀態會變更為 `Active`。 + 對於具有多個不連續預留容量的計畫，狀態會在作用中期間之間還原為 `Scheduled`，直到下一個預留容量的開始日期為止。 + 在計畫的結束日期之後，狀態會變成 `Expired`。 一旦狀態為 `Scheduled`，您就可以針對 SageMaker 訓練任務或 HyperPod 叢集工作負載，利用計畫中預留的容量。 **注意** 與計畫相關聯的訓練任務會保持 `Pending` 狀態，直到計畫變成 `Active` 為止。 對於針對運算容量使用訓練計畫的 HyperPod 叢集，一旦建立，執行個體群組狀態就會以 `InService` 出現。 下列範例使用 AWS CLI 命令，依其名稱擷取訓練計劃的詳細資訊。 ``` aws sagemaker describe-training-plan \ --training-plan-name "name" ``` 此 JSON 文件是來自 SageMaker 訓練計畫 API 的範例回應。此回應提供已成功建立之訓練計畫的詳細資訊。 ``` { "AvailableInstanceCount": 2, "CurrencyCode": "USD", "DurationHours": 48, "DurationMinutes": 0, "EndTime": "2024-09-28T04:30:00-07:00", "InUseInstanceCount": 2, "[ReservedCapacitySummaries](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ReservedCapacitySummary.html)": [ { "AvailabilityZone": "string", "DurationHours": 48, "DurationMinutes": 0, "EndTime": "2024-09-28T04:30:00-07:00", "InstanceType": "ml.p5.48xlarge", "ReservedCapacityArn": "arn:aws:sagemaker:us-east-1:123456789123:reserved-capacity/large-models-fine-tuning-rc1", "StartTime": "2024-09-26T04:30:00-07:00", "Status": "Scheduled", "TotalInstanceCount": 4, "UltraServerCount": 4, "UltraServerType": "ml.p6e-gb200.36xlarge" } ], "StartTime": "2024-09-26T04:30:00-07:00", "Status": "Scheduled", "StatusMessage": "Payment confirmed, training plan scheduled." "TargetResources": [ "training-job" ], "TotalInstanceCount": 4, "TotalUltraServerCount": 4, "TrainingPlanArn": "arn:aws:sagemaker:us-east-1:123456789123:training-plan/large-models-fine-tuning", "TrainingPlanName": "large-models-fine-tuning", "UpfrontFee": "xxxx.xx" } ``` 下列各節定義 `DescribeTrainingPlan` API 操作的必要輸入請求參數。 ## 必要參數 + `TrainingPlanName`：您要描述的訓練計畫名稱。