Get began with the open-source Amazon SageMaker Distribution



Information scientists want a constant and reproducible surroundings for machine studying (ML) and knowledge science workloads that allows managing dependencies and is safe. AWS Deep Studying Containers already offers pre-built Docker pictures for coaching and serving fashions in widespread frameworks corresponding to TensorFlow, PyTorch, and MXNet. To enhance this expertise, we introduced a public beta of the SageMaker open-source distribution at 2023 JupyterCon. This offers a unified end-to-end ML expertise throughout ML builders of various ranges of experience. Builders not want to change between completely different framework containers for experimentation, or as they transfer from native JupyterLab environments and SageMaker notebooks to manufacturing jobs on SageMaker. The open-source SageMaker Distribution helps the most typical packages and libraries for knowledge science, ML, and visualization, corresponding to TensorFlow, PyTorch, Scikit-learn, Pandas, and Matplotlib. You can begin utilizing the container from the Amazon ECR Public Gallery beginning as we speak.

On this publish, we present you ways you should utilize the SageMaker open-source distribution to shortly experiment in your native surroundings and simply promote them to jobs on SageMaker.

Resolution overview

For our instance, we showcase coaching a picture classification mannequin utilizing PyTorch. We use the KMNIST dataset out there publicly on PyTorch. We practice a neural community mannequin, take a look at the mannequin’s efficiency, and at last print the coaching and take a look at loss. The total pocket book for this instance is obtainable within the SageMaker Studio Lab examples repository. We begin experimentation on an area laptop computer utilizing the open-source distribution, transfer it to Amazon SageMaker Studio for utilizing a bigger occasion, after which schedule the pocket book as a pocket book job.


You want the next conditions:

Arrange your native surroundings

You’ll be able to instantly begin utilizing the open-source distribution in your native laptop computer. To begin JupyterLab, run the next instructions in your terminal:

export ECR_IMAGE_ID=''
docker run -it 
    -p 8888:8888 
    --user `id -u`:`id -g` 
    -v `pwd`/sample-notebooks:/dwelling/sagemaker-user/sample-notebooks 
    $ECR_IMAGE_ID jupyter-lab --no-browser --ip=

You’ll be able to change ECR_IMAGE_ID with any of the picture tags out there within the Amazon ECR Public Gallery, or select the latest-gpu tag in case you are utilizing a machine that helps GPU.

This command will begin JupyterLab and supply a URL on the terminal, like<token>. Copy the hyperlink and enter it in your most popular browser to start out JupyterLab.

Arrange Studio

Studio is an end-to-end built-in growth surroundings (IDE) for ML that lets builders and knowledge scientists construct, practice, deploy, and monitor ML fashions at scale. Studio offers an intensive listing of first-party pictures with widespread frameworks and packages, corresponding to Information Science, TensorFlow, PyTorch, and Spark. These pictures make it easy for knowledge scientists to get began with ML by merely selecting a framework and occasion sort of their alternative for compute.

