SageMaker Training Basics

Six examples to get you launching and monitoring SageMaker training jobs - four basic and two intermediate.

Each example shows the same operation in Python (boto3) and TypeScript (AWS SDK v3), using a built-in algorithm (XGBoost) as the running example.

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-sagemaker (Node.js 18+).
An IAM role that SageMaker can assume, with permission to read your input S3 prefix and write to your output S3 prefix (an "SageMaker execution role").
Training data already uploaded to S3 in a format the chosen algorithm expects (CSV for XGBoost in these examples).
Credentials configured via aws configure, environment variables, or an IAM role - the SDK resolves them automatically.

Quick Install

# --- Python (boto3) ---
import boto3
 
sm = boto3.client("sagemaker", region_name="us-east-1")

// --- TypeScript (AWS SDK v3) ---
import { SageMakerClient } from "@aws-sdk/client-sagemaker";
 
const sm = new SageMakerClient({ region: "us-east-1" });

Basic Examples

1. Point the Job at Training Data in S3

InputDataConfig is a list of named channels. Each channel says where its data lives in S3 and what content type it is.

# --- Python (boto3) ---
input_data_config = [{
    "ChannelName": "train",
    "DataSource": {
        "S3DataSource": {
            "S3DataType": "S3Prefix",
            "S3Uri": "s3://my-ml-bucket/training-data/train/",
            "S3DataDistributionType": "FullyReplicated",
        }
    },
    "ContentType": "text/csv",
}]

// --- TypeScript (AWS SDK v3) ---
const inputDataConfig = [{
  ChannelName: "train",
  DataSource: {
    S3DataSource: {
      S3DataType: "S3Prefix",
      S3Uri: "s3://my-ml-bucket/training-data/train/",
      S3DataDistributionType: "FullyReplicated",
    },
  },
  ContentType: "text/csv",
}];

ChannelName becomes an environment variable inside the container (SM_CHANNEL_TRAIN), which is how the training code finds the data.
S3Uri can point at a single object or a prefix; S3Prefix pulls down every object under it.
Add a second channel (e.g. validation) the same way if your algorithm needs held-out data.
FullyReplicated copies the full dataset to every training instance; distributed training pages cover sharding.

Related: Training Jobs: Built-in Algorithms vs Custom Containers.

2. Choose Resources and an Output Location

ResourceConfig picks the compute; OutputDataConfig says where the trained model artifact should be written.

# --- Python (boto3) ---
resource_config = {
    "InstanceType": "ml.m5.xlarge",
    "InstanceCount": 1,
    "VolumeSizeInGB": 30,
}
output_data_config = {"S3OutputPath": "s3://my-ml-bucket/training-output/"}

// --- TypeScript (AWS SDK v3) ---
const resourceConfig = {
  InstanceType: "ml.m5.xlarge",
  InstanceCount: 1,
  VolumeSizeInGB: 30,
};
const outputDataConfig = { S3OutputPath: "s3://my-ml-bucket/training-output/" };

InstanceCount above 1 splits work across a cluster; single-instance jobs are the simplest starting point.
VolumeSizeInGB sizes the EBS volume attached to each training instance for data and checkpoints.
SageMaker appends the job name under S3OutputPath, so multiple jobs never collide.
Larger or GPU instance types (like ml.g5.xlarge) matter for deep learning workloads, not for lightweight algorithms like XGBoost on small data.

3. Launch a Training Job

CreateTrainingJob ties the algorithm image, IAM role, data, resources, and stopping condition together into one job.

# --- Python (boto3) ---
sm.create_training_job(
    TrainingJobName="xgboost-basics-001",
    AlgorithmSpecification={
        # AWS-published built-in algorithm image, referenced like any other container.
        "TrainingImage": "683313688378.dkr.ecr.us-east-1.amazonaws.com/xgboost:1.7-1",
        "TrainingInputMode": "File",
    },
    RoleArn="arn:aws:iam::111122223333:role/SageMakerExecutionRole",
    InputDataConfig=input_data_config,
    OutputDataConfig=output_data_config,
    ResourceConfig=resource_config,
    HyperParameters={"num_round": "100", "objective": "binary:logistic"},
    StoppingCondition={"MaxRuntimeInSeconds": 3600},
)

// --- TypeScript (AWS SDK v3) ---
import { CreateTrainingJobCommand } from "@aws-sdk/client-sagemaker";
 
