SageMaker Python SDK

The SageMaker Python SDK is a comprehensive Python library for training and deploying machine learning models on Amazon SageMaker. It provides a unified interface for the complete machine learning workflow from data preparation and distributed training to model deployment, monitoring, and pipeline orchestration.

Package Information

• Package Name: sagemaker
• Language: Python
• Installation: pip install sagemaker
• Supported Python: 3.9, 3.10, 3.11, 3.12
• PyPI: https://pypi.org/project/sagemaker/
• Documentation: https://sagemaker.readthedocs.io/

Core Imports

# Training
from sagemaker.train import ModelTrainer, Session, get_execution_role
from sagemaker.train.tuner import HyperparameterTuner

# Serving/Inference
from sagemaker.serve import ModelBuilder, InferenceSpec, ModelServer

# MLOps/Pipelines
from sagemaker.mlops.workflow import Pipeline, TrainingStep, ProcessingStep

# Core functionality
from sagemaker.core import Processor, Transformer
from sagemaker.core.workflow import ParameterString, ConditionEquals

Basic Usage

Training a Model

from sagemaker.train import ModelTrainer
from sagemaker.train.configs import InputData, Compute

# Create trainer
trainer = ModelTrainer(
    training_image="my-training-image",
    role="arn:aws:iam::123456789012:role/SageMakerRole",
    compute=Compute(instance_type="ml.m5.xlarge", instance_count=1)
)

# Prepare training data
train_data = InputData(
    channel_name="training",
    data_source="s3://my-bucket/train"
)

# Start training
trainer.train(input_data_config=[train_data])

Deploying a Model

from sagemaker.serve import ModelBuilder

# Build model
builder = ModelBuilder(
    model="my-model",
    model_path="s3://my-bucket/model.tar.gz",
    role_arn="arn:aws:iam::123456789012:role/SageMakerRole",
    instance_type="ml.m5.xlarge"
)

# Deploy to endpoint
model = builder.build()
endpoint = builder.deploy(endpoint_name="my-endpoint")

# Make predictions
result = endpoint.invoke(data=input_data)

Creating a Pipeline

from sagemaker.mlops.workflow import Pipeline, TrainingStep, ProcessingStep
from sagemaker.train import ModelTrainer
from sagemaker.core import Processor

# Define steps
training_step = TrainingStep(name="Train", estimator=trainer)
processing_step = ProcessingStep(name="Process", processor=processor)

# Create pipeline
pipeline = Pipeline(
    name="my-pipeline",
    steps=[processing_step, training_step]
)

# Execute pipeline
execution = pipeline.start()

Architecture

The SageMaker Python SDK V3 uses a modular architecture with four sub-packages:

• sagemaker-core: Foundation layer providing processing, batch transform, workflow primitives, and resource management
• sagemaker-train: Training functionality with unified ModelTrainer class and fine-tuning capabilities
• sagemaker-serve: Serving/inference with unified ModelBuilder class
• sagemaker-mlops: Pipeline orchestration and workflow management

All packages use namespace packaging under sagemaker.* for unified imports.

Capabilities

Training

Comprehensive model training capabilities including distributed training, hyperparameter tuning, and fine-tuning for foundation models.

from sagemaker.train import ModelTrainer
from sagemaker.train.tuner import HyperparameterTuner
from sagemaker.train.sft_trainer import SFTTrainer
from sagemaker.train.dpo_trainer import DPOTrainer
from sagemaker.train.rlaif_trainer import RLAIFTrainer
from sagemaker.train.rlvr_trainer import RLVRTrainer

Training

Serving & Inference

Unified interface for model deployment with support for multiple frameworks, model servers, and deployment modes (SageMaker endpoint, local container, in-process).

from sagemaker.serve import ModelBuilder, InferenceSpec, ModelServer, Mode
from sagemaker.serve.builder.schema_builder import SchemaBuilder
from sagemaker.serve.utils.payload_translator import CustomPayloadTranslator

Serving & Inference

MLOps & Pipelines

Pipeline orchestration with 13+ step types for building complex ML workflows with conditional execution, parallelism, and retry policies.

from sagemaker.mlops.workflow import Pipeline, PipelineGraph
from sagemaker.mlops.workflow import TrainingStep, ProcessingStep, TransformStep, TuningStep
from sagemaker.mlops.workflow import ConditionStep, LambdaStep, ModelStep

