As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# SageMaker criação de planos de treinamento usando a SageMaker API, ou AWS CLI
SageMaker os planos de treinamento apoiam a criação programática de planos de treinamento por meio de sua API. Você pode interagir com a API de planos de treinamento usando o AWS CLI ou SageMaker SDKs.
SageMaker As ações de API dos planos de treinamento fornecem um fluxo de trabalho abrangente para gerenciar os planos de treinamento de forma programática:
+ **`SearchTrainingPlanOfferings`:** permite que os usuários consultem e descubram os recursos de computação disponíveis especificando determinados parâmetros, como tipo de instância, contagem e janela de tempo desejada. A API exibe uma lista classificada das ofertas de plano de treinamento que melhor atendem aos requisitos do usuário.
+ **`CreateTrainingPlan`:** permite a reserva de uma oferta específica de plano de treinamento, transformando uma possível capacidade computacional em uma capacidade reservada programada com um ARN de plano de treinamento exclusivo.
+ **`ListTrainingPlans`:** fornece um método para recuperar e revisar todos os planos de treinamento existentes na AWS conta de um usuário, com recursos opcionais de filtragem e classificação.
+ **`DescribeTrainingPlan`:** oferece informações detalhadas sobre um plano de treinamento específico, inclusive os respectivos estágios do ciclo de vida, como `Pending`, `Active` e `Expired`.
+ **`ExtendTrainingPlan`:** amplia um plano de treinamento existente comprando uma oferta de extensão. Para obter mais informações, consulte [Extensão dos planos de treinamento](training-plan-extension.md).
+ **`DescribeTrainingPlanExtensionHistory`:** recupera o histórico de extensões de um plano de treinamento. Para obter mais informações, consulte [Extensão dos planos de treinamento](training-plan-extension.md).
**Topics**
+ [Pesquisar ofertas de plano de treinamento](search-training-plan-offerings-api-cli-sdk.md)
+ [Reservar o melhor plano de treinamento](choose-best-training-plan-using-api-cli-sdk.md)
+ [Listar as tarefas de treinamento](list-training-plans-using-api-cli-sdk.md)
+ [Visualizar detalhes do plano de treinamento](training-plan-details-using-api-cli-sdk.md)
# Pesquisar ofertas de plano de treinamento
Para criar um plano de treinamento, primeiro chame a operação de API [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html), inserindo os requisitos do plano (como tipo de instância, contagem e janela de tempo desejada) como parâmetros de entrada. Os planos de treinamento são específicos para seus recursos de destino. Especifique para qual recurso de destino o plano será usado (`training-job` ou `hyperpod-cluster`). A API exibe uma lista de ofertas disponíveis que correspondem aos seus requisitos. Se nenhuma oferta adequada for encontrada, talvez seja necessário ajustar seus requisitos e pesquisar novamente.
Essa chamada de API recupera as ofertas do plano de treinamento que melhor atendem às suas necessidades de capacidade. Cada resposta [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanOffering.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanOffering.html) exibida é identificada por um ID de oferta exclusivo. A primeira oferta da lista representa a melhor opção para suas necessidades. Se nenhum plano de treinamento adequado estiver disponível nas datas especificadas, a lista estará vazia. Ajuste seus critérios de pesquisa e procure um novo conjunto de ofertas.
+ As durações das reservas estão disponíveis em incrementos de 1 dia, de 1 a 182 dias.
+ As opções de quantidade de instâncias de reserva são 1, 2, 4, 8, 16, 32 ou 64 instâncias.
Para saber mais sobre a lista de instâncias disponíveis suportadas pelos planos de SageMaker treinamento, consulte[Tipos de instância Regiões da AWS e preços suportados](reserve-capacity-with-training-plans.md#training-plans-supported-instances-and-regions).
O exemplo a seguir usa um AWS CLI comando para solicitar ofertas de planos de treinamento com informações específicas sobre tipo de instância, contagem e horário.
```
# 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"
```
Este documento JSON é um exemplo de resposta da API de planos de SageMaker treinamento. A resposta fornece informações sobre várias ofertas de planos de treinamento disponíveis que atendem aos requisitos de capacidade especificados. Inclui três ofertas distintas com durações, taxas iniciais e start/end horários variados, todas usando o mesmo tipo de instância e visando trabalhos de treinamento.
```
{
"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"
}
]
}
]
}
```
A seguir está um exemplo de comando de como usar o AWS CLI para pesquisar ofertas de planos de treinamento que UltraServers incluam.
```
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"
}
]
}
]
}
```
As seções a seguir definem os parâmetros de solicitação de entrada obrigatórios e opcionais para a operação de API `SearchTrainingPlanOfferings`.
## Parâmetros necessários
Ao chamar a API [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html) para listar ofertas de plano de treinamento que atendam aos seus requisitos, você deve fornecer os seguintes valores:
+ `TargetResources`: os recursos de destino (`training-job` ou `hyperpod-cluster`) para os quais o plano será usado. O valor padrão é `training-job`. Os planos de treinamento são específicos para seus recursos de destino.
+ Um plano de treinamento projetado para trabalhos de SageMaker treinamento só pode ser usado para agendar e executar trabalhos de treinamento.
+ Um plano de treinamento para HyperPod clusters pode ser usado exclusivamente para fornecer recursos computacionais ao grupo de instâncias de um cluster.
+ `InstanceType`: o tipo de instância a ser provisionada. O `InstanceType` deve ser de um tipo compatível.
Para saber mais sobre a lista de instâncias disponíveis suportadas pelos planos de SageMaker treinamento, consulte[Tipos de instância Regiões da AWS e preços suportados](reserve-capacity-with-training-plans.md#training-plans-supported-instances-and-regions).
+ `InstanceCount`: o número de instâncias a serem provisionadas. Se o número de instâncias for maior que 1, deve ser uma potência de 2.
+ `DurationHour`: a duração total em horas do plano solicitado. `DurationHour` é arredondado para o próximo múltiplo de 24.
## Parâmetros opcionais
As seções a seguir fornecem detalhes de alguns parâmetros opcionais que você pode passar para a solicitação de API `SearchTrainingPlanOfferings`.
+ `StartTimeAfter`: especifique a hora de início solicitada do plano. `StartTimeAfter` deve ser um `timestamp` ou um valor `ISO 8601 date/time` no futuro.
+ `EndTimeBefore`: especifique a hora de término solicitada do plano no formato `timestamp` ou `ISO 8601 date/time`. `EndTimeBefore` deve ser pelo menos 24 horas após a hora de início.
+ `UltraServerType`: especifique o tipo UltraServer de pesquisa. Para obter mais informações sobre UltraServers, consulte[UltraServers em SageMaker IA](reserve-capacity-with-training-plans.md#training-plans-ultraservers).
+ `UltraServerCount`: especifique o número de UltraServers para pesquisar.
# Reservar o melhor plano de treinamento
Depois de analisar as ofertas de plano de treinamento disponíveis que melhor atendem às suas necessidades, você pode reservar um plano específico chamando a operação de API [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html). Quando criado, a princípio o plano entra em um estado `Pending` e permanece nele até que o processo de reserva seja concluído. A resposta à chamada de API exibirá o nome do recurso da Amazon (ARN) do plano de treinamento. Anote esse ARN para fins de rastreamento e monitoramento posteriores. A reserva do plano de treinamento é preenchida de forma assíncrona no backend. O pagamento do valor total é cobrado como parte do processo de atendimento. Depois que a transação de pagamento é concluída e as capacidades reservadas solicitadas são garantidas, o plano de treinamento é definido com o estado `Scheduled` e está pronto para ser agendado.
**Importante**
Os planos de treinamento não podem ser modificados após a compra.
Os planos de treinamento não podem ser compartilhados entre AWS contas ou dentro AWS da sua organização.
O exemplo a seguir usa o AWS CLI comando an para solicitar um plano de treinamento específico, passando o ID do plano como parâmetro.
```
aws sagemaker create-training-plan \
--training-plan-offering-id "tpo-SHA-256-hash-value" \
--training-plan-name "name" \
```
Este documento JSON é um exemplo de resposta da API de planos de SageMaker treinamento. A resposta contém o nome do recurso da Amazon (ARN) do plano de treinamento que foi criado com êxito.
**nota**
O plano de treinamento permanece no status `Pending` até que o processo de atendimento seja concluído.
```
{
"TrainingPlanArn":"arn:aws:sagemaker:us-east-1:123456789123:training-plan/large-models-fine-tuning"
}
```
As seções a seguir definem os parâmetros de solicitação de entrada obrigatórios e opcionais para a operação de API [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html).
## Parâmetros necessários
Ao chamar a API [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html) para reservar um plano de treinamento específico, você deve fornecer os seguintes valores:
+ `TrainingPlanOfferingId`: o ID do plano que você está escolhendo. Você pode recuperar o ID de uma oferta de plano na resposta da chamada de API `SearchTrainingPlanOfferings`. O formato deve começar com `pto-*`.
+ `TrainingPlanName`: o nome do plano que você está criando.
# Listar as tarefas de treinamento
Você pode listar todos os planos de treinamento que foram criados em sua AWS conta e região chamando a [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListTrainingPlans.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListTrainingPlans.html)API.
O exemplo a seguir usa um AWS CLI comando para recuperar a lista dos seus planos de treinamento.
```
aws sagemaker list-training-plans \
--start-time-after "2024-09-26T00:00:01.000Z"
```
Este documento JSON é um exemplo de resposta da API de planos de SageMaker treinamento. A resposta fornece detalhes sobre um plano de treinamento que foi criado e reservado com êxito.
```
{
"[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"
}
]
}
```
As seções a seguir fornecem detalhes de alguns parâmetros opcionais que você pode passar para solicitação de API `ListTrainingPlans`.
## Parâmetros opcionais
As seções a seguir fornecem detalhes de alguns parâmetros opcionais que você pode passar para a solicitação de API `ListTrainingPlans`.
+ `StartTimeAfter`: a hora de início do intervalo de tempo real dos planos listados, especificada como `timestamp` ou `ISO 8601 date/time`.
+ `StartTimeBefore`: a hora de término do intervalo de tempo real dos planos listados, especificada como `timestamp` ou `ISO 8601 date/time`.
+ `Filters`: Critérios usados para filtrar os resultados, com até 5 pares nome-valor em que “Nome” é o nome de um campo de a [TrainingPlanSummary](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanSummary.html)e “Valor” é o valor a ser considerado para o filtro. Por exemplo, `Name=Status,Value=Active`.
O exemplo a seguir usa um AWS CLI comando para recuperar sua lista de planos de treinamento, usando alguns dos parâmetros opcionais descritos acima.
```
aws sagemaker list-training-plans --max-results 10 --sort-by StartTime --sort-order Descending --start-time-after 13000000 --filters Name=Status,Value=Active
```
# Visualizar detalhes do plano de treinamento
Para monitorar o status ou recuperar detalhes de um plano de treinamento, você pode usar a API [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingPlan.html). A resposta da API inclui um campo `Status` que mostra o estado atual do plano de treinamento:
+ Se a compra do plano falhar, o status será definido como `Failed`.
+ Após o pagamento bem-sucedido, o status muda de `Pending` para `Scheduled`, com base na data de início do plano.
+ Quando o plano atinge a data de início, o status muda para `Active`.
+ Para planos com várias capacidades reservadas descontínuas, o status reverte para `Scheduled` entre os períodos ativos, até a data de início da próxima capacidade reservada.
+ Após a data de término do plano, o status passa a ser `Expired`.
Quando o status for`Scheduled`, você poderá utilizar a capacidade reservada no plano para seus trabalhos de SageMaker treinamento ou cargas de trabalho de HyperPod cluster.
**nota**
As tarefas de treinamento associadas ao plano permanecem no status `Pending` até que o plano se torne `Active`.
Para HyperPod clusters que usam um plano de treinamento para capacidade computacional, o status do grupo de instâncias aparece como `InService` uma vez criado.
O exemplo a seguir usa um AWS CLI comando para recuperar os detalhes de um plano de treinamento pelo nome.
```
aws sagemaker describe-training-plan \
--training-plan-name "name"
```
Este documento JSON é um exemplo de resposta da API de planos de SageMaker treinamento. Essa resposta fornece detalhes sobre um plano de treinamento que foi criado com êxito.
```
{
"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"
}
```
As seções a seguir definem o parâmetro de solicitação de entrada obrigatório para a operação de API `DescribeTrainingPlan`.
## Parâmetros necessários
+ `TrainingPlanName`: o nome do plano de treinamento que você deseja descrever.