await sm.send(new CreateTrainingJobCommand({
  TrainingJobName: "xgboost-basics-001",
  AlgorithmSpecification: {
    // AWS-published built-in algorithm image, referenced like any other container.
    TrainingImage: "683313688378.dkr.ecr.us-east-1.amazonaws.com/xgboost:1.7-1",
    TrainingInputMode: "File",
  },
  RoleArn: "arn:aws:iam::111122223333:role/SageMakerExecutionRole",
  InputDataConfig: inputDataConfig,
  OutputDataConfig: outputDataConfig,
  ResourceConfig: resourceConfig,
  HyperParameters: { num_round: "100", objective: "binary:logistic" },
  StoppingCondition: { MaxRuntimeInSeconds: 3600 },
}));

Built-in algorithm image URIs are region-specific and published in the SageMaker documentation; check yours before hardcoding one.
HyperParameters values are always strings, even for numeric settings - the container parses them.
MaxRuntimeInSeconds is a hard cap; SageMaker stops the job (and billing) once it is reached.
The call returns immediately with a TrainingJobArn - the job runs asynchronously from here.

Related: SageMaker's End-to-End ML Lifecycle Model.

4. Check Job Status

DescribeTrainingJob reports the current TrainingJobStatus - InProgress, Completed, Failed, or Stopped - plus a failure reason if it did not succeed.

# --- Python (boto3) ---
desc = sm.describe_training_job(TrainingJobName="xgboost-basics-001")
print("status:", desc["TrainingJobStatus"])
if desc["TrainingJobStatus"] == "Failed":
    print("reason:", desc["FailureReason"])

// --- TypeScript (AWS SDK v3) ---
import { DescribeTrainingJobCommand } from "@aws-sdk/client-sagemaker";
 
const desc = await sm.send(new DescribeTrainingJobCommand({ TrainingJobName: "xgboost-basics-001" }));
console.log("status:", desc.TrainingJobStatus);
if (desc.TrainingJobStatus === "Failed") {
  console.log("reason:", desc.FailureReason);
}

InProgress covers everything from provisioning through the container actually running.
FailureReason is a plain-text summary - the full logs live in CloudWatch Logs under /aws/sagemaker/TrainingJobs.
SecondaryStatus gives a finer-grained phase (Starting, Downloading, Training, Uploading) if you need it.
A single describe call is cheap; poll on an interval rather than in a tight loop.

Intermediate Examples

5. Wait for the Job to Finish

Instead of hand-rolled polling, use the training_job_completed_or_stopped waiter (boto3) or its SDK v3 equivalent.

# --- Python (boto3) ---
waiter = sm.get_waiter("training_job_completed_or_stopped")
waiter.wait(
    TrainingJobName="xgboost-basics-001",
    WaiterConfig={"Delay": 30, "MaxAttempts": 120},   # up to 60 minutes
)
print("job finished")

// --- TypeScript (AWS SDK v3) ---
import { waitUntilTrainingJobCompletedOrStopped } from "@aws-sdk/client-sagemaker";
 
await waitUntilTrainingJobCompletedOrStopped(
  { client: sm, maxWaitTime: 3600 },
  { TrainingJobName: "xgboost-basics-001" },
);
console.log("job finished");

The waiter polls DescribeTrainingJob on your behalf and returns once the status is terminal (Completed, Failed, or Stopped).
It does not throw on Failed in every SDK - always check TrainingJobStatus afterward rather than assuming success.
Set the timeout generously for larger datasets or instance types; a training job can run far longer than a control-plane call.
Polling still counts as SDK calls; the waiter's delay keeps that volume reasonable.

6. Read Back the Model Artifact

Once the job completes, ModelArtifacts.S3ModelArtifacts is the S3 path your deployment stage will use next.

# --- Python (boto3) ---
desc = sm.describe_training_job(TrainingJobName="xgboost-basics-001")
artifact_uri = desc["ModelArtifacts"]["S3ModelArtifacts"]
print("model artifact:", artifact_uri)   # e.g. s3://.../xgboost-basics-001/output/model.tar.gz

// --- TypeScript (AWS SDK v3) ---
const desc2 = await sm.send(new DescribeTrainingJobCommand({ TrainingJobName: "xgboost-basics-001" }));
const artifactUri = desc2.ModelArtifacts?.S3ModelArtifacts;
console.log("model artifact:", artifactUri);

The artifact is only present once TrainingJobStatus is Completed - it is absent while the job is running.
This URI is exactly what CreateModel expects for its ModelDataUrl/PrimaryContainer.ModelDataUrl field when you deploy.
The artifact is a plain model.tar.gz; its internal contents depend entirely on what the algorithm's container wrote.
Nothing about training or this artifact tells you how well the model performs - check the job's logged metrics for that.