MLOps & Pipelines

Processing & Transform

Data processing and batch transformation capabilities for preprocessing, feature engineering, and batch inference.

from sagemaker.core import Processor, ScriptProcessor, FrameworkProcessor, Transformer

Processing & Transform

Workflow Primitives

Building blocks for creating parameterized, conditional workflows with pipeline variables, parameters, functions, and conditions.

from sagemaker.core.workflow import (
    ParameterString, ParameterInteger, ParameterFloat, ParameterBoolean,
    ConditionEquals, ConditionGreaterThan, ConditionLessThan,
    Join, JsonGet, Properties, ExecutionVariables
)

Workflow Primitives

Model Evaluation

Comprehensive model evaluation with benchmark evaluations, custom scorers, and LLM-as-judge evaluations.

from sagemaker.train import (
    BenchMarkEvaluator, CustomScorerEvaluator, LLMAsJudgeEvaluator,
    EvaluationPipelineExecution, get_benchmarks, get_builtin_metrics
)

Model Evaluation

Model Monitoring

Monitor model quality, data quality, bias, and explainability in production with customizable monitoring schedules and alerts.

from sagemaker.core.model_monitor import (
    ModelMonitor, DefaultModelMonitor, ModelQualityMonitor,
    ModelBiasMonitor, ModelExplainabilityMonitor,
    DataCaptureConfig, MonitoringSchedule
)

Model Monitoring

Experiments & Tracking

Track, organize, and compare machine learning experiments with integration for MLflow.

from sagemaker.core.experiments import Experiment, Run

Experiments

JumpStart

Access pre-trained models, example notebooks, and solution templates from SageMaker JumpStart.

from sagemaker.core.jumpstart import (
    JumpStartModelsAccessor, JumpStartConfig,
    SageMakerSettings
)

JumpStart

Remote Functions

Execute Python functions remotely on SageMaker infrastructure with automatic dependency management.

from sagemaker.core.remote_function import remote, RemoteExecutor

Remote Functions

Debugger & Profiling

Debug and profile training jobs with TensorBoard integration and rule-based monitoring.

from sagemaker.core.debugger import (
    DebuggerHookConfig, TensorBoardOutputConfig, Rule, ProfilerRule,
    ProfilerConfig, FrameworkProfile
)

Debugger & Profiling

Bias & Explainability

Detect bias and explain model predictions using SageMaker Clarify.

from sagemaker.core.clarify import (
    SageMakerClarifyProcessor, DataConfig, BiasConfig, ModelConfig,
    SHAPConfig, PDPConfig
)

Bias & Explainability

Data I/O

Serializers and deserializers for various data formats including JSON, CSV, NumPy, Pandas, PyTorch tensors, and more.

from sagemaker.core.serializers import (
    JSONSerializer, CSVSerializer, NumpySerializer,
    TorchTensorSerializer, IdentitySerializer
)
from sagemaker.core.deserializers import (
    JSONDeserializer, CSVDeserializer, NumpyDeserializer,
    PandasDeserializer, BytesDeserializer
)

Data I/O

Lineage & Tracking

Track lineage of ML artifacts, models, datasets, and their relationships.

from sagemaker.core.lineage import (
    Action, Artifact, Association, Context,
    LineageQuery, LineageFilter
)

Lineage

Resources

Auto-generated resource classes providing direct access to 110+ SageMaker APIs for advanced use cases.

from sagemaker.core.resources import (
    TrainingJob, ProcessingJob, TransformJob,
    Model, Endpoint, EndpointConfig,
    ModelPackage, ModelPackageGroup, ModelCard,
    Pipeline, PipelineExecution, Experiment, Trial
)

Resources

S3 Utilities

Helper utilities for uploading and downloading files to/from Amazon S3.

from sagemaker.core.s3 import S3Uploader, S3Downloader
from sagemaker.core.s3 import parse_s3_url, is_s3_url, s3_path_join

Quick Example:

from sagemaker.core.s3 import S3Uploader, S3Downloader, s3_path_join

# Upload files
s3_uri = S3Uploader.upload(
    local_path="./model.tar.gz",
    desired_s3_uri="s3://my-bucket/models/"
)

# Download files
files = S3Downloader.download(
    s3_uri="s3://my-bucket/models/model.tar.gz",
    local_path="./downloaded/"
)

# Build S3 paths
path = s3_path_join("s3://", "bucket", "prefix", "file.txt")

