Repository files navigation

Amazon SageMaker Distribution is a set of Docker images that include popular frameworks for machine learning, datascience and visualization. For the list of supported SageMaker Distributions images, seeSageMaker Distributions Images.

These images come in two variants, CPU and GPU, and include deep learning frameworks like PyTorch, TensorFlow andKeras; popular Python packages like numpy, scikit-learn and pandas; and IDEs like Jupyter Lab. The distribution containsthelatest versions of all these packagessuch that they aremutually compatible.

This project follows semver (more on that below) and comes with a helper tool to automate new releases of thedistribution.

If you just want to use the images, you donot need to use this GitHub repository. Instead, you can pull pre-builtand ready-to-use images from ourAWS ECR Gallery repository.

If you want to check what packages are installed in a given version of Amazon SageMaker Distribution, you can find thatin the relevantRELEASE.md file in thebuild_artifacts directory.

Amazon SageMaker Distribution supports semantic versioning as described onsemver.org. A majorversion upgrade of Amazon SageMaker Distribution allows major version upgrades of all its dependencies, and similarlyfor minor and patch version upgrades. However, it is important to note that Amazon SageMaker Distribution’s ability tofollow semver guidelines is currently dependent on how its dependencies adhere to them.

Some dependencies, such as Python, will be treated differently. Amazon SageMaker Distribution will allow a minorupgrade of Python (say, 3.10 to 3.11) only during a major upgrade (say, 4.8 to 5.0).

Our current image tagging scheme is:<AMAZON_SAGEMAKER_DISTRIBUTION_VERSION_NUMBER>-<CPU_OR_GPU>. For example, the CPUversion of Amazon SageMaker Distribution'sv0.1.2 will carry the following tags:

1. 0.1.2-cpu: Once an image is tagged with such a patch version, that tag willnot be assigned to any other imagein future.
2. 0.1-cpu: this, and the two below,can change when new versions of Amazon SageMaker Distribution are released.
3. 0-cpu
4. latest-cpu

So, if you want to stay on the latest software as and when release by Amazon SageMaker Distribution, you can uselatest-cpu and do adocker pull latest-cpu when needed. If you use, say,0.1.2-cpu, the underlying distributionwill remain the same over time.

If you want to generate/view the staleness report for each of the individual packages in a givenSageMaker distribution image version, then run the following command:

VERSION=<Insert SageMaker Distribution version in semver format here. example: 0.4.2>python ./src/main.py generate-staleness-report --target-patch-version $VERSION

If you want to generate/view the package size delta report for a givenSageMaker distribution image version comparing to a base image version, then run the following command:

BASE_PATCH_VERSION=<Insert SageMaker Distribution version of the base image in semver format here. example: 1.6.1>VERSION=<Insert SageMaker Distribution version of the target image in semver format here. example: 1.6.2>python ./src/main.py generate-size-report --base-patch-version $BASE_PATCH_VERSION --target-patch-version $VERSION

Here are some examples on how you can try out one of our images.

The easiest way to get it running on your laptop is through the Docker CLI:

export ECR_IMAGE_ID='INSERT_IMAGE_YOU_WANT_TO_USE'docker run -it \    -p 8888:8888 \    -v`pwd`/sample-notebooks:/home/sagemaker-user/sample-notebooks \$ECR_IMAGE_ID jupyter-lab --no-browser --ip=0.0.0.0

(If you have access to Nvidia GPUs, you can pass--gpus=all to the Docker command.)

In the image, we also have entrypoints built in, that automatically starts IDE server and automatically restartsIDE server in case of minor IDE server interruptions or crashes. For example, to start JupyterLab server using theentrypoint built in:

export ECR_IMAGE_ID='INSERT_IMAGE_YOU_WANT_TO_USE'docker run -it \    -p 8888:8888 \    --entrypoint entrypoint-jupyter-server \    -v`pwd`/sample-notebooks:/home/sagemaker-user/sample-notebooks \$ECR_IMAGE_ID

In the console output, you'll then see a URL similar tohttp://127.0.0.1:8888/lab?token=foo. Just open that URL inyour browser, create a Jupyter Lab notebook or open a terminal, and start hacking.

Note that the sample command above bind mounts a directory inpwd inside the container. That way, if you were tore-create the container (say, to use a different version or CPU/GPU variant), any files you created within thatdirectory (such as Jupyter Lab notebooks) will persist.

Amazon SageMaker Studio is a web-based, integrateddevelopment environment (IDE) for machine learning that lets you build, train, debug, deploy, and monitor yourmachine learning models.

To use the sagemaker-distribution image in SageMaker Studio, selectSageMaker Distribution v{Major_version} {CPU/GPU} using theSageMaker Studio Launcher.

Amazon SageMaker Distribution supports full reproducibility of Conda environments, so you don't necessarily need to useDocker. Just find the version number you want to use in thebuild_artifacts directory, open one ofcpu.env.out orgpu.env.out and follow the instructions in the first 2 lines.

If you'd like to create a new Docker image on top of what we offer, we recommend you usemicromamba install ... instead ofpip install ....

For example:

FROM public.ecr.aws/sagemaker/sagemaker-distribution:latest-cpuUSER $ROOTRUN apt-get install -y vimUSER $MAMBA_USERRUN micromamba install sagemaker-inference --freeze-installed --yes --channel conda-forge --name base

As of sagemaker-distribution: v0.12+, v1.6+, and v2+, the images come with FIPS 140-2 validated openssl provideravailable for use. You can enable the FIPS provider by running:

export OPENSSL_CONF=/opt/conda/ssl/openssl-fips.cnf

For more info on the FIPS provider see:https://github.com/openssl/openssl/blob/master/README-FIPS.md

SeeCONTRIBUTING for more information.

This project is licensed under the Apache-2.0 License.