Now you can use the SageMaker open-source distribution on Studio utilizing Studio’s convey your personal picture characteristic. So as to add the open-source distribution to your SageMaker area, full the next steps:

  1. Add the open-source distribution to your account’s Amazon Elastic Container Registry (Amazon ECR) repository by working the next instructions in your terminal:
    # Use the latest-cpu or latest-gpu tag based mostly in your necessities
    export ECR_GALLERY_IMAGE_ID='sagemaker-distribution:latest-cpu'
    export SAGEMAKER_IMAGE_NAME='sagemaker-runtime'
    export SAGEMAKER_STUDIO_DOMAIN_ID='d-xxxx'
    export SAGEMAKER_STUDIO_IAM_ROLE_ARN='<studio-default-execution-role-arn>'
    docker pull$ECR_GALLERY_IMAGE_ID
    export ECR_PRIVATE_REPOSITORY_NAME='sm-distribution'
    export ECR_IMAGE_TAG='sagemaker-runtime-cpu'
    export AWS_ACCOUNT_ID='0123456789'
    export AWS_ECR_REPOSITORY_REGION='us-east-1'
    # create repository
    aws --region ${AWS_ECR_REPOSITORY_REGION} ecr create-repository --repository-name $ECR_PRIVATE_REPOSITORY_NAME
    aws --region ${AWS_ECR_REPOSITORY_REGION} ecr get-login-password | docker login --username AWS --password-stdin ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_ECR_REPOSITORY_REGION}
    # Tag
    # Push the picture to your non-public repository
    docker push $ECR_IMAGE_URI

  2. Create a SageMaker picture and fasten the picture to the Studio area:
    # Create a SageMaker picture
    aws sagemaker create-image 
        --image-name $SAGEMAKER_IMAGE_NAME 
    # Create a SageMaker Picture Model.
    aws sagemaker create-image-version 
        --image-name $SAGEMAKER_IMAGE_NAME 
        --base-image $ECR_IMAGE_URI
    # Optionally, describe the picture model to make sure it is succesfully created
    aws sagemaker describe-image-version 
        --image-name $SAGEMAKER_IMAGE_NAME 
        --version-number 1
    # Create the app picture configuration file
    cat > /tmp/app-config.json << EOF
       "AppImageConfigName": "app-image-config-$SAGEMAKER_IMAGE_NAME",
       "KernelGatewayImageConfig": { 
          "FileSystemConfig": { 
             "DefaultGid": 100,
             "DefaultUid": 1000,
             "MountPath": "/dwelling/sagemaker-user"
          "KernelSpecs": [ 
                "DisplayName": "Python 3 (ipykernel)",
                "Name": "python3"
    # Create an Amazon SageMaker App Picture Config.
    aws sagemaker create-app-image-config 
        --cli-input-json file:///tmp/app-config.json
    # Create a default consumer settings file
    # Replace the file together with your current settings you probably have further customized pictures
    cat > /tmp/default-user-settings.json << EOF
        "DefaultUserSettings": {
            "KernelGatewayAppSettings": {
                "CustomImages": [
                        "ImageName": "$SAGEMAKER_IMAGE_NAME",
                        "AppImageConfigName": "app-image-config-$SAGEMAKER_IMAGE_NAME",
                        "ImageVersionNumber": 1
    # Replace Amazon SageMaker Area with the brand new default Person Settings.
    aws sagemaker update-domain 
        --domain-id $SAGEMAKER_STUDIO_DOMAIN_ID 
        --cli-input-json file:///tmp/default-user-settings.json

  3. On the SageMaker console, launch Studio by selecting your area and current consumer profile.
  4. Optionally, restart Studio by following the steps in Shut down and replace SageMaker Studio.


Obtain the pocket book

Obtain the pattern pocket book domestically from the GitHub repo.

Open the pocket book in your alternative of IDE and add a cell to the start of the pocket book to put in torchsummary. The torchsummary bundle isn’t a part of the distribution, and putting in this on the pocket book will make sure the pocket book runs finish to finish. We advocate utilizing conda or micromamba to handle environments and dependencies. Add the next cell to the pocket book and save the pocket book:

%pip set up torchsummary

Experiment on the native pocket book

Add the pocket book to the JupyterLab UI you launched by selecting the add icon as proven within the following screenshot.


When it’s uploaded, launch the cv-kmnist.ipynb pocket book. You can begin working the cells instantly, with out having to put in any dependencies corresponding to torch, matplotlib, or ipywidgets.

When you adopted the previous steps, you’ll be able to see that you should utilize the distribution domestically out of your laptop computer. Within the subsequent step, we use the identical distribution on Studio to make the most of Studio’s options.

Transfer the experimentation to Studio (optionally available)

Optionally, let’s promote the experimentation to Studio. One of many benefits of Studio is that the underlying compute assets are totally elastic, so you’ll be able to simply dial the out there assets up or down, and the modifications happen robotically within the background with out interrupting your work. When you wished to run the identical pocket book from earlier on a bigger dataset and compute occasion, you’ll be able to migrate to Studio.

Navigate to the Studio UI you launched earlier and select the add icon to add the pocket book.


After you launch the pocket book, you can be prompted to decide on the picture and occasion sort. On the kernel launcher, select sagemaker-runtime because the picture and an ml.t3.medium occasion, then select Choose.


Now you can run the pocket book finish to finish while not having any modifications on the pocket book out of your native growth surroundings to Studio notebooks!

Schedule the pocket book as a job

While you’re performed together with your experimentation, SageMaker offers a number of choices to productionalize your pocket book, corresponding to coaching jobs and SageMaker pipelines. One such choice is to instantly run the pocket book itself as a non-interactive, scheduled pocket book job utilizing SageMaker pocket book jobs. For instance, you may need to retrain your mannequin periodically, or get inferences on incoming knowledge periodically and generate experiences for consumption by your stakeholders.

From Studio, select the pocket book job icon to launch the pocket book job. You probably have put in the pocket book jobs extension domestically in your laptop computer, you can even schedule the pocket book instantly out of your laptop computer. See Set up Information to arrange the pocket book jobs extension domestically.


The pocket book job robotically makes use of the ECR picture URI of the open-source distribution, so you’ll be able to instantly schedule the pocket book job.


Select Run on schedule, select a schedule, for instance each week on Saturday, and select Create. You may as well select Run now in the event you’d wish to view the outcomes instantly.


When the primary pocket book job is full, you’ll be able to view the pocket book outputs instantly from the Studio UI by selecting Pocket book below Output recordsdata.


Extra concerns

Along with utilizing the publicly out there ECR picture instantly for ML workloads, the open-source distribution provides the next benefits:

  • The Dockerfile used to construct the picture is obtainable publicly for builders to discover and construct their very own pictures. You may as well inherit this picture as the bottom picture and set up your customized libraries to have a reproducible surroundings.
  • When you’re not used to Docker and like to make use of Conda environments in your JupyterLab surroundings, we offer an env.out file for every of the printed variations. You should use the directions within the file to create your personal Conda surroundings that can mimic the identical surroundings. For instance, see the CPU surroundings file cpu.env.out.
  • You should use the GPU variations of the picture to run GPU-compatible workloads corresponding to deep studying and picture processing.

Clear up

Full the next steps to wash up your assets:

  1. You probably have scheduled your pocket book to run on a schedule, pause or delete the schedule on the Pocket book Job Definitions tab to keep away from paying for future jobs.
  2. Shut down all Studio apps to keep away from paying for unused compute utilization. See Shut down and Replace Studio Apps for directions.
  3. Optionally, delete the Studio area in the event you created one.


Sustaining a reproducible surroundings throughout completely different phases of the ML lifecycle is without doubt one of the largest challenges for knowledge scientists and builders. With the SageMaker open-source distribution, we offer a picture with mutually suitable variations of the most typical ML frameworks and packages. The distribution can also be open supply, offering builders with transparency into the packages and construct processes, making it simpler to customise their very own distribution.

On this publish, we confirmed you the right way to use the distribution in your native surroundings, on Studio, and because the container to your coaching jobs. This characteristic is presently in public beta. We encourage you to do this out and share your suggestions and points on the public GitHub repository!

Concerning the authors

Durga Sury is an ML Options Architect on the Amazon SageMaker Service SA workforce. She is captivated with making machine studying accessible to everybody. In her 4 years at AWS, she has helped arrange AI/ML platforms for enterprise prospects. When she isn’t working, she loves bike rides, thriller novels, and lengthy walks along with her 5-year-old husky.

Ketan Vijayvargiya is a Senior Software program Growth Engineer in Amazon Internet Companies (AWS). His focus areas are machine studying, distributed programs and open supply. Exterior work, he likes to spend his time self-hosting and having fun with nature.