S3 Utilities

AI Registry

Manage datasets and evaluators in the SageMaker AI Registry Hub for model customization workflows.

from sagemaker.ai_registry.dataset import DataSet
from sagemaker.ai_registry.evaluator import Evaluator, EvaluatorMethod
from sagemaker.ai_registry.dataset_utils import DataSetMethod
from sagemaker.ai_registry.air_constants import HubContentStatus

Quick Example:

from sagemaker.ai_registry.dataset import DataSet
from sagemaker.ai_registry.evaluator import Evaluator

# Create dataset
dataset = DataSet.create(
    name="training-data",
    source="./data/train.jsonl",
    wait=True
)

# Create evaluator
evaluator = Evaluator.create(
    name="reward-function",
    type="RewardFunction",
    source="arn:aws:lambda:us-west-2:123456789012:function:reward",
    wait=True
)

# List datasets
datasets = DataSet.list()

AI Registry

Explainer Configuration

Configuration classes for SageMaker Clarify explainability to interpret model predictions using SHAP values.

from sagemaker.core.explainer import (
    ClarifyExplainerConfig, ClarifyShapConfig,
    ClarifyInferenceConfig, ClarifyShapBaselineConfig, ClarifyTextConfig
)

Quick Example:

from sagemaker.core.explainer import (
    ClarifyExplainerConfig, ClarifyShapConfig, ClarifyShapBaselineConfig
)

# Configure explainability
baseline_config = ClarifyShapBaselineConfig(
    mime_type="text/csv",
    shap_baseline="0,0,0,0"
)

shap_config = ClarifyShapConfig(
    shap_baseline_config=baseline_config,
    number_of_samples=100
)

explainer_config = ClarifyExplainerConfig(shap_config=shap_config)

# Deploy with explainability
endpoint = builder.deploy(
    endpoint_name="explainable-endpoint",
    explainer_config=explainer_config
)

Explainer Configuration

Important Notes

IAM Permissions

All SageMaker operations require appropriate IAM permissions. The execution role must have:

• AmazonSageMakerFullAccess managed policy, or
• Custom policy with specific permissions for operations used

Minimum permissions include:

• sagemaker:CreateTrainingJob, sagemaker:DescribeTrainingJob for training
• sagemaker:CreateEndpoint, sagemaker:InvokeEndpoint for inference
• s3:GetObject, s3:PutObject for S3 data access
• logs:CreateLogGroup, logs:CreateLogStream for CloudWatch logs

Security Best Practices:

• Use least privilege principle - grant only required permissions
• Separate roles for different tasks (training vs. inference)
• Enable encryption with KMS keys for sensitive data
• Use VPC isolation for production workloads
• Implement resource tagging for access control

AWS Region Availability

Not all SageMaker features and instance types are available in all regions. Check AWS documentation for regional availability of:

• Specific instance types (especially GPU/Inferentia)
• JumpStart models
• SageMaker features (e.g., some monitoring capabilities)
• Service quotas and limits

Regional Considerations:

• Data residency requirements
• Latency to data sources
• Service quota limits vary by region
• Cost differences between regions
• Availability zone considerations for VPC deployments

Cost Considerations

• Training and inference instances incur charges per second of usage
• Endpoint instances run continuously until deleted (ongoing charges)
• S3 storage incurs charges for data stored
• Data transfer between regions incurs additional costs
• Spot instances can reduce training costs by up to 90%

Cost Optimization Strategies:

• Use managed spot instances for training
• Delete endpoints when not in use or use auto-scaling
• Implement lifecycle policies for S3 storage
• Right-size instances based on actual resource usage
• Use serverless inference for sporadic traffic
• Enable checkpointing to resume interrupted spot training
• Monitor costs with AWS Cost Explorer and budget alerts

Best Practices

1. Use Spot Instances: Enable use_spot_instances=True for training to reduce costs by up to 90%. Always set max_wait_time_in_seconds appropriately.

2. Right-size Instances: Start with smaller instances and scale up as needed. Profile workload before choosing expensive GPU instances.

3. Enable Logging: Always enable CloudWatch logs for debugging with appropriate retention periods. Use structured logging in training code.

4. Tag Resources: Use consistent tagging for cost tracking and resource management. Include project, environment, and owner tags.

5. Clean Up Resources: Delete endpoints when not in use to avoid ongoing charges. Implement automated cleanup for test resources.