Related: SageMaker Training via SDK Best Practices.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Each example shows the same operation in Python (boto3) and TypeScript (AWS SDK v3), using a built-in algorithm (XGBoost) as the running example.

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-sagemaker (Node.js 18+).
An IAM role that SageMaker can assume, with permission to read your input S3 prefix and write to your output S3 prefix (an "SageMaker execution role").
Training data already uploaded to S3 in a format the chosen algorithm expects (CSV for XGBoost in these examples).
Credentials configured via aws configure, environment variables, or an IAM role - the SDK resolves them automatically.

Quick Install

# --- Python (boto3) ---
import boto3
 
sm = boto3.client("sagemaker", region_name="us-east-1")

// --- TypeScript (AWS SDK v3) ---
import { SageMakerClient } from "@aws-sdk/client-sagemaker";
 
const sm = new SageMakerClient({ region: "us-east-1" });

Basic Examples

1. Point the Job at Training Data in S3

InputDataConfig is a list of named channels. Each channel says where its data lives in S3 and what content type it is.

# --- Python (boto3) ---
input_data_config = [{
    "ChannelName": "train",
    "DataSource": {
        "S3DataSource": {
            "S3DataType": "S3Prefix",
            "S3Uri": "s3://my-ml-bucket/training-data/train/",
            "S3DataDistributionType": "FullyReplicated",
        }
    },
    "ContentType": "text/csv",
}]

// --- TypeScript (AWS SDK v3) ---
const inputDataConfig = [{
  ChannelName: "train",
  DataSource: {
    S3DataSource: {
      S3DataType: "S3Prefix",
      S3Uri: "s3://my-ml-bucket/training-data/train/",
      S3DataDistributionType: "FullyReplicated",
    },
  },
  ContentType: "text/csv",
}];

ChannelName becomes an environment variable inside the container (SM_CHANNEL_TRAIN), which is how the training code finds the data.
S3Uri can point at a single object or a prefix; S3Prefix pulls down every object under it.
Add a second channel (e.g. validation) the same way if your algorithm needs held-out data.
FullyReplicated copies the full dataset to every training instance; distributed training pages cover sharding.

Related: Training Jobs: Built-in Algorithms vs Custom Containers.

2. Choose Resources and an Output Location

ResourceConfig picks the compute; OutputDataConfig says where the trained model artifact should be written.

# --- Python (boto3) ---
resource_config = {
    "InstanceType": "ml.m5.xlarge",
    "InstanceCount": 1,
    "VolumeSizeInGB": 30,
}
output_data_config = {"S3OutputPath": "s3://my-ml-bucket/training-output/"}

// --- TypeScript (AWS SDK v3) ---
const resourceConfig = {
  InstanceType: "ml.m5.xlarge",
  InstanceCount: 1,
  VolumeSizeInGB: 30,
};
const outputDataConfig = { S3OutputPath: "s3://my-ml-bucket/training-output/" };

InstanceCount above 1 splits work across a cluster; single-instance jobs are the simplest starting point.
VolumeSizeInGB sizes the EBS volume attached to each training instance for data and checkpoints.
SageMaker appends the job name under S3OutputPath, so multiple jobs never collide.
Larger or GPU instance types (like ml.g5.xlarge) matter for deep learning workloads, not for lightweight algorithms like XGBoost on small data.

3. Launch a Training Job

CreateTrainingJob ties the algorithm image, IAM role, data, resources, and stopping condition together into one job.

# --- Python (boto3) ---
sm.create_training_job(
    TrainingJobName="xgboost-basics-001",
    AlgorithmSpecification={
        # AWS-published built-in algorithm image, referenced like any other container.
        "TrainingImage": "683313688378.dkr.ecr.us-east-1.amazonaws.com/xgboost:1.7-1",
        "TrainingInputMode": "File",
    },
    RoleArn="arn:aws:iam::111122223333:role/SageMakerExecutionRole",
    InputDataConfig=input_data_config,
    OutputDataConfig=output_data_config,
    ResourceConfig=resource_config,
    HyperParameters={"num_round": "100", "objective": "binary:logistic"},
    StoppingCondition={"MaxRuntimeInSeconds": 3600},
)

// --- TypeScript (AWS SDK v3) ---
import { CreateTrainingJobCommand } from "@aws-sdk/client-sagemaker";
 
await sm.send(new CreateTrainingJobCommand({
  TrainingJobName: "xgboost-basics-001",
  AlgorithmSpecification: {
    // AWS-published built-in algorithm image, referenced like any other container.
    TrainingImage: "683313688378.dkr.ecr.us-east-1.amazonaws.com/xgboost:1.7-1",
    TrainingInputMode: "File",
  },
  RoleArn: "arn:aws:iam::111122223333:role/SageMakerExecutionRole",
  InputDataConfig: inputDataConfig,
  OutputDataConfig: outputDataConfig,
  ResourceConfig: resourceConfig,
  HyperParameters: { num_round: "100", objective: "binary:logistic" },
  StoppingCondition: { MaxRuntimeInSeconds: 3600 },
}));

Built-in algorithm image URIs are region-specific and published in the SageMaker documentation; check yours before hardcoding one.
HyperParameters values are always strings, even for numeric settings - the container parses them.
MaxRuntimeInSeconds is a hard cap; SageMaker stops the job (and billing) once it is reached.
The call returns immediately with a TrainingJobArn - the job runs asynchronously from here.

Related: SageMaker's End-to-End ML Lifecycle Model.

4. Check Job Status

DescribeTrainingJob reports the current TrainingJobStatus - InProgress, Completed, Failed, or Stopped - plus a failure reason if it did not succeed.

# --- Python (boto3) ---
desc = sm.describe_training_job(TrainingJobName="xgboost-basics-001")
print("status:", desc["TrainingJobStatus"])
if desc["TrainingJobStatus"] == "Failed":
    print("reason:", desc["FailureReason"])

// --- TypeScript (AWS SDK v3) ---
import { DescribeTrainingJobCommand } from "@aws-sdk/client-sagemaker";
 
const desc = await sm.send(new DescribeTrainingJobCommand({ TrainingJobName: "xgboost-basics-001" }));
console.log("status:", desc.TrainingJobStatus);
if (desc.TrainingJobStatus === "Failed") {
  console.log("reason:", desc.FailureReason);
}

InProgress covers everything from provisioning through the container actually running.
FailureReason is a plain-text summary - the full logs live in CloudWatch Logs under /aws/sagemaker/TrainingJobs.
SecondaryStatus gives a finer-grained phase (Starting, Downloading, Training, Uploading) if you need it.
A single describe call is cheap; poll on an interval rather than in a tight loop.

Intermediate Examples

5. Wait for the Job to Finish

Instead of hand-rolled polling, use the training_job_completed_or_stopped waiter (boto3) or its SDK v3 equivalent.

# --- Python (boto3) ---
waiter = sm.get_waiter("training_job_completed_or_stopped")
waiter.wait(
    TrainingJobName="xgboost-basics-001",
    WaiterConfig={"Delay": 30, "MaxAttempts": 120},   # up to 60 minutes
)
print("job finished")

// --- TypeScript (AWS SDK v3) ---
import { waitUntilTrainingJobCompletedOrStopped } from "@aws-sdk/client-sagemaker";
 
await waitUntilTrainingJobCompletedOrStopped(
  { client: sm, maxWaitTime: 3600 },
  { TrainingJobName: "xgboost-basics-001" },
);
console.log("job finished");

The waiter polls DescribeTrainingJob on your behalf and returns once the status is terminal (Completed, Failed, or Stopped).
It does not throw on Failed in every SDK - always check TrainingJobStatus afterward rather than assuming success.
Set the timeout generously for larger datasets or instance types; a training job can run far longer than a control-plane call.
Polling still counts as SDK calls; the waiter's delay keeps that volume reasonable.

6. Read Back the Model Artifact

Once the job completes, ModelArtifacts.S3ModelArtifacts is the S3 path your deployment stage will use next.

# --- Python (boto3) ---
desc = sm.describe_training_job(TrainingJobName="xgboost-basics-001")
artifact_uri = desc["ModelArtifacts"]["S3ModelArtifacts"]
print("model artifact:", artifact_uri)   # e.g. s3://.../xgboost-basics-001/output/model.tar.gz

// --- TypeScript (AWS SDK v3) ---
const desc2 = await sm.send(new DescribeTrainingJobCommand({ TrainingJobName: "xgboost-basics-001" }));
const artifactUri = desc2.ModelArtifacts?.S3ModelArtifacts;
console.log("model artifact:", artifactUri);

The artifact is only present once TrainingJobStatus is Completed - it is absent while the job is running.
This URI is exactly what CreateModel expects for its ModelDataUrl/PrimaryContainer.ModelDataUrl field when you deploy.
The artifact is a plain model.tar.gz; its internal contents depend entirely on what the algorithm's container wrote.
Nothing about training or this artifact tells you how well the model performs - check the job's logged metrics for that.

Related: SageMaker Training via SDK Best Practices.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

SageMaker Training Basics

Buscar na documentação

SageMaker Training Basics