6. Use Checkpoints: Enable checkpointing for long-running training jobs. Critical for spot instance training to resume after interruptions.

7. Monitor Metrics: Track training metrics to detect issues early. Set up CloudWatch alarms for anomalies.

8. Version Models: Use Model Registry to track model versions and lineage. Implement approval workflows for production deployments.

9. Implement Retry Logic: Use retry strategies for transient failures. Configure appropriate backoff and maximum attempts.

10. VPC Configuration: Use VPC for production workloads requiring network isolation. Configure security groups and NACLs appropriately.

11. Data Validation: Validate input data before training. Implement data quality checks in processing steps.

12. Experiment Tracking: Use Experiments to organize and compare runs. Log all hyperparameters and metrics systematically.

Error Handling

Always implement proper error handling when using SageMaker SDK:

from botocore.exceptions import ClientError, WaiterError
from sagemaker.exceptions import CapacityError

try:
    trainer.train(input_data_config=[train_data])
except ClientError as e:
    error_code = e.response['Error']['Code']
    if error_code == 'ResourceLimitExceeded':
        print("Instance limit exceeded, try different instance type or region")
    elif error_code == 'ValidationException':
        print(f"Invalid configuration: {e}")
    elif error_code == 'ThrottlingException':
        print("API rate limit exceeded, implement exponential backoff")
    else:
        raise
except CapacityError as e:
    print(f"Insufficient capacity: {e}. Try different instance type or region")
except WaiterError as e:
    print(f"Training job did not reach expected state: {e}")
except Exception as e:
    print(f"Training failed: {e}")
    # Implement appropriate recovery logic

Common Error Scenarios:

1. ResourceLimitExceeded: Exceeded service quota for instance type or concurrent jobs. Request quota increase or use different resources.

2. CapacityError: Insufficient capacity in availability zone. Retry in different region or use different instance type.

3. ValidationException: Invalid parameter values or configurations. Review API documentation for valid ranges and formats.

4. AccessDeniedException: Insufficient IAM permissions. Review and update execution role permissions.

5. ThrottlingException: API rate limits exceeded. Implement exponential backoff and retry logic.

6. AlgorithmError: Error in training script. Check CloudWatch logs for stack traces and debugging information.

Performance Tips

• Use Pipe input mode for large datasets to stream data instead of downloading. Reduces training start time significantly.

• Enable managed spot training for cost savings on interruptible workloads. Set max_wait_time_in_seconds > max_runtime_in_seconds.

• Use distributed training for large models and datasets. Choose appropriate strategy (data parallel, model parallel, or hybrid).

• Configure appropriate instance types based on workload:

  • CPU instances (ml.m5, ml.c5) for inference and light training
  • GPU instances (ml.p3, ml.p4d) for deep learning training
  • Inferentia (ml.inf1) for optimized inference at lower cost

• Use SageMaker Processing for data preparation to parallelize across multiple instances with automatic data distribution.

• Enable caching in pipelines to avoid re-running unchanged steps. Specify cache_config with appropriate expiration.

• Optimize Docker images: Use multi-stage builds, minimize layers, cache dependencies appropriately.

• Batch predictions efficiently: Use appropriate max_payload and max_concurrent_transforms for transform jobs.

• Use keep-alive for endpoints: Configure warm pools to reduce cold start latency for repeated invocations.

Validation and Constraints

Training Jobs:

• Maximum runtime: 28 days (2,419,200 seconds)
• Minimum instance count: 1
• Maximum instance count: 20 (can request increase)
• S3 URIs must be in same region as training job
• Instance volume size: 1 GB - 16,384 GB
• Hyperparameter values must be strings (converted internally)

Endpoints:

• Endpoint names: 1-63 characters, alphanumeric and hyphens only
• Maximum variants per endpoint: 10
• Initial instance count: 1-100 (production) or 1-10 (serverless)
• Data capture sampling: 0-100%
• Model container timeout: 3,600 seconds maximum

Pipelines:

• Maximum steps: 50
• Maximum parameters: 200
• Maximum execution time: 45 days
• Maximum concurrent executions: 100 (can request increase)
• Step names must be unique within pipeline

Monitoring:

• Minimum monitoring frequency: hourly
• Maximum captured data retention: 45 days default
• Baseline dataset maximum size: 5 GB
• Maximum monitoring schedules per account: 100