diff --git a/.codecov.yml b/.codecov.yml deleted file mode 100644 index 046261603d..0000000000 --- a/.codecov.yml +++ /dev/null @@ -1,2 +0,0 @@ -ignore: - - "**/tensorflow/tensorflow_serving/.*" diff --git a/.coveragerc b/.coveragerc deleted file mode 100644 index 35f9af99dd..0000000000 --- a/.coveragerc +++ /dev/null @@ -1,5 +0,0 @@ -[run] -concurrency = threading -omit = sagemaker/tests/* -timid = True -disable_warnings = module-not-measured diff --git a/.dictionary b/.dictionary deleted file mode 100644 index 8907f4ff9b..0000000000 --- a/.dictionary +++ /dev/null @@ -1,38 +0,0 @@ -args -arn -autoscaling -aws -bool -boolean -boto -botocore -clienterror -cloudwatch -cron -config -dataset -datasets -datetime -desc -docstring -entrypoint -env -iam -hyperparameter -hyperparameters -jupyter -kms -kwargs -neo -noqa -rc -runtime -sagemaker -stdout -str -subdirectories -subnet -subnets -unexpectedstatusexception -uri -vpc diff --git a/.flake8 b/.flake8 deleted file mode 100644 index 53e43383ac..0000000000 --- a/.flake8 +++ /dev/null @@ -1,6 +0,0 @@ -[flake8] -application_import_names = sagemaker, tests -import-order-style = google -per-file-ignores = - tests/unit/test_tuner.py: F405 - src/sagemaker/config/config_schema.py: E501 diff --git a/.githooks/pre-push b/.githooks/pre-push deleted file mode 100755 index 995ab70108..0000000000 --- a/.githooks/pre-push +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/sh -# this pre-push hook runs style checks and unit tests in python 3.8, 3.9, and 3.10 using tox. - -set -e - -TOX_PARALLEL_NO_SPINNER=1, -PY_COLORS=0 -start_time=`date +%s` -tox -e flake8,pylint,docstyle,black-check,twine --parallel all -./ci-scripts/displaytime.sh 'flake8,pylint,docstyle,black-check,twine' $start_time -start_time=`date +%s` -tox -e sphinx,doc8 --parallel all -./ci-scripts/displaytime.sh 'sphinx,doc8' $start_time -start_time=`date +%s` -tox -e py38,py39,py310 --parallel all -- tests/unit -./ci-scripts/displaytime.sh 'py38,py39,py310 unit' $start_time diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 048133d265..746d95a2aa 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -7,6 +7,10 @@ assignees: '' --- +**PySDK Version** +- [ ] PySDK V2 (2.x) +- [ ] PySDK V3 (3.x) + **Describe the bug** A clear and concise description of what the bug is. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index e659c40513..0000000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,27 +0,0 @@ -*Issue #, if available:* - -*Description of changes:* - -*Testing done:* - -## Merge Checklist - -_Put an `x` in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your pull request._ - -#### General - -- [ ] I have read the [CONTRIBUTING](https://github.com/aws/sagemaker-python-sdk/blob/master/CONTRIBUTING.md) doc -- [ ] I certify that the changes I am introducing will be backward compatible, and I have discussed concerns about this, if any, with the Python SDK team -- [ ] I used the commit message format described in [CONTRIBUTING](https://github.com/aws/sagemaker-python-sdk/blob/master/CONTRIBUTING.md#committing-your-change) -- [ ] I have passed the region in to all S3 and STS clients that I've initialized as part of this change. -- [ ] I have updated any necessary documentation, including [READMEs](https://github.com/aws/sagemaker-python-sdk/blob/master/README.rst) and [API docs](https://github.com/aws/sagemaker-python-sdk/tree/master/doc) (if appropriate) - -#### Tests - -- [ ] I have added tests that prove my fix is effective or that my feature works (if appropriate) -- [ ] I have added unit and/or integration tests as appropriate to ensure backward compatibility of the changes -- [ ] I have checked that my tests are not configured for a specific region or account (if appropriate) -- [ ] I have used [`unique_name_from_base`](https://github.com/aws/sagemaker-python-sdk/blob/master/src/sagemaker/utils.py#L77) to create resource names in integ tests (if appropriate) -- [ ] If adding any dependency in requirements.txt files, I have spell checked and ensured they exist in PyPi - -By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. diff --git a/.github/workflows/ci-health.yml b/.github/workflows/ci-health.yml new file mode 100644 index 0000000000..db94ce084a --- /dev/null +++ b/.github/workflows/ci-health.yml @@ -0,0 +1,38 @@ +name: CI Health +on: + schedule: + - cron: "0 */3 * * *" + workflow_dispatch: + +permissions: + id-token: write # This is required for requesting the JWT + +jobs: + canaries-v3: + runs-on: ubuntu-latest + steps: + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} + aws-region: us-west-2 + role-duration-seconds: 10800 + - name: Run Canaries V3 + uses: aws-actions/aws-codebuild-run-build@v1 + with: + project-name: sagemaker-python-sdk-ci-health-canaries-v3 + source-version: refs/heads/master + canaries-v2: + runs-on: ubuntu-latest + steps: + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} + aws-region: us-west-2 + role-duration-seconds: 10800 + - name: Run Canaries V2 + uses: aws-actions/aws-codebuild-run-build@v1 + with: + project-name: sagemaker-python-sdk-ci-health-canaries-v2 + source-version: refs/heads/master-v2 diff --git a/.github/workflows/codebuild-ci-health.yml b/.github/workflows/codebuild-ci-health.yml deleted file mode 100644 index 7ecefd310f..0000000000 --- a/.github/workflows/codebuild-ci-health.yml +++ /dev/null @@ -1,84 +0,0 @@ -name: CI Health -on: - schedule: - - cron: "0 */3 * * *" - workflow_dispatch: - -permissions: - id-token: write # This is required for requesting the JWT - -jobs: - codestyle-doc-tests: - runs-on: ubuntu-latest - steps: - - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v4 - with: - role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} - aws-region: us-west-2 - role-duration-seconds: 10800 - - name: Run Codestyle & Doc Tests - uses: aws-actions/aws-codebuild-run-build@v1 - with: - project-name: sagemaker-python-sdk-ci-health-codestyle-doc-tests - unit-tests: - runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - python-version: ["py38", "py39", "py310", "py311"] - steps: - - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v4 - with: - role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} - aws-region: us-west-2 - role-duration-seconds: 10800 - - name: Run Unit Tests - uses: aws-actions/aws-codebuild-run-build@v1 - with: - project-name: sagemaker-python-sdk-ci-health-unit-tests - env-vars-for-codebuild: | - PY_VERSION - env: - PY_VERSION: ${{ matrix.python-version }} - integ-tests: - runs-on: ubuntu-latest - steps: - - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v4 - with: - role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} - aws-region: us-west-2 - role-duration-seconds: 10800 - - name: Run Integ Tests - uses: aws-actions/aws-codebuild-run-build@v1 - id: codebuild - with: - project-name: sagemaker-python-sdk-ci-health-integ-tests - slow-tests: - runs-on: ubuntu-latest - steps: - - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v4 - with: - role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} - aws-region: us-west-2 - role-duration-seconds: 10800 - - name: Run Slow Tests - uses: aws-actions/aws-codebuild-run-build@v1 - with: - project-name: sagemaker-python-sdk-ci-health-slow-tests - localmode-tests: - runs-on: ubuntu-latest - steps: - - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v4 - with: - role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} - aws-region: us-west-2 - role-duration-seconds: 10800 - - name: Run Local Mode Tests - uses: aws-actions/aws-codebuild-run-build@v1 - with: - project-name: sagemaker-python-sdk-ci-health-localmode-tests \ No newline at end of file diff --git a/.github/workflows/codebuild-ci.yml b/.github/workflows/codebuild-ci.yml deleted file mode 100644 index 8c6bd6b337..0000000000 --- a/.github/workflows/codebuild-ci.yml +++ /dev/null @@ -1,97 +0,0 @@ -name: PR Checks -on: - pull_request_target: - branches: - - "master*" - -concurrency: - group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.head_ref }} - cancel-in-progress: true - -permissions: - id-token: write # This is required for requesting the JWT - -jobs: - collab-check: - runs-on: ubuntu-latest - outputs: - approval-env: ${{ steps.collab-check.outputs.result }} - steps: - - name: Collaborator Check - uses: actions/github-script@v7 - id: collab-check - with: - github-token: ${{ secrets.COLLAB_CHECK_TOKEN }} - result-encoding: string - script: | - try { - const res = await github.rest.repos.checkCollaborator({ - owner: context.repo.owner, - repo: context.repo.repo, - username: "${{ github.event.pull_request.user.login }}", - }); - console.log("Verifed ${{ github.event.pull_request.user.login }} is a repo collaborator. Auto Approving PR Checks.") - return res.status == "204" ? "auto-approve" : "manual-approval" - } catch (error) { - console.log("${{ github.event.pull_request.user.login }} is not a collaborator. Requiring Manual Approval to run PR Checks.") - return "manual-approval" - } - wait-for-approval: - runs-on: ubuntu-latest - needs: [collab-check] - environment: ${{ needs.collab-check.outputs.approval-env }} - steps: - - run: echo "Workflow Approved! Starting PR Checks." - codestyle-doc-tests: - runs-on: ubuntu-latest - needs: [wait-for-approval] - steps: - - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v4 - with: - role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} - aws-region: us-west-2 - role-duration-seconds: 10800 - - name: Run Codestyle & Doc Tests - uses: aws-actions/aws-codebuild-run-build@v1 - with: - project-name: ${{ github.event.repository.name }}-ci-codestyle-doc-tests - source-version-override: 'refs/pull/${{ github.event.pull_request.number }}/head^{${{ github.event.pull_request.head.sha }}}' - unit-tests: - runs-on: ubuntu-latest - needs: [wait-for-approval] - strategy: - fail-fast: false - matrix: - python-version: ["py38","py39","py310","py311"] - steps: - - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v4 - with: - role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} - aws-region: us-west-2 - role-duration-seconds: 10800 - - name: Run Unit Tests - uses: aws-actions/aws-codebuild-run-build@v1 - with: - project-name: ${{ github.event.repository.name }}-ci-unit-tests - source-version-override: 'refs/pull/${{ github.event.pull_request.number }}/head^{${{ github.event.pull_request.head.sha }}}' - env-vars-for-codebuild: | - PY_VERSION - env: - PY_VERSION: ${{ matrix.python-version }} - integ-tests: - runs-on: ubuntu-latest - needs: [wait-for-approval] - steps: - - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v4 - with: - role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} - aws-region: us-west-2 - role-duration-seconds: 10800 - - name: Run Integ Tests - uses: aws-actions/aws-codebuild-run-build@v1 - with: - project-name: ${{ github.event.repository.name }}-ci-integ-tests - source-version-override: 'refs/pull/${{ github.event.pull_request.number }}/head^{${{ github.event.pull_request.head.sha }}}' diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 8fbf42803b..c6df60d630 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -32,4 +32,4 @@ jobs: - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@4b1d7da102ff94aca014c0245062b1a463356d72 with: - category: "/language:${{matrix.language}}" + category: "/language:${{matrix.language}}" \ No newline at end of file diff --git a/.github/workflows/pr-checks-master-v2.yml b/.github/workflows/pr-checks-master-v2.yml new file mode 100644 index 0000000000..2004af5ea5 --- /dev/null +++ b/.github/workflows/pr-checks-master-v2.yml @@ -0,0 +1,97 @@ +name: Sagemaker PR Checks (Master-v2) +on: + pull_request_target: + branches: + - "master-v2" + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.head_ref }} + cancel-in-progress: true + +permissions: + id-token: write + +jobs: + collab-check: + runs-on: ubuntu-latest + outputs: + approval-env: ${{ steps.collab-check.outputs.result }} + steps: + - name: Collaborator Check + uses: actions/github-script@v7 + id: collab-check + with: + github-token: ${{ secrets.COLLAB_CHECK_TOKEN }} + result-encoding: string + script: | + try { + const res = await github.rest.repos.checkCollaborator({ + owner: context.repo.owner, + repo: context.repo.repo, + username: "${{ github.event.pull_request.user.login }}", + }); + console.log("Verifed ${{ github.event.pull_request.user.login }} is a repo collaborator. Auto Approving PR Checks.") + return res.status == "204" ? "auto-approve" : "manual-approval" + } catch (error) { + console.log("${{ github.event.pull_request.user.login }} is not a collaborator. Requiring Manual Approval to run PR Checks.") + return "manual-approval" + } + wait-for-approval: + runs-on: ubuntu-latest + needs: [collab-check] + environment: ${{ needs.collab-check.outputs.approval-env }} + steps: + - run: echo "Workflow Approved! Starting PR Checks." + codestyle-doc-tests: + runs-on: ubuntu-latest + needs: [wait-for-approval] + steps: + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} + aws-region: us-west-2 + role-duration-seconds: 10800 + - name: Run Codestyle & Doc Tests + uses: aws-actions/aws-codebuild-run-build@v1 + with: + project-name: ${{ github.event.repository.name }}-ci-codestyle-doc-tests + source-version-override: 'refs/pull/${{ github.event.pull_request.number }}/head^{${{ github.event.pull_request.head.sha }}}' + unit-tests: + runs-on: ubuntu-latest + needs: [wait-for-approval] + strategy: + fail-fast: false + matrix: + python-version: ["py39","py310","py311","py312"] + steps: + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} + aws-region: us-west-2 + role-duration-seconds: 10800 + - name: Run Unit Tests + uses: aws-actions/aws-codebuild-run-build@v1 + with: + project-name: ${{ github.event.repository.name }}-ci-unit-tests + source-version-override: 'refs/pull/${{ github.event.pull_request.number }}/head^{${{ github.event.pull_request.head.sha }}}' + env-vars-for-codebuild: | + PY_VERSION + env: + PY_VERSION: ${{ matrix.python-version }} + integ-tests: + runs-on: ubuntu-latest + needs: [wait-for-approval] + steps: + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} + aws-region: us-west-2 + role-duration-seconds: 10800 + - name: Run Integ Tests + uses: aws-actions/aws-codebuild-run-build@v1 + with: + project-name: ${{ github.event.repository.name }}-ci-integ-tests + source-version-override: 'refs/pull/${{ github.event.pull_request.number }}/head^{${{ github.event.pull_request.head.sha }}}' diff --git a/.github/workflows/pr-checks-master.yml b/.github/workflows/pr-checks-master.yml new file mode 100644 index 0000000000..4f63ad0b9a --- /dev/null +++ b/.github/workflows/pr-checks-master.yml @@ -0,0 +1,217 @@ +name: Sagemaker PR Checks (Master) +on: + pull_request_target: + branches: + - "master" + paths: + - 'sagemaker-train/**' + - 'sagemaker-serve/**' + - 'sagemaker-mlops/**' + - 'sagemaker-core/**' + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.head_ref }} + cancel-in-progress: true + +permissions: + id-token: write + +jobs: + collab-check: + runs-on: ubuntu-latest + outputs: + approval-env: ${{ steps.collab-check.outputs.result }} + steps: + - name: Collaborator Check + uses: actions/github-script@v7 + id: collab-check + with: + github-token: ${{ secrets.COLLAB_CHECK_TOKEN }} + result-encoding: string + script: | + try { + const res = await github.rest.repos.checkCollaborator({ + owner: context.repo.owner, + repo: context.repo.repo, + username: "${{ github.event.pull_request.user.login }}", + }); + console.log("Verifed ${{ github.event.pull_request.user.login }} is a repo collaborator. Auto Approving PR Checks.") + return res.status == "204" ? "auto-approve" : "manual-approval" + } catch (error) { + console.log("${{ github.event.pull_request.user.login }} is not a collaborator. Requiring Manual Approval to run PR Checks.") + return "manual-approval" + } + wait-for-approval: + runs-on: ubuntu-latest + needs: [ collab-check ] + environment: ${{ needs.collab-check.outputs.approval-env }} + steps: + - run: echo "Workflow Approved! Starting PR Checks." + detect-changes: + runs-on: ubuntu-latest + needs: [wait-for-approval] + outputs: + submodules: ${{ steps.check-changes.outputs.submodules }} + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + token: ${{ secrets.GH_PAT }} + ref: ${{ github.event.pull_request.base.ref }} + - name: Detect Changes + id: check-changes + run: | + set -e + + echo "Target Branch: ${{ github.event.pull_request.base.ref }}" + echo "Current Target SHA: $(git rev-parse HEAD)" + echo "PR Number: ${{ github.event.pull_request.number }}" + echo "PR Latest SHA: ${{ github.event.pull_request.head.sha }}" + + git fetch origin pull/${{ github.event.pull_request.number }}/head + CHANGES=$(git diff --name-only HEAD FETCH_HEAD) + + echo "Changed files:" + echo "$CHANGES" + + # Function to extract dependencies from pyproject.toml + get_dependencies() { + local module=$1 + grep "sagemaker-" "$module/pyproject.toml" | grep -o 'sagemaker-[a-z]*' | sort -u + } + + # Function to find all modules that depend on a given module (recursively) + find_dependents() { + local target=$1 + local all_modules=("sagemaker-core" "sagemaker-train" "sagemaker-serve" "sagemaker-mlops") + local dependents=() + + for module in "${all_modules[@]}"; do + if [ "$module" != "$target" ]; then + if get_dependencies "$module" | grep -q "^$target$"; then + dependents+=("$module") + fi + fi + done + + echo "${dependents[@]}" + } + + # Initialize set of submodules to test (using associative array) + declare -A SUBMODULES_SET + + # Function to recursively add module and all its dependents + add_module_and_dependents() { + local module=$1 + + if [ -z "${SUBMODULES_SET[$module]}" ]; then + SUBMODULES_SET["$module"]=1 + echo "Adding $module to test set" + + # Find all modules that depend on this one and add them recursively + local dependents=$(find_dependents "$module") + for dependent in $dependents; do + add_module_and_dependents "$dependent" + done + fi + } + + # Check which submodules changed and add them plus their dependents + if echo "$CHANGES" | grep -q "^sagemaker-core/"; then + echo "sagemaker-core changed - will add core and all dependents" + add_module_and_dependents "sagemaker-core" + fi + + if echo "$CHANGES" | grep -q "^sagemaker-train/"; then + echo "sagemaker-train changed - will add train and all dependents" + add_module_and_dependents "sagemaker-train" + fi + + if echo "$CHANGES" | grep -q "^sagemaker-serve/"; then + echo "sagemaker-serve changed - will add serve and all dependents" + add_module_and_dependents "sagemaker-serve" + fi + + if echo "$CHANGES" | grep -q "^sagemaker-mlops/"; then + echo "sagemaker-mlops changed - will add mlops" + add_module_and_dependents "sagemaker-mlops" + fi + + # Convert associative array to JSON array + SUBMODULES='[]' + for submodule in "${!SUBMODULES_SET[@]}"; do + if [ "$SUBMODULES" = '[]' ]; then + SUBMODULES="[\"$submodule\"]" + else + SUBMODULES=$(echo $SUBMODULES | sed "s/\]$/,\"$submodule\"\]/") + fi + done + + echo "Final SUBMODULES: $SUBMODULES" + echo "submodules=$SUBMODULES" >> $GITHUB_OUTPUT + + codestyle-doc-tests: + runs-on: ubuntu-latest + needs: [detect-changes] + if: needs.detect-changes.outputs.submodules != '[]' + strategy: + fail-fast: false + matrix: + submodule: ${{ fromJson(needs.detect-changes.outputs.submodules) }} + steps: + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} + aws-region: us-west-2 + role-duration-seconds: 10800 + + - name: Run CodeBuild for ${{ matrix.submodule }} + uses: aws-actions/aws-codebuild-run-build@v1 + with: + project-name: ${{ github.event.repository.name }}-ci-${{ matrix.submodule }}-codestyle-doc-tests + source-version-override: 'refs/pull/${{ github.event.pull_request.number }}/head^{${{ github.event.pull_request.head.sha }}}' + + unit-tests: + runs-on: ubuntu-latest + needs: [detect-changes] + if: needs.detect-changes.outputs.submodules != '[]' + strategy: + fail-fast: false + matrix: + submodule: ${{ fromJson(needs.detect-changes.outputs.submodules) }} + steps: + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} + aws-region: us-west-2 + role-duration-seconds: 10800 + + - name: Run Unit Tests for ${{ matrix.submodule }} + uses: aws-actions/aws-codebuild-run-build@v1 + with: + project-name: ${{ github.event.repository.name }}-ci-${{ matrix.submodule }}-unit-tests + source-version-override: 'refs/pull/${{ github.event.pull_request.number }}/head^{${{ github.event.pull_request.head.sha }}}' + + integ-tests: + runs-on: ubuntu-latest + needs: [detect-changes] + if: needs.detect-changes.outputs.submodules != '[]' + strategy: + fail-fast: false + matrix: + submodule: ${{ fromJson(needs.detect-changes.outputs.submodules) }} + steps: + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} + aws-region: us-west-2 + role-duration-seconds: 10800 + + - name: Run Integ Tests for ${{ matrix.submodule }} + uses: aws-actions/aws-codebuild-run-build@v1 + with: + project-name: ${{ github.event.repository.name }}-ci-${{ matrix.submodule }}-integ-tests + source-version-override: 'refs/pull/${{ github.event.pull_request.number }}/head^{${{ github.event.pull_request.head.sha }}}' diff --git a/.github/workflows/security-monitoring.yml b/.github/workflows/security-monitoring.yml index ecce0643e6..8e44b426c2 100644 --- a/.github/workflows/security-monitoring.yml +++ b/.github/workflows/security-monitoring.yml @@ -118,4 +118,4 @@ jobs: aws cloudwatch put-metric-data --metric-name SecretScanningAlert --namespace SecurityMonitoringMetrics --value 1 --unit Count --dimensions ProjectName=sagemaker-python-sdk else aws cloudwatch put-metric-data --metric-name SecretScanningAlert --namespace SecurityMonitoringMetrics --value 0 --unit Count --dimensions ProjectName=sagemaker-python-sdk - fi + fi \ No newline at end of file diff --git a/.gitignore b/.gitignore index fc07847fba..09935a1dc9 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,7 @@ dist/ **/*.pyc **.pyc scratch*.py +scratch/ .eggs *.egg examples/tensorflow/distributed_mnist/data @@ -32,9 +33,6 @@ env/ .python-version *.html **/_repack_script_launcher.sh -src/sagemaker/modules/train/container_drivers/sm_train.sh -src/sagemaker/modules/train/container_drivers/sourcecode.json -src/sagemaker/modules/train/container_drivers/distributed.json -tests/data/**/_repack_model.py -tests/data/experiment/sagemaker-dev-1.0.tar.gz -src/sagemaker/serve/tmp_workspace \ No newline at end of file +sagemaker_train/src/**/container_drivers/sm_train.sh +sagemaker_train/src/**/container_drivers/sourcecode.json +sagemaker_train/src/**/container_drivers/distributed.json diff --git a/.pydocstylerc b/.pydocstylerc deleted file mode 100644 index 9ed879a760..0000000000 --- a/.pydocstylerc +++ /dev/null @@ -1,5 +0,0 @@ -[pydocstyle] -inherit = false -ignore = D104,D107,D202,D203,D213,D214,D400,D401,D404,D406,D407,D411,D413,D414,D415,D417 -match = (?!record_pb2).*\.py -match-dir = (?!.*test).* \ No newline at end of file diff --git a/.pylintrc b/.pylintrc index 5428b86be0..223580f4d3 100644 --- a/.pylintrc +++ b/.pylintrc @@ -94,7 +94,24 @@ disable= useless-object-inheritance, # TODO: Enable this check and fix code once Python 2 is no longer supported. super-with-arguments, raise-missing-from, - E1136, + C0116, # Missing function or method docstring + C0209, # Use f-string instead of format + E0015, # Unrecognized option found in config + E0702, # Raising a string instead of an exception + E1101, # Module has no member (likely dynamic attr) + E1136, # Value assigned to something inferred as None + R0022, # Useless option value in config + R1710, # Inconsistent return statements + R1714, # Consider using `in` with comparisons + R1729, # Use a generator + R1732, + R1735, # Consider using a dict or list literal + W0237, # Argument renamed in override + W0613, # Unused argument + W0621, # Redefining name from outer scope + W0719 + W1404, # Implicit string concatenation + W1514, # `open()` used without encoding [REPORTS] # Set the output format. Available formats are text, parseable, colorized, msvs @@ -436,4 +453,4 @@ analyse-fallback-blocks=no # Exceptions that will emit a warning when being caught. Defaults to # "Exception" -overgeneral-exceptions=Exception +overgeneral-exceptions=builtins.Exception diff --git a/.readthedocs.yaml b/.readthedocs.yaml deleted file mode 100644 index 0a6e3928b5..0000000000 --- a/.readthedocs.yaml +++ /dev/null @@ -1,22 +0,0 @@ -# ReadTheDocs environment customization to allow us to use conda to install -# libraries which have C dependencies for the doc build. See: -# https://docs.readthedocs.io/en/latest/config-file/v2.html - -version: 2 - -build: - os: ubuntu-20.04 - tools: - python: "3.9" - - -python: - install: - - method: pip - path: . - - requirements: doc/requirements.txt - - -sphinx: - configuration: doc/conf.py - fail_on_warning: true # http://www.sphinx-doc.org/en/master/man/sphinx-build.html#id6 diff --git a/CHANGELOG.md b/CHANGELOG.md index e68653ce0d..1ef97b034b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,473 @@ # Changelog +## v3.3.0 (2025-12-19) + +### Features + * AWS_Batch: queueing of training jobs with ModelTrainer +### Bug fixes and Other Changes + * Fixes for model registry with ModelBuilder + +## v3.2.0 (2025-12-18) + +### Features + * Evaluator handshake with trainer + * Datasets Format validation +### Bug fixes and Other Changes + * Add xgboost 3.0-5 to release + * Fix get_child_process_ids parsing issue + +## v3.1.1 (2025-12-10) + +### Bug fixes and Other Changes +* Add validation to bedrock reward models +* Hyperparameter issue fixes, Add validation s3 output path +* Fix the recipe selection for multiple recipe scenario +* Train wait() timeout exception handling +* Update example notebooks to reflect recent code changes +* Update `model_package_group_name` param to `model_package_group` in finetuning interfaces +* remove `dataset` param for benchmark evaluator + +## v3.1.0 (2025-12-03) + +### Features + +* Fine-tuning SDK: SFT, RLVR, and RLAIF techniques with standardized parameter design +* AIRegistry Integration: Added CRUD operations for datasets and evaluators +* Enhanced Training Experience: Implemented MLFlow metrics tracking and deployment workflows + +## v3.0.1 (2025-11-19) + +* Update project dependencies to include submodules: sagemaker-core, sagemaker-train, sagemaker-serve, sagemaker-mlops + +## v3.0.0 (2025-11-19) + +### Major Version Release + +#### ⚠️ Breaking Changes + +#### Important: Please review these breaking changes before upgrading. + +* Version 3.0.0 represents a significant milestone in our product's evolution. This major release introduces a modernized architecture, enhanced performance, and powerful new features while maintaining our commitment to user experience and reliability. +* Older interfaces such as Estimator, Model, Predictor and all their subclasses will not be supported in V3. +* Please review documentation of interfaces for parameters support (especially ModelBuilder) + +## v2.254.1 (2025-10-31) + +### Bug Fixes and Other Changes + + * update get_execution_role to directly return the ExecutionRoleArn if it presents in the resource metadata file + * [hf] HF PT Training DLCs + +## v2.254.0 (2025-10-29) + +### Features + + * Triton v25.09 DLC + +### Bug Fixes and Other Changes + + * Add Numpy 2.0 support + * add HF Optimum Neuron DLCs + * [Hugging Face][Pytorch] Inference DLC 4.51.3 + * [hf] HF Inference TGI + +## v2.253.1 (2025-10-14) + +### Bug Fixes and Other Changes + + * Update instance type regex to also include hyphens + * Revert the change "Add Numpy 2.0 support" + * [hf-tei] add image uri to utils + * add TEI 1.8.2 + +## v2.253.0 (2025-10-10) + +### Features + + * Added condition to allow eval recipe. + * add model_type hyperparameter support for Nova recipes + +### Bug Fixes and Other Changes + + * Fix for a failed slow test: numpy fix + * Add numpy 2.0 support + * chore: domain support for eu-isoe-west-1 + * Adding default identity implementations to InferenceSpec + * djl regions fixes #5273 + * Fix flaky integ test + +## v2.252.0 (2025-09-29) + +### Features + + * change S3 endpoint env name + * add eval custom lambda arn to hyperparameters + +### Bug Fixes and Other Changes + + * merge rba without the iso region changes + * handle trial component status message longer than API supports + * Add nova custom lambda in hyperparameter from estimator + * add retryable option to emr step in SageMaker Pipelines + * Feature/js mlops telemetry + * latest tgi + +## v2.251.1 (2025-08-29) + +### Bug Fixes and Other Changes + + * chore: onboard tei 1.8.0 + +## v2.251.0 (2025-08-21) + +### Features + + * support pipeline versioning + +### Bug Fixes and Other Changes + + * GPT OSS Hotfix + * dockerfile stuck on interactive shell + * add sleep for model deployment + +## v2.250.0 (2025-08-08) + +### Features + + * Add support for InstancePlacementConfig in Estimator for training jobs running on ultraserver capacity + +### Bug Fixes and Other Changes + + * Add more constraints to test requirements + +## v2.249.0 (2025-07-31) + +### Features + + * AWS Batch for SageMaker Training jobs + +### Bug Fixes and Other Changes + + * Directly use customer-provided endpoint name for ModelBuilder deployment. + * update image_uri_configs 07-23-2025 07:18:25 PST + +## v2.248.2 (2025-07-22) + +### Bug Fixes and Other Changes + + * Relax boto3 version requirement + * update image_uri_configs 07-22-2025 07:18:25 PST + * update image_uri_configs 07-18-2025 07:18:28 PST + * add hard dependency on sagemaker-core pypi lib + * When rootlessDocker is enabled, return a fixed SageMaker IP + +## v2.248.1 (2025-07-16) + +### Bug Fixes and Other Changes + + * Nova training support + +## v2.248.0 (2025-07-15) + +### Features + + * integrate amtviz for visualization of tuning jobs + +### Bug Fixes and Other Changes + + * build(deps): bump requests in /tests/data/serve_resources/mlflow/pytorch + * build(deps): bump protobuf from 4.25.5 to 4.25.8 in /requirements/extras + * build(deps): bump mlflow in /tests/data/serve_resources/mlflow/xgboost + * build(deps): bump torch in /tests/data/modules/script_mode + * sanitize git clone repo input url + * Adding Hyperpod feature to enable hyperpod telemetry + * Adding Hyperpod feature to enable hyperpod telemetry + * Bump SMD version to enable custom workflow deployment. + * Update TF DLC python version to py312 + * update image_uri_configs 07-04-2025 07:18:27 PST + * update image_uri_configs 06-26-2025 07:18:35 PST + * relax protobuf to <6.32 + +## v2.247.1 (2025-06-23) + +### Bug Fixes and Other Changes + + * update image_uri_configs 06-19-2025 07:18:34 PST + +## v2.247.0 (2025-06-13) + +### Features + + * Add support for MetricDefinitions in ModelTrainer + +### Bug Fixes and Other Changes + + * update jumpstart region_config, update image_uri_configs 06-12-2025 07:18:12 PST + * Add ignore_patterns in ModelTrainer to ignore specific files/folders + * Allow import failure for internal _hashlib module + +## v2.246.0 (2025-06-04) + +### Features + + * Triton v25.04 DLC + +### Bug Fixes and Other Changes + + * Update Attrs version to widen support + * update estimator documentation regarding hyperparameters for source_dir + +## v2.245.0 (2025-05-28) + +### Features + + * Correct mypy type checking through PEP 561 + +### Bug Fixes and Other Changes + + * MLFLow update for dependabot + * addWaiterTimeoutHandling + * merge method inputs with class inputs + * update image_uri_configs 05-20-2025 07:18:17 PST + +## v2.244.2 (2025-05-19) + +### Bug Fixes and Other Changes + + * include model channel for gated uncompressed models + * clarify model monitor one time schedule bug + * update jumpstart region_config 05-15-2025 07:18:15 PST + * update image_uri_configs 05-14-2025 07:18:16 PST + * Add image configs and region config for TPE (ap-east-2) + * Improve defaults handling in ModelTrainer + +## v2.244.1 (2025-05-15) + +### Bug Fixes and Other Changes + + * Fix Flask-Limiter version + * Fix test_huggingface_tei_uris() + * huggingface-llm-neuronx dlc + * huggingface-neuronx dlc image_uri + * huggingface-tei dlc image_uri + * Fix test_deploy_with_update_endpoint() + * add AG v1.3 + * parameter mismatch in update_endpoint + * remove --strip-component for untar source tar.gz + * Fix type annotations + * chore: Allow omegaconf >=2.2,<3 + * honor json serialization of HPs + * Map llama models to correct script + * pin test dependency + * fix bad initialization script error message + * Improve error logging and documentation for issue 4007 + * build(deps): bump scikit-learn + * build(deps): bump mlflow + * build(deps): bump mlflow in /tests/data/serve_resources/mlflow/pytorch + * chore: Add tei 1.6.0 image + +## v2.244.0 (2025-05-02) + +### Features + + * support custom workflow deployment in ModelBuilder using SMD image. + +### Bug Fixes and Other Changes + + * Add Owner ID check for bucket with path when prefix is provided + * Add model server timeout + * pin mamba version to 24.11.3-2 to avoid inconsistent test runs + * Update ModelTrainer to support s3 uri and tar.gz file as source_dir + * chore: add huggingface images + +## v2.243.3 (2025-04-23) + +### Bug Fixes and Other Changes + + * update readme to reflect py312 upgrade + * Revert the PR changes 5122 + * Py312 upgrade step 2: Update dependencies, integ tests and unit tests + * update pr test to deprecate py38 and add py312 + * update image_uri_configs 04-16-2025 07:18:18 PST + * update image_uri_configs 04-15-2025 07:18:10 PST + * update image_uri_configs 04-11-2025 07:18:19 PST + +## v2.243.2 (2025-04-16) + +### Bug Fixes and Other Changes + + * tgi image uri unit tests + * Fix deepdiff dependencies + +## v2.243.1 (2025-04-11) + +### Bug Fixes and Other Changes + + * Added handler for pipeline variable while creating process job + * Fix issue #4856 by copying environment variables + * remove historical job_name caching which causes long job name + * Update instance gpu info + * Master + * Add mlflow tracking arn telemetry + * chore: fix semantic versioning for wildcard identifier + * flaky test + +### Documentation Changes + + * update pipelines step caching examples to include more steps + * update ModelStep data dependency info + +## v2.243.0 (2025-03-27) + +### Features + + * Enabled update_endpoint through model_builder + +### Bug Fixes and Other Changes + + * Update for PT 2.5.1, SMP 2.8.0 + * chore: move jumpstart region definitions to json file + * fix flaky clarify model monitor test + * fix flaky spark processor integ + * use temp file in unit tests + * Update transformers version + * Aligned disable_output_compression for @remote with Estimator + * Update Jinja version + * update image_uri_configs 03-26-2025 07:18:16 PST + * chore: fix integ tests to use latest version of model + * update image_uri_configs 03-25-2025 07:18:13 PST + * Skip tests failed due to deprecated instance type + * update image_uri_configs 03-21-2025 07:17:55 PST + * factor in set instance type when building JumpStart models in ModelBuilder. + * ADD Documentation to ReadtheDocs for Upgrading torch versions + * add new regions to JUMPSTART_LAUNCHED_REGIONS + +## v2.242.0 (2025-03-14) + +### Features + + * add integ tests for training JumpStart models in private hub + +### Bug Fixes and Other Changes + + * Torch upgrade + * Prevent RunContext overlap between test_run tests + * remove s3 output location requirement from hub class init + * Fixing Pytorch training python version in tests + * update image_uri_configs 03-11-2025 07:18:09 PST + * resolve infinite loop in _find_config on Windows systems + * pipeline definition function doc update + +## v2.241.0 (2025-03-06) + +### Features + + * Make DistributedConfig Extensible + * support training for JumpStart model references as part of Curated Hub Phase 2 + * Allow ModelTrainer to accept hyperparameters file + +### Bug Fixes and Other Changes + + * Skip tests with deprecated instance type + * Ensure Model.is_repack() returns a boolean + * Fix error when there is no session to call _create_model_request() + * Use sagemaker session's s3_resource in download_folder + * Added check for the presence of model package group before creating one + * Fix key error in _send_metrics() + +## v2.240.0 (2025-02-25) + +### Features + + * Add support for TGI Neuronx 0.0.27 and HF PT 2.3.0 image in PySDK + +### Bug Fixes and Other Changes + + * Remove main function entrypoint in ModelBuilder dependency manager. + * forbid extras in Configs + * altconfig hubcontent and reenable integ test + * Merge branch 'master-rba' into local_merge + * py_version doc fixes + * Add backward compatbility for RecordSerializer and RecordDeserializer + * update image_uri_configs 02-21-2025 06:18:10 PST + * update image_uri_configs 02-20-2025 06:18:08 PST + +### Documentation Changes + + * Removed a line about python version requirements of training script which can misguide users. + +## v2.239.3 (2025-02-19) + +### Bug Fixes and Other Changes + + * added ap-southeast-7 and mx-central-1 for Jumpstart + * update image_uri_configs 02-19-2025 06:18:15 PST + +## v2.239.2 (2025-02-18) + +### Bug Fixes and Other Changes + + * Add warning about not supporting torch.nn.SyncBatchNorm + * pass in inference_ami_version to model_based endpoint type + * Fix hyperparameter strategy docs + * Add framework_version to all TensorFlowModel examples + * Move RecordSerializer and RecordDeserializer to sagemaker.serializers and sagemaker.deserialzers + +## v2.239.1 (2025-02-14) + +### Bug Fixes and Other Changes + + * keep sagemaker_session from being overridden to None + * Fix all type hint and docstrings for callable + * Fix the workshop link for Step Functions + * Fix Tensorflow doc link + * Fix FeatureGroup docstring + * Add type hint for ProcessingOutput + * Fix sourcedir.tar.gz filenames in docstrings + * Fix documentation for local mode + * bug in get latest version was getting the max sorted alphabetically + * Add cleanup logic to model builder integ tests for endpoints + * Fixed pagination failing while listing collections + * fix ValueError when updating a data quality monitoring schedule + * Add docstring for image_uris.retrieve + * Create GitHub action to trigger canaries + * update image_uri_configs 02-04-2025 06:18:00 PST + +## v2.239.0 (2025-02-01) + +### Features + + * Add support for deepseek recipes + +### Bug Fixes and Other Changes + + * mpirun protocol - distributed training with @remote decorator + * Allow telemetry only in supported regions + * Fix ssh host policy + +## v2.238.0 (2025-01-29) + +### Features + + * use jumpstart deployment config image as default optimization image + +### Bug Fixes and Other Changes + + * chore: add new images for HF TGI + * update image_uri_configs 01-29-2025 06:18:08 PST + * skip TF tests for unsupported versions + * Merge branch 'master-rba' into local_merge + * Add missing attributes to local resourceconfig + * update image_uri_configs 01-27-2025 06:18:13 PST + * update image_uri_configs 01-24-2025 06:18:11 PST + * add missing schema definition in docs + * Omegaconf upgrade + * SageMaker @remote function: Added multi-node functionality + * remove option + * fix typo + * fix tests + * Add an option for user to remove inputs and container artifacts when using local model trainer + ## v2.237.3 (2025-01-09) ### Bug Fixes and Other Changes diff --git a/CODEOWNERS b/CODEOWNERS deleted file mode 100644 index 7f7ac28644..0000000000 --- a/CODEOWNERS +++ /dev/null @@ -1 +0,0 @@ -* @aws/sagemaker-ml-frameworks diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 3b64466870..0000000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,4 +0,0 @@ -## Code of Conduct -This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). -For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact -opensource-codeofconduct@amazon.com with any additional questions or comments. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 24226af4ee..6a78a25c21 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,7 @@ information to effectively respond to your bug report or contribution. * [Run the Unit Tests](#run-the-unit-tests) * [Run the Integration Tests](#run-the-integration-tests) * [Make and Test Your Change](#make-and-test-your-change) + * [Lint Your Change](#lint-your-change) * [Commit Your Change](#commit-your-change) * [Send a Pull Request](#send-a-pull-request) * [Documentation Guidelines](#documentation-guidelines) @@ -61,6 +62,10 @@ Before sending us a pull request, please ensure that: 1. Follow the instructions at [Modifying an EBS Volume Using Elastic Volumes (Console)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/requesting-ebs-volume-modifications.html#modify-ebs-volume) to increase the EBS volume size associated with the newly created EC2 instance. 1. Wait 5-10min for the new EBS volume increase to finalize. 1. Allow EC2 to claim the additional space by stopping and then starting your EC2 host. +2. Set up a venv to manage dependencies: + 1. `python -m venv ~/.venv/myproject-env` to create the venv + 2. `source ~/.venv/myproject-env/bin/activate` to activate the venv + 3. `deactivate` to exit the venv ### Pull Down the Code @@ -74,8 +79,8 @@ Before sending us a pull request, please ensure that: ### Run the Unit Tests 1. Install tox using `pip install tox` -1. Install coverage using `pip install .[test]` -1. cd into the sagemaker-python-sdk folder: `cd sagemaker-python-sdk` or `cd /environment/sagemaker-python-sdk` +1. cd into the github project sagemaker-python-sdk folder: `cd sagemaker-python-sdk` or `cd /environment/sagemaker-python-sdk` +1. Install coverage using `pip install '.[test]'` 1. Run the following tox command and verify that all code checks and unit tests pass: `tox tests/unit` 1. You can also run a single test with the following command: `tox -e py310 -- -s -vv ::` 1. You can run coverage via runcvoerage env : `tox -e runcoverage -- tests/unit` or `tox -e py310 -- tests/unit --cov=sagemaker --cov-append --cov-report xml` @@ -113,6 +118,13 @@ If you are writing or modifying a test that creates a SageMaker job (training, t 1. If your changes include documentation changes, please see the [Documentation Guidelines](#documentation-guidelines). 1. If you include integration tests, do not mark them as canaries if they will not run in all regions. +### Lint Your Change + +Before submitting, ensure your code meets our quality and style guidelines. Run: +```shell +tox -e flake8,pylint,docstyle,black-check,twine --parallel all +``` +Address any errors or warnings before opening a pull request. ### Commit Your Change diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000000..f49a4e16e6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/LICENSE.txt b/LICENSE.txt deleted file mode 100644 index 0633468f44..0000000000 --- a/LICENSE.txt +++ /dev/null @@ -1,193 +0,0 @@ - Apache License - Version 2.0, January 2004 - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - ====================================================================================== - Amazon SageMaker Examples Subcomponents: - - The Amazon SageMaker Examples project contains subcomponents with separate - copyright notices and license terms. Your use of the source code for the - these subcomponents is subject to the terms and conditions of the following - licenses. See licenses/ for text of these licenses. - - If a folder hierarchy is listed as subcomponent, separate listings of - further subcomponents (files or folder hierarchies) part of the hierarchy - take precedence. - - ======================================================================================= - 2-clause BSD license - ======================================================================================= - _static/kendrasearchtools.js - _templates/search.html diff --git a/MANIFEST.in b/MANIFEST.in deleted file mode 100644 index 28f1569c35..0000000000 --- a/MANIFEST.in +++ /dev/null @@ -1,18 +0,0 @@ -recursive-include src/sagemaker *.py - -include src/sagemaker/image_uri_config/*.json -include src/sagemaker/pytorch/training_recipes.json -include src/sagemaker/serve/schema/*.json -include src/sagemaker/serve/requirements.txt -include src/sagemaker/modules/train/sm_recipes/training_recipes.json -recursive-include requirements * - -include VERSION -include LICENSE.txt -include README.rst -include hatch_build.py - -prune tests - -recursive-exclude * __pycache__ -recursive-exclude * *.py[co] diff --git a/NOTICE.txt b/NOTICE.txt deleted file mode 100644 index 46da7e5caa..0000000000 --- a/NOTICE.txt +++ /dev/null @@ -1,2 +0,0 @@ -Amazon SageMaker Python SDK -Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. diff --git a/README.rst b/README.rst index 68cf79c55b..e39f955deb 100644 --- a/README.rst +++ b/README.rst @@ -10,10 +10,6 @@ SageMaker Python SDK :target: https://pypi.python.org/pypi/sagemaker :alt: Latest Version -.. image:: https://img.shields.io/conda/vn/conda-forge/sagemaker-python-sdk.svg - :target: https://anaconda.org/conda-forge/sagemaker-python-sdk - :alt: Conda-Forge Version - .. image:: https://img.shields.io/pypi/pyversions/sagemaker.svg :target: https://pypi.python.org/pypi/sagemaker :alt: Supported Python Versions @@ -32,40 +28,170 @@ SageMaker Python SDK SageMaker Python SDK is an open source library for training and deploying machine learning models on Amazon SageMaker. -With the SDK, you can train and deploy models using popular deep learning frameworks **Apache MXNet** and **TensorFlow**. +With the SDK, you can train and deploy models using popular deep learning frameworks **Apache MXNet** and **PyTorch**. You can also train and deploy models with **Amazon algorithms**, which are scalable implementations of core machine learning algorithms that are optimized for SageMaker and GPU training. If you have **your own algorithms** built into SageMaker compatible Docker containers, you can train and host models using these as well. -For detailed documentation, including the API reference, see `Read the Docs `_. +To install SageMaker Python SDK, see `Installing SageMaker Python SDK <#installing-the-sagemaker-python-sdk>`_. + +❗🔥 SageMaker V3 Release +------------------------- + +Version 3.0.0 represents a significant milestone in our product's evolution. This major release introduces a modernized architecture, enhanced performance, and powerful new features while maintaining our commitment to user experience and reliability. + +**Important: Please review these breaking changes before upgrading.** + +* Older interfaces such as Estimator, Model, Predictor and all their subclasses will not be supported in V3. +* Please see our `V3 examples folder `__ for example notebooks and usage patterns. + + +Migrating to V3 +---------------- + +**Upgrading to 3.x** + +To upgrade to the latest version of SageMaker Python SDK 3.x: + +:: + + pip install --upgrade sagemaker + +If you prefer to downgrade to the 2.x version: + +:: + + pip install sagemaker==2.* + +See `SageMaker V2 Examples <#sagemaker-v2-examples>`__ for V2 documentation and examples. + +**Key Benefits of 3.x** + +* **Modular Architecture**: Separate PyPI packages for core, training, and serving capabilities + + * `sagemaker-core `__ + * `sagemaker-train `__ + * `sagemaker-serve `__ + * `sagemaker-mlops `__ + +* **Unified Training & Inference**: Single classes (ModelTrainer, ModelBuilder) replace multiple framework-specific classes +* **Object-Oriented API**: Structured interface with auto-generated configs aligned with AWS APIs +* **Simplified Workflows**: Reduced boilerplate and more intuitive interfaces + +**Training Experience** + +V3 introduces the unified ModelTrainer class to reduce complexity of initial setup and deployment for model training. This replaces the V2 Estimator class and framework-specific classes (PyTorchEstimator, SKLearnEstimator, etc.). + +This example shows how to train a model using a custom training container with training data from S3. + +*SageMaker Python SDK 2.x:* + +.. code:: python + + from sagemaker.estimator import Estimator + estimator = Estimator( + image_uri="my-training-image", + role="arn:aws:iam::123456789012:role/SageMakerRole", + instance_count=1, + instance_type="ml.m5.xlarge", + output_path="s3://my-bucket/output" + ) + estimator.fit({"training": "s3://my-bucket/train"}) + +*SageMaker Python SDK 3.x:* + +.. code:: python + + from sagemaker.train import ModelTrainer + from sagemaker.train.configs import InputData + + trainer = ModelTrainer( + training_image="my-training-image", + role="arn:aws:iam::123456789012:role/SageMakerRole" + ) + + train_data = InputData( + channel_name="training", + data_source="s3://my-bucket/train" + ) + + trainer.train(input_data_config=[train_data]) + +**See more examples:** `SageMaker V3 Examples <#sagemaker-v3-examples>`__ + +**Inference Experience** + +V3 introduces the unified ModelBuilder class for model deployment and inference. This replaces the V2 Model class and framework-specific classes (PyTorchModel, TensorFlowModel, SKLearnModel, XGBoostModel, etc.). + +This example shows how to deploy a trained model for real-time inference. + +*SageMaker Python SDK 2.x:* + +.. code:: python + + from sagemaker.model import Model + from sagemaker.predictor import Predictor + model = Model( + image_uri="my-inference-image", + model_data="s3://my-bucket/model.tar.gz", + role="arn:aws:iam::123456789012:role/SageMakerRole" + ) + predictor = model.deploy( + initial_instance_count=1, + instance_type="ml.m5.xlarge" + ) + result = predictor.predict(data) + +*SageMaker Python SDK 3.x:* + +.. code:: python + + from sagemaker.serve import ModelBuilder + model_builder = ModelBuilder( + model="my-model", + model_path="s3://my-bucket/model.tar.gz" + ) + endpoint = model_builder.build() + result = endpoint.invoke(...) + +**See more examples:** `SageMaker V3 Examples <#sagemaker-v3-examples>`__ + +SageMaker V3 Examples +--------------------- + +**Training Examples** + +#. `Custom Distributed Training Example `__ +#. `Distributed Local Training Example `__ +#. `Hyperparameter Training Example `__ +#. `JumpStart Training Example `__ +#. `Local Training Example `__ + +**Inference Examples** + +#. `HuggingFace Example `__ +#. `In-Process Mode Example `__ +#. `Inference Spec Example `__ +#. `JumpStart E2E Training Example `__ +#. `JumpStart Example `__ +#. `Local Mode Example `__ +#. `Optimize Example `__ +#. `Train Inference E2E Example `__ + +**ML Ops Examples** + +#. `V3 Hyperparameter Tuning Example `__ +#. `V3 Hyperparameter Tuning Pipeline `__ +#. `V3 Model Registry Example `__ +#. `V3 PyTorch Processing Example `__ +#. `V3 Pipeline Train Create Registry `__ +#. `V3 Processing Job Sklearn `__ +#. `V3 SageMaker Clarify `__ +#. `V3 Transform Job Example `__ + +**Looking for V2 Examples?** See `SageMaker V2 Examples <#sagemaker-v2-examples>`__ below. -Table of Contents ------------------ -#. `Installing SageMaker Python SDK <#installing-the-sagemaker-python-sdk>`__ -#. `Using the SageMaker Python SDK `__ -#. `Using MXNet `__ -#. `Using TensorFlow `__ -#. `Using Chainer `__ -#. `Using PyTorch `__ -#. `Using Scikit-learn `__ -#. `Using XGBoost `__ -#. `SageMaker Reinforcement Learning Estimators `__ -#. `SageMaker SparkML Serving <#sagemaker-sparkml-serving>`__ -#. `Amazon SageMaker Built-in Algorithm Estimators `__ -#. `Using SageMaker AlgorithmEstimators `__ -#. `Consuming SageMaker Model Packages `__ -#. `BYO Docker Containers with SageMaker Estimators `__ -#. `SageMaker Automatic Model Tuning `__ -#. `SageMaker Batch Transform `__ -#. `Secure Training and Inference with VPC `__ -#. `BYO Model `__ -#. `Inference Pipelines `__ -#. `Amazon SageMaker Operators in Apache Airflow `__ -#. `SageMaker Autopilot `__ -#. `Model Monitoring `__ -#. `SageMaker Debugger `__ -#. `SageMaker Processing `__ Installing the SageMaker Python SDK @@ -94,10 +220,10 @@ Supported Python Versions SageMaker Python SDK is tested on: -- Python 3.8 - Python 3.9 - Python 3.10 - Python 3.11 +- Python 3.12 Telemetry ~~~~~~~~~~~~~~~ @@ -191,9 +317,9 @@ Setup a Python environment, and install the dependencies listed in ``doc/require :: # conda - conda create -n sagemaker python=3.7 + conda create -n sagemaker python=3.12 conda activate sagemaker - conda install sphinx=3.1.1 sphinx_rtd_theme=0.5.0 + conda install sphinx=5.1.1 sphinx_rtd_theme=0.5.0 # pip pip install -r doc/requirements.txt @@ -254,3 +380,77 @@ For more information about the different ``content-type`` and ``Accept`` formats ``schema`` that SageMaker SparkML Serving recognizes, please see `SageMaker SparkML Serving Container`_. .. _SageMaker SparkML Serving Container: https://github.com/aws/sagemaker-sparkml-serving-container + + +SageMaker V2 Examples +--------------------- + +#. `Using the SageMaker Python SDK `__ +#. `Using MXNet `__ +#. `Using TensorFlow `__ +#. `Using Chainer `__ +#. `Using PyTorch `__ +#. `Using Scikit-learn `__ +#. `Using XGBoost `__ +#. `SageMaker Reinforcement Learning Estimators `__ +#. `SageMaker SparkML Serving <#sagemaker-sparkml-serving>`__ +#. `Amazon SageMaker Built-in Algorithm Estimators `__ +#. `Using SageMaker AlgorithmEstimators `__ +#. `Consuming SageMaker Model Packages `__ +#. `BYO Docker Containers with SageMaker Estimators `__ +#. `SageMaker Automatic Model Tuning `__ +#. `SageMaker Batch Transform `__ +#. `Secure Training and Inference with VPC `__ +#. `BYO Model `__ +#. `Inference Pipelines `__ +#. `Amazon SageMaker Operators in Apache Airflow `__ +#. `SageMaker Autopilot `__ +#. `Model Monitoring `__ +#. `SageMaker Debugger `__ +#. `SageMaker Processing `__ + +🚀 Model Fine-Tuning Support Now Available in V3 +------------------------------------------------- + +We're excited to announce model fine-tuning capabilities in SageMaker Python SDK V3! + +**What's New** + +Four new trainer classes for fine-tuning foundation models: + +* SFTTrainer - Supervised fine-tuning +* DPOTrainer - Direct preference optimization +* RLAIFTrainer - RL from AI feedback +* RLVRTrainer - RL from verifiable rewards + +**Quick Example** + +.. code:: python + + from sagemaker.train import SFTTrainer + from sagemaker.train.common import TrainingType + + trainer = SFTTrainer( + model="meta-llama/Llama-2-7b-hf", + training_type=TrainingType.LORA, + model_package_group_name="my-models", + training_dataset="s3://bucket/train.jsonl" + ) + + training_job = trainer.train() + +**Key Features** + +* ✨ LoRA & full fine-tuning +* 📊 MLflow integration with real-time metrics +* 🚀 Deploy to SageMaker or Bedrock +* 📈 Built-in evaluation (11 benchmarks) +* ☁️ Serverless training + +**Get Started** + +.. code:: python + + pip install sagemaker>=3.1.0 + +`📓 Example notebooks `__ \ No newline at end of file diff --git a/VERSION b/VERSION index 1ca006360a..15a2799817 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.237.4.dev0 +3.3.0 diff --git a/bin/README b/bin/README deleted file mode 100644 index 6accc729fc..0000000000 --- a/bin/README +++ /dev/null @@ -1,5 +0,0 @@ -Put your python scripts into this directory. - -Any script that has a shebang line with python in it and is executable -will be automatically included in your package. All others must be -declared explicitly in the setup.py file. diff --git a/ci-scripts/displaytime.sh b/ci-scripts/displaytime.sh deleted file mode 100755 index 6e1e474b4a..0000000000 --- a/ci-scripts/displaytime.sh +++ /dev/null @@ -1,29 +0,0 @@ -#!/usr/bin/env bash -# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"). You -# may not use this file except in compliance with the License. A copy of -# the License is located at -# -# http://aws.amazon.com/apache2.0/ -# -# or in the "license" file accompanying this file. This file is -# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF -# ANY KIND, either express or implied. See the License for the specific -# language governing permissions and limitations under the License. - -set -euo pipefail - -echo =================== $1 execution time =================== - -start_time=$2 -end_time=`date +%s` -total_time=$(expr $end_time - $start_time + 1) -hours=$((total_time/60/60%24)) -minutes=$((total_time/60%60)) -secs=$((total_time%60)) - -(( $hours > 0 )) && printf '%d hours ' $hours -(( $minutes > 0 )) && printf '%d minutes ' $minutes -(( $hours > 0 || $minutes > 0 )) && printf 'and ' -printf '%d seconds\n\n' $secs diff --git a/ci-scripts/queue_build.py b/ci-scripts/queue_build.py deleted file mode 100644 index fcff0b9a9b..0000000000 --- a/ci-scripts/queue_build.py +++ /dev/null @@ -1,161 +0,0 @@ -# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"). You -# may not use this file except in compliance with the License. A copy of -# the License is located at -# -# http://aws.amazon.com/apache2.0/ -# -# or in the "license" file accompanying this file. This file is -# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF -# ANY KIND, either express or implied. See the License for the specific -# language governing permissions and limitations under the License. -from __future__ import absolute_import - -import os -import re -import time - -import boto3 - -account = boto3.client( - "sts", region_name="us-west-2", endpoint_url="https://sts.us-west-2.amazonaws.com" -).get_caller_identity()["Account"] -bucket_name = "sagemaker-us-west-2-%s" % account - -MAX_IN_PROGRESS_BUILDS = 3 -INTERVAL_BETWEEN_CONCURRENT_RUNS = 15 # minutes -CLEAN_UP_TICKETS_OLDER_THAN = 8 # hours - - -def queue_build(): - ticket_number = int(1000 * time.time()) - files = _list_tickets() - _cleanup_tickets_older_than(files) - _wait_for_other_builds(ticket_number) - - -def _build_info_from_file(file): - filename = file.key.split("/")[2] - ticket_number, build_id, source_version = filename.split("_") - return int(ticket_number), build_id, source_version - - -def _wait_for_other_builds(ticket_number): - sorted_files = _list_tickets() - - print("build queue status:") - print() - - for order, file in enumerate(sorted_files): - file_ticket_number, build_id, source_version = _build_info_from_file(file) - print( - "%s -> %s %s, ticket number: %s status: %s" - % (order, build_id, source_version, file_ticket_number, file.key.split("/")[1]) - ) - print() - build_id = re.sub("[_/]", "-", os.environ.get("CODEBUILD_BUILD_ID", "CODEBUILD-BUILD-ID")) - source_version = re.sub( - "[_/]", - "-", - os.environ.get("CODEBUILD_SOURCE_VERSION", "CODEBUILD-SOURCE-VERSION"), - ) - filename = "%s_%s_%s" % (ticket_number, build_id, source_version) - s3_file_obj = _write_ticket(filename, status="waiting") - print("Build %s waiting to be scheduled" % filename) - - while True: - _cleanup_tickets_with_terminal_states() - waiting_tickets = _list_tickets("waiting") - if waiting_tickets: - first_waiting_ticket_number, _, _ = _build_info_from_file(_list_tickets("waiting")[0]) - else: - first_waiting_ticket_number = ticket_number - - if ( - len(_list_tickets(status="in-progress")) < 3 - and last_in_progress_elapsed_time_check() - and first_waiting_ticket_number == ticket_number - ): - # put the build in progress - print("Scheduling build %s for running.." % filename) - s3_file_obj.delete() - _write_ticket(filename, status="in-progress") - break - else: - # wait - time.sleep(30) - - -def last_in_progress_elapsed_time_check(): - in_progress_tickets = _list_tickets("in-progress") - if not in_progress_tickets: - return True - last_in_progress_ticket, _, _ = _build_info_from_file(_list_tickets("in-progress")[-1]) - _elapsed_time = int(1000 * time.time()) - last_in_progress_ticket - last_in_progress_elapsed_time = int(_elapsed_time / (1000 * 60)) # in minutes - return last_in_progress_elapsed_time > INTERVAL_BETWEEN_CONCURRENT_RUNS - - -def _cleanup_tickets_with_terminal_states(): - files = _list_tickets() - build_ids = [] - for file in files: - _, build_id, _ = _build_info_from_file(file) - build_ids.append(build_id) - - client = boto3.client("codebuild") - response = client.batch_get_builds(ids=build_ids) - - for file, build_details in zip(files, response["builds"]): - _, _build_id_from_file, _ = _build_info_from_file(file) - build_status = build_details["buildStatus"] - - if build_status != "IN_PROGRESS" and _build_id_from_file == build_details["id"]: - print( - "Build %s in terminal state: %s, deleting lock" - % (_build_id_from_file, build_status) - ) - file.delete() - - -def _cleanup_tickets_older_than(files): - oldfiles = list(filter(_file_older_than, files)) - for file in oldfiles: - print("object %s older than 8 hours. Deleting" % file.key) - file.delete() - return files - - -def _list_tickets(status=None): - s3 = boto3.resource("s3") - bucket = s3.Bucket(bucket_name) - prefix = "ci-integ-queue/{}/".format(status) if status else "ci-integ-queue/" - objects = [file for file in bucket.objects.filter(Prefix=prefix)] - files = list(filter(lambda x: x != prefix, objects)) - sorted_files = list(sorted(files, key=lambda y: y.key)) - return sorted_files - - -def _file_older_than(file): - timelimit = 1000 * 60 * 60 * CLEAN_UP_TICKETS_OLDER_THAN - file_ticket_number, build_id, source_version = _build_info_from_file(file) - return int(1000 * time.time()) - file_ticket_number > timelimit - - -def _write_ticket(filename, status="waiting"): - file_path = "ci-integ-queue/{}".format(status) - if not os.path.exists(file_path): - os.makedirs(file_path) - - file_full_path = file_path + "/" + filename - with open(file_full_path, "w") as file: - file.write(filename) - s3_file_obj = boto3.Session().resource("s3").Object(bucket_name, file_full_path) - s3_file_obj.upload_file(file_full_path) - print("Build %s is now in state %s" % (filename, status)) - return s3_file_obj - - -if __name__ == "__main__": - queue_build() diff --git a/doc/_static/js/datatable.js b/doc/_static/js/datatable.js deleted file mode 100644 index 897204e8df..0000000000 --- a/doc/_static/js/datatable.js +++ /dev/null @@ -1,4 +0,0 @@ -$(document).ready( function () { - $('table.datatable').DataTable(); - $('a.external').attr('target', '_blank'); -} ); \ No newline at end of file diff --git a/doc/_static/kendrasearchtools.js b/doc/_static/kendrasearchtools.js deleted file mode 100644 index 4920607010..0000000000 --- a/doc/_static/kendrasearchtools.js +++ /dev/null @@ -1,700 +0,0 @@ -/* - * kendrasearchtools.js - * ~~~~~~~~~~~~~~~~ - * - * A modification of searchtools.js (https://github.com/sphinx-doc/sphinx/blob/275d9/sphinx/themes/basic/static/searchtools.js) - * where the default full-text search implemented in searchtools.js is replaced with AWS Kendra searching over multiple - * websites. The default full-text search is still kept and implemented as a fallback in the case that the Kendra search doesn't work. - * - * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -if (!Scorer) { - /** - * Simple result scoring code. - */ - var Scorer = { - // Implement the following function to further tweak the score for each result - // The function takes a result array [filename, title, anchor, descr, score] - // and returns the new score. - /* - score: function(result) { - return result[4]; - }, - */ - - // query matches the full name of an object - objNameMatch: 11, - // or matches in the last dotted part of the object name - objPartialMatch: 6, - // Additive scores depending on the priority of the object - objPrio: {0: 15, // used to be importantResults - 1: 5, // used to be objectResults - 2: -5}, // used to be unimportantResults - // Used when the priority is not in the mapping. - objPrioDefault: 0, - - // query found in title - title: 15, - partialTitle: 7, - // query found in terms - term: 5, - partialTerm: 2 - }; -} - -if (!splitQuery) { - function splitQuery(query) { - return query.split(/\s+/); - } -} - -/** - * default rtd search (used as fallback) - */ -var Search = { - - _index : null, - _queued_query : null, - _pulse_status : -1, - - htmlToText : function(htmlString) { - var virtualDocument = document.implementation.createHTMLDocument('virtual'); - var htmlElement = $(htmlString, virtualDocument); - htmlElement.find('.headerlink').remove(); - docContent = htmlElement.find('[role=main]')[0]; - if(docContent === undefined) { - console.warn("Content block not found. Sphinx search tries to obtain it " + - "via '[role=main]'. Could you check your theme or template."); - return ""; - } - return docContent.textContent || docContent.innerText; - }, - - init : function() { - var params = $.getQueryParameters(); - if (params.q) { - var query = params.q[0]; - $('input[name="q"]')[0].value = query; - // this.performSearch(query); - } - }, - - loadIndex : function(url) { - $.ajax({type: "GET", url: url, data: null, - dataType: "script", cache: true, - complete: function(jqxhr, textstatus) { - if (textstatus != "success") { - document.getElementById("searchindexloader").src = url; - } - }}); - }, - - setIndex : function(index) { - var q; - this._index = index; - if ((q = this._queued_query) !== null) { - this._queued_query = null; - Search.query(q); - } - }, - - hasIndex : function() { - return this._index !== null; - }, - - deferQuery : function(query) { - this._queued_query = query; - }, - - stopPulse : function() { - this._pulse_status = 0; - }, - - startPulse : function() { - if (this._pulse_status >= 0) - return; - function pulse() { - var i; - Search._pulse_status = (Search._pulse_status + 1) % 4; - var dotString = ''; - for (i = 0; i < Search._pulse_status; i++) - dotString += '.'; - Search.dots.text(dotString); - if (Search._pulse_status > -1) - window.setTimeout(pulse, 500); - } - pulse(); - }, - - /** - * perform a search for something (or wait until index is loaded) - */ - performSearch : function(query) { - // create the required interface elements - this.out = $('#search-results'); - this.title = $('#search-results h2:first'); // $('

' + _('Searching') + '

').appendTo(this.out); - this.dots = $('#search-results span:first'); //$('').appendTo(this.title); - this.status = $('#search-results p:first'); // $('

 

').appendTo(this.out); - this.output = $('#search-results ul:first'); //$('
    ').appendTo(this.out); - - $('#search-progress').text(_('Preparing search...')); - this.startPulse(); - - // index already loaded, the browser was quick! - if (this.hasIndex()) - this.query(query); - else - this.deferQuery(query); - }, - - /** - * execute search (requires search index to be loaded) - */ - query : function(query) { - var i; - - // stem the searchterms and add them to the correct list - var stemmer = new Stemmer(); - var searchterms = []; - var excluded = []; - var hlterms = []; - var tmp = splitQuery(query); - var objectterms = []; - for (i = 0; i < tmp.length; i++) { - if (tmp[i] !== "") { - objectterms.push(tmp[i].toLowerCase()); - } - - if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i] === "") { - // skip this "word" - continue; - } - // stem the word - var word = stemmer.stemWord(tmp[i].toLowerCase()); - // prevent stemmer from cutting word smaller than two chars - if(word.length < 3 && tmp[i].length >= 3) { - word = tmp[i]; - } - var toAppend; - // select the correct list - if (word[0] == '-') { - toAppend = excluded; - word = word.substr(1); - } - else { - toAppend = searchterms; - hlterms.push(tmp[i].toLowerCase()); - } - // only add if not already in the list - if (!$u.contains(toAppend, word)) - toAppend.push(word); - } - var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" ")); - - // console.debug('SEARCH: searching for:'); - // console.info('required: ', searchterms); - // console.info('excluded: ', excluded); - - // prepare search - var terms = this._index.terms; - var titleterms = this._index.titleterms; - - // array of [filename, title, anchor, descr, score] - var results = []; - $('#search-progress').empty(); - - // lookup as object - for (i = 0; i < objectterms.length; i++) { - var others = [].concat(objectterms.slice(0, i), - objectterms.slice(i+1, objectterms.length)); - results = results.concat(this.performObjectSearch(objectterms[i], others)); - } - - // lookup as search terms in fulltext - results = results.concat(this.performTermsSearch(searchterms, excluded, terms, titleterms)); - - // let the scorer override scores with a custom scoring function - if (Scorer.score) { - for (i = 0; i < results.length; i++) - results[i][4] = Scorer.score(results[i]); - } - - // now sort the results by score (in opposite order of appearance, since the - // display function below uses pop() to retrieve items) and then - // alphabetically - results.sort(function(a, b) { - var left = a[4]; - var right = b[4]; - if (left > right) { - return 1; - } else if (left < right) { - return -1; - } else { - // same score: sort alphabetically - left = a[1].toLowerCase(); - right = b[1].toLowerCase(); - return (left > right) ? -1 : ((left < right) ? 1 : 0); - } - }); - - // for debugging - //Search.lastresults = results.slice(); // a copy - //console.info('search results:', Search.lastresults); - - // print the results - var resultCount = results.length; - function displayNextItem() { - // results left, load the summary and display it - if (results.length) { - var item = results.pop(); - var listItem = $('
  • '); - var requestUrl = ""; - var linkUrl = ""; - if (DOCUMENTATION_OPTIONS.BUILDER === 'dirhtml') { - // dirhtml builder - var dirname = item[0] + '/'; - if (dirname.match(/\/index\/$/)) { - dirname = dirname.substring(0, dirname.length-6); - } else if (dirname == 'index/') { - dirname = ''; - } - requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + dirname; - linkUrl = requestUrl; - - } else { - // normal html builders - requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX; - linkUrl = item[0] + DOCUMENTATION_OPTIONS.LINK_SUFFIX; - } - listItem.append($('').attr('href', - linkUrl + - highlightstring + item[2]).html(item[1])); - if (item[3]) { - listItem.append($(' (' + item[3] + ')')); - Search.output.append(listItem); - setTimeout(function() { - displayNextItem(); - }, 5); - } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { - $.ajax({url: requestUrl, - dataType: "text", - complete: function(jqxhr, textstatus) { - var data = jqxhr.responseText; - if (data !== '' && data !== undefined) { - var summary = Search.makeSearchSummary(data, searchterms, hlterms); - if (summary) { - listItem.append(summary); - } - } - Search.output.append(listItem); - setTimeout(function() { - displayNextItem(); - }, 5); - }}); - } else { - // no source available, just display title - Search.output.append(listItem); - setTimeout(function() { - displayNextItem(); - }, 5); - } - } - // search finished, update title and status message - else { - Search.stopPulse(); - Search.title.text(_('Search Results')); - if (!resultCount) - Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve used the correct terminology.')); - else - Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount)); - Search.status.fadeIn(500); - } - } - displayNextItem(); - }, - - /** - * search for object names - */ - performObjectSearch : function(object, otherterms) { - var filenames = this._index.filenames; - var docnames = this._index.docnames; - var objects = this._index.objects; - var objnames = this._index.objnames; - var titles = this._index.titles; - - var i; - var results = []; - - for (var prefix in objects) { - for (var name in objects[prefix]) { - var fullname = (prefix ? prefix + '.' : '') + name; - var fullnameLower = fullname.toLowerCase() - if (fullnameLower.indexOf(object) > -1) { - var score = 0; - var parts = fullnameLower.split('.'); - // check for different match types: exact matches of full name or - // "last name" (i.e. last dotted part) - if (fullnameLower == object || parts[parts.length - 1] == object) { - score += Scorer.objNameMatch; - // matches in last name - } else if (parts[parts.length - 1].indexOf(object) > -1) { - score += Scorer.objPartialMatch; - } - var match = objects[prefix][name]; - var objname = objnames[match[1]][2]; - var title = titles[match[0]]; - // If more than one term searched for, we require other words to be - // found in the name/title/description - if (otherterms.length > 0) { - var haystack = (prefix + ' ' + name + ' ' + - objname + ' ' + title).toLowerCase(); - var allfound = true; - for (i = 0; i < otherterms.length; i++) { - if (haystack.indexOf(otherterms[i]) == -1) { - allfound = false; - break; - } - } - if (!allfound) { - continue; - } - } - var descr = objname + _(', in ') + title; - - var anchor = match[3]; - if (anchor === '') - anchor = fullname; - else if (anchor == '-') - anchor = objnames[match[1]][1] + '-' + fullname; - // add custom score for some objects according to scorer - if (Scorer.objPrio.hasOwnProperty(match[2])) { - score += Scorer.objPrio[match[2]]; - } else { - score += Scorer.objPrioDefault; - } - results.push([docnames[match[0]], fullname, '#'+anchor, descr, score, filenames[match[0]]]); - } - } - } - - return results; - }, - - /** - * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions - */ - escapeRegExp : function(string) { - return string.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string - }, - - /** - * search for full-text terms in the index - */ - performTermsSearch : function(searchterms, excluded, terms, titleterms) { - var docnames = this._index.docnames; - var filenames = this._index.filenames; - var titles = this._index.titles; - - var i, j, file; - var fileMap = {}; - var scoreMap = {}; - var results = []; - - // perform the search on the required terms - for (i = 0; i < searchterms.length; i++) { - var word = searchterms[i]; - var files = []; - var _o = [ - {files: terms[word], score: Scorer.term}, - {files: titleterms[word], score: Scorer.title} - ]; - // add support for partial matches - if (word.length > 2) { - var word_regex = this.escapeRegExp(word); - for (var w in terms) { - if (w.match(word_regex) && !terms[word]) { - _o.push({files: terms[w], score: Scorer.partialTerm}) - } - } - for (var w in titleterms) { - if (w.match(word_regex) && !titleterms[word]) { - _o.push({files: titleterms[w], score: Scorer.partialTitle}) - } - } - } - - // no match but word was a required one - if ($u.every(_o, function(o){return o.files === undefined;})) { - break; - } - // found search word in contents - $u.each(_o, function(o) { - var _files = o.files; - if (_files === undefined) - return - - if (_files.length === undefined) - _files = [_files]; - files = files.concat(_files); - - // set score for the word in each file to Scorer.term - for (j = 0; j < _files.length; j++) { - file = _files[j]; - if (!(file in scoreMap)) - scoreMap[file] = {}; - scoreMap[file][word] = o.score; - } - }); - - // create the mapping - for (j = 0; j < files.length; j++) { - file = files[j]; - if (file in fileMap && fileMap[file].indexOf(word) === -1) - fileMap[file].push(word); - else - fileMap[file] = [word]; - } - } - - // now check if the files don't contain excluded terms - for (file in fileMap) { - var valid = true; - - // check if all requirements are matched - var filteredTermCount = // as search terms with length < 3 are discarded: ignore - searchterms.filter(function(term){return term.length > 2}).length - if ( - fileMap[file].length != searchterms.length && - fileMap[file].length != filteredTermCount - ) continue; - - // ensure that none of the excluded terms is in the search result - for (i = 0; i < excluded.length; i++) { - if (terms[excluded[i]] == file || - titleterms[excluded[i]] == file || - $u.contains(terms[excluded[i]] || [], file) || - $u.contains(titleterms[excluded[i]] || [], file)) { - valid = false; - break; - } - } - - // if we have still a valid result we can add it to the result list - if (valid) { - // select one (max) score for the file. - // for better ranking, we should calculate ranking by using words statistics like basic tf-idf... - var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]})); - results.push([docnames[file], titles[file], '', null, score, filenames[file]]); - } - } - return results; - }, - - /** - * helper function to return a node containing the - * search summary for a given text. keywords is a list - * of stemmed words, hlwords is the list of normal, unstemmed - * words. the first one is used to find the occurrence, the - * latter for highlighting it. - */ - makeSearchSummary : function(htmlText, keywords, hlwords) { - var text = Search.htmlToText(htmlText); - if (text == "") { - return null; - } - var textLower = text.toLowerCase(); - var start = 0; - $.each(keywords, function() { - var i = textLower.indexOf(this.toLowerCase()); - if (i > -1) - start = i; - }); - start = Math.max(start - 120, 0); - var excerpt = ((start > 0) ? '...' : '') + - $.trim(text.substr(start, 240)) + - ((start + 240 - text.length) ? '...' : ''); - var rv = $('

    ').text(excerpt); - $.each(hlwords, function() { - rv = rv.highlightText(this, 'highlighted'); - }); - return rv; - } -}; - -/** - * kendra search (used by default) - */ -var KendraSearch = { - - _pulse_status : -1, - - init : function() { - var filters = {}; - var params = $.getQueryParameters(); - if (params.q) { - var query = params.q[0]; - $('input[name="q"]')[0].value = query; - - Object.keys(params).forEach(function(key) { - if(key.startsWith("filter")){ - filters[key] = true; - $('input[name="' + key + '"]')[0].checked = true; - } - }); - this.performSearch(query, filters=filters); - } - }, - - stopPulse : function() { - this._pulse_status = 0; - }, - - startPulse : function() { - if (this._pulse_status >= 0) - return; - function pulse() { - var i; - KendraSearch._pulse_status = (KendraSearch._pulse_status + 1) % 4; - var dotString = ''; - for (i = 0; i < KendraSearch._pulse_status; i++) - dotString += '.'; - KendraSearch.dots.text(dotString); - if (KendraSearch._pulse_status > -1) - window.setTimeout(pulse, 500); - } - pulse(); - }, - - sanitize : function(text){ - const map = { - '&': '&', - '<': '<', - '>': '>', - '"': '"', - "'": ''', - "/": '/', - }; - const reg = /[&<>"'/]/ig; - return text.replace(reg, (match)=>(map[match])); - }, - - /** - * execute search (requires search index to be loaded) - */ - query : function(query, pageNumber, pageSize=10, filters={}) { - var url = "https://9cs56celvj.execute-api.us-west-2.amazonaws.com/prod" - - $('#search-progress').empty(); - - query = KendraSearch.sanitize(query); - - fetch(url, { - method: 'post', - body: JSON.stringify({ "queryText": query , "pageNumber": pageNumber, "pageSize": pageSize, "filters": filters, "host": window.location.host}), - }).then(response => response.json()) - .then(function(data) { - var docs = data["ResultItems"]; - for(var i = 0; i < docs.length; i++){ - var listItem = $('
  • '); - var doc = docs[i]; - var doc_title = doc["DocumentTitle"]["Text"]; - var doc_url = doc["DocumentURI"]; - var text_excerpt = doc["DocumentExcerpt"]["Text"] - var text_excerpt_highlights = doc["DocumentExcerpt"]["Highlights"] - - var type_badge_html; - if(doc_url.includes("sagemaker-examples.readthedocs.io")){ - type_badge_html = 'Example' - }else if(doc_url.includes("docs.aws.amazon.com")){ - type_badge_html = 'Dev Guide' - }else if(doc_url.includes("sagemaker.readthedocs.io") || doc_url.includes("sagemaker-debugger.readthedocs.io")){ - type_badge_html = 'SDK Guide' - } - - listItem.append($('    ').attr('href', doc_url).html(doc_title + " " + type_badge_html)); - - resHTML = ''; - - if(text_excerpt_highlights.length > 0){ - resHTML += text_excerpt.slice(0, text_excerpt_highlights[0]["BeginOffset"]).replaceAll(/\u00B6/g, "...") - for(var j = 0; j < text_excerpt_highlights.length; j++){ - resHTML += ''; - resHTML += text_excerpt.slice(text_excerpt_highlights[j]["BeginOffset"], text_excerpt_highlights[j]["EndOffset"]).replaceAll(/\u00B6/g, "..."); - - resHTML += ''; - - if( j + 1 == text_excerpt_highlights.length){ - resHTML += text_excerpt.slice(text_excerpt_highlights[j]["EndOffset"]).replaceAll(/\u00B6/g, "..."); - }else{ - resHTML += text_excerpt.slice(text_excerpt_highlights[j]["EndOffset"], text_excerpt_highlights[j+1]["BeginOffset"]).replaceAll(/\u00B6/g, "..."); - } - } - } - listItem.append($('

    ').html(resHTML)); - listItem.append($('').html(doc_url).css("color", "#969696").css("font-size", "0.80rem")); - - KendraSearch.output.append(listItem); - - } - - if(data["ResponseMetadata"]["HTTPStatusCode"] != 200){ - Search.performSearch(query); - }else{ - KendraSearch.stopPulse(); - KendraSearch.title.text(_('Search Results')); - var no_pages = Math.min(Math.floor(parseFloat(data["TotalNumberOfResults"])/parseFloat(pageSize))+1, 100.00/parseFloat(pageSize)); - var maxPaginationButtons = Math.min(6, no_pages); - var startPaginationButtons = Math.max(1, pageNumber-Math.ceil(maxPaginationButtons/2)); - var endPaginationButtons = Math.min(no_pages, startPaginationButtons + maxPaginationButtons); - var paginationItem = $('

    '); - for(var i = startPaginationButtons; i < endPaginationButtons+1; i++){ - if(i == pageNumber){ - paginationItem.append($('    ').attr('id', 'pagination-' + String(i)).html(i).addClass("paginationnolink").addClass("active")); - }else{ - paginationItem.append($('').attr('id', 'pagination-' + String(i)).html(i).addClass("paginationnolink")); - } - } - KendraSearch.out.append(paginationItem); - - $('.paginationnolink').each(function ( index, element ) { - $(element).on('click', function() { - KendraSearch.output.empty(); - paginationItem.remove(); - KendraSearch.query(query, parseInt($(element).attr('id').split("-")[1]), pageSize, filters); - }); - }); - } - - }).catch(function(err) { - console.log("Kendra Search Failed: ", err); - Search.performSearch(query); - }); - }, - - /** - * perform a search for something (or wait until index is loaded) - */ - performSearch : function(query, filters) { - // create the required interface elements - this.out = $('#search-results'); - this.title = $('

    ' + _('Searching...') + '

    ').appendTo(this.out); - this.dots = $('').appendTo(this.title); - this.status = $('

     

    ').appendTo(this.out); - this.output = $('
      ').appendTo(this.out); - this.out.css("margin", "auto"); - - $('#search-progress').text(_('Preparing search...')); - this.startPulse(); - - this.query(query, 1, pageSize=10, filters=filters) - }, - -}; - -$(document).ready(function() { - KendraSearch.init(); -}); diff --git a/doc/_static/pagination.css b/doc/_static/pagination.css deleted file mode 100644 index 7584510574..0000000000 --- a/doc/_static/pagination.css +++ /dev/null @@ -1,17 +0,0 @@ -.pagination { - display: inline-block; -} - -.pagination a { - color: black; - float: left; - padding: 8px 16px; - text-decoration: none; -} - -.pagination a.active { - background-color: #2a80b9; - color: white; -} - -.pagination a:hover:not(.active) {background-color: #ddd;} \ No newline at end of file diff --git a/doc/_static/search_accessories.css b/doc/_static/search_accessories.css deleted file mode 100644 index c7e09e1f06..0000000000 --- a/doc/_static/search_accessories.css +++ /dev/null @@ -1,29 +0,0 @@ -.example-badge { - background-color: #c63340; - color: white; - padding: 0.25rem 0.5rem; - text-align: center; - border-radius: 5px; - font-size: 0.8rem; - display: inline-block; -} - -.aws-doc-badge { - background-color: #e18b50; - color: white; - padding: 0.25rem 0.5rem; - text-align: center; - border-radius: 5px; - font-size: 0.8rem; - display: inline-block; -} - -.sdk-doc-badge { - background-color: #4c968f; - color: white; - padding: 0.25rem 0.5rem; - text-align: center; - border-radius: 5px; - font-size: 0.8rem; - display: inline-block; -} \ No newline at end of file diff --git a/doc/_static/theme_overrides.css b/doc/_static/theme_overrides.css deleted file mode 100644 index 7c1a520223..0000000000 --- a/doc/_static/theme_overrides.css +++ /dev/null @@ -1,10 +0,0 @@ -/* override table width restrictions */ -.wy-table-responsive table td, .wy-table-responsive table th { - white-space: normal; -} - -.wy-table-responsive { - margin-bottom: 24px; - max-width: 100%; - overflow: visible; -} diff --git a/doc/_templates/search.html b/doc/_templates/search.html deleted file mode 100644 index 93c01c7799..0000000000 --- a/doc/_templates/search.html +++ /dev/null @@ -1,56 +0,0 @@ -{# - basic/search.html - ~~~~~~~~~~~~~~~~~ - - Template for the search page. - - :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS. - :license: BSD, see https://github.com/sphinx-doc/sphinx/blob/master/LICENSE for details. -#} -{%- extends "layout.html" %} -{% set title = _('Search') %} -{% set display_vcs_links = False %} -{%- block scripts %} - {{ super() }} - - -{%- endblock %} -{% block footer %} -{# this is used when loading the search index using $.ajax fails, - such as on Chrome for documents on localhost #} - - -{{ super() }} -{% endblock %} -{% block body %} - - -{% if search_performed %} - {# Translators: Search is a noun, not a verb #} -

      {{ _('Search Results') }}

      - {% if not search_results %} -

      {{ _('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve used the correct terminology.') }}

      - {% endif %} -{% endif %} -       -{% endblock %} diff --git a/doc/_templates/searchbox.html b/doc/_templates/searchbox.html deleted file mode 100644 index a7c5aeb1d8..0000000000 --- a/doc/_templates/searchbox.html +++ /dev/null @@ -1,14 +0,0 @@ -
      -
      - -
      -
      -
      -
      Filters:
      -
      -
      -
      -
      - -
      -
      \ No newline at end of file diff --git a/doc/algorithms/index.rst b/doc/algorithms/index.rst deleted file mode 100644 index 87d1c62a89..0000000000 --- a/doc/algorithms/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -###################### -Built-in Algorithms -###################### - -Built-in algorithms are offered in 2 modes: - -* Container mode algorithms offered through :ref:`Estimators ` & :ref:`Amazon Estimators ` - -* Script mode algorithms based on `pre-built SageMaker Docker Images `__ offered through Estimators - -.. toctree:: - :maxdepth: 2 - - sagemaker.amazon.amazon_estimator - tabular/index - text/index - time_series/index - unsupervised/index - vision/index diff --git a/doc/algorithms/sagemaker.amazon.amazon_estimator.rst b/doc/algorithms/sagemaker.amazon.amazon_estimator.rst deleted file mode 100644 index 0273c44c17..0000000000 --- a/doc/algorithms/sagemaker.amazon.amazon_estimator.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _amazon_estimators: - -Amazon Estimators --------------------- - -Base class for Amazon Estimator implementations - -.. autoclass:: sagemaker.amazon.amazon_estimator.AmazonAlgorithmEstimatorBase - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/tabular/autogluon.rst b/doc/algorithms/tabular/autogluon.rst deleted file mode 100644 index 8eae72187e..0000000000 --- a/doc/algorithms/tabular/autogluon.rst +++ /dev/null @@ -1,28 +0,0 @@ -############ -AutoGluon -############ - -`AutoGluon-Tabular `__ is a popular open-source AutoML framework that trains highly accurate machine learning models on an unprocessed tabular dataset. -Unlike existing AutoML frameworks that primarily focus on model and hyperparameter selection, AutoGluon-Tabular succeeds by ensembling multiple models and stacking them in multiple layers. - - -The following table outlines a variety of sample notebooks that address different use cases of Amazon SageMaker AutoGluon-Tabular algorithm. - -.. list-table:: - :widths: 25 25 - :header-rows: 1 - - * - Notebook Title - - Description - * - `Tabular classification with Amazon SageMaker AutoGluon-Tabular algorithm `__ - - This notebook demonstrates the use of the Amazon SageMaker AutoGluon-Tabular algorithm to train and host a tabular classification model. - * - `Tabular regression with Amazon SageMaker AutoGluon-Tabular algorithm `__ - - This notebook demonstrates the use of the Amazon SageMaker AutoGluon-Tabular algorithm to train and host a tabular regression model. - - -For instructions on how to create and access Jupyter notebook instances that you can use to run the example in SageMaker, see -`Use Amazon SageMaker Notebook Instances `__. After you have created a notebook -instance and opened it, choose the SageMaker Examples tab to see a list of all of the SageMaker samples. To open a notebook, choose its -Use tab and choose Create copy. - -For detailed documentation, please refer to the `Sagemaker AutoGluon-Tabular Algorithm `__. diff --git a/doc/algorithms/tabular/catboost.rst b/doc/algorithms/tabular/catboost.rst deleted file mode 100644 index e7c72aa5c4..0000000000 --- a/doc/algorithms/tabular/catboost.rst +++ /dev/null @@ -1,37 +0,0 @@ -############ -CatBoost -############ - - -`CatBoost `__ is a popular and high-performance open-source implementation of the Gradient Boosting Decision Tree (GBDT) -algorithm. GBDT is a supervised learning algorithm that attempts to accurately predict a target variable by combining an ensemble of -estimates from a set of simpler and weaker models. - -CatBoost introduces two critical algorithmic advances to GBDT: - -* The implementation of ordered boosting, a permutation-driven alternative to the classic algorithm - -* An innovative algorithm for processing categorical features - -Both techniques were created to fight a prediction shift caused by a special kind of target leakage present in all currently existing -implementations of gradient boosting algorithms. - -The following table outlines a variety of sample notebooks that address different use cases of Amazon SageMaker CatBoost algorithm. - -.. list-table:: - :widths: 25 25 - :header-rows: 1 - - * - Notebook Title - - Description - * - `Tabular classification with Amazon SageMaker LightGBM and CatBoost algorithm `__ - - This notebook demonstrates the use of the Amazon SageMaker CatBoost algorithm to train and host a tabular classification model. - * - `Tabular regression with Amazon SageMaker LightGBM and CatBoost algorithm `__ - - This notebook demonstrates the use of the Amazon SageMaker CatBoost algorithm to train and host a tabular regression model. - -For instructions on how to create and access Jupyter notebook instances that you can use to run the example in SageMaker, see -`Use Amazon SageMaker Notebook Instances `__. After you have created a notebook -instance and opened it, choose the SageMaker Examples tab to see a list of all of the SageMaker samples. To open a notebook, choose its -Use tab and choose Create copy. - -For detailed documentation, please refer to the `Sagemaker CatBoost Algorithm `__. diff --git a/doc/algorithms/tabular/factorization_machines.rst b/doc/algorithms/tabular/factorization_machines.rst deleted file mode 100644 index 77997702bf..0000000000 --- a/doc/algorithms/tabular/factorization_machines.rst +++ /dev/null @@ -1,22 +0,0 @@ -Factorization Machines -------------------------- - -The Amazon SageMaker Factorization Machines algorithm. - -.. autoclass:: sagemaker.FactorizationMachines - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - :exclude-members: image_uri, num_factors, predictor_type, epochs, clip_gradient, mini_batch_size, feature_dim, eps, rescale_grad, bias_lr, linear_lr, factors_lr, bias_wd, linear_wd, factors_wd, bias_init_method, bias_init_scale, bias_init_sigma, bias_init_value, linear_init_method, linear_init_scale, linear_init_sigma, linear_init_value, factors_init_method, factors_init_scale, factors_init_sigma, factors_init_value - - -.. autoclass:: sagemaker.FactorizationMachinesModel - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.FactorizationMachinesPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/tabular/index.rst b/doc/algorithms/tabular/index.rst deleted file mode 100644 index b6924c86e7..0000000000 --- a/doc/algorithms/tabular/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -###################### -Tabular -###################### - -Amazon SageMaker provides built-in algorithms that are tailored to the analysis of tabular data. The built-in SageMaker algorithms for tabular data can be used for either classification or regression problems. - -.. toctree:: - :maxdepth: 2 - - autogluon - catboost - factorization_machines - knn - lightgbm - linear_learner - tabtransformer - xgboost diff --git a/doc/algorithms/tabular/knn.rst b/doc/algorithms/tabular/knn.rst deleted file mode 100644 index 89180ce3d8..0000000000 --- a/doc/algorithms/tabular/knn.rst +++ /dev/null @@ -1,22 +0,0 @@ -K-Nearest Neighbors -------------------- - -The Amazon SageMaker K-Nearest Neighbors (k-NN) algorithm. - -.. autoclass:: sagemaker.KNN - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - :exclude-members: image_uri, k, sample_size, predictor_type, dimension_reduction_target, dimension_reduction_type, - index_metric, index_type, faiss_index_ivf_nlists, faiss_index_pq_m - -.. autoclass:: sagemaker.KNNModel - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.KNNPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/tabular/lightgbm.rst b/doc/algorithms/tabular/lightgbm.rst deleted file mode 100644 index 176b10cdba..0000000000 --- a/doc/algorithms/tabular/lightgbm.rst +++ /dev/null @@ -1,28 +0,0 @@ -############ -LightGBM -############ - -`LightGBM `__ is a popular and efficient open-source implementation of the Gradient Boosting -Decision Tree (GBDT) algorithm. GBDT is a supervised learning algorithm that attempts to accurately predict a target variable by -combining an ensemble of estimates from a set of simpler and weaker models. LightGBM uses additional techniques to significantly improve -the efficiency and scalability of conventional GBDT. - -The following table outlines a variety of sample notebooks that address different use cases of Amazon SageMaker LightGBM algorithm. - -.. list-table:: - :widths: 25 25 - :header-rows: 1 - - * - Notebook Title - - Description - * - `Tabular classification with Amazon SageMaker LightGBM and CatBoost algorithm `__ - - This notebook demonstrates the use of the Amazon SageMaker LightGBM algorithm to train and host a tabular classification model. - * - `Tabular regression with Amazon SageMaker LightGBM and CatBoost algorithm `__ - - This notebook demonstrates the use of the Amazon SageMaker LightGBM algorithm to train and host a tabular regression model. - -For instructions on how to create and access Jupyter notebook instances that you can use to run the example in SageMaker, see -`Use Amazon SageMaker Notebook Instances `__. After you have created a notebook -instance and opened it, choose the SageMaker Examples tab to see a list of all of the SageMaker samples. To open a notebook, choose its -Use tab and choose Create copy. - -For detailed documentation, please refer to the `Sagemaker LightGBM Algorithm `__. diff --git a/doc/algorithms/tabular/linear_learner.rst b/doc/algorithms/tabular/linear_learner.rst deleted file mode 100644 index db9685d24f..0000000000 --- a/doc/algorithms/tabular/linear_learner.rst +++ /dev/null @@ -1,21 +0,0 @@ -LinearLearner --------------------- - -The Amazon SageMaker LinearLearner algorithm. - -.. autoclass:: sagemaker.LinearLearner - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - :exclude-members: image_uri, instance_count, instance_type, predictor_type, binary_classifier_model_selection_criteria, target_recall, target_precision, positive_example_weight_mult, epochs, use_bias, num_models, parameter, num_calibration_samples, calibration, init_method, init_scale, init_sigma, init_bias, optimizer, loss, wd, l1, momentum, learning_rate, beta_1, beta_2, bias_lr_mult, use_lr_scheduler, lr_scheduler_step, lr_scheduler_factor, lr_scheduler_minimum_lr, lr_scheduler_minimum_lr, mini_batch_size, feature_dim, bias_wd_mult, MAX_DEFAULT_BATCH_SIZE - -.. autoclass:: sagemaker.LinearLearnerModel - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.LinearLearnerPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/tabular/tabtransformer.rst b/doc/algorithms/tabular/tabtransformer.rst deleted file mode 100644 index facebfcd83..0000000000 --- a/doc/algorithms/tabular/tabtransformer.rst +++ /dev/null @@ -1,28 +0,0 @@ -############### -TabTransformer -############### - -`TabTransformer `__ is a novel deep tabular data modeling architecture for supervised learning. The TabTransformer architecture is built on self-attention-based Transformers. -The Transformer layers transform the embeddings of categorical features into robust contextual embeddings to achieve higher prediction accuracy. Furthermore, the contextual embeddings learned from TabTransformer -are highly robust against both missing and noisy data features, and provide better interpretability. - - -The following table outlines a variety of sample notebooks that address different use cases of Amazon SageMaker TabTransformer algorithm. - -.. list-table:: - :widths: 25 25 - :header-rows: 1 - - * - Notebook Title - - Description - * - `Tabular classification with Amazon SageMaker TabTransformer algorithm `__ - - This notebook demonstrates the use of the Amazon SageMaker TabTransformer algorithm to train and host a tabular classification model. - * - `Tabular regression with Amazon SageMaker TabTransformer algorithm `__ - - This notebook demonstrates the use of the Amazon SageMaker TabTransformer algorithm to train and host a tabular regression model. - -For instructions on how to create and access Jupyter notebook instances that you can use to run the example in SageMaker, see -`Use Amazon SageMaker Notebook Instances `__. After you have created a notebook -instance and opened it, choose the SageMaker Examples tab to see a list of all of the SageMaker samples. To open a notebook, choose its -Use tab and choose Create copy. - -For detailed documentation, please refer to the `Sagemaker TabTransformer Algorithm `__. diff --git a/doc/algorithms/tabular/xgboost.rst b/doc/algorithms/tabular/xgboost.rst deleted file mode 100644 index 829af00ac5..0000000000 --- a/doc/algorithms/tabular/xgboost.rst +++ /dev/null @@ -1,40 +0,0 @@ -############ -XGBoost -############ - -The `XGBoost `__ (eXtreme Gradient Boosting) is a popular and efficient open-source implementation of the gradient boosted trees algorithm. Gradient boosting is a supervised learning algorithm that attempts to accurately predict a target variable -by combining an ensemble of estimates from a set of simpler and weaker models. The XGBoost algorithm performs well in machine learning competitions because of its robust handling of a variety of data types, relationships, distributions, and the variety of hyperparameters that you can -fine-tune. You can use XGBoost for regression, classification (binary and multiclass), and ranking problems. - -You can use the new release of the XGBoost algorithm either as a Amazon SageMaker built-in algorithm or as a framework to run training scripts in your local environments. This implementation has a smaller memory footprint, better logging, improved hyperparameter validation, and -an expanded set of metrics than the original versions. It provides an XGBoost estimator that executes a training script in a managed XGBoost environment. The current release of SageMaker XGBoost is based on the original XGBoost versions 1.0, 1.2, 1.3, and 1.5. - -The following table outlines a variety of sample notebooks that address different use cases of Amazon SageMaker XGBoost algorithm. - -.. list-table:: - :widths: 25 25 - :header-rows: 1 - - * - Notebook Title - - Description - * - `How to Create a Custom XGBoost container? `__ - - This notebook shows you how to build a custom XGBoost Container with Amazon SageMaker Batch Transform. - * - `Regression with XGBoost using Parquet `__ - - This notebook shows you how to use the Abalone dataset in Parquet to train a XGBoost model. - * - `How to Train and Host a Multiclass Classification Model? `__ - - This notebook shows how to use the MNIST dataset to train and host a multiclass classification model. - * - `How to train a Model for Customer Churn Prediction? `__ - - This notebook shows you how to train a model to Predict Mobile Customer Departure in an effort to identify unhappy customers. - * - `An Introduction to Amazon SageMaker Managed Spot infrastructure for XGBoost Training `__ - - This notebook shows you how to use Spot Instances for training with a XGBoost Container. - * - `How to use Amazon SageMaker Debugger to debug XGBoost Training Jobs? `__ - - This notebook shows you how to use Amazon SageMaker Debugger to monitor training jobs to detect inconsistencies. - * - `How to use Amazon SageMaker Debugger to debug XGBoost Training Jobs in Real-Time? `__ - - This notebook shows you how to use the MNIST dataset and Amazon SageMaker Debugger to perform real-time analysis of XGBoost training jobs while training jobs are running. - -For instructions on how to create and access Jupyter notebook instances that you can use to run the example in SageMaker, see -`Use Amazon SageMaker Notebook Instances `__. After you have created a notebook -instance and opened it, choose the SageMaker Examples tab to see a list of all of the SageMaker samples. To open a notebook, choose its -Use tab and choose Create copy. - -For detailed documentation, please refer to the `Sagemaker XGBoost Algorithm `__. diff --git a/doc/algorithms/text/blazing_text.rst b/doc/algorithms/text/blazing_text.rst deleted file mode 100644 index e42f4a0cc2..0000000000 --- a/doc/algorithms/text/blazing_text.rst +++ /dev/null @@ -1,27 +0,0 @@ -############# -Blazing Text -############# - - -The Amazon SageMaker BlazingText algorithm provides highly optimized implementations of the Word2vec and text classification algorithms. The Word2vec algorithm is useful for many downstream natural language processing (NLP) -tasks, such as sentiment analysis, named entity recognition, machine translation, etc. Text classification is an important task for applications that perform web searches, information retrieval, ranking, and document classification. - -The Word2vec algorithm maps words to high-quality distributed vectors. The resulting vector representation of a word is called a word embedding. Words that are semantically similar correspond to vectors that are close together. -That way, word embeddings capture the semantic relationships between words. - -Many natural language processing (NLP) applications learn word embeddings by training on large collections of documents. These pretrained vector representations provide information about semantics and word distributions that -typically improves the generalizability of other models that are later trained on a more limited amount of data. Most implementations of the Word2vec algorithm are not optimized for multi-core CPU architectures. This makes it -difficult to scale to large datasets. - -With the BlazingText algorithm, you can scale to large datasets easily. Similar to Word2vec, it provides the Skip-gram and continuous bag-of-words (CBOW) training architectures. BlazingText's implementation of the supervised -multi-class, multi-label text classification algorithm extends the fastText text classifier to use GPU acceleration with custom `CUDA `__ - -kernels. You can train a model on more than a billion words in a couple of minutes using a multi-core CPU or a GPU. And, you achieve performance on par with the state-of-the-art deep learning text classification algorithms. - -The BlazingText algorithm is not parallelizable. For more information on parameters related to training, see `Docker Registry Paths for SageMaker Built-in Algorithms `__. - -For a sample notebook that uses the SageMaker BlazingText algorithm to train and deploy supervised binary and multiclass classification models, see -`Blazing Text classification on the DBPedia dataset `__. -For instructions for creating and accessing Jupyter notebook instances that you can use to run the example in SageMaker, see `Use Amazon SageMaker Notebook Instances `__. -After creating and opening a notebook instance, choose the SageMaker Examples tab to see a list of all the SageMaker examples. The topic modeling example notebooks that use the Blazing Text are located in the Introduction to Amazon -algorithms section. To open a notebook, choose its Use tab, then choose Create copy. diff --git a/doc/algorithms/text/index.rst b/doc/algorithms/text/index.rst deleted file mode 100644 index 3e59aac0f0..0000000000 --- a/doc/algorithms/text/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -###################### -Text -###################### - -Amazon SageMaker provides algorithms that are tailored to the analysis of textual documents used in natural language processing, document classification or summarization, topic modeling or classification, and language transcription or translation. - -.. toctree:: - :maxdepth: 2 - - blazing_text - lda - ntm - object2vec - sequence_to_sequence - text_classification_tensorflow - sentence_pair_classification_tensorflow - sentence_pair_classification_hugging_face - question_answering_pytorch - named_entity_recognition_hugging_face - text_summarization_hugging_face - text_generation_hugging_face - machine_translation_hugging_face diff --git a/doc/algorithms/text/lda.rst b/doc/algorithms/text/lda.rst deleted file mode 100644 index 394503b90b..0000000000 --- a/doc/algorithms/text/lda.rst +++ /dev/null @@ -1,22 +0,0 @@ -LDA --------------------- - -The Amazon SageMaker LDA algorithm. - -.. autoclass:: sagemaker.LDA - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - :exclude-members: image_uri, num_topics, alpha0, max_restarts, max_iterations, mini_batch_size, feature_dim, tol - - -.. autoclass:: sagemaker.LDAModel - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.LDAPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/text/machine_translation_hugging_face.rst b/doc/algorithms/text/machine_translation_hugging_face.rst deleted file mode 100644 index d533d0e64d..0000000000 --- a/doc/algorithms/text/machine_translation_hugging_face.rst +++ /dev/null @@ -1,10 +0,0 @@ -##################################### -Machine Translation - HuggingFace -##################################### - - -This is a supervised machine translation algorithm which supports many pre-trained models available in Hugging Face. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Machine Translation for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK `. diff --git a/doc/algorithms/text/named_entity_recognition_hugging_face.rst b/doc/algorithms/text/named_entity_recognition_hugging_face.rst deleted file mode 100644 index fc0fbd212c..0000000000 --- a/doc/algorithms/text/named_entity_recognition_hugging_face.rst +++ /dev/null @@ -1,10 +0,0 @@ -######################################## -Named Entity Recognition - HuggingFace -######################################## - -This is a supervised named entity recognition algorithm which supports fine-tuning of many pre-trained models available in Hugging Face. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Named Entity Recognition for using these algorithms. - -For detailed documentation please refer `Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK `__ - diff --git a/doc/algorithms/text/ntm.rst b/doc/algorithms/text/ntm.rst deleted file mode 100644 index 2d72cda2b2..0000000000 --- a/doc/algorithms/text/ntm.rst +++ /dev/null @@ -1,23 +0,0 @@ -NTM ---- - -The Amazon SageMaker NTM algorithm. - -.. autoclass:: sagemaker.NTM - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - :exclude-members: image_uri, num_topics, encoder_layers, epochs, encoder_layers_activation, optimizer, tolerance, - num_patience_epochs, batch_norm, rescale_gradient, clip_gradient, weight_decay, learning_rate - - -.. autoclass:: sagemaker.NTMModel - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.NTMPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/text/object2vec.rst b/doc/algorithms/text/object2vec.rst deleted file mode 100644 index 102db5ee5d..0000000000 --- a/doc/algorithms/text/object2vec.rst +++ /dev/null @@ -1,21 +0,0 @@ -Object2Vec ----------- - -The Amazon SageMaker Object2Vec algorithm. - -.. autoclass:: sagemaker.Object2Vec - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - :exclude-members: image_uri, enc_dim, mini_batch_size, epochs, early_stopping_patience, early_stopping_tolerance, - dropout, weight_decay, bucket_width, num_classes, mlp_layers, mlp_dim, mlp_activation, - output_layer, optimizer, learning_rate, enc0_network, enc1_network, enc0_cnn_filter_width, - enc1_cnn_filter_width, enc0_max_seq_len, enc1_max_seq_len, enc0_token_embedding_dim, - enc1_token_embedding_dim, enc0_vocab_size, enc1_vocab_size, enc0_layers, enc1_layers, - enc0_freeze_pretrained_embedding, enc1_freeze_pretrained_embedding - -.. autoclass:: sagemaker.Object2VecModel - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/text/question_answering_pytorch.rst b/doc/algorithms/text/question_answering_pytorch.rst deleted file mode 100644 index 9d9d74ccb1..0000000000 --- a/doc/algorithms/text/question_answering_pytorch.rst +++ /dev/null @@ -1,9 +0,0 @@ -##################################### -Question Answering - PyTorch -##################################### - -This is a supervised question answering algorithm which supports fine-tuning of many pre-trained models available in Hugging Face. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Question Answering for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/text/sentence_pair_classification_hugging_face.rst b/doc/algorithms/text/sentence_pair_classification_hugging_face.rst deleted file mode 100644 index 2892b9d516..0000000000 --- a/doc/algorithms/text/sentence_pair_classification_hugging_face.rst +++ /dev/null @@ -1,9 +0,0 @@ -############################################ -Sentence Pair Classification - HuggingFace -############################################ - -This is a supervised sentence pair classification algorithm which supports fine-tuning of many pre-trained models available in Hugging Face. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Sentence Pair Classification for using these algorithms. - -For detailed documentation please refer `Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK `__ diff --git a/doc/algorithms/text/sentence_pair_classification_tensorflow.rst b/doc/algorithms/text/sentence_pair_classification_tensorflow.rst deleted file mode 100644 index 80264e84f3..0000000000 --- a/doc/algorithms/text/sentence_pair_classification_tensorflow.rst +++ /dev/null @@ -1,9 +0,0 @@ -############################################ -Sentence Pair Classification - TensorFlow -############################################ - -This is a supervised sentence pair classification algorithm which supports fine-tuning of many pre-trained models available in Tensorflow Hub. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Sentence Pair Classification for using these algorithms. - -For detailed documentation please refer `Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK `__ diff --git a/doc/algorithms/text/sequence_to_sequence.rst b/doc/algorithms/text/sequence_to_sequence.rst deleted file mode 100644 index 00d9302a01..0000000000 --- a/doc/algorithms/text/sequence_to_sequence.rst +++ /dev/null @@ -1,14 +0,0 @@ -####################### -Sequence-to-Sequence -####################### - -Amazon SageMaker Sequence to Sequence is a supervised learning algorithm where the input is a sequence of tokens (for example, text, audio) and the output generated is another sequence of tokens. Example applications include: machine -translation (input a sentence from one language and predict what that sentence would be in another language), text summarization (input a longer string of words and predict a shorter string of words that is a summary), speech-to-text -(audio clips converted into output sentences in tokens). Recently, problems in this domain have been successfully modeled with deep neural networks that show a significant performance boost over previous methodologies. Amazon SageMaker -seq2seq uses Recurrent Neural Networks (RNNs) and Convolutional Neural Network (CNN) models with attention as encoder-decoder architectures. - -For a sample notebook that shows how to use the SageMaker Sequence to Sequence algorithm to train a English-German translation model, see -`Machine Translation English-German Example Using SageMaker Seq2Seq `__. -For instructions how to create and access Jupyter notebook instances that you can use to run the example in SageMaker, see `Use Amazon SageMaker Notebook Instances `__. Once you have -created a notebook instance and opened it, select the SageMaker Examples tab to see a list of all the SageMaker samples. The topic modeling example notebooks using the NTM algorithms are located in the Introduction to Amazon algorithms section. -To open a notebook, click on its Use tab and select Create copy. diff --git a/doc/algorithms/text/text_classification_tensorflow.rst b/doc/algorithms/text/text_classification_tensorflow.rst deleted file mode 100644 index c60a5b3e1c..0000000000 --- a/doc/algorithms/text/text_classification_tensorflow.rst +++ /dev/null @@ -1,9 +0,0 @@ -################################## -Text Classification - TensorFlow -################################## - -This is a supervised text classification algorithm which supports fine-tuning of many pre-trained models available in Tensorflow Hub. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Text Classification for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/text/text_generation_hugging_face.rst b/doc/algorithms/text/text_generation_hugging_face.rst deleted file mode 100644 index 30fae26196..0000000000 --- a/doc/algorithms/text/text_generation_hugging_face.rst +++ /dev/null @@ -1,9 +0,0 @@ -############################################ -Text Generation - HuggingFace -############################################ - -This is a supervised text generation algorithm which supports many pre-trained models available in Hugging Face. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Text Generation for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/text/text_summarization_hugging_face.rst b/doc/algorithms/text/text_summarization_hugging_face.rst deleted file mode 100644 index 206c880ba3..0000000000 --- a/doc/algorithms/text/text_summarization_hugging_face.rst +++ /dev/null @@ -1,9 +0,0 @@ -############################################ -Text Summarization - HuggingFace -############################################ - -This is a supervised text summarization algorithm which supports many pre-trained models available in Hugging Face. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Text Summarization for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/time_series/deep_ar.rst b/doc/algorithms/time_series/deep_ar.rst deleted file mode 100644 index c373cb7405..0000000000 --- a/doc/algorithms/time_series/deep_ar.rst +++ /dev/null @@ -1,11 +0,0 @@ -################################## -Deep AR Forecasting -################################## - -The Amazon SageMaker DeepAR forecasting algorithm is a supervised learning algorithm for forecasting scalar (one-dimensional) time series using recurrent neural networks (RNN). Classical forecasting methods, such as autoregressive integrated moving average (ARIMA) or exponential smoothing (ETS), fit a single model to each individual time series. They then use that model to extrapolate the time series into the future. - -In many applications, however, you have many similar time series across a set of cross-sectional units. For example, you might have time series groupings for demand for different products, server loads, and requests for webpages. For this type of application, you can benefit from training a single model jointly over all of the time series. DeepAR takes this approach. When your dataset contains hundreds of related time series, DeepAR outperforms the standard ARIMA and ETS methods. You can also use the trained model to generate forecasts for new time series that are similar to the ones it has been trained on. - -The training input for the DeepAR algorithm is one or, preferably, more target time series that have been generated by the same process or similar processes. Based on this input dataset, the algorithm trains a model that learns an approximation of this process/processes and uses it to predict how the target time series evolves. Each target time series can be optionally associated with a vector of static (time-independent) categorical features provided by the cat field and a vector of dynamic (time-dependent) time series provided by the dynamic_feat field. SageMaker trains the DeepAR model by randomly sampling training examples from each target time series in the training dataset. Each training example consists of a pair of adjacent context and prediction windows with fixed predefined lengths. To control how far in the past the network can see, use the context_length hyperparameter. To control how far in the future predictions can be made, use the prediction_length hyperparameter. For more information, see `How the DeepAR Algorithm Works `__. - -For a sample notebook that shows how to prepare a time series dataset for training the SageMaker DeepAR algorithm and how to deploy the trained model for performing inferences, see `Time series forecasting with DeepAR - Synthetic data `__ as well as `DeepAR demo on electricity dataset `__, which illustrates the advanced features of DeepAR on a real world dataset. For instructions on creating and accessing Jupyter notebook instances that you can use to run the example in SageMaker, see `Use Amazon SageMaker Notebook Instances `__. After creating and opening a notebook instance, choose the SageMaker Examples tab to see a list of all of the SageMaker examples. To open a notebook, choose its Use tab, and choose Create copy. diff --git a/doc/algorithms/time_series/index.rst b/doc/algorithms/time_series/index.rst deleted file mode 100644 index 05d2464ccd..0000000000 --- a/doc/algorithms/time_series/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -###################### -Time-series -###################### - -Amazon SageMaker provides algorithms that are tailored to the analysis of textual documents used in natural language processing, document classification or summarization, topic modeling or classification, and language transcription or translation. - -.. toctree:: - :maxdepth: 2 - - deep_ar diff --git a/doc/algorithms/unsupervised/index.rst b/doc/algorithms/unsupervised/index.rst deleted file mode 100644 index a3e6af9801..0000000000 --- a/doc/algorithms/unsupervised/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -###################### -Unsupervised -###################### - -Amazon SageMaker provides several built-in algorithms that can be used for a variety of unsupervised learning tasks such as clustering, dimension reduction, pattern recognition, and anomaly detection. - -.. toctree:: - :maxdepth: 2 - - ipinsights - kmeans - pca - randomcutforest diff --git a/doc/algorithms/unsupervised/ipinsights.rst b/doc/algorithms/unsupervised/ipinsights.rst deleted file mode 100644 index f3aa8ac437..0000000000 --- a/doc/algorithms/unsupervised/ipinsights.rst +++ /dev/null @@ -1,22 +0,0 @@ -IP Insights ------------ - -The Amazon SageMaker IP Insights algorithm. - -.. autoclass:: sagemaker.IPInsights - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - :exclude-members: image_uri, num_entity_vectors, vector_dim, batch_metrics_publish_interval, epochs, learning_rate, - num_ip_encoder_layers, random_negative_sampling_rate, shuffled_negative_sampling_rate, weight_decay - -.. autoclass:: sagemaker.IPInsightsModel - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.IPInsightsPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/unsupervised/kmeans.rst b/doc/algorithms/unsupervised/kmeans.rst deleted file mode 100644 index bcf2b221bf..0000000000 --- a/doc/algorithms/unsupervised/kmeans.rst +++ /dev/null @@ -1,21 +0,0 @@ -K-means --------------------- - -The Amazon SageMaker K-means algorithm. - -.. autoclass:: sagemaker.KMeans - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - :exclude-members: image_uri, k, init_method, max_iterations, tol, num_trials, local_init_method, half_life_time_size, epochs, center_factor, mini_batch_size, feature_dim, MAX_DEFAULT_BATCH_SIZE - -.. autoclass:: sagemaker.KMeansModel - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.KMeansPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/unsupervised/pca.rst b/doc/algorithms/unsupervised/pca.rst deleted file mode 100644 index 68a5db29f3..0000000000 --- a/doc/algorithms/unsupervised/pca.rst +++ /dev/null @@ -1,22 +0,0 @@ -PCA --------------------- - -The Amazon SageMaker PCA algorithm. - -.. autoclass:: sagemaker.PCA - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - :exclude-members: image_uri, num_components, algorithm_mode, subtract_mean, extra_components, mini_batch_size, feature_dim, MAX_DEFAULT_BATCH_SIZE - - -.. autoclass:: sagemaker.PCAModel - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.PCAPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/unsupervised/randomcutforest.rst b/doc/algorithms/unsupervised/randomcutforest.rst deleted file mode 100644 index b723319a52..0000000000 --- a/doc/algorithms/unsupervised/randomcutforest.rst +++ /dev/null @@ -1,22 +0,0 @@ -Random Cut Forest ------------------ - -The Amazon SageMaker Random Cut Forest algorithm. - -.. autoclass:: sagemaker.RandomCutForest - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - :exclude-members: image_uri, num_trees, num_samples_per_tree, eval_metrics, feature_dim, MINI_BATCH_SIZE - - -.. autoclass:: sagemaker.RandomCutForestModel - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.RandomCutForestPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/algorithms/vision/image_classification_mxnet.rst b/doc/algorithms/vision/image_classification_mxnet.rst deleted file mode 100644 index 1550a6026c..0000000000 --- a/doc/algorithms/vision/image_classification_mxnet.rst +++ /dev/null @@ -1,18 +0,0 @@ -############################# -Image Classification - MxNet -############################# - -The Amazon SageMaker image classification algorithm is a supervised learning algorithm that supports multi-label classification. It takes an image as input and outputs one or more labels assigned to that image. -It uses a convolutional neural network that can be trained from scratch or trained using transfer learning when a large number of training images are not available. - -The recommended input format for the Amazon SageMaker image classification algorithms is Apache MXNet `RecordIO `__. -However, you can also use raw images in .jpg or .png format. Refer to `this discussion `__ for a broad overview of efficient -data preparation and loading for machine learning systems. - -For a sample notebook that uses the SageMaker image classification algorithm to train a model on the caltech-256 dataset and then to deploy it to perform inferences, see the -`End-to-End Multiclass Image Classification Example `__. -For instructions how to create and access Jupyter notebook instances that you can use to run the example in SageMaker, see `Use Amazon SageMaker Notebook Instances `__. -Once you have created a notebook instance and opened it, select the SageMaker Examples tab to see a list of all the SageMaker samples. The example image classification notebooks are located in the Introduction to Amazon -algorithms section. To open a notebook, click on its Use tab and select Create copy. - -For detailed documentation, please refer to the `Sagemaker Image Classification Algorithm `__ diff --git a/doc/algorithms/vision/image_classification_pytorch.rst b/doc/algorithms/vision/image_classification_pytorch.rst deleted file mode 100644 index 3c154c6cfe..0000000000 --- a/doc/algorithms/vision/image_classification_pytorch.rst +++ /dev/null @@ -1,9 +0,0 @@ -############################### -Image Classification - PyTorch -############################### - -This is a supervised image clasification algorithm which supports fine-tuning of many pre-trained models available in Pytorch Hub. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Image Classification for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/vision/image_classification_tensorflow.rst b/doc/algorithms/vision/image_classification_tensorflow.rst deleted file mode 100644 index e49820ee50..0000000000 --- a/doc/algorithms/vision/image_classification_tensorflow.rst +++ /dev/null @@ -1,9 +0,0 @@ -################################## -Image Classification - TensorFlow -################################## - -This is a supervised image clasification algorithm which supports fine-tuning of many pre-trained models available in Tensorflow Hub. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Image Classification for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/vision/image_embedding_tensorflow.rst b/doc/algorithms/vision/image_embedding_tensorflow.rst deleted file mode 100644 index 0938377354..0000000000 --- a/doc/algorithms/vision/image_embedding_tensorflow.rst +++ /dev/null @@ -1,9 +0,0 @@ -############################# -Image Embedding - TensorFlow -############################# - -This is a supervised image embedding algorithm which supports many pre-trained models available in Tensorflow Hub. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Image Embedding for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/vision/index.rst b/doc/algorithms/vision/index.rst deleted file mode 100644 index c17871d8f3..0000000000 --- a/doc/algorithms/vision/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -###################### -Vision -###################### - -Amazon SageMaker provides image processing algorithms that are used for image classification, object detection, and computer vision. - -.. toctree:: - :maxdepth: 2 - - image_classification_tensorflow - image_classification_pytorch - image_classification_mxnet - image_embedding_tensorflow - instance_segmentation_mxnet - object_detection_tensorflow - object_detection_pytorch - object_detection_mxnet_gluoncv - object_detection_mxnet - semantic_segmentation_mxnet_gluoncv - semantic_segmentation_mxnet - text_embedding_tensorflow_mxnet diff --git a/doc/algorithms/vision/instance_segmentation_mxnet.rst b/doc/algorithms/vision/instance_segmentation_mxnet.rst deleted file mode 100644 index a38611bc9a..0000000000 --- a/doc/algorithms/vision/instance_segmentation_mxnet.rst +++ /dev/null @@ -1,9 +0,0 @@ -############################## -Instance Segmentation - MXNet -############################## - -This is a supervised image segmentation algorithm which supports many pre-trained models available in MXNet. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Image Segmentation for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/vision/object_detection_mxnet.rst b/doc/algorithms/vision/object_detection_mxnet.rst deleted file mode 100644 index 9ce52f992b..0000000000 --- a/doc/algorithms/vision/object_detection_mxnet.rst +++ /dev/null @@ -1,9 +0,0 @@ -########################## -Object Detection - MxNet -########################## - -This is a supervised object detection algorithm which supports fine-tuning of many pre-trained models available in MXNet. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Object Detection for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/vision/object_detection_mxnet_gluoncv.rst b/doc/algorithms/vision/object_detection_mxnet_gluoncv.rst deleted file mode 100644 index 857360b68e..0000000000 --- a/doc/algorithms/vision/object_detection_mxnet_gluoncv.rst +++ /dev/null @@ -1,19 +0,0 @@ -################################## -Object Detection - MxNet GluonCV -################################## - - -The Amazon SageMaker Object Detection algorithm detects and classifies objects in images using a single deep neural network. -It is a supervised learning algorithm that takes images as input and identifies all instances of objects within the image scene. -The object is categorized into one of the classes in a specified collection with a confidence score that it belongs to the class. -Its location and scale in the image are indicated by a rectangular bounding box. It uses the `Single Shot multibox Detector (SSD) `__ -framework and supports two base networks: `VGG `__ and `ResNet `__. The network can be trained from scratch, -or trained with models that have been pre-trained on the `ImageNet `__ dataset. - -For a sample notebook that shows how to use the SageMaker Object Detection algorithm to train and host a model on the `Caltech Birds (CUB 200 2011) `__ -dataset using the Single Shot multibox Detector algorithm, see `Amazon SageMaker Object Detection for Bird Species `__. -For instructions how to create and access Jupyter notebook instances that you can use to run the example in SageMaker, see `Use Amazon SageMaker Notebook Instances `__. -Once you have created a notebook instance and opened it, select the SageMaker Examples tab to see a list of all the SageMaker samples. The object detection example notebook using the Object Detection -algorithm is located in the Introduction to Amazon Algorithms section. To open a notebook, click on its Use tab and select Create copy. - -For detailed documentation, please refer to the `Sagemaker Object Detection Algorithm `__ diff --git a/doc/algorithms/vision/object_detection_pytorch.rst b/doc/algorithms/vision/object_detection_pytorch.rst deleted file mode 100644 index aa703e74b5..0000000000 --- a/doc/algorithms/vision/object_detection_pytorch.rst +++ /dev/null @@ -1,9 +0,0 @@ -########################### -Object Detection - PyTorch -########################### - -This is a supervised object detection algorithm which supports fine-tuning of many pre-trained models available in Pytorch Hub. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Object Detection for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/vision/object_detection_tensorflow.rst b/doc/algorithms/vision/object_detection_tensorflow.rst deleted file mode 100644 index 2536322847..0000000000 --- a/doc/algorithms/vision/object_detection_tensorflow.rst +++ /dev/null @@ -1,9 +0,0 @@ -############################### -Object Detection - TensorFlow -############################### - -This is a supervised object detection algorithm which supports fine-tuning of many pre-trained models available in Tensorflow Hub. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Object Detection for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/vision/semantic_segmentation_mxnet.rst b/doc/algorithms/vision/semantic_segmentation_mxnet.rst deleted file mode 100644 index b0c60cd560..0000000000 --- a/doc/algorithms/vision/semantic_segmentation_mxnet.rst +++ /dev/null @@ -1,9 +0,0 @@ -############################## -Semantic Segmentation - MxNet -############################## - -This is a supervised semantic segmentation algorithm which supports fine-tuning of many pre-trained models available in MXNet. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Semantic Segmentation for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/algorithms/vision/semantic_segmentation_mxnet_gluoncv.rst b/doc/algorithms/vision/semantic_segmentation_mxnet_gluoncv.rst deleted file mode 100644 index 53e532f6ea..0000000000 --- a/doc/algorithms/vision/semantic_segmentation_mxnet_gluoncv.rst +++ /dev/null @@ -1,43 +0,0 @@ -##################################### -Semantic Segmentation - MxNet GluonCV -##################################### - -The SageMaker semantic segmentation algorithm provides a fine-grained, pixel-level approach to developing computer vision applications. -It tags every pixel in an image with a class label from a predefined set of classes. Tagging is fundamental for understanding scenes, which is -critical to an increasing number of computer vision applications, such as self-driving vehicles, medical imaging diagnostics, and robot sensing. - -For comparison, the `SageMaker Image Classification Algorithm `__ is a -supervised learning algorithm that analyzes only whole images, classifying them into one of multiple output categories. The -`Object Detection Algorithm `__ is a supervised learning algorithm that detects and -classifies all instances of an object in an image. It indicates the location and scale of each object in the image with a rectangular bounding box. - -Because the semantic segmentation algorithm classifies every pixel in an image, it also provides information about the shapes of the objects contained in the image. -The segmentation output is represented as a grayscale image, called a segmentation mask. A segmentation mask is a grayscale image with the same shape as the input image. - -The SageMaker semantic segmentation algorithm is built using the `MXNet Gluon framework and the Gluon CV toolkit `__ -. It provides you with a choice of three built-in algorithms to train a deep neural network. You can use the `Fully-Convolutional Network (FCN) algorithm `__ , -`Pyramid Scene Parsing (PSP) algorithm `__, or `DeepLabV3 `__. - - -Each of the three algorithms has two distinct components: - -* The backbone (or encoder)—A network that produces reliable activation maps of features. - -* The decoder—A network that constructs the segmentation mask from the encoded activation maps. - -You also have a choice of backbones for the FCN, PSP, and DeepLabV3 algorithms: `ResNet50 or ResNet101 `__. -These backbones include pretrained artifacts that were originally trained on the `ImageNet `__ classification task. You can fine-tune these backbones -for segmentation using your own data. Or, you can initialize and train these networks from scratch using only your own data. The decoders are never pretrained. - -To deploy the trained model for inference, use the SageMaker hosting service. During inference, you can request the segmentation mask either as a -PNG image or as a set of probabilities for each class for each pixel. You can use these masks as part of a larger pipeline that includes additional downstream image processing or other applications. - - -For a sample Jupyter notebook that uses the SageMaker semantic segmentation algorithm to train a model and deploy it to perform inferences, see the -`Semantic Segmentation Example `__. For instructions -on how to create and access Jupyter notebook instances that you can use to run the example in SageMaker, see `Use Amazon SageMaker Notebook Instances `__. - -To see a list of all of the SageMaker samples, create and open a notebook instance, and choose the SageMaker Examples tab. The example semantic segmentation notebooks are located under -Introduction to Amazon algorithms. To open a notebook, choose its Use tab, and choose Create copy. - -For detailed documentation, please refer to the `Sagemaker Semantic Segmentation Algorithm `__ diff --git a/doc/algorithms/vision/text_embedding_tensorflow_mxnet.rst b/doc/algorithms/vision/text_embedding_tensorflow_mxnet.rst deleted file mode 100644 index d015c2ef30..0000000000 --- a/doc/algorithms/vision/text_embedding_tensorflow_mxnet.rst +++ /dev/null @@ -1,9 +0,0 @@ -#################################### -Text Embedding - TensorFlow, MxNet -#################################### - -This is a supervised text embedding algorithm which supports many pre-trained models available in MXNet and Tensorflow Hub. The following -`sample notebook `__ -demonstrates how to use the Sagemaker Python SDK for Text Embedding for using these algorithms. - -For detailed documentation please refer :ref:`Use Built-in Algorithms with Pre-trained Models in SageMaker Python SDK ` diff --git a/doc/amazon_sagemaker_debugger.rst b/doc/amazon_sagemaker_debugger.rst deleted file mode 100644 index 2066aaf524..0000000000 --- a/doc/amazon_sagemaker_debugger.rst +++ /dev/null @@ -1,420 +0,0 @@ - -######################### -Amazon SageMaker Debugger -######################### - - -.. warning:: - - This page is no longer supported for maintenence. The live documentation is at `Debug and Profile Training Jobs Using Amazon SageMaker Debugger `_ - and `Debugger API `_. - - -Amazon SageMaker Debugger allows you to detect anomalies while training your machine learning model by emitting relevant data during training, storing the data and then analyzing it. - -.. contents:: - -Background -========== - -Amazon SageMaker provides every developer and data scientist with the ability to build, train, and deploy machine learning models quickly. Amazon SageMaker is a fully-managed service that encompasses the entire machine learning workflow. You can label and prepare your data, choose an algorithm, train a model, and then tune and optimize it for deployment. You can deploy your models to production with Amazon SageMaker to make predictions at lower costs than was previously possible. - -`SageMaker Debugger `__ provides a way to hook into the training process and emit debug artifacts (a.k.a. "tensors") that represent the training state at each point in the training lifecycle. Debugger then stores the data in real time and uses rules that encapsulate logic to analyze tensors and react to anomalies. Debugger provides built-in rules and allows you to write custom rules for analysis. - -Setup -===== - -To get started, you must satisfy the following prerequisites: - -* Specify an AWS Region where you'll train your model. -* Give Amazon SageMaker the access to your data in Amazon Simple Storage Service (Amazon S3) needed to train your model by creating an IAM role ARN. See the `AWS IAM documentation `__ for how to fine tune the permissions needed. - -Capture real-time debugging data during model training in Amazon SageMaker -========================================================================== - -To enable data emission for debugging model training, Amazon SageMaker initializes a "hook" which attaches itself to the training process and emits data necessary for debugging, i.e. tensors. To provide the hook's configuration, specify the option called ``DebuggerHookConfig`` when training your model. For more about the ``DebuggerHookConfig`` object, see the `API documentation `__. - -The ``DebuggerHookConfig`` accepts one or more objects of type ``CollectionConfig``, which defines the configuration around the tensor collection you intend to emit and save during model training. The concept of a "collection" helps group tensors for easier handling. - -.. code:: python - - from sagemaker.debugger import CollectionConfig, DebuggerHookConfig - - collection_config = CollectionConfig( - name='collection_name', - parameters={ - 'key': 'value' - } - ) - - debugger_hook_config = DebuggerHookConfig( - s3_output_path='s3://path/for/data/emission', - container_local_output_path='/local/path/for/data/emission', - hook_parameters={ - 'key': 'value' - }, - collection_configs=[ - collection_config - ] - ) - - estimator = TensorFlow( - role=role, - instance_count=1, - instance_type=instance_type, - debugger_hook_config=debugger_hook_config - ) - -Specifying configurations for collections ------------------------------------------ - -Collection Name -~~~~~~~~~~~~~~~ - -``name`` in ``CollectionConfig`` is used to specify the name of the tensor collection you wish to emit and store. This name is used by SageMaker Debugger to refer to all the tensors in this collection. You can supply any valid string for the collection name. In addition, there are "built-in" collections, whose names are recognized by the hook, that you can emit simply by specifying their names. Examples of these collections are "gradients", "weights", "biases", etc. A full list is available at `SageMaker Debugger Built-in Collections `__. - -To emit and store one of the built-in collections: - -.. code:: python - - collection_config_biases = CollectionConfig(name='biases') - -Collection Parameters -~~~~~~~~~~~~~~~~~~~~~ - -To specify additional configuration for a particular collection, use ``parameters`` in the ``CollectionConfig``. This parameter provides a mapping that defines what group of tensors are saved and how frequently they are to be saved. - -For instance, suppose you want to save a collection of tensors with the following properties: - -========================================================= ========= -**Desired Property** **Value** ---------------------------------------------------------- --------- -regex of tensors which should be saved ``relu`` -step frequency at which the said tensors should be saved 20 -starting at step 5 -ending at step 100 -========================================================= ========= - -You should configure the ``CollectionConfig`` as: - -.. code:: python - - collection_config_for_relu = CollectionConfig( - name='custom_relu_collection', - parameters={ - 'include_regex': 'relu', - 'save_interval': '20', - 'start_step': '5', - 'end_step': '100' - } - } - -The possible values of ``parameters`` in ``CollectionConfig`` can be viewed at `CollectionParameters `__. - -Hook Parameters -~~~~~~~~~~~~~~~ - -To apply properties across all collections, use ``hook_parameters`` within the ``DebuggerHookConfig`` object. For example, to apply a value of ``10`` for ``save_interval`` across all collections: - -.. code:: python - - from sagemaker.debugger import CollectionConfig, DebuggerHookConfig - - collection_config_1 = CollectionConfig( - name='collection_name_1', - parameters={ - 'include_regex': '.*' - } - ) - collection_config_2 = CollectionConfig( - name='collection_name_2', - parameters={ - 'include_regex': '.*' - } - } - - debugger_hook_config = DebuggerHookConfig( - s3_output_path='s3://path/for/data/emission', - container_local_output_path='/local/path/for/data/emission', - hook_parameters={ - 'save_interval': '10' - }, - collection_configs=[ - collection_config_1, collection_config_2 - ] - ) - -In the above sample code, the ``save_interval`` of ``10`` will be applied for storing both collections. - -Note that the ``save_interval`` value set in the ``collection_parameters`` will override the value for ``save_interval`` in the ``hook_parameters``. For example, in the above sample code, if ``collection_config_2`` had a ``save_interval`` value set to ``20``, then the tensors for that collection would be saved with step interval ``20`` while those for ``collection_config_1`` would still be saved with a step interval of ``10``. This holds true for any parameters common in ``hook_parameters`` and ``parameters`` in ``CollectionConfig``. - -The possible values of ``hook_parameters`` in ``DebuggerHookConfig`` can be viewed at `SageMaker Debugger Hook `__. - -Begin model training --------------------- - -To create a training job that initializes the debugging hook with the value of the ``DebuggerHookConfig`` object, call ``fit()`` on the ``estimator``. The hook starts emitting the relevant debugging data, i.e. the tensor collections, in real time and stores the data locally in the local path provided in ``DebuggerHookConfig``. This data is then uploaded in near real time to an S3 path derived from the path provided in the hook configuration. - -.. code:: - - s3://{destination-bucket-prefix}/{training-job-name}/debug-output/ - -The path is derived from the value of ``s3_output_path``, and not used verbatim, to ensure that artifacts from different training jobs are placed in different Amazon S3 paths. To enable correct analyses of different training jobs, it is essential to keep the debug artifacts from these jobs separate. - -To access the above Amazon S3 path through the estimator object, you can use the following command: - -.. code:: python - - tensors_s3_output_path = estimator.latest_job_debugger_artifacts_path() - -You can use the ``S3Downloader`` utility to view and download the debugging data emitted during training in Amazon S3. (Note that data is stored in a streaming fashion so the data you download locally through ``S3Downloader`` will be a snapshot of the data generated until that time.) Here is the code: - -.. code:: python - - from sagemaker.s3 import S3Downloader - - # Start the training by calling fit - # Setting the wait to `False` would make the fit asynchronous - estimator.fit(wait=False) - - # Get a list of S3 URIs - S3Downloader.list(estimator.latest_job_debugger_artifacts_path()) - -Continuous analyses through rules -================================= - -In addition to collecting the debugging data, Amazon SageMaker Debugger provides the capability for you to analyze it in a streaming fashion using "rules". A SageMaker Debugger "rule" is a piece of code which encapsulates the logic for analyzing debugging data. - -SageMaker Debugger provides a set of built-in rules curated by data scientists and engineers at Amazon to identify common problems while training machine learning models. There is also support for using custom rule source codes for evaluation. In the following sections, you'll learn how to use both the built-in and custom rules while training your model. - -Relationship between debugger hook and rules --------------------------------------------- - -Using SageMaker Debugger is, broadly, a two-pronged approach. On one hand you have the production of debugging data, which is done through the Debugger Hook, and on the other hand you have the consumption of this data, which can be with rules (for continuous analyses) or by using the SageMaker Debugger SDK (for interactive analyses). - -The production and consumption of data are defined independently. For example, you could configure the debugging hook to store only the collection "gradients" and then configure the rules to operate on some other collection, say, "weights". While this is possible, it's quite useless as it gives you no meaningful insight into the training process. This is because the rule will do nothing in this example scenario since it will wait for the tensors in the collection "gradients" which are never be emitted. - -For more useful and efficient debugging, configure your debugging hook to produce and store the debugging data that you care about and employ rules that operate on that particular data. This way, you ensure that the Debugger is utilized to its maximum potential in detecting anomalies. In this sense, there is a loose binding between the hook and the rules. - -Normally, you'd achieve this binding for a training job by providing values for both ``debugger_hook_config`` and ``rules`` in your estimator. However, SageMaker Debugger simplifies this by allowing you to specify the collection configuration within the ``Rule`` object itself. This way, you don't have to specify the ``debugger_hook_config`` in your estimator separately. - -Using built-in rules --------------------- - -SageMaker Debugger comes with a set of built-in rules which can be used to identify common problems in model training, for example vanishing gradients or exploding tensors. You can choose to evaluate one or more of these rules while training your model to obtain meaningful insight into the training process. To learn more about these built in rules, see `SageMaker Debugger Built-in Rules `__. - -Pre-defined debugger hook configuration for built-in rules -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As mentioned earlier, for efficient analyses, it's important that the debugging data that is emitted by the hook is relevant to the rules used to operate and analyze the data. For example, if the hook is configured to emit the collection "weights", you should evaluate a rule that operates on this collection and not some other collection. - -Determining the types of data to emit for debugging with the built-in rules during the model training can be tricky. To guide you in this choice, Amazon SageMaker provides you with predefined collection configurations best suited for each of the built-in rules. So when you use built-in Debugger rules, you just need to specify the names of the built-in rule and SageMaker Debugger configures the collection(s) to emit that the rules need to operate on. To learn more about the mapping of each rule to the appropriate collection configuration, see `Amazon SageMaker Debugger Rules Config `__. - -Sample Usages -~~~~~~~~~~~~~ - -**Example 1**: Using a single built-in rule without any customization. - -.. code:: python - - from sagemaker.debugger import Rule - from smdebug_rulesconfig import vanishing_gradient - - estimator = TensorFlow( - role=role, - instance_count=1, - instance_type=instance_type, - rules=[Rule.sagemaker(vanishing_gradient())] - ) - - -In the example above, Amazon SageMaker pulls the collection configuration best suited for the built-in rule Vanishing Gradient from `SageMaker Debugger Rules Config `__ and configures the debugging data to be stored in the manner specified in the configuration. - -**Example 2**: Using more than one built-in rules without any customization. - -.. code:: python - - from sagemaker.debugger import Rule - from smdebug_rulesconfig import vanishing_gradient, weight_update_ratio - - estimator = TensorFlow( - role=role, - instance_count=1, - instance_type=instance_type, - rules=[Rule.sagemaker(vanishing_gradient()), Rule.sagemaker(weight_update_ratio())] - ) - -In the example above, Amazon SageMaker pulls the hook configurations for Vanishing Gradient and Weight Update Ratio rules from `SageMaker Debugger Rules Config `__ and configures the collections to be stored in the manner specified in each configuration. - -**Example 3**: Using a built-in rule with no customization and another built-in rule with customization. - -Here we modify the ``weight_update_ratio`` rule to store a custom collection rather than "weights" which it would normally do if the behavior is not overridden. - - -.. code:: python - - from sagemaker.debugger import Rule - from smdebug_rulesconfig import vanishing_gradient, weight_update_ratio - - wur_with_customization = Rule.sagemaker( - base_config=weight_update_ratio(), - name="custom_wup_rule_name", - rule_parameters={ - 'key1': 'value1', - 'key2': 'value2' - }, - collections_to_save=[ - CollectionConfig( - name="custom_collection_name", - parameters= { - 'key1': 'value1', - 'key2': 'value2' - } - ) - ] - ) - - estimator = TensorFlow( - role=role, - instance_count=1, - instance_type=instance_type, - rules=[ - Rule.sagemaker(vanishing_gradient()), - wur_with_customization - ] - ) - - -In the example above, the collection configuration for Vanishing Gradient is pulled from `SageMaker Debugger Rules Config `__ and the user supplied configuration is used for the Weight Update Ratio rule. - -Using custom rules ------------------- - -SageMaker Debugger also allows the users to create custom rules and have those evaluated against the debugging data. To use custom rules, you must provide two items: - -* Custom rule source file and its local or S3 location. You can learn more about how to write custom rules at `How to Write Custom Debugger Rules `__ -* Rule evaluator image for the corresponding region available from `Amazon SageMaker Debugger Custom Rule Images `__ - -To learn more about how to write your custom rules and use them see `SageMaker Debugger Custom Rules `__. - -Sample Usage -~~~~~~~~~~~~ - -For this example, we evaluate an altered version of the Vanishing Gradient rule against our model training. The rule checks the gradients and asserts that the mean value of the gradients at any step is always above a certain threshold. The source code for the rule is available `here `__ and is assumed to be in the relative directory path ``rules/custom_gradient_rule.py``. - -To evaluate the custom rule against the training: - -.. code:: python - - from sagemaker.debugger import Rule - - region = 'us-east-1' # the AWS region of the training job - custom_gradient_rule = Rule.custom( - name='MyCustomRule', - image_uri='864354269164.dkr.ecr.{}.amazonaws.com/sagemaker-debugger-rule-evaluator:latest'.format(region), - instance_type='ml.t3.medium', # instance type to run the rule evaluation on - source='rules/custom_gradient_rule.py', # path to the rule source file - rule_to_invoke='CustomGradientRule', # name of the class to invoke in the rule source file - volume_size_in_gb=30, # EBS volume size required to be attached to the rule evaluation instance - collections_to_save=[CollectionConfig("gradients")], # collections to be analyzed by the rule - rule_parameters={ - 'threshold': '20.0' # this will be used to initialize 'threshold' param in your rule constructor - } - ) - - estimator = TensorFlow( - role=role, - instance_count=1, - instance_type=instance_type, - rules=[ - custom_gradient_rule - ] - ) - -While initializing the custom rule through ``Rules.custom()``, you must specify a valid S3 location for rule source location as the value of ``source``. - -Capture real-time TensorBoard data from the debugging hook -========================================================== - -In addition to emitting and storing the debugging data useful for analyses, the debugging hook is also capable of emitting `TensorBoard `__ data for you to point your TensorBoard application at and to visualize. - -To enable the debugging hook to emit TensorBoard data, you need to specify the new option ``TensorBoardOutputConfig`` as follows: - -.. code:: python - - from sagemaker.debugger import TensorBoardOutputConfig - - tensorboard_output_config = TensorBoardOutputConfig( - s3_output_path='s3://path/for/tensorboard/data/emission', - container_local_output_path='/local/path/for/tensorboard/data/emission' - ) - - estimator = TensorFlow( - role=role, - instance_count=1, - instance_type=instance_type, - tensorboard_output_config=tensorboard_output_config - ) - -To create a training job where the debugging hook emits and stores TensorBoard data using the configuration specified in the ``TensorBoardOutputConfig`` object, call ``fit()`` on the ``estimator``. The debugging hook uploads the generated TensorBoard data in near real-time to an S3 path derived from the value of ``s3_output_path`` provided in the configuration: - -.. code:: - - s3://{destination-bucket-prefix}/{training-job-name}/tensorboard-output/ - -To access the S3 path where the tensorboard data is stored, you can do: - -.. code:: python - - tensorboard_s3_output_path = estimator.latest_job_tensorboard_artifacts_path() - -The reason for deriving the path from the value supplied to ``s3_output_path`` is the same as that provided for ``DebuggerHookConfig`` case - the directory for TensorBoard artifact storage needs be different for each training job. - -Note that having the TensorBoard data emitted from the hook in addition to the tensors will incur a cost to the training and may slow it down. - -Interactive analysis using SageMaker Debugger SDK and visualizations -==================================================================== - -`Amazon SageMaker Debugger SDK `__ also allows you to do interactive analyses on the debugging data produced from a training job run and to render visualizations of it. After calling ``fit()`` on the estimator, you can use the SDK to load the saved data in a SageMaker Debugger ``trial`` and do an analysis on the data: - -.. code:: python - - from smdebug.trials import create_trial - - s3_output_path = estimator.latest_job_debugger_artifacts_path() - trial = create_trial(s3_output_path) - -To learn more about the programming model for analysis using the SageMaker Debugger SDK, see `SageMaker Debugger Analysis `__. - -For a tutorial on what you can do after creating the trial and how to visualize the results, see `SageMaker Debugger - Visualizing Debugging Results `__. - -Default behavior and opting out -=============================== - -For ``TensorFlow``, ``Keras``, ``MXNet``, ``PyTorch`` and ``XGBoost`` estimators, the ``DebuggerHookConfig`` is always initialized regardless of specification while initializing the estimator. This is done to minimize code changes needed to get useful debugging information. - -To disable the hook initialization, you can do so by specifying ``False`` for value of ``debugger_hook_config`` in your framework estimator's initialization: - -.. code:: python - - estimator = TensorFlow( - role=role, - instance_count=1, - instance_type=instance_type, - debugger_hook_config=False - ) - -Learn More -========== - -Further documentation ---------------------- - -* API documentation: https://sagemaker.readthedocs.io/en/stable/debugger.html -* AWS documentation: https://docs.aws.amazon.com/sagemaker/latest/dg/train-debugger.html -* SageMaker Debugger SDK: https://github.com/awslabs/sagemaker-debugger -* ``S3Downloader``: https://sagemaker.readthedocs.io/en/stable/s3.html#sagemaker.s3.S3Downloader - -Notebook examples ------------------ - -Consult our notebook examples for in-depth tutorials: https://github.com/awslabs/amazon-sagemaker-examples/tree/master/sagemaker-debugger diff --git a/doc/amazon_sagemaker_featurestore.rst b/doc/amazon_sagemaker_featurestore.rst deleted file mode 100644 index 447f16877e..0000000000 --- a/doc/amazon_sagemaker_featurestore.rst +++ /dev/null @@ -1,499 +0,0 @@ -############################## -Amazon SageMaker Feature Store -############################## - -.. rubric:: **Create Feature Groups** - :name: bCe9CAXalwH - -This guide will show you how to create and use -`Amazon SageMaker Feature Store `__. -The example code in this guide covers using the SageMaker Python SDK. The -underlying APIs are available for developers using other languages. - -.. rubric:: Features - :name: bCe9CAtWHPP - -Prior to using a feature store you will typically load your dataset, run -transformations, and set up your features for ingestion. This step has a -lot of variation and is highly dependent on your data. The example code -in the following code blocks will often make reference to an example -notebook, \ `Fraud Detection with Amazon SageMaker Feature Store -`__. -It is recommended that you run this notebook -in SageMaker Studio and use the code from there, as the code in this -guide is conceptual and not fully functional if copied. - -.. rubric:: Feature store data types and schema - :name: bCe9CAr4kIT - -Feature Store supported types are ``String``, ``Fractional``, and -``Integral``. The default type is set to ``String``. This means that, if -a column in your dataset is not a ``float`` or ``long`` type, it will -default to ``String`` in your feature store. - - -You may use a schema to describe your data’s columns and data types. You -pass this schema into FeatureDefinitions, a required parameter for a -FeatureGroup. However, for Python developers, the SageMaker Python SDK -has automatic data type detection when you use the -``load_feature_definitions`` function. - -.. rubric:: Feature store setup - :name: bCe9CAgy6IH - -To start using Feature Store, first create a SageMaker session, boto3 -session, and a Feature Store session. Also, setup the bucket you will -use for your features; this is your Offline Store. The following will -use the SageMaker default bucket and add a custom prefix to it. - -.. note:: - - The role that you use requires these managed - policies:\ ``AmazonSageMakerFullAccess``\ and\ ``AmazonSageMakerFeatureStoreAccess``\ . - - -.. code:: python - - import boto3 - import sagemaker - from sagemaker.session import Session - - boto_session = boto3.Session(region_name=region) - role = sagemaker.get_execution_role() - sagemaker_session = sagemaker.Session() - region = sagemaker_session.boto_region_name - default_bucket = sagemaker_session.default_bucket() - prefix = 'sagemaker-featurestore' - offline_feature_store_bucket = 's3://*{}*/*{}*'.format(default_bucket, prefix) - - sagemaker_client = boto_session.client(service_name='sagemaker', region_name=region) - featurestore_runtime = boto_session.client(service_name='sagemaker-featurestore-runtime', region_name=region) - - feature_store_session = Session( -     boto_session=boto_session, -     sagemaker_client=sagemaker_client, -     sagemaker_featurestore_runtime_client=featurestore_runtime - ) - -.. rubric:: Load datasets and partition data into feature groups - :name: bCe9CA31y9f - -You will load your data into data frames for each of your features. You -will use these data frames after you setup the feature group. In the -fraud detection example, you can see these steps in the following code. - -.. code:: python - - import numpy as np - import pandas as pd - import matplotlib.pyplot as plt - import io - - fraud_detection_bucket_name = 'sagemaker-featurestore-fraud-detection' - identity_file_key = 'sampled_identity.csv' - transaction_file_key = 'sampled_transactions.csv' - - identity_data_object = s3_client.get_object(Bucket=fraud_detection_bucket_name, Key=identity_file_key) - transaction_data_object = s3_client.get_object(Bucket=fraud_detection_bucket_name, Key=transaction_file_key) - - identity_data = pd.read_csv(io.BytesIO(identity_data_object['Body'].read())) - transaction_data = pd.read_csv(io.BytesIO(transaction_data_object['Body'].read())) - - identity_data = identity_data.round(5) - transaction_data = transaction_data.round(5) - - identity_data = identity_data.fillna(0) - transaction_data = transaction_data.fillna(0) - - # Feature transformations for this dataset are applied before ingestion into FeatureStore. - # One hot encode card4, card6 - encoded_card_bank = pd.get_dummies(transaction_data['card4'], prefix = 'card_bank') - encoded_card_type = pd.get_dummies(transaction_data['card6'], prefix = 'card_type') - - transformed_transaction_data = pd.concat([transaction_data, encoded_card_type, encoded_card_bank], axis=1) - transformed_transaction_data = transformed_transaction_data.rename(columns={"card_bank_american express": "card_bank_american_express"}) - -.. rubric:: Feature group setup - :name: bCe9CARx8h9 - -Name your feature groups and customize the feature names with a unique -name, and setup each feature group with the ``FeatureGroup`` class. - -.. code:: python - - from sagemaker.feature_store.feature_group import FeatureGroup - feature_group_name = "some string for a name" - feature_group = FeatureGroup(name=feature_group_name, sagemaker_session=feature_store_session) - -For example, in the fraud detection example, the two feature groups are -“identity” and “transaction”. In the following code you can see how the -names are customized with a timestamp, then each group is setup by -passing in the name and the session. - -.. code:: python - - import time - from time import gmtime, strftime, sleep - from sagemaker.feature_store.feature_group import FeatureGroup - - identity_feature_group_name = 'identity-feature-group-' + strftime('%d-%H-%M-%S', gmtime()) - transaction_feature_group_name = 'transaction-feature-group-' + strftime('%d-%H-%M-%S', gmtime()) - - identity_feature_group = FeatureGroup(name=identity_feature_group_name, sagemaker_session=feature_store_session) - transaction_feature_group = FeatureGroup(name=transaction_feature_group_name, sagemaker_session=feature_store_session) - -.. rubric:: Record identifier and event time feature - :name: bCe9CA17VV7 - -Next, you will need a record identifier name and an event time feature -name. This will match the column of the corresponding features in your -data. For example, in the fraud detection example, the column of -interest is “TransactionID”. “EventTime” can be appended to your data -when no timestamp is available. In the following code, you can see how -these variables are set, and then ``EventTime`` is appended to both -feature’s data. - -.. code:: python - - record_identifier_name = "TransactionID" - event_time_feature_name = "EventTime" - current_time_sec = int(round(time.time())) - identity_data[event_time_feature_name] = pd.Series([current_time_sec]*len(identity_data), dtype="float64") - transformed_transaction_data[event_time_feature_name] = pd.Series([current_time_sec]*len(transaction_data), dtype="float64") - -.. rubric:: Feature definitions - :name: bCe9CA4yUcO - -You can now load the feature definitions by passing a data frame -containing the feature data. In the following code for the fraud -detection example, the identity feature and transaction feature are each -loaded by using ``load_feature_definitions``, and this function -automatically detects the data type of each column of data. For -developers using a schema rather than automatic detection, refer to the -`Creating Feature Groups with Data Wrangler example `__ for -code that shows loading the schema, mapping it and adding as a -``FeatureDefinition`` that is used when you create the ``FeatureGroup``. -This example also covers a boto3 implementation, instead of using the -SageMaker Python SDK. - -.. code:: python - - identity_feature_group.load_feature_definitions(data_frame=identity_data); # output is suppressed - transaction_feature_group.load_feature_definitions(data_frame=transformed_transaction_data); # output is suppressed - -.. rubric:: Create a feature group - :name: bCe9CAwMEgY - -The last step for creating the feature group is to use the -``create`` function. The following code shows all of the available -parameters. The online store is not created by default, so you must set -this as \ ``True`` if you want to enable it. The ``s3_uri`` is the -location of your offline store. - -.. code:: python - - # create a FeatureGroup - feature_group.create( -     description = "Some info about the feature group", -     feature_group_name = feature_group_name, -     record_identifier_name = record_identifier_name, -     event_time_feature_name = event_time_feature_name, -     feature_definitions = feature_definitions, -     role_arn = role, -     s3_uri = offline_feature_store_bucket, -     enable_online_store = True, -     ttl_duration = None, -     online_store_kms_key_id = None, -     offline_store_kms_key_id = None, -     disable_glue_table_creation = False, -     data_catalog_config = None, -     tags = ["tag1","tag2"]) - -The following code from the fraud detection example shows a minimal -``create`` call for each of the two features groups being created. - -.. code:: python - - identity_feature_group.create( -     s3_uri=offline_feature_store_bucket, -     record_identifier_name=record_identifier_name, -     event_time_feature_name=event_time_feature_name, -     role_arn=role, -     enable_online_store=True - ) - - transaction_feature_group.create( -     s3_uri=offline_feature_store_bucket, -     record_identifier_name=record_identifier_name, -     event_time_feature_name=event_time_feature_name, -     role_arn=role, -     enable_online_store=True - ) - -Creating a feature group takes time as the data is loaded. You will -need to wait until it is created before you can use it. You can -check status using the following method. Note that it can take -approximately 10-15 minutes to provision an online ``FeatureGroup`` -with the ``InMemory`` ``StorageType``. - -.. code:: python - -  status = feature_group.describe().get("FeatureGroupStatus") - -While it is creating you will get a ``Creating`` as a response. When -this has finished successfully the response will be ``Created``. The -other possible statuses are ``CreateFailed``, ``Deleting``, or -``DeleteFailed``. - -.. rubric:: Describe a feature group - :name: bCe9CA2TNON - -You can retrieve information about your feature group with the -``describe`` function. - -.. code:: python - - feature_group.describe() - -.. rubric:: List feature groups - :name: bCe9CA2wPF2 - -You can list all of your feature groups with the -``list_feature_groups`` function. - -.. code:: python - - sagemaker_client.list_feature_groups() - -.. rubric:: Put records in a feature group - :name: bCe9CAymRdA - -You can use the ``ingest`` function to load your feature data. You pass -in a data frame of feature data, set the number of workers, and choose -to wait for it to return or not. The following example demonstrates -using the ``ingest`` function. - -.. code:: python - - feature_group.ingest( -     data_frame=feature_data, max_workers=3, wait=True - ) - -For each feature group you have, run the ``ingest`` function on the -feature data you want to load. - -.. rubric:: Get records from a feature group - :name: bCe9CA25xj5 - -You can use the ``get_record`` function to retrieve the data for a -specific feature by its record identifier. The following example uses an -example identifier to retrieve the record. - -.. code:: python - - record_identifier_value = str(2990130) - featurestore_runtime.get_record(FeatureGroupName=transaction_feature_group_name, RecordIdentifierValueAsString=record_identifier_value) - -You can use the ``batch_get_record`` function to retrieve multiple records simultaneously from your feature store. The following example uses this API to retrieve a batch of records. - -.. code:: python - - record_identifier_values = ["573291", "109382", "828400", "124013"] - featurestore_runtime.batch_get_record(Identifiers=[{"FeatureGroupName": transaction_feature_group_name, "RecordIdentifiersValueAsString": record_identifier_values}]) - -An example response from the fraud detection example: - -.. code:: python - - ... - 'Record': [{'FeatureName': 'TransactionID', 'ValueAsString': '2990130'}, -   {'FeatureName': 'isFraud', 'ValueAsString': '0'}, -   {'FeatureName': 'TransactionDT', 'ValueAsString': '152647'}, -   {'FeatureName': 'TransactionAmt', 'ValueAsString': '75.0'}, -   {'FeatureName': 'ProductCD', 'ValueAsString': 'H'}, -   {'FeatureName': 'card1', 'ValueAsString': '4577'}, - ... - -.. rubric:: Hive DDL commands - :name: bCe9CA30nHn - -The SageMaker Python SDK’s FeatureStore class also provides the -functionality to generate Hive DDL commands. The schema of the table is -generated based on the feature definitions. Columns are named after -feature name and data-type are inferred based on feature type. - -.. code:: python - - print(feature_group.as_hive_ddl()) - -An example output: - -.. code:: python - - CREATE EXTERNAL TABLE IF NOT EXISTS sagemaker_featurestore.identity-feature-group-27-19-33-00 ( -   TransactionID INT -   id_01 FLOAT -   id_02 FLOAT -   id_03 FLOAT -   id_04 FLOAT -  ... - -.. rubric:: Build a Training Dataset - :name: bCe9CAVnDLV - -Feature Store automatically builds a Amazon Glue Data Catalog when -Feature Groups are created and can optionally be turned off. The -following we show how to create a single training dataset with feature -values from both identity and transaction feature groups created above. -Also, the following shows how to run an Amazon Athena query to join data -stored in the Offline Store from both identity and transaction feature -groups. - - -To start, create an Athena query using\ ``athena_query()``\ for both -identity and transaction feature groups. The ``table_name`` is the Glue -table that is auto-generated by Feature Store. - -.. code:: python - - identity_query = identity_feature_group.athena_query() - transaction_query = transaction_feature_group.athena_query() - - identity_table = identity_query.table_name - transaction_table = transaction_query.table_name - -.. rubric:: Writing and Executing your Athena Query - :name: bCe9CArSR5J - -You will write your query using SQL on these feature groups, and then -execute the query with the ``.run()`` command and specify your S3 bucket -location for the data set to be saved there. - -.. code:: python - - # Athena query - query_string = 'SELECT * FROM "'+transaction_table+'" LEFT JOIN "'+identity_table+'" ON "'+transaction_table+'".transactionid = "'+identity_table+'".transactionid' - - # run Athena query. The output is loaded to a Pandas dataframe. - dataset = pd.DataFrame() - identity_query.run(query_string=query_string, output_location='s3://'+default_s3_bucket_name+'/query_results/') - identity_query.wait() - dataset = identity_query.as_dataframe() - -From here you can train a model using this data set and then perform -inference. - -.. rubric:: Using the Offline Store SDK: Getting Started - :name: bCe9CA61b79 - -The Feature Store Offline SDK provides the ability to quickly and easily -build ML-ready datasets for use by ML model training or pre-processing. -The SDK makes it easy to build datasets from SQL join, point-in-time accurate -join, and event range time frames, all without the need to write any SQL code. -This functionality is accessed via the DatasetBuilder class which is the -primary entry point for the SDK functionality. - -.. code:: python - - from sagemaker.feature_store.feature_store import FeatureStore - - feature_store = FeatureStore(sagemaker_session=feature_store_session) - -.. code:: python - - base_feature_group = identity_feature_group - target_feature_group = transaction_feature_group - -You can create dataset using `create_dataset` of feature store API. -`base` can either be a feature group or a pandas dataframe. - -.. code:: python - - result_df, query = feature_store.create_dataset( - base=base_feature_group, - output_path=f"s3://{s3_bucket_name}" - ).to_dataframe() - -If you want to join other feature group, you can specify extra -feature group using `with_feature_group` method. - -.. code:: python - - dataset_builder = feature_store.create_dataset( - base=base_feature_group, - output_path=f"s3://{s3_bucket_name}" - ).with_feature_group(target_feature_group, record_identifier_name) - - result_df, query = dataset_builder.to_dataframe() - -.. rubric:: Using the Offline Store SDK: Configuring the DatasetBuilder - :name: bCe9CA61b80 - -How the DatasetBuilder produces the resulting dataframe can be configured -in various ways. - -By default the Python SDK will exclude all deleted and duplicate records. -However if you need either of them in returned dataset, you can call -`include_duplicated_records` or `include_deleted_records` when creating -dataset builder. - -.. code:: python - - dataset_builder.include_duplicated_records() - dataset_builder.include_deleted_records() - -The DatasetBuilder provides `with_number_of_records_from_query_results` and -`with_number_of_recent_records_by_record_identifier` methods to limit the -number of records returned for the offline snapshot. - -`with_number_of_records_from_query_results` will limit the number of records -in the output. For example, when N = 100, only 100 records are going to be -returned in either the csv or dataframe. - -.. code:: python - - dataset_builder.with_number_of_records_from_query_results(number_of_records=N) - -On the other hand, `with_number_of_recent_records_by_record_identifier` is -used to deal with records which have the same identifier. They are going -to be sorted according to `event_time` and return at most N recent records -in the output. - -.. code:: python - - dataset_builder.with_number_of_recent_records_by_record_identifier(number_of_recent_records=N) - -Since these functions return the dataset builder, these functions can -be chained. - -.. code:: python - - dataset_builder - .with_number_of_records_from_query_results(number_of_records=N) - .include_duplicated_records() - .with_number_of_recent_records_by_record_identifier(number_of_recent_records=N) - .to_dataframe() - -There are additional configurations that can be made for various use cases, -such as time travel and point-in-time join. These are outlined in the -Feature Store `DatasetBuilder API Reference -`__. - -.. rubric:: Delete a feature group - :name: bCe9CA61b78 - -You can delete a feature group with the ``delete`` function. Note that it -can take approximately 10-15 minutes to delete an online ``FeatureGroup`` -with the ``InMemory`` ``StorageType``. - -.. code:: python - - feature_group.delete() - -The following code example is from the fraud detection example. - -.. code:: python - - identity_feature_group.delete() - transaction_feature_group.delete() - diff --git a/doc/amazon_sagemaker_model_building_pipeline.rst b/doc/amazon_sagemaker_model_building_pipeline.rst deleted file mode 100644 index e3548f80f2..0000000000 --- a/doc/amazon_sagemaker_model_building_pipeline.rst +++ /dev/null @@ -1,1393 +0,0 @@ -######################################### -Amazon SageMaker Model Building Pipeline -######################################### - - -.. contents:: - -========== -Background -========== - -Amazon SageMaker Model Building Pipelines is the first purpose-built, easy-to-use continuous integration and continuous delivery (CI/CD) service for machine learning (ML). With SageMaker Pipelines, you can create, automate, and manage end-to-end ML workflows at scale. - -A pipeline is a series of interconnected steps that is defined by a JSON pipeline definition. The SageMaker Python SDK offers convenient abstractions to help construct a pipeline with ease. The following pages include code examples for some of the most common SageMaker Pipelines use cases. - -For a higher-level conceptual guide and more information on integration with additional AWS services and features, see :`Amazon SageMaker Model Building Pipelines`_ in the Amazon SageMaker Developer Guide. - -.. _Amazon SageMaker Model Building Pipelines: https://docs.aws.amazon.com/sagemaker/latest/dg/pipelines.html - - -================ -Code Examples -================ - -Pipeline Session -================== -Pipeline Session helps manage AWS service integrations during pipeline creation. - -Pipeline Session is an extension of SageMaker Session, which manages the interactions between SageMaker APIs and AWS services like Amazon S3. SageMaker Session provides convenient methods for manipulating entities and resources that Amazon SageMaker uses, such as training jobs, endpoints, and S3 input datasets. AWS service calls are delegated to an underlying Boto3 session, which by default is initialized using the AWS configuration chain. - -The following example shows how to construct an estimator and start a :code:`TrainingJob` with SageMaker Session: - -.. code-block:: python - - pytorch_estimator = PyTorch( - *sagemaker_session=sagemaker.Session(),* - role=sagemaker.get_execution_role(), - instance_type="ml.c5.xlarge", - instance_count=1, - framework_version="1.8.0", - py_version="py36", - entry_point="./entry_point.py", - ) - pytorch_estimator.fit( - inputs=TrainingInput(s3_data="s3://my-bucket/my-data/train"), - ) - -The :class:`sagemaker.estimator.EstimatorBase.fit` method will call the underlying SageMaker :code:`CreateTrainingJob` API to start a TrainingJob immediately. When composing a pipeline to run a training job, one need to define a :class:`sagemaker.workflow.steps.TrainingStep` first, and we need the training job to be started only when this :class:`sagemaker.workflow.steps.TrainingStep` gets executed during a pipeline execution. This is where the pipeline session :class:`sagemaker.workflow.pipeline_context.PipelineSession` came in. - -.. code-block:: python - - pytorch_estimator = PyTorch( - sagemaker_session=sagemaker.Session(), - role=sagemaker.get_execution_role(), - instance_type="ml.c5.xlarge", - instance_count=1, - framework_version="1.8.0", - py_version="py36", - entry_point="./entry_point.py", - ) - pytorch_estimator.fit( - inputs=TrainingInput(s3_data="s3://my-bucket/my-data/train"), - ) - - -.. code-block:: python - - from sagemaker.workflow.pipeline_context import PipelineSession - - pytorch_estimator = PyTorch( - sagemaker_session=PipelineSession(), - role=sagemaker.get_execution_role(), - instance_type="ml.c5.xlarge", - instance_count=1, - framework_version="1.8.0", - py_version="py36", - entry_point="./entry_point.py", - ) - - step = TrainingStep( - name="MyTrainingStep", - // code just like how you trigger a training job before, - // pipeline session will take care of delaying the start - // of the training job during pipeline execution. - step_args=pytorch_estimator.fit( - inputs=TrainingInput(s3_data="s3://my-bucket/my-data/train"), - ), - displayName="MyTrainingStepDisplayName", - description="This is MyTrainingStep", - cache_config=CacheConfig(...), - retry_policies=[...], - depends_on=[...], - ) - -When you use :class:`sagemaker.workflow.pipeline_context.PipelineSession` rather than :class:`sagemaker.session.Session`, the :code:`.fit` method does not immediately start a training job. Instead, the :code:`.fit` method delays the request to call :code:`CreateTrainingJob`, so that you can first define your :class:`sagemaker.workflow.steps.TrainingStep`. - -.. warning:: - A :class:`sagemaker.workflow.pipeline_context.PipelineSession` must be given in order to start the job during pipeline execution time. Otherwise, a training job will get started immediately. - -Local Pipeline Session -====================== - -Like Pipeline Session, Local Pipeline Session provides a convenient way to capture input job arguments without starting the job. These input arguments can be provided in the :code:`step_args` parameter to their corresponding `Pipelines step type `__. The difference between :class:`sagemaker.workflow.pipeline_context.PipelineSession` and :class:`sagemaker.workflow.pipeline_context.LocalPipelineSession` is that :class:`sagemaker.workflow.pipeline_context.LocalPipelineSession` is used to run SageMaker pipelines locally (in local mode) whereas using :class:`sagemaker.workflow.pipeline_context.PipelineSession` runs the job on the managed service. - -.. code-block:: python - - from sagemaker.workflow.pipeline_context import LocalPipelineSession - - local_pipeline_session = LocalPipelineSession() - - pytorch_estimator = PyTorch( - sagemaker_session=local_pipeline_session, - role=sagemaker.get_execution_role(), - instance_type="ml.c5.xlarge", - instance_count=1, - framework_version="1.8.0", - py_version="py36", - entry_point="./entry_point.py", - ) - - step = TrainingStep( - name="MyTrainingStep", - step_args=pytorch_estimator.fit( - inputs=TrainingInput(s3_data="s3://my-bucket/my-data/train"), - ) - ) - - pipeline = Pipeline( - name="MyPipeline", - steps=[step], - sagemaker_session=local_pipeline_session - ) - - pipeline.create( - role_arn=sagemaker.get_execution_role(), - description="local pipeline example" - ) - - // pipeline will execute locally - pipeline.start() - - steps = pipeline.list_steps() - - training_job_name = steps['PipelineExecutionSteps'][0]['Metadata']['TrainingJob']['Arn'] - - step_outputs = pipeline_session.sagemaker_client.describe_training_job(TrainingJobName = training_job_name) - - -Pipeline Parameters -====================== - -You can parameterize your pipeline definition using parameters. You can reference parameters that you define throughout your pipeline definition. Parameters have a default value, which you can override by specifying parameter values when starting a pipeline execution. - -- :class:`sagemaker.workflow.parameters.ParameterString` – Representing a string parameter. -- :class:`sagemaker.workflow.parameters.ParameterInteger` – Representing an integer parameter. -- :class:`sagemaker.workflow.parameters.ParameterFloat` – Representing a float parameter. -- :class:`sagemaker.workflow.parameters.ParameterBoolean` – Representing a Boolean Python type. - -Here is an example: - -.. code-block:: python - - from sagemaker.workflow.parameters import ( - ParameterInteger, - ParameterString, - ParameterFloat, - ParameterBoolean, - ) - from sagemaker.workflow.pipeline_context import PipelineSession - - session = PipelineSession() - - instance_count = ParameterInteger(name="InstanceCount", default_value=2) - app_managed = ParameterBoolean(name="AppManaged", default_value=False) - - inputs = [ - ProcessingInput( - source="s3://my-bucket/sourcefile", - destination="/opt/ml/processing/inputs/", - app_managed=app_managed - ), - ] - - sklearn_processor = SKLearnProcessor( - framework_version="0.23-1", - role=sagemaker.get_execution_role(), - instance_type="ml.m5.xlarge", - instance_count=instance_count, - command=["python3"], - sagemaker_session=session, - base_job_name="test-sklearn", - ) - - step_sklearn = ProcessingStep( - name="MyProcessingStep", - step_args=sklearn_processor.run( - inputs=inputs, code="./my-local/script.py" - ), - ) - - pipeline = Pipeline( - name=pipeline_name, - parameters=[instance_count, app_managed], - steps=[step_sklearn], - sagemaker_session=session, - ) - - # you can override the default parameter values - pipeline.start({ - "InstanceCount": 2, - "AppManaged": True, - }) - -Step Dependencies -==================== -There are two types of step dependencies: a `data dependency`_ and a `custom dependency`_. To create data dependencies between steps, pass the properties or the outputs of one step as the input to another step in the pipeline. This is called property reference. Alternatively, you can specify a custom dependency to make sure that a pipeline execution does not start a new step until all dependent steps are completed. - -.. _data dependency: https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html#build-and-manage-data-dependency -.. _custom dependency: https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html#build-and-manage-custom-dependency - -Data Dependency — Property Reference --------------------------------------------- - -A step property is an attribute of a step that represents the output values from a step execution. For example, :code:`TrainingStep.Properties.TrainingJobName` is a property of a :class:`sagemaker.workflow.steps.TrainingStep`. - -For a step that references a SageMaker job (e.g. :class:`sagemaker.workflow.steps.ProcessingStep`, :class:`sagemaker.workflow.steps.TrainingStep`, or :class:`sagemaker.workflow.steps.TransformStep`), the step property matches the attributes of that SageMaker job. For example, :class:`sagemaker.workflow.steps.TrainingStep`. properties match the attributes that result from calling :code:`DescribeTrainingJob`. :code:`TrainingJobName` is an attribute from a :code:`DescribeTrainingJob` result. Therefore, :code:`TrainingJobName` is a :class:`sagemaker.workflow.steps.TrainingStep` property, and can be referenced as :code:`TrainingStep.Properties.TrainingJobName`. - -You can build data dependencies from one step to another using this kind of property reference. These data dependencies are then used by SageMaker Pipelines to construct the directed acyclic graph (DAG) from the pipeline definition. These properties can be referenced as placeholder values and are resolved at runtime. - -For each step type you can refer to the following properties for data dependency creation: - -TrainingStep -````````````` -Referable Property List: - -- `DescribeTrainingJob`_ - -.. _DescribeTrainingJob: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingJob.html#API_DescribeTrainingJob_ResponseSyntax - -Example: - -.. code-block:: python - - step_train = TrainingStep(...) - model = Model( - image_uri="my-dummy-image", - model_data=step_train.properties.ModelArtifacts.S3ModelArtifacts, - ... - ) - # assume your training job will produce a metric called "val:acc" - # and you would like to use it to demtermine if you want to create - # a SageMaker Model for it. - step_condition = ConditionStep( - conditions = [ - ConditionGreaterThanOrEqualTo( - left=step_train.properties.FinalMetricDataList['val:acc'].Value - right=0.95 - )], - if_steps = [step_model_create], - ) - -ProcessingStep -```````````````` -Referable Property List: - -- `DescribeProcessingJob`_ - -.. _DescribeProcessingJob: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeProcessingJob.html#API_DescribeProcessingJob_ResponseSyntax - -.. code-block:: python - - sklearn_processor = SKLearnProcessor( - framework_version="0.23-1", - instance_type="ml.m5.xlarge", - instance_count=1, - base_job_name="sklearn-abalone-preprocess", - sagemaker_session=PipelineSession(), - role=sagemaker.get_execution_role(), - ) - - step_process = ProcessingStep( - name="MyProcessingStep", - ..., - step_args = sklearn_processor.run( - ..., - outputs=[ - ProcessingOutput(output_name="train", source="/opt/ml/processing/train"), - ], - code="./local/preprocess.py", - arguments=["--input-data", "s3://my-input"] - ), - ) - - step_args = estimator.fit(inputs=TrainingInput( - s3_data=step_process.properties.ProcessingOutputConfig.Outputs["train"].S3Output.S3Uri, - )) - -TransformStep -```````````````` -Referable Property List: - -`DescribeTransformJob`_ - -.. _DescribeTransformJob: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTransformJob.html#API_DescribeTransformJob_ResponseSyntax - -.. code-block:: python - - step_transform = TransformStep(...) - transform_output = step_transform.TransformOutput.S3OutputPath - -TuningStep -````````````` -Referable Property List: - -- `DescribeHyperParameterTuningJob`_ -- `ListTrainingJobsForHyperParameterTuningJob`_ - -.. _DescribeHyperParameterTuningJob: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeHyperParameterTuningJob.html#API_DescribeHyperParameterTuningJob_ResponseSyntax -.. _ListTrainingJobsForHyperParameterTuningJob: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListTrainingJobsForHyperParameterTuningJob.html#API_ListTrainingJobsForHyperParameterTuningJob_ResponseSyntax - -Example: - -.. code-block:: python - - bucket = "my-bucket" - model_prefix = "my-model" - - step_tune = TuningStep(...) - # tuning step can launch multiple training jobs, thus producing multiple model artifacts - # we can create a model with the best performance - best_model = Model( - model_data=Join( - on="/", - values=[ - f"s3://{bucket}/{model_prefix}", - # from DescribeHyperParameterTuningJob - step_tune.properties.BestTrainingJob.TrainingJobName, - "output/model.tar.gz", - ], - ) - ) - # we can also access any top-k best as we wish - second_best_model = Model( - model_data=Join( - on="/", - values=[ - f"s3://{bucket}/{model_prefix}", - # from ListTrainingJobsForHyperParameterTuningJob - step_tune.properties.TrainingJobSummaries[1].TrainingJobName, - "output/model.tar.gz", - ], - ) - ) - -:class:`sagemaker.workflow.steps.TuningStep` also has a helper function to generate any :code:`top-k` model data URI easily: - -.. code-block:: python - - model_data = step_tune.get_top_model_s3_uri( - top_k=0, # best model - s3_bucket=bucket, - prefix=model_prefix - ) - -AutoMLStep -````````````` -Referable Property List: - -- `DescribeAutoMLJob`_ -- `BestCandidateProperties.ModelInsightsJsonReportPath`_ -- `BestCandidateProperties.ExplainabilityJsonReportPath`_ - -.. _DescribeAutoMLJob: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeAutoMLJob -.. _BestCandidateProperties.ModelInsightsJsonReportPath: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CandidateArtifactLocations.html#sagemaker-Type-CandidateArtifactLocations-ModelInsights -.. _BestCandidateProperties.ExplainabilityJsonReportPath: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CandidateArtifactLocations.html#sagemaker-Type-CandidateArtifactLocations-Explainability - -Example: - -.. code-block:: python - - step_automl = AutoMLStep(...) - - auto_ml_model = step_automl.get_best_model() - - model_metrics = ModelMetrics( - model_statistics=MetricsSource( - s3_uri=auto_ml_step.properties.BestCandidateProperties.ModelInsightsJsonReportPath, - content_type="application/json", - ), - explainability=MetricsSource( - s3_uri=auto_ml_step.properties.BestCandidateProperties.ExplainabilityJsonReportPath, - content_type="application/json", - ) - ) - - step_args_register_model = auto_ml_model.register( - content_types=["text/csv"], - response_types=["text/csv"], - inference_instances=["ml.t2.medium", "ml.m5.large"], - transform_instances=["ml.m5.large"], - model_package_group_name="My model package group name", - approval_status="PendingManualApproval", - model_metrics=model_metrics, - ) - - step_register_model = ModelStep( - name="auto-ml-model-register", - step_args=step_args_register_model, - ) - -CreateModelStep -```````````````` -Referable Property List: - -- `DescribeModel`_ - -.. _DescribeModel: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeModel.html#API_DescribeModel_ResponseSyntax - -Example: - -.. code-block:: python - - step_model = CreateModelStep(...) - model_data = step_model.PrimaryContainer.ModelDataUrl - - -LambdaStep -````````````` -Referable Property List: - -- :code:`OutputParameters`: A list of key-value pairs `OutputParameter`_ as the output of the Lambda execution. - -.. _OutputParameter: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_OutputParameter.html - - -Example: - -.. code-block:: python - - str_outputParam = LambdaOutput(output_name="output1", output_type=LambdaOutputTypeEnum.String) - int_outputParam = LambdaOutput(output_name"output2", output_type=LambdaOutputTypeEnum.Integer) - bool_outputParam = LambdaOutput(output_name"output3", output_type=LambdaOutputTypeEnum.Boolean) - float_outputParam = LambdaOutput(output_name"output4", output_type=LambdaOutputTypeEnum.Float) - - step_lambda = LambdaStep( - name="MyLambdaStep", - lambda_func=Lambda( - function_arn="arn:aws:lambda:us-west-2:123456789012:function:sagemaker_test_lambda", - session=PipelineSession(), - ), - inputs={"arg1": "foo", "arg2": 5}, - outputs=[ - str_outputParam, int_outputParam, bool_outputParam, float_outputParam - ], - ) - output_ref = step_lambda.properties.Outputs["output1"] - -Where the lambda function with :code:`arn arn:aws:lambda:us-west-2:123456789012:function:sagemaker_test_lambda` -should output like this: - -.. code-block:: python - - def handler(event, context): - ... - return { - "output1": "string_value", - "output2": 1, - "output3": True, - "output4": 2.0, - } - -Note that the output parameters can not be nested. Otherwise, the value will be treated as a single string. For instance, if your lambda outputs - -.. code-block:: json - - { - "output1": { - "nested_output1": "my-output" - } - } - -This will be resolved as :code:`{"output1": "{\"nested_output1\":\"my-output\"}"}` by which if you refer :code:`step_lambda.properties.Outputs["output1"]["nested_output1"]` later, a non-retryable client error will be thrown. - -CallbackStep -````````````` - -Referable Property List: - -- :code:`OutputParameters`: A list of key-value pairs `OutputParameter`_ defined by `SendPipelineExecutionStepSuccess`_ call. - -.. _SendPipelineExecutionStepSuccess: https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SendPipelineExecutionStepSuccess.html call. - -Example: - -.. code-block:: python - - param = ParameterInteger(name="MyInt") - outputParam = CallbackOutput(output_name="output1", output_type=CallbackOutputTypeEnum.String) - step_callback = CallbackStep( - name="MyCallbackStep", - depends_on=["TestStep"], - sqs_queue_url="https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue", - inputs={"arg1": "foo", "arg2": 5, "arg3": param}, - outputs=[outputParam], - ) - output_ref = step_callback.properties.Outputs["output1] - -The output parameters cannot be nested. If the values are nested, they will be treated as a single string value. For example, a nested output value of - -.. code-block:: json - - { - "output1": { - "nested_output1": "my-output" - } - } - -is resolved as :code:`{"output1": "{\"nested_output1\":\"my-output\"}"}`. If you try to refer to :code:`step_callback.properties.Outputs["output1"]["nested_output1"]` this will throw a non-retryable client error. - - -QualityCheckStep -``````````````````` - -Referable Property List: - -- :code:`CalculatedBaselineConstraints`: The baseline constraints file calculated by the underlying Model Monitor container. -- :code:`CalculatedBaselineStatistics`: The baseline statistics file calculated by the underlying Model Monitor container. -- :code:`BaselineUsedForDriftCheckStatistics & BaselineUsedForDriftCheckConstraints`: These are the two properties used to set drift_check_baseline in the Model Registry. The values set in these properties vary depending on the parameters passed to the step. - -ClarifyCheckStep -``````````````````` - -Referable Property List: - -- :code:`CalculatedBaselineConstraints`: The baseline constraints file calculated by the underlying Clarify container. -- :code:`BaselineUsedForDriftCheckConstraints`: This property is used to set drift_check_baseline in the Model Registry. The values set in this property will vary depending on the parameters passed to the step. - -More examples about QualityCheckStep and ClarifyCheckStep can be found in `SageMaker Pipelines integration with Model Monitor and Clarify`_ notebook - -EMRStep -````````````` -Referable Property List: - -- :code:`ClusterId`: The Id of the EMR cluster. - -You can see more details at `AWS official developer guide for Step Introductions`_ - -.. _AWS official developer guide for Step Introductions: https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-steps.html - -Custom Dependency ------------------- -To build a custom dependency, simply add the desired step or steps to another step’s :code:`depends_on` attribute as follows: - -.. code-block:: python - - step_1 = ProcessingStep( - name="MyProcessingStep", - step_args=sklearn_processor.run( - inputs=inputs, - code="./my-local/my-first-script.py" - ), - ) - - step_2 = ProcessingStep( - name="MyProcessingStep", - step_args=sklearn_processor.run( - inputs=inputs, - code="./my-local/my-second-script.py" - ), - depends_on=[step_1.name], - ) - -In this case, :code:`step_2` will start only when :code:`step_1` is done. - -Property File -============== - -A :class:`sagemaker.workflow.properties.PropertyFile` is designed to store information that is output from :class:`sagemaker.workflow.steps.ProcessingStep`. The :class:`sagemaker.workflow.functions.JsonGet` function processes a property file . You can use JsonPath notation to query the information. - -.. code-block:: python - - sklearn_processor = SKLearnProcessor( - framework_version="0.23-1", - instance_type="ml.m5.xlarge", - instance_count=1, - base_job_name="sklearn-abalone-preprocess", - sagemaker_session=session, - role=sagemaker.get_execution_role(), - ) - - step_args = sklearn_processor.run( - outputs=[ - ProcessingOutput(output_name="train", source="/opt/ml/processing/train"), - ProcessingOutput(output_name="validation", source="/opt/ml/processing/validation"), - ProcessingOutput(output_name="test", source="/opt/ml/processing/test"), - ProcessingOutput(output_name="hyperparam", source="/opt/ml/processing/evaluation"), - ], - code="./local/preprocess.py", - arguments=["--input-data", "s3://my-input"], - ) - - hyperparam_report = PropertyFile( - name="AbaloneHyperparamReport", - output_name="hyperparam", - path="hyperparam.json", - ) - - step_process = ProcessingStep( - name="PreprocessAbaloneData", - step_args=step_args, - property_files=[hyperparam_report], - ) - -To retrieve a file produced by the :class:`sagemaker.workflow.steps.ProcessingStep` as a property file, the :code:`ProcessingOutput.output_name` and the :code:`PropertyFile.output_name` values must be the same. For this example, assume that the :code:`hyperparam.json` value produced by the ProcessingStep in the :code:`/opt/ml/processing/evaluation` directory looks similar to the following: - -.. code-block:: json - - { - "hyperparam": { - "eta": { - "value": 0.6 - } - } - } - -Then, you can query this value using :class:`sagemaker.workflow.functions.JsonGet` and use the value for any subsequent steps: - -.. code-block:: python - - eta = JsonGet( - step_name=step_process.name, - property_file=hyperparam_report, - json_path="hyperparam.eta.value", - ) - -Conditions -============ - -Condition step is used to evaluate the condition of step properties to assess which action should be taken next in the pipeline. It takes a list of conditions, and a list steps to execute if all conditions are evaluated to be true, and another list of steps to execute otherwise. For instance: - -.. code-block:: python - - step_condition = ConditionStep( - # The conditions are evaluated with operator AND - conditions = [condition_1, condition_2, condition_3, condition_4], - if_steps = [step_register], - else_steps = [step_fail], - ) - -There are eight types of condition are supported, they are: - -- :class:`sagemaker.workflow.conditions.ConditionEquals` -- :class:`sagemaker.workflow.conditions.ConditionGreaterThan` -- :class:`sagemaker.workflow.conditions.ConditionGreaterThanOrEqualTo` -- :class:`sagemaker.workflow.conditions.ConditionLessThan` -- :class:`sagemaker.workflow.conditions.ConditionLessThanOrEqualTo` -- :class:`sagemaker.workflow.conditions.ConditionIn` -- :class:`sagemaker.workflow.conditions.ConditionNot` -- :class:`sagemaker.workflow.conditions.ConditionOr` - -:class:`sagemaker.workflow.properties.PropertyFile` and :class:`sagemaker.workflow.functions.JsonGet` introduced above is particularly handy when used together with conditions. Here is an example: - -.. code-block:: python - - step_train = TrainingStep(...) - model = Model( - image_uri="my-dummy-image", - model_data=step_train.properties.ModelArtifacts.S3ModelArtifacts, - ... - ) - - step_args = sklearn_processor.run( - outputs=[ - ProcessingOutput(output_name="train", source="/opt/ml/processing/train"), - ProcessingOutput(output_name="validation", source="/opt/ml/processing/validation"), - ProcessingOutput(output_name="test", source="/opt/ml/processing/test"), - ProcessingOutput(output_name="hyperparam", source="/opt/ml/processing/evaluation"), - ], - code="./local/preprocess.py", - arguments=["--input-data", "s3://my-input"], - ) - - eval_report = PropertyFile( - name="AbaloneHyperparamReport", - output_name="hyperparam", - path="hyperparam.json", - ) - - step_process = ProcessingStep( - name="PreprocessAbaloneData", - step_args=step_args, - property_files=[eval_report], - ) - - eval_score = JsonGet( - step_name=step_process.name, - property_file=eval_report, - json_path="eval.accuracy", - ) - - # register the model if evaluation score is satisfactory - register_arg = model.register( - content_types=["application/json"], - response_types=["application/json"], - inference_instances=["ml.m5.large"], - transform_instances=["ml.m5.large"], - model_package_group_name="my-model-pkg-name", - approval_status="Approved", - ) - step_register = ModelStep( - name="MyModelCreationStep", - step_args=register_arg, - ) - # otherwise, transit to a failure step - step_fail = FailStep(name="FailStep", ...) - - cond = ConditionStep( - conditions = [ConditionGreaterThanOrEqualTo(left=eval_score, right=0.95)], - if_steps = [step_register], - else_steps = [step_fail], - ) - - -Pipeline Functions -=================== -Several pipeline built-in functions are offered to help you compose your pipeline. Use pipeline functions to assign values to properties that are not available until pipeline execution time. - -Join ------------ -Use the :class:`sagemaker.workflow.functions.Join` function to join a list of properties. For example, you can use Join to construct an S3 URI that can only be evaluated at run time, and use that URI to construct the :class:`sagemaker.workflow.steps.TrainingStep` at compile time. - -.. code-block:: python - - bucket = ParameterString('bucket', default_value='my-bucket') - - input_uri = Join( - on="/", - values=['s3:/', bucket, "my-input")] - ) - - step = TrainingStep( - name="MyTrainingStep", - run_args=estimator.fit(inputs=TrainingInput(s3_data=input_uri)), - ) - -JsonGet ------------ -Use :class:`sagemaker.workflow.functions.JsonGet` to extract a Json property from a :class:`sagemaker.workflow.properties.PropertyFile` produced by a :class:`sagemaker.workflow.steps.ProcessingStep`, and pass it to subsequent steps. The following example retrieves a hyperparameter value from the :class:`sagemaker.workflow.properties.PropertyFile`, and pass it to a subsequent :class:`sagemaker.workflow.steps.TrainingStep` - -.. code-block:: python - - session = PipelineSession() - - sklearn_processor = SKLearnProcessor( - framework_version="0.23-1", - instance_type="ml.m5.xlarge", - instance_count=1, - base_job_name="sklearn-abalone-preprocess", - sagemaker_session=session, - role=sagemaker.get_execution_role(), - ) - - step_args = sklearn_processor.run( - outputs=[ - ProcessingOutput(output_name="train", source="/opt/ml/processing/train"), - ProcessingOutput(output_name="validation", source="/opt/ml/processing/validation"), - ProcessingOutput(output_name="test", source="/opt/ml/processing/test"), - ProcessingOutput(output_name="hyperparam", source="/opt/ml/processing/evaluation"), - ], - code="./local/preprocess.py", - arguments=["--input-data", "s3://my-input"], - ) - - hyperparam_report = PropertyFile( - name="AbaloneHyperparamReport", - output_name="hyperparam", - path="hyperparam.json", - ) - - step_process = ProcessingStep( - name="PreprocessAbaloneData", - step_args=step_args, - property_files=[hyperparam_report], - ) - - xgb_train = Estimator( - image_uri="s3://my-image-uri", - instance_type="ml.c5.xlarge", - instance_count=1, - output_path="s3://my-output-path", - base_job_name="abalone-train", - sagemaker_session=session, - role=sagemaker.get_execution_role(), - ) - - eta = JsonGet( - step_name=step_process.name, - property_file=hyperparam_report, - json_path="hyperparam.eta.value", - ) - - xgb_train.set_hyperparameters( - objective="reg:linear", - num_round=50, - max_depth=5, - eta=eta, - gamma=4, - min_child_weight=6, - subsample=0.7, - silent=0, - ) - - step_args = xgb_train.fit(inputs={ - "train": TrainingInput( - s3_data=step_process.properties.ProcessingOutputConfig.Outputs[ - "train" - ].S3Output.S3Uri, - content_type="text/csv", - ), - "validation": TrainingInput( - s3_data=step_process.properties.ProcessingOutputConfig.Outputs[ - "validation" - ].S3Output.S3Uri, - content_type="text/csv", - ), - },) - - step_train = TrainingStep( - name="TrainAbaloneModel", - step_args=step_args, - ) - -Execution Variable -==================== - -There are a number of properties for a pipeline execution that can only be resolved at run time. However, they can be accessed at compile time using execution variables. - -- :class:`sagemaker.workflow.execution_variables.ExecutionVariables.START_DATETIME`: The start time of an execution. -- :class:`sagemaker.workflow.execution_variables.ExecutionVariables.CURRENT_DATETIME`: The time when the variable is being evaluated during an execution. -- :class:`sagemaker.workflow.execution_variables.ExecutionVariables.PIPELINE_EXECUTION_ID`: The Id of an execution. -- :class:`sagemaker.workflow.execution_variables.ExecutionVariables.PIPELINE_EXECUTION_ARN`: The execution ARN for an execution. -- :class:`sagemaker.workflow.execution_variables.ExecutionVariables.PIPELINE_NAME`: The name of the pipeline. -- :class:`sagemaker.workflow.execution_variables.ExecutionVariables.PIPELINE_ARN`: The ARN of the pipeline. -- :class:`sagemaker.workflow.execution_variables.ExecutionVariables.TRAINING_JOB_NAME`: The name of the training job launched by the training step. -- :class:`sagemaker.workflow.execution_variables.ExecutionVariables.PROCESSING_JOB_NAME`: The name of the processing job launched by the processing step. - -You can use these execution variables as you see fit. The following example uses the :code:`START_DATETIME` execution variable to construct a processing output path: - -.. code-block:: python - - bucket = ParameterString('bucket', default_value='my-bucket') - - output_path = Join( - on="/", - values=['s3:/', bucket, 'my-train-output-', ExecutionVariables.START_DATETIME])] - ) - - step = ProcessingStep( - name="MyTrainingStep", - step_args=processor.fit( - inputs=ProcessingInput(source="s3://my-input"), - outputs=[ - ProcessingOutput( - output_name="train", - source="/opt/ml/processing/train", - destination=output_path, - ), - ], - ), - ) - - -Step Parallelism -=================== -When a step does not depend on any other step, it is run immediately upon pipeline execution. However, executing too many pipeline steps in parallel can quickly exhaust available resources. Control the number of concurrent steps for a pipeline execution with :class:`sagemaker.workflow.parallelism_config.ParallelismConfiguration`. - -The following example uses :class:`sagemaker.workflow.parallelism_config.ParallelismConfiguration` to set the concurrent step limit to five. - -.. code-block:: python - - pipeline.create( - parallelism_config=ParallelismConfiguration(5), - ) - - -Caching Configuration -============================== -Executing the step without changing its configurations, inputs, or outputs can be a waste. Thus, we can enable caching for pipeline steps. When you use step signature caching, SageMaker Pipelines tries to use a previous run of your current pipeline step instead of running the step again. When previous runs are considered for reuse, certain arguments from the step are evaluated to see if any have changed. If any of these arguments have been updated, the step will execute again with the new configuration. - -When you turn on caching, you supply an expiration time (in `ISO8601 duration string format `__). The expiration time indicates how old a previous execution can be to be considered for reuse. - -.. code-block:: python - - cache_config = CacheConfig( - enable_caching=True, - expire_after="P30d" # 30-day - ) - -You can format your ISO8601 duration strings like the following examples: - -- :code:`p30d`: 30 days -- :code:`P4DT12H`: 4 days and 12 hours -- :code:`T12H`: 12 hours - -Caching is supported for the following step types: - -- :class:`sagemaker.workflow.steps.TrainingStep` -- :class:`sagemaker.workflow.steps.ProcessingStep` -- :class:`sagemaker.workflow.steps.TransformStep` -- :class:`sagemaker.workflow.steps.TuningStep` -- :class:`sagemaker.workflow.quality_check_step.QualityCheckStep` -- :class:`sagemaker.workflow.clarify_check_step.ClarifyCheckStep` -- :class:`sagemaker.workflow.emr_step.EMRStep` - -In order to create pipeline steps and eventually construct a SageMaker pipeline, you provide parameters within a Python script or notebook. The SageMaker Python SDK creates a pipeline definition by translating these parameters into SageMaker job attributes. Some of these attributes, when changed, cause the step to re-run (See `Caching Pipeline Steps `__ for a detailed list). Therefore, if you update a SDK parameter that is used to create such an attribute, the step will rerun. See the following discussion for examples of this in processing and training steps, which are commonly used steps in Pipelines. - -The following example creates a processing step: - -.. code-block:: python - - from sagemaker.workflow.pipeline_context import PipelineSession - from sagemaker.sklearn.processing import SKLearnProcessor - from sagemaker.workflow.steps import ProcessingStep - from sagemaker.dataset_definition.inputs import S3Input - from sagemaker.processing import ProcessingInput, ProcessingOutput - - pipeline_session = PipelineSession() - - framework_version = "0.23-1" - - sklearn_processor = SKLearnProcessor( - framework_version=framework_version, - instance_type="ml.m5.xlarge", - instance_count=processing_instance_count, - role=role, - sagemaker_session=pipeline_session - ) - - processor_args = sklearn_processor.run( - inputs=[ - ProcessingInput( - source="artifacts/data/abalone-dataset.csv", - input_name="abalone-dataset", - s3_input=S3Input( - local_path="/opt/ml/processing/input", - s3_uri="artifacts/data/abalone-dataset.csv", - s3_data_type="S3Prefix", - s3_input_mode="File", - s3_data_distribution_type="FullyReplicated", - s3_compression_type="None", - ) - ) - ], - outputs=[ - ProcessingOutput(output_name="train", source="/opt/ml/processing/train"), - ProcessingOutput(output_name="validation", source="/opt/ml/processing/validation"), - ProcessingOutput(output_name="test", source="/opt/ml/processing/test"), - ], - code="artifacts/code/process/preprocessing.py", - ) - - processing_step = ProcessingStep( - name="Process", - step_args=processor_args, - cache_config=cache_config - ) - -The following parameters from the example cause additional processing step iterations when you change them: - -- :code:`framework_version`: This parameter is used to construct the :code:`image_uri` for the `AppSpecification `__ attribute of the processing job. -- :code:`inputs`: Any :class:`ProcessingInputs` are passed through directly as job `ProcessingInputs `__. Input :code:`source` files that exist in the container’s local file system are uploaded to S3 and given a new :code:`S3_Uri`. If the S3 path changes, a new processing job is initiated. For examples of S3 paths, see the **S3 Artifact Folder Structure** section. -- :code:`code`: The code parameter is also packaged as a `ProcessingInput `__ job. For local files, a unique hash is created from the file. The file is then uploaded to S3 with the hash included in the path. When a different local file is used, a new hash is created and the S3 path for that `ProcessingInput `__ changes, initiating a new step run. For examples S3 paths, see the **S3 Artifact Folder Structure** section. - -The following example creates a training step: - -.. code-block:: python - - from sagemaker.sklearn.estimator import SKLearn - from sagemaker.workflow.steps import TrainingStep - - pipeline_session = PipelineSession() - - image_uri = sagemaker.image_uris.retrieve( - framework="xgboost", - region=region, - version="1.0-1", - py_version="py3", - instance_type="ml.m5.xlarge", - ) - - hyperparameters = { - "dataset_frequency": "H", - "timestamp_format": "yyyy-MM-dd hh:mm:ss", - "number_of_backtest_windows": "1", - "role_arn": role_arn, - "region": region, - } - - sklearn_estimator = SKLearn( - entry_point="train.py", - role=role_arn, - image_uri=container_image_uri, - instance_type=training_instance_type, - sagemaker_session=pipeline_session, - base_job_name="training_job", - hyperparameters=hyperparameters, - enable_sagemaker_metrics=True, - ) - - train_args = xgb_train.fit( - inputs={ - "train": TrainingInput( - s3_data=step_process.properties.ProcessingOutputConfig.Outputs[ - "train" - ].S3Output.S3Uri, - content_type="text/csv", - ), - "validation": TrainingInput( - s3_data=step_process.properties.ProcessingOutputConfig.Outputs[ - "validation" - ].S3Output.S3Uri, - content_type="text/csv", - ), - } - ) - - training_step = TrainingStep( - name="Train", - estimator=sklearn_estimator, - cache_config=cache_config - ) - -The following parameters from the example cause additional training step iterations when you change them: - -- :code:`image_uri`: The :code:`image_uri` parameter defines the image used for training, and is used directly in the `AlgorithmSpecification `__ attribute of the training job. -- :code:`hyperparameters`: All of the hyperparameters are used directly in the `HyperParameters `__ attribute for the training job. -- :code:`entry_point`: The entry point file is included in the training job’s `InputDataConfig Channel `__ array. A unique hash is created from the file (and any other dependencies), and then the file is uploaded to S3 with the hash included in the path. When a different entry point file is used, a new hash is created and the S3 path for that `InputDataConfig Channel `__ object changes, initiating a new step run. For examples of what the S3 paths look like, see the **S3 Artifact Folder Structure** section. -- :code:`inputs`: The inputs are also included in the training job’s `InputDataConfig `__. Local inputs are uploaded to S3. If the S3 path changes, a new training job is initiated. For examples of S3 paths, see the **S3 Artifact Folder Structure** section. - -S3 Artifact Folder Structure ----------------------------- - -You use the following S3 paths when uploading local input and code artifacts, and when saving output artifacts. - -*Processing* - -- Code: :code:`s3://bucket_name/pipeline_name/code//file.py`. The file could also be a tar.gz of source_dir and dependencies. -- Input Data: :code:`s3://bucket_name/pipeline_name/step_name/input/input_name/file.csv` -- Configuration: :code:`s3://bucket_name/pipeline_name/step_name/input/conf//configuration.json` -- Output: :code:`s3://bucket_name/pipeline_name//step_name/output/output_name` - -*Training* - -- Code: :code:`s3://bucket_name/code_location/pipeline_name/code//code.tar.gz` -- Output: The output paths for Training jobs can vary - the default output path is the root of the s3 bucket: :code:`s3://bucket_name`. For Training jobs created from a Tuning job, the default path includes the Training job name created by the Training platform, formatted as :code:`s3://bucket_name//output/model.tar.gz`. - -*Transform* - -- Output: :code:`s3://bucket_name/pipeline_name//step_name` - -.. warning:: - For input artifacts such as data or code files, the actual content of the artifacts is not tracked, only the S3 path. This means that if a file in S3 is updated and re-uploaded directly with an identical name and path, then the step does NOT run again. - - -Retry Policy -=============== - -We can configure step wise retry behavior for certain step types. During a pipeline step execution, there are two points in which you might encounter errors. - -1. You might encounter errors when trying to create or start a SageMaker job like a :code:`ProcessingJob` or :code:`TrainingJob`. -2. You might encounter errors when a SageMaker job like a :code:`ProcessingJob` or :code:`TrainingJob`. finishes with failures. - -There are two types of retry policies to handle these scenarios: - -- :class:`sagemaker.workflow.retry.StepRetryPolicy` -- :class:`sagemaker.workflow.retry.SageMakerJobStepRetryPolicy` - -The :code:`StepRetryPolicy` is used if service faults (like a network issue) or throttling are recognized when creating a SageMaker job. - -.. code-block:: python - - StepRetryPolicy( - exception_types=[ - StepExceptionTypeEnum.SERVICE_FAULT, - StepExceptionTypeEnum.THROTTLING, - ], - expire_after_min=5, - interval_seconds=10, - backoff_rate=2.0 - ) - - -Note: A pipeline step type that supports the :code:`StepRetryPolicy` will attempt exponential retries with a one-second interval by default for service faults and throttling. This behavior can be overridden using the policy above. - -The :code:`SageMakerJobStepRetryPolicy` is used if a failure reason is given after a job is done. There are many reasons why a job can fail. The :code:`SageMakerJobStepRetryPolicy` supports retry configuration for the following failures: - -- :code:`SageMaker.JOB_INTERNAL_ERROR` -- :code:`SageMaker.CAPACITY_ERROR` -- :code:`SageMaker.RESOURCE_LIMIT` - -The following example specifies that a SageMaker job should retry if it fails due to a resource limit exception. The job will retry exponentially, starting at an interval of 60 seconds, and will only attempt to retry this job for two hours total. - -.. code-block:: python - - SageMakerJobStepRetryPolicy( - exception_types=[SageMakerJobExceptionTypeEnum.RESOURCE_LIMIT] - expire_after_min=120, - interval_seconds=60, - backoff_rate=2.0 - ) - - -For more information, see `Retry Policy for Pipeline Steps`_ in the *Amazon SageMaker Developer Guide*. - -.. _Retry Policy for Pipeline Steps: https://docs.aws.amazon.com/sagemaker/latest/dg/pipelines-retry-policy.html. - -Model Step -=============== - -After model artifacts are produced by either a :code:`TrainingJob` or :code:`TuningJob`, you might want to create a SageMaker Model, or register that model to SageMaker Model Registry. This is where the :class:`sagemaker.workflow.model_step.ModelStep` comes in. - -Follow the example below to create a SageMaker Model and register it to SageMaker Model Registry using :class:`sagemaker.workflow.model_step.ModelStep`. - -.. code-block:: python - - step_train = TrainingStep(...) - model = Model( - image_uri=pytorch_estimator.training_image_uri(), - model_data=step_train.properties.ModelArtifacts.S3ModelArtifacts, - sagemaker_session=pipeline_session, - role=role, - ) - - # we might also want to create a SageMaker Model - step_model_create = ModelStep( - name="MyModelCreationStep", - step_args=model.create(instance_type="ml.m5.xlarge"), - ) - - # in addition, we might also want to register a model to SageMaker Model Registry - register_model_step_args = model.register( - content_types=["*"], - response_types=["application/json"], - inference_instances=["ml.m5.xlarge"], - transform_instances=["ml.m5.xlarge"], - description="MyModelPackage", - ) - - step_model_registration = ModelStep( - name="MyModelRegistration", - step_args=register_model_step_args, - ) - ... - -When model repacking is needed, :class:`sagemaker.workflow.model_step.ModelStep`. is a collection of steps. Model repacking unpacks model data, creates a new model tarball file that includes any custom inference scripts, and uploads this tarball file to Amazon S3. Once a model is repacked, it is ready to deploy to an endpoint or be registered as a model package. - -:class:`sagemaker.workflow.model_step.ModelStep` uses the provided inputs to automatically detect if a repack is needed. If a repack is needed, :class:`sagemaker.workflow.steps.TrainingStep` is added to the step collection for that repack. Then, either :class:`sagemaker.workflow.steps.CreateModelStep` or :class:`sagemaker.workflow.step_collections.RegisterModelStep` will be chained after it. - -MonitorBatchTransform Step -=========================== - -MonitorBatchTransformStep is a new step type that allows customers to use SageMaker Model Monitor with batch transform jobs that are a part of their pipeline. Using this step, customers can set up the following monitors for their batch transform job: data quality, model quality, model bias, and feature attribution. - - -When configuring this step, customers have the flexibility to run the monitoring job before or after the transform job executes. There is an additional flag called :code:`fail_on_violation` which will fail the step if set to true and there is a monitoring violation, or will continue to execute the step if set to false. - -Here is an example showing you how to configure a :class:`sagemaker.workflow.monitor_batch_transform_step.MonitorBatchTransformStep` with a Data Quality monitor. - -.. code-block:: python - - from sagemaker.workflow.pipeline_context import PipelineSession - - from sagemaker.transformer import Transformer - from sagemaker.model_monitor import DefaultModelMonitor - from sagemaker.model_monitor.dataset_format import DatasetFormat - from sagemaker.workflow.check_job_config import CheckJobConfig - from sagemaker.workflow.quality_check_step import DataQualityCheckConfig - - from sagemaker.workflow.parameters import ParameterString - - pipeline_session = PipelineSession() - - transform_input_param = ParameterString( - name="transform_input", - default_value=f"s3://my-bucket/my-prefix/my-transform-input", - ) - - # the resource configuration for the monitoring job - job_config = CheckJobConfig( - role=role, - instance_count=1, - instance_type="ml.m5.xlarge", - ... - ) - -The following code sample demonstrates how to set up an on-demand batch transform *data quality* monitor: - -.. code-block:: python - - # configure your transformer - transformer = Transformer(..., sagemaker_session=pipeline_session) - transform_arg = transformer.transform( - transform_input_param, - content_type="text/csv", - split_type="Line", - ... - ) - - data_quality_config = DataQualityCheckConfig( - baseline_dataset=transform_input_param, - dataset_format=DatasetFormat.csv(header=False), - output_s3_uri="s3://my-report-path", - ) - - from sagemaker.workflow.monitor_batch_transform_step import MonitorBatchTransformStep - - transform_and_monitor_step = MonitorBatchTransformStep( - name="MyMonitorBatchTransformStep", - transform_step_args=transform_arg, - monitor_configuration=data_quality_config, - check_job_configuration=job_config, - # since data quality only looks at the inputs, - # so there is no need to wait for the transform output. - monitor_before_transform=True, - # if violation is detected in the monitoring, and you want to skip it - # and continue running batch transform, you can set fail_on_violation - # to false. - fail_on_violation=False, - supplied_baseline_statistics="s3://my-baseline-statistics.json", - supplied_baseline_constraints="s3://my-baseline-constraints.json", - ) - ... - -The same example can be extended for model quality, bias, and feature attribute monitoring. - -.. warning:: - Note that to run on-demand model quality, you will need to have the ground truth data ready. When running the transform job, include the ground truth inside your transform input, and join the transform inference input and output. Then you can indicate which attribute or column name/index points to the ground truth when run the monitoring job. - -.. code-block:: python - - transformer = Transformer(..., sagemaker_session=pipeline_session) - - transform_arg = transformer.transform( - transform_input_param, - content_type="text/csv", - split_type="Line", - # Note that we need to join both the inference input and output - # into transform outputs. The inference input needs to have the ground truth. - # details can be found here - # https://docs.aws.amazon.com/sagemaker/latest/dg/batch-transform-data-processing.html - join_source="Input", - # We need to exclude the ground truth inside the inference input - # before passing it to the prediction model. - # Assume the first column of our csv file is the ground truth - input_filter="$[1:]", - ... - ) - - model_quality_config = ModelQualityCheckConfig( - baseline_dataset=transformer.output_path, - problem_type="BinaryClassification", - dataset_format=DatasetFormat.csv(header=False), - output_s3_uri="s3://my-output", - # assume the model output is at column idx 10 - inference_attribute="_c10", - # As pointed out previously, the first column is the ground truth. - ground_truth_attribute="_c0", - ) - from sagemaker.workflow.monitor_batch_transform_step import MonitorBatchTransformStep - - transform_and_monitor_step = MonitorBatchTransformStep( - name="MyMonitorBatchTransformStep", - transform_step_args=transform_arg, - monitor_configuration=data_quality_config, - check_job_configuration=job_config, - # model quality job needs the transform outputs, therefore - # monitor_before_transform can not be true for model quality - monitor_before_transform=False, - fail_on_violation=True, - supplied_baseline_statistics="s3://my-baseline-statistics.json", - supplied_baseline_constraints="s3://my-baseline-constraints.json", - ) - ... - -================= -Example Notebooks -================= - -Feel free to explore the `Amazon SageMaker Example Notebook`_ to explore and experiment with specific SageMaker use cases. The following Notebooks demonstrate examples related to the SageMaker Model Building Pipeline: - -.. _Amazon SageMaker Example Notebook: https://sagemaker-examples.readthedocs.io/en/latest/ - -- `Orchestrate Jobs to Train and Evaluate Models with Amazon SageMaker Pipelines`_ -- `Glue ETL as part of a SageMaker pipeline using Pipeline Callback Step`_ -- `SageMaker Pipelines Lambda Step`_ -- `SageMaker Pipelines integration with Model Monitor and Clarify`_ -- `SageMaker Pipelines Tuning Step`_ - -.. _Orchestrate Jobs to Train and Evaluate Models with Amazon SageMaker Pipelines: https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-pipelines/tabular/abalone_build_train_deploy/sagemaker-pipelines-preprocess-train-evaluate-batch-transform.ipynb -.. _Glue ETL as part of a SageMaker pipeline using Pipeline Callback Step: https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-pipelines/tabular/custom_callback_pipelines_step/sagemaker-pipelines-callback-step.ipynb -.. _SageMaker Pipelines Lambda Step: https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-pipelines/tabular/lambda-step/sagemaker-pipelines-lambda-step.ipynb -.. _SageMaker Pipelines integration with Model Monitor and Clarify: https://github.com/aws/amazon-sagemaker-examples/tree/main/sagemaker-pipelines/tabular/model-monitor-clarify-pipelines -.. _SageMaker Pipelines Tuning Step: https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-pipelines/tabular/tuning-step/sagemaker-pipelines-tuning-step.ipynb - -=================== -Limitations -=================== - -The SageMaker Model Building Pipeline Python SDK offers abstractions to help you construct a pipeline definition at ease. However, there are certain limitations. Read on for information about known issues. If you discover additional limitations, open an issue in the `sagemaker-python-sdk`_ repository. - -.. _sagemaker-python-sdk: https://github.com/aws/sagemaker-python-sdk/issues - - -Parameterization -================ - -Parameterization is crucial for pipeline composition, it allows you to assign values to properties that are not available until runtime. However, there are limitations. - -Incompatibility with other SageMaker Python SDK modules ---------------------------------------------------------- - -Pipeline parameterization includes pipeline parameters like :class:`sagemaker.workflow.parameters.ParameterString` and :class:`sagemaker.workflow.parameters.ParameterInteger`, property reference, functions like :class:`sagemaker.workflow.functions.Join` and :class:`sagemaker.workflow.functions.JsonGet`, and pipeline execution variables. Pipeline parameterization might not be supported with 100% compatibility when used with other SageMaker Python SDK modules. - -For example, when running a training job in script mode, you cannot parameterize the :code:`entry_point` value for estimators inherited from :class:`sagemaker.estimator.EstimatorBase` because a SageMaker EstimatorBase expects an :code:`entry_point` to point to a local Python source file. - -.. code-block:: python - - # An example of what not to do - script_path = ParameterString(name="MyScript", default="s3://my-bucket/my-script.py") - xgb_script_mode_estimator = XGBoost( - entry_point=script_path, - framework_version="1.5-1", - role=role, - ... - ) - -Not all arguments can be parameterized ---------------------------------------- - -Many arguments for class constructors or methods from other modules can be parameterized, but not all of them. For example, Inputs or outputs can be parameterized when calling :code:`processor.run`. - -.. code-block:: python - - instance_count = ParameterInteger(name="InstanceCount", default_value=2) - process_s3_input_url = ParameterString(name="ProcessingInputUrl") - - processor = Processor( - instance_type=instance_count, - instance_count="ml.m5.xlarge", - ... - ) - processor.run(inputs=ProcessingInput(source=process_s3_input_url), ...) - -However, you cannot parameterize :code:`git_config` when calling :code:`processor.run`. This is because the source code needs to be downloaded, packaged, and uploaded S3 at compile time and parameterization can only be evaluated at run time. - -Not all built-in Python operations can be applied to parameters ------------------------------------------------------------------ - -Another limitation of parameterization is that not all built-in Python operations can be applied to a pipeline parameter. For example, You cannot concatenate the pipeline variables using Python primitives: - -.. code-block:: python - - # An example of what not to do - my_string = "s3://{}/training".format(ParameterString(name="MyBucket", default_value="")) - - # Another example of what not to do - int_param = str(ParameterInteger(name="MyBucket", default_value=1)) - - # Instead, if you want to convert the parameter to string type, do - int_param.to_string() - -The concatenation example above will not work, as the :class:`sagemaker.workflow.parameters.ParameterString` can only be evaluated at run time. Instead, you can concatenate parameters using :class:`sagemaker.workflow.functions.Join`: - - -This concatenation of :code:`my_string` will not work, as the parameter :code:`MyBucket` can only be evaluated at run time. Instead, the same concatenation can be achieved using function :class:`sagemaker.workflow.functions.Join`: - -.. code-block:: python - - my_string = Join(on="", values=[ - "s3://", - ParameterString(name="MyBucket", default_value=""), - "/training"] - ) - -Pipeline parameters can only be evaluated at run time. If a pipeline parameter needs to be evaluated at compile time, then it will throw an exception. - -==================================== -Pipeline Composition Alternative -==================================== - -The SageMaker Python SDK provides you with tools for pipeline composition. Under the hood, it produces a pipeline definition JSON file. If you want to author the pipeline definition by hand, you can follow the `SageMaker Pipeline Definition JSON Schema`_ - -.. _SageMaker Pipeline Definition JSON Schema: https://aws-sagemaker-mlops.github.io/sagemaker-model-building-pipeline-definition-JSON-schema/index.html diff --git a/doc/amazon_sagemaker_model_monitoring.rst b/doc/amazon_sagemaker_model_monitoring.rst deleted file mode 100644 index e493c24e2f..0000000000 --- a/doc/amazon_sagemaker_model_monitoring.rst +++ /dev/null @@ -1,204 +0,0 @@ - -############################## -Amazon SageMaker Model Monitor -############################## - - -Amazon SageMaker Model Monitor allows you to create a set of baseline statistics and constraints using the data with which your model was trained, then set up a schedule to monitor the predictions made on your endpoint. - -.. contents:: - -Background -========== - -Amazon SageMaker provides every developer and data scientist with the ability to build, train, and deploy machine learning models quickly. Amazon SageMaker is a fully-managed service that encompasses the entire machine learning workflow. You can label and prepare your data, choose an algorithm, train a model, and then tune and optimize it for deployment. You can deploy your models to production with Amazon SageMaker to make predictions at lower costs than was previously possible. - -Amazon SageMaker Model Monitor enables you to capture the input, output and metadata for the invocations of the models that you deploy. It also enables you to analyze the data and monitor its quality. In this notebook, you learn how Amazon SageMaker enables these capabilities. - -Setup -===== - -To get started, you must satisfy the following prerequisites: - -* Specify an AWS Region to host your model. -* Create an IAM role ARN that is used to give Amazon SageMaker access to your data in Amazon Simple Storage Service (Amazon S3). See the `AWS IAM documentation `__ for how to fine tune the permissions needed. -* Create an S3 bucket used to store the data used to train your model, any additional model data, and the data captured from model invocations. You can use the same bucket for these, or use separate buckets (e.g. if you want different security policies). - -Capture real-time inference data from Amazon SageMaker endpoints -================================================================ - -To enable data capture for monitoring the model data quality, specify the new capture option called ``DataCaptureConfig`` when deploying to an endpoint. You can choose to capture the request payload, the response payload or both with this configuration. The capture config applies to all variants. For more about the ``DataCaptureConfig`` object, see the `API documentation `__. - -.. code:: python - - from sagemaker.model_monitor import DataCaptureConfig - - data_capture_config = DataCaptureConfig( - enable_capture=True, - sampling_percentage=100, - destination_s3_uri='s3://path/for/data/capture' - ) - - predictor = model.deploy( - initial_instance_count=1, - instance_type='ml.m4.xlarge', - data_capture_config=data_capture_config - ) - -When you invoke the endpoint, the request and response payload, along with some additional metadata, is saved in the Amazon S3 location that you have specified in the ``DataCaptureConfig``. You should expect to see different files from different time periods, organized based on the hour in which the invocation occurred. The format of the Amazon S3 path is: - -.. code:: - - s3://{destination-bucket-prefix}/{endpoint-name}/{variant-name}/yyyy/mm/dd/hh/filename.jsonl - -You can use the ``S3Downloader`` utility to view and download the captured data in Amazon S3: - -.. code:: python - - from sagemaker.s3 import S3Downloader - - # Invoke the endpoint - predictor.predict(data) - - # Get a list of S3 URIs - S3Downloader.list('s3://path/for/data/capture') - - # Read a specific file - S3Downloader.read_file('s3://path/for/data/capture/endpoint-name/variant-name/2020/01/01/00/filename.jsonl') - -The contents of the single captured file should be all the data captured in an Amazon SageMaker-specific JSON-line formatted file. Each inference request is captured in a single line in the jsonl file. The line contains both the input and output merged together. - -Baselining and continuous monitoring -==================================== - -In addition to collecting the data, Amazon SageMaker provides the capability for you to monitor and evaluate the data observed by the endpoints. Two tasks are needed for this: - -* Create a baseline with which you compare the realtime traffic. -* Setup a schedule to continuously evaluate and compare against the baseline after it has been created. - -Constraint suggestion with baseline/training dataset ----------------------------------------------------- - -You can ask Amazon SageMaker to suggest a set of baseline constraints and generate descriptive statistics that characterize the data in a training dataset stored in Amazon S3. ``DefaultModelMonitor.suggest_baseline()`` starts a Processing Job using a Model Monitor container provided by Amazon SageMaker to generate the constraints. You can read more about ``suggest_baseline()`` in the `API documentation `__. - -.. code:: python - - from sagemaker.model_monitor import DefaultModelMonitor - from sagemaker.model_monitor.dataset_format import DatasetFormat - - my_monitor = DefaultModelMonitor( - role=role, - instance_count=1, - instance_type='ml.m5.xlarge', - volume_size_in_gb=20, - max_runtime_in_seconds=3600, - ) - - my_monitor.suggest_baseline( - baseline_dataset='s3://path/to/training-dataset-with-header.csv', - dataset_format=DatasetFormat.csv(header=True), - ) - -With the monitor object, you can also explore the generated constraints and statistics: - -.. code:: python - - import pandas as pd - - baseline_job = my_monitor.latest_baselining_job - schema_df = pd.io.json.json_normalize(baseline_job.baseline_statistics().body_dict["features"]) - schema_df.head(10) - - constraints_df = pd.io.json.json_normalize(baseline_job.suggested_constraints().body_dict["features"]) - constraints_df.head(10) - -Analyze the data collected for data quality issues --------------------------------------------------- - -You can also analyze and monitor the data with Monitoring Schedules. - -Using ``DefaultMonitor.create_monitoring_schedule()``, you can create a model monitoring schedule for an endpoint that compares the baseline resources (constraints and statistics) against the realtime traffic. For more about this method, see the `API documentation `__. - -.. code:: python - - from sagemaker.model_monitor import CronExpressionGenerator - - my_monitor.create_monitoring_schedule( - monitor_schedule_name='my-monitoring-schedule', - endpoint_input=predictor.endpoint_name, - statistics=my_monitor.baseline_statistics(), - constraints=my_monitor.suggested_constraints(), - schedule_cron_expression=CronExpressionGenerator.hourly(), - ) - -The schedule starts jobs at the specified interval. - -.. note:: - - Even for an hourly schedule, Amazon SageMaker has a buffer period of 20 minutes to schedule your execution. This is expected and done for load balancing on the backend. - -Once the executions have started, you can use ``list_executions()`` to view them: - -.. code:: python - - executions = my_monitor.list_executions() - -You can also view the status of a specific execution: - -.. code:: python - - latest_execution = executions[-1] - - latest_execution.describe()['ProcessingJobStatus'] - latest_execution.describe()['ExitMessage'] - -Here are the possible terminal states and what each of them means: - -* ``Completed`` - This means the monitoring execution completed and no issues were found in the violations report. -* ``CompletedWithViolations`` - This means the execution completed, but constraint violations were detected. -* ``Failed`` - The monitoring execution failed, maybe due to client error (perhaps incorrect role premissions) or infrastructure issues. Further examination of the FailureReason and ExitMessage is necessary to identify what exactly happened. -* ``Stopped`` - job exceeded the max runtime or was manually stopped. - -You can also get the S3 URI for the output with ``latest_execution.output.destination`` and analyze the results. - -Visualize results -================= - -You can use the monitor object to gather reports for visualization: - -.. code:: python - - suggested_constraints = my_monitor.suggested_constraints() - baseline_statistics = my_monitor.baseline_statistics() - - latest_monitoring_violations = my_monitor.latest_monitoring_constraint_violations() - latest_monitoring_statistics = my_monitor.latest_monitoring_statistics() - -For a tutorial on how to visualize the results, see `SageMaker Model Monitor - visualizing monitoring results `__. - -Delete the resources -==================== - -When deleting an endpoint, you need to first delete the monitoring schedule: - -.. code:: python - - my_monitor.delete_monitoring_schedule() - - predictor.delete_endpoint() - predictor.delete_model() - -Learn More -========== - -Further documentation ---------------------- - -* API documentation: https://sagemaker.readthedocs.io/en/stable/model_monitor.html -* AWS documentation: https://docs.aws.amazon.com/sagemaker/latest/dg/model-monitor.html -* ``S3Downloader``: https://sagemaker.readthedocs.io/en/stable/s3.html#sagemaker.s3.S3Downloader - -Notebook examples ------------------ - -Consult our notebook examples for in-depth tutorials: https://github.com/awslabs/amazon-sagemaker-examples/tree/master/sagemaker_model_monitor diff --git a/doc/amazon_sagemaker_processing.rst b/doc/amazon_sagemaker_processing.rst deleted file mode 100644 index ac168578cd..0000000000 --- a/doc/amazon_sagemaker_processing.rst +++ /dev/null @@ -1,247 +0,0 @@ -########################### -Amazon SageMaker Processing -########################### - - -Amazon SageMaker Processing allows you to run steps for data pre- or post-processing, feature engineering, data validation, or model evaluation workloads on Amazon SageMaker. - -.. contents:: - -Background -========== - -Amazon SageMaker lets developers and data scientists train and deploy machine learning models. With Amazon SageMaker Processing, you can run processing jobs for data processing steps in your machine learning pipeline. Processing jobs accept data from Amazon S3 as input and store data into Amazon S3 as output. - -.. image:: ./amazon_sagemaker_processing_image1.png - -Setup -===== - -The fastest way to get started with Amazon SageMaker Processing is by running a Jupyter notebook. You can follow the `Getting Started with Amazon SageMaker`_ guide to start running notebooks on Amazon SageMaker. - -.. _Getting Started with Amazon SageMaker: https://docs.aws.amazon.com/sagemaker/latest/dg/gs.html - -You can run notebooks on Amazon SageMaker that demonstrate end-to-end examples of using processing jobs to perform data pre-processing, feature engineering and model evaluation steps. See `Learn More`_ at the bottom of this page for more in-depth information. - - -Data Pre-Processing and Model Evaluation with scikit-learn -========================================================== - -You can run a scikit-learn script to do data processing on SageMaker using the :class:`sagemaker.sklearn.processing.SKLearnProcessor` class. - -You first create a ``SKLearnProcessor`` - -.. code:: python - - from sagemaker.sklearn.processing import SKLearnProcessor - - sklearn_processor = SKLearnProcessor( - framework_version="0.20.0", - role="[Your SageMaker-compatible IAM role]", - instance_type="ml.m5.xlarge", - instance_count=1, - ) - -Then you can run a scikit-learn script ``preprocessing.py`` in a processing job. In this example, our script takes one input from S3 and one command-line argument, processes the data, then splits the data into two datasets for output. When the job is finished, we can retrive the output from S3. - -.. code:: python - - from sagemaker.processing import ProcessingInput, ProcessingOutput - - sklearn_processor.run( - code="preprocessing.py", - inputs=[ - ProcessingInput(source="s3://your-bucket/path/to/your/data", destination="/opt/ml/processing/input"), - ], - outputs=[ - ProcessingOutput(output_name="train_data", source="/opt/ml/processing/train"), - ProcessingOutput(output_name="test_data", source="/opt/ml/processing/test"), - ], - arguments=["--train-test-split-ratio", "0.2"], - ) - - preprocessing_job_description = sklearn_processor.jobs[-1].describe() - -For an in-depth look, please see the `Scikit-learn Data Processing and Model Evaluation`_ example notebook. - -.. _Scikit-learn Data Processing and Model Evaluation: https://github.com/awslabs/amazon-sagemaker-examples/blob/master/sagemaker_processing/scikit_learn_data_processing_and_model_evaluation/scikit_learn_data_processing_and_model_evaluation.ipynb - - -Data Processing with Spark -============================================ -SageMaker provides two classes for customers to run Spark applications: :class:`sagemaker.spark.processing.PySparkProcessor` and :class:`sagemaker.spark.processing.SparkJarProcessor` - - -PySparkProcessor ---------------------- - -You can use the :class:`sagemaker.spark.processing.PySparkProcessor` class to run PySpark scripts as processing jobs. - -This example shows how you can take an existing PySpark script and run a processing job with the :class:`sagemaker.spark.processing.PySparkProcessor` class and the pre-built SageMaker Spark container. - -First you need to create a :class:`PySparkProcessor` object - -.. code:: python - - from sagemaker.processing import PySparkProcessor, ProcessingInput - - spark_processor = PySparkProcessor( - base_job_name="sm-spark", - framework_version="2.4", - py_version="py37", - container_version="1", - role="[Your SageMaker-compatible IAM role]", - instance_count=2, - instance_type="ml.c5.xlarge", - max_runtime_in_seconds=1200, - image_uri="your-image-uri" - ) - -The ``framework_version`` is the spark version where the script will be running. -``py_version`` and ``container_version`` are two new parameters you can specify in the constructor. They give you more flexibility to select the container version to avoid any backward incompatibilities and unnecessary dependency upgrade. - -If you just specify the ``framework_version``, Sagemaker will default to a python version and the latest container version. To pin to an exact version of the SageMaker Spark container you need to specify all the three parameters: ``framework_version``, ``py_version`` and ``container_version``. - -You can also specify the ``image_uri`` and it will override all the three parameters. - -Note that ``command`` option will not be supported on either :class:`PySparkProcessor` or :class:`SparkJarProcessor`. If you want to run the script on your own container, please use :class:`ScriptProcessor` instead. - -Then you can run your existing spark script ``preprocessing.py`` in a processing job. - -.. code:: python - - spark_processor.run( - submit_app="preprocess.py", - submit_py_files=["module.py", "lib.egg"], - submit_jars=["lib.jar", "lib2.jar"], - submit_files=["file.txt", "file2.csv"], - arguments=["s3_input_bucket", bucket, - "s3_input_key_prefix", input_prefix, - "s3_output_bucket", bucket, - "s3_output_key_prefix", input_preprocessed_prefix], - spark_event_logs_s3_uri="s3://your-bucket/your-prefix/store-spark-events" - ) - -``submit_app`` is the local relative path or s3 path of your python script, it's ``preprocess.py`` in this case. - -You can also specify any python or jar dependencies or files that your script depends on with ``submit_py_files``, ``submit_jars`` and ``submit_files``. - -``submit_py_files`` is a list of .zip, .egg, or .py files to place on the PYTHONPATH for Python apps. ``submit_jars`` is a list of jars to include on the driver and executor classpaths. ``submit_files`` is list of files to be placed in the working directory of each executor. File paths of these files in executors can be accessed via SparkFiles.get(fileName). - -Each item in the list can be either s3 path or local path, and if you have dependencies stored both in s3 and locally, you can put all of them in ``submit_py_files``, ``submit_jars``, and ``submit_files`` - -Just like using the ScriptProcessor, you can pass any arguments to your script by specifying ``arguments`` parameter. In this example, four arguments are passed to the script to get and upload data from/to s3. - -To support Spark history server, you can specify the parameter ``spark_event_logs_s3_uri`` when you invoke run() method to continuously upload spark events to s3. Note that the performance will be slightly impacted if you decide to publish spark event to s3. - -Spark History Server ---------------------- - -While script is running, or after script has run, you can view spark UI by running history server locally or in the notebook. By default, the s3 URI you provided in previous ``run()`` method will be used as spark event source, but you can also specify a different URI. Last but not the least, you can terminate the history server with ``terminate_history_server()``. Note that only one history server process will be running at a time. - -Here's an example to start and terminate history server - -.. code:: python - - spark_processor.start_history_server() - spark_processor.terminate_history_server() - -You don't always have to run the script first to start history server, you can also specify the s3 URI with spark event logs stored. For example - -.. code:: python - - spark_processor.start_history_server(spark_event_logs_s3_uri="s3://your-bucket/your-prefix/store-spark-events") - -To successfully run the history server, first you need to make sure ``docker`` is installed in your machine. Then you need to configure your aws credentials with S3 read permission. Last but not the least, you need to either invoke ``run()`` method with ``spark_event_logs_s3_uri`` first, or specify the ``spark_event_logs_s3_uri`` in ``start_history_server()`` method, otherwise it will fail. - -SparkJarProcessor ---------------------- - -Supposed that you have the jar file "preprocessing.jar" stored in the same directory as you are now, and the java package is ``com.path.to.your.class.PreProcessing.java`` -Here's an example of using PySparkProcessor. - -.. code:: python - - spark = SparkJarProcessor( - base_job_name="sm-spark-java", - image_uri=beta_image_uri, - role=role, - instance_count=2, - instance_type="ml.c5.xlarge", - max_runtime_in_seconds=1200, - ) - - spark.run( - submit_app="preprocessing.jar", - submit_class="com.amazonaws.sagemaker.spark.test.HelloJavaSparkApp", - arguments=["--input", input_s3_uri, "--output", output_s3_uri] - ) - -:class:`SparkJarProcessor` is very similar to :class:`PySparkProcessor` except that the ``run()`` method takes only jar file path, configured by ``submit_app`` parameter, and ``submit_class`` parameter, which is equivalent to "--class" option for "spark-submit" command. - -Configuration Override ----------------------- - -Overriding Spark configuration is crucial for a number of tasks such as tuning your Spark application or configuring the hive metastore. Using our Python SDK, you can easily override Spark/Hive/Hadoop configuration. - -An example usage would be overriding Spark executor memory/cores as demonstrated in the following code snippet: - -.. code:: python - - spark_processor = PySparkProcessor( - base_job_name="sm-spark", - image_uri=beta_image_uri, - role=role, - instance_count=2, - instance_type="ml.c5.xlarge", - max_runtime_in_seconds=1200, - ) - - configuration = [{ - "Classification": "spark-defaults", - "Properties": {"spark.executor.memory": "2g", "spark.executor.cores": "1"}, - }] - - spark_processor.run( - submit_app="./code/preprocess.py", - arguments=["s3_input_bucket", bucket, - "s3_input_key_prefix", input_prefix_abalone, - "s3_output_bucket", bucket, - "s3_output_key_prefix", input_preprocessed_prefix_abalone], - configuration=configuration, - logs=False - ) - -For an in-depth look of how to write your configuration, please see `Amazon EMR Configuring Applications`_ document. - -.. _Amazon EMR Configuring Applications: https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-configure-apps.html - -For an in-depth look, please see the `Feature Transformation with Spark`_ example notebook. - -.. _Feature Transformation with Spark: https://github.com/awslabs/amazon-sagemaker-examples/blob/master/sagemaker_processing/feature_transformation_with_sagemaker_processing/feature_transformation_with_sagemaker_processing.ipynb - - -Learn More -========== - -Processing class documentation ------------------------------- - -- :class:`sagemaker.processing.Processor` -- :class:`sagemaker.processing.ScriptProcessor` -- :class:`sagemaker.sklearn.processing.SKLearnProcessor` -- :class:`sagemaker.spark.processing.PySparkProcessor` -- :class:`sagemaker.spark.processing.SparkJarProcessor` -- :class:`sagemaker.processing.ProcessingInput` -- :class:`sagemaker.processing.ProcessingOutput` -- :class:`sagemaker.processing.ProcessingJob` - - -Further documentation ---------------------- - -- `Processing class documentation `_ -- `AWS Documentation `_ -- `AWS Notebook examples `_ -- `Processing API documentation `_ -- `Processing container specification `_ diff --git a/doc/amazon_sagemaker_processing_image1.png b/doc/amazon_sagemaker_processing_image1.png deleted file mode 100644 index 1cd4ab5e28..0000000000 Binary files a/doc/amazon_sagemaker_processing_image1.png and /dev/null differ diff --git a/doc/api/governance/index.rst b/doc/api/governance/index.rst deleted file mode 100644 index 8df0ef2ff4..0000000000 --- a/doc/api/governance/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -############### -Governance APIs -############### - -.. toctree:: - :maxdepth: 1 - :glob: - - * diff --git a/doc/api/governance/model_card.rst b/doc/api/governance/model_card.rst deleted file mode 100644 index d8f805e408..0000000000 --- a/doc/api/governance/model_card.rst +++ /dev/null @@ -1,49 +0,0 @@ -Amazon SageMaker Model Cards ----------------------------- - -For more information about using model cards with the SageMaker Python SDK, -see `Amazon SageMaker Model Cards `__ in the *Amazon SageMaker Developer Guide*. - -.. currentmodule:: sagemaker.model_card - -.. autoclass:: AdditionalInformation - :show-inheritance: - -.. autoclass:: Environment - :show-inheritance: - -.. autoclass:: EvaluationJob - :show-inheritance: - -.. autoclass:: Function - :show-inheritance: - -.. autoclass:: IntendedUses - :show-inheritance: - -.. autoclass:: Metric - :show-inheritance: - -.. autoclass:: MetricGroup - :show-inheritance: - -.. autoclass:: ModelCard - :show-inheritance: - -.. autoclass:: ModelOverview - :show-inheritance: - -.. autoclass:: ObjectiveFunction - :show-inheritance: - -.. autoclass:: TrainingDetails - :show-inheritance: - -.. autoclass:: TrainingJobDetails - :show-inheritance: - -.. autoclass:: BusinessDetails - :show-inheritance: - -.. autoclass:: HyperParameter - :show-inheritance: diff --git a/doc/api/index.rst b/doc/api/index.rst deleted file mode 100644 index bd639ffea8..0000000000 --- a/doc/api/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -#### -APIs -#### - -The SageMaker Python SDK consists of a variety classes for preparing data, training, inference and general utility: - -.. toctree:: - :maxdepth: 2 - - prep_data/feature_store - training/index - training/distributed - inference/index - governance/index - utility/index diff --git a/doc/api/inference/async_inference.rst b/doc/api/inference/async_inference.rst deleted file mode 100644 index 493cab40eb..0000000000 --- a/doc/api/inference/async_inference.rst +++ /dev/null @@ -1,19 +0,0 @@ -Async Inference ------------------ - -This module contains classes related to Amazon Sagemaker Async Inference - -.. automodule:: sagemaker.async_inference.async_inference_config - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.async_inference.async_inference_response - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.async_inference.waiter_config - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/inference/deserializers.rst b/doc/api/inference/deserializers.rst deleted file mode 100644 index 57e579562d..0000000000 --- a/doc/api/inference/deserializers.rst +++ /dev/null @@ -1,12 +0,0 @@ -Deserializers -------------- - -.. automodule:: sagemaker.base_deserializers - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.deserializers - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/inference/explainer.rst b/doc/api/inference/explainer.rst deleted file mode 100644 index d522e6c1dc..0000000000 --- a/doc/api/inference/explainer.rst +++ /dev/null @@ -1,16 +0,0 @@ -Online Explainability ---------------------- - -This module contains classes related to Amazon Sagemaker Clarify Online Explainability - -.. automodule:: sagemaker.explainer.explainer_config - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.explainer.clarify_explainer_config - :members: - :undoc-members: - :show-inheritance: - - diff --git a/doc/api/inference/index.rst b/doc/api/inference/index.rst deleted file mode 100644 index 1efdabea54..0000000000 --- a/doc/api/inference/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -############## -Inference APIs -############## - -.. toctree:: - :maxdepth: 1 - :glob: - - * diff --git a/doc/api/inference/model.rst b/doc/api/inference/model.rst deleted file mode 100644 index d52ca3500a..0000000000 --- a/doc/api/inference/model.rst +++ /dev/null @@ -1,25 +0,0 @@ -Model ------ - -.. autoclass:: sagemaker.model.Model - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - -.. autoclass:: sagemaker.jumpstart.model.JumpStartModel - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - -.. autoclass:: sagemaker.model.FrameworkModel - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.model.ModelPackage - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/api/inference/model_builder.rst b/doc/api/inference/model_builder.rst deleted file mode 100644 index 3099441850..0000000000 --- a/doc/api/inference/model_builder.rst +++ /dev/null @@ -1,16 +0,0 @@ -Model Builder -------------- - -This module contains classes related to Amazon Sagemaker Model Builder - -.. autoclass:: sagemaker.serve.builder.model_builder.ModelBuilder - -.. automethod:: sagemaker.serve.builder.model_builder.ModelBuilder.build - -.. automethod:: sagemaker.serve.builder.model_builder.ModelBuilder.save - -.. autoclass:: sagemaker.serve.spec.inference_spec.InferenceSpec - -.. autoclass:: sagemaker.serve.builder.schema_builder.SchemaBuilder - -.. autoclass:: sagemaker.serve.marshalling.custom_payload_translator.CustomPayloadTranslator diff --git a/doc/api/inference/model_collection.rst b/doc/api/inference/model_collection.rst deleted file mode 100644 index 7281350ae6..0000000000 --- a/doc/api/inference/model_collection.rst +++ /dev/null @@ -1,8 +0,0 @@ -Model Collection ----------------- - -.. automodule:: sagemaker.collection - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/api/inference/model_monitor.rst b/doc/api/inference/model_monitor.rst deleted file mode 100644 index 3ca63c1713..0000000000 --- a/doc/api/inference/model_monitor.rst +++ /dev/null @@ -1,48 +0,0 @@ -Model Monitor -------------- - - -.. automodule:: sagemaker.model_monitor.model_monitoring - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.model_monitor.monitoring_files - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.model_monitor.dataset_format - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.model_monitor.data_capture_config - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.model_monitor.cron_expression_generator - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.model_monitor.clarify_model_monitoring - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.model_metrics - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.drift_check_baselines - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.model_monitor.data_quality_monitoring_config - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/inference/multi_data_model.rst b/doc/api/inference/multi_data_model.rst deleted file mode 100644 index fec64a172e..0000000000 --- a/doc/api/inference/multi_data_model.rst +++ /dev/null @@ -1,7 +0,0 @@ -MultiDataModel --------------- - -.. automodule:: sagemaker.multidatamodel - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/inference/pipeline.rst b/doc/api/inference/pipeline.rst deleted file mode 100644 index ea4bdb5937..0000000000 --- a/doc/api/inference/pipeline.rst +++ /dev/null @@ -1,7 +0,0 @@ -PipelineModel -------------- - -.. autoclass:: sagemaker.pipeline.PipelineModel - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/inference/predictor_async.rst b/doc/api/inference/predictor_async.rst deleted file mode 100644 index e5b83e2324..0000000000 --- a/doc/api/inference/predictor_async.rst +++ /dev/null @@ -1,9 +0,0 @@ -AsyncPredictor --------------------- - -Make async predictions against SageMaker endpoints with Python objects - -.. autoclass:: sagemaker.predictor_async.AsyncPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/inference/predictors.rst b/doc/api/inference/predictors.rst deleted file mode 100644 index 6a9243f329..0000000000 --- a/doc/api/inference/predictors.rst +++ /dev/null @@ -1,9 +0,0 @@ -Predictors --------------------- - -Make real-time predictions against SageMaker endpoints with Python objects - -.. autoclass:: sagemaker.predictor.Predictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/inference/serializers.rst b/doc/api/inference/serializers.rst deleted file mode 100644 index 6b902c98c9..0000000000 --- a/doc/api/inference/serializers.rst +++ /dev/null @@ -1,12 +0,0 @@ -Serializers ------------ - -.. automodule:: sagemaker.base_serializers - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.serializers - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/inference/serverless.rst b/doc/api/inference/serverless.rst deleted file mode 100644 index d338efd7be..0000000000 --- a/doc/api/inference/serverless.rst +++ /dev/null @@ -1,9 +0,0 @@ -Serverless Inference ---------------------- - -This module contains classes related to Amazon Sagemaker Serverless Inference - -.. automodule:: sagemaker.serverless.serverless_inference_config - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/inference/transformer.rst b/doc/api/inference/transformer.rst deleted file mode 100644 index 1c49ac9945..0000000000 --- a/doc/api/inference/transformer.rst +++ /dev/null @@ -1,7 +0,0 @@ -Transformer ------------ - -.. autoclass:: sagemaker.transformer.Transformer - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/prep_data/feature_store.rst b/doc/api/prep_data/feature_store.rst deleted file mode 100644 index 731b2e32d1..0000000000 --- a/doc/api/prep_data/feature_store.rst +++ /dev/null @@ -1,212 +0,0 @@ -Feature Store APIs ------------------- - -Feature Group -************* - -.. autoclass:: sagemaker.feature_store.feature_group.FeatureGroup - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_group.AthenaQuery - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_group.IngestionManagerPandas - :members: - :show-inheritance: - - -Feature Definition -****************** - -.. autoclass:: sagemaker.feature_store.feature_definition.FeatureDefinition - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_definition.FractionalFeatureDefinition - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_definition.IntegralFeatureDefinition - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_definition.StringFeatureDefinition - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_definition.FeatureTypeEnum - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_definition.CollectionTypeEnum - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_definition.CollectionType - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_definition.ListCollectionType - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_definition.SetCollectionType - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_definition.VectorCollectionType - :members: - :show-inheritance: - - -Inputs -****** - -.. autoclass:: sagemaker.feature_store.inputs.Config - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.DataCatalogConfig - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.OfflineStoreConfig - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.ThroughputConfig - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.ThroughputConfigUpdate - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.OnlineStoreConfig - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.OnlineStoreSecurityConfig - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.TtlDuration - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.S3StorageConfig - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.FeatureValue - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.TableFormatEnum - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.OnlineStoreStorageTypeEnum - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.ThroughputModeEnum - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.ResourceEnum - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.SearchOperatorEnum - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.SortOrderEnum - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.FilterOperatorEnum - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.Filter - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.Identifier - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.inputs.FeatureParameter - :members: - :show-inheritance: - - -Dataset Builder -*************** - -.. autoclass:: sagemaker.feature_store.dataset_builder.DatasetBuilder - :members: - :show-inheritance: - - -Feature Store -************* - -.. autoclass:: sagemaker.feature_store.feature_store.FeatureStore - :members: - :show-inheritance: - - -@feature_processor Decorator -**************************** - -.. autodecorator:: sagemaker.feature_store.feature_processor.feature_processor - - -Feature Processor Data Source -***************************** - -.. autoclass:: sagemaker.feature_store.feature_processor.FeatureGroupDataSource - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_processor.CSVDataSource - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_processor.ParquetDataSource - :members: - :show-inheritance: - -.. autoclass:: sagemaker.feature_store.feature_processor.PySparkDataSource - :members: - :show-inheritance: - - -Feature Processor Scheduler and Triggers -**************************************** - -.. automethod:: sagemaker.feature_store.feature_processor.to_pipeline - -.. automethod:: sagemaker.feature_store.feature_processor.schedule - -.. automethod:: sagemaker.feature_store.feature_processor.execute - -.. automethod:: sagemaker.feature_store.feature_processor.delete_schedule - -.. automethod:: sagemaker.feature_store.feature_processor.describe - -.. automethod:: sagemaker.feature_store.feature_processor.list_pipelines - -.. automethod:: sagemaker.feature_store.feature_processor.put_trigger - -.. automethod:: sagemaker.feature_store.feature_processor.enable_trigger - -.. automethod:: sagemaker.feature_store.feature_processor.disable_trigger - -.. automethod:: sagemaker.feature_store.feature_processor.delete_trigger - diff --git a/doc/api/training/algorithm.rst b/doc/api/training/algorithm.rst deleted file mode 100644 index 778738a192..0000000000 --- a/doc/api/training/algorithm.rst +++ /dev/null @@ -1,7 +0,0 @@ -Algorithm Estimator -------------------- - -.. automodule:: sagemaker.algorithm - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/training/analytics.rst b/doc/api/training/analytics.rst deleted file mode 100644 index e60d6f21f8..0000000000 --- a/doc/api/training/analytics.rst +++ /dev/null @@ -1,22 +0,0 @@ -Analytics ---------- - -.. autoclass:: sagemaker.analytics.AnalyticsMetricsBase - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.analytics.HyperparameterTuningJobAnalytics - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.analytics.TrainingJobAnalytics - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.analytics.ExperimentAnalytics - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/training/automl.rst b/doc/api/training/automl.rst deleted file mode 100644 index 1d7907dc2b..0000000000 --- a/doc/api/training/automl.rst +++ /dev/null @@ -1,12 +0,0 @@ -AutoML ------- - -.. automodule:: sagemaker.automl.automl - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.automl.candidate_estimator - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/training/automlv2.rst b/doc/api/training/automlv2.rst deleted file mode 100644 index 212918a4f4..0000000000 --- a/doc/api/training/automlv2.rst +++ /dev/null @@ -1,7 +0,0 @@ -AutoMLV2 --------- - -.. automodule:: sagemaker.automl.automlv2 - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/training/debugger.rst b/doc/api/training/debugger.rst deleted file mode 100644 index ed6c8b84f1..0000000000 --- a/doc/api/training/debugger.rst +++ /dev/null @@ -1,58 +0,0 @@ -Debugger --------- - -Amazon SageMaker Debugger provides full visibility -into training jobs of state-of-the-art machine learning models. -This SageMaker Debugger module provides high-level methods -to set up Debugger configurations to -monitor, profile, and debug your training job. -Configure the Debugger-specific parameters when constructing -a SageMaker estimator to gain visibility and insights -into your training job. - -.. contents:: - -.. currentmodule:: sagemaker.debugger - -Debugger Rule APIs -~~~~~~~~~~~~~~~~~~ - -.. autoclass:: get_rule_container_image_uri - :show-inheritance: - -.. autoclass:: get_default_profiler_processing_job - :show-inheritance: - -.. class:: sagemaker.debugger.rule_configs - - A helper module to configure the SageMaker Debugger built-in rules with - the :class:`~sagemaker.debugger.Rule` classmethods and - and the :class:`~sagemaker.debugger.ProfilerRule` classmethods. - - For a full list of built-in rules, see - `List of Debugger Built-in Rules - `_. - - This module is imported from the Debugger client library for rule configuration. - For more information, see - `Amazon SageMaker Debugger RulesConfig - `_. - -.. autoclass:: RuleBase - :show-inheritance: - -.. autoclass:: Rule - :show-inheritance: - :inherited-members: - -Debugger Configuration APIs -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. autoclass:: CollectionConfig - :show-inheritance: - -.. autoclass:: DebuggerHookConfig - :show-inheritance: - -.. autoclass:: TensorBoardOutputConfig - :show-inheritance: diff --git a/doc/api/training/distributed.rst b/doc/api/training/distributed.rst deleted file mode 100644 index be050d1011..0000000000 --- a/doc/api/training/distributed.rst +++ /dev/null @@ -1,40 +0,0 @@ -Distributed Training APIs -------------------------- -SageMaker distributed training libraries offer both data parallel and model parallel training strategies. -They combine software and hardware technologies to improve inter-GPU and inter-node communications. -They extend SageMaker’s training capabilities with built-in options that require only small code changes to your training scripts. - -.. _sdp_api_docs_toc: - -The SageMaker Distributed Data Parallel Library -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. toctree:: - :maxdepth: 2 - - smd_data_parallel - sdp_versions/latest - smd_data_parallel_use_sm_pysdk - smd_data_parallel_release_notes/smd_data_parallel_change_log - -.. _smp_api_docs_toc: - -The SageMaker Distributed Model Parallel Library -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Since the release of the SageMaker model parallelism (SMP) version 2 in December 2023, - this documentation is no longer supported for maintenence. - The live documentation is available at - `SageMaker model parallelism library v2 - `_ - in the *Amazon SageMaker User Guide*. - - The documentation for the SMP library v1.x is archived and available at - `Run distributed training with the SageMaker model parallelism library - `_ - in the *Amazon SageMaker User Guide*, - and the SMP v1.x API reference is available in the - `SageMaker Python SDK v2.199.0 documentation - `_. diff --git a/doc/api/training/estimators.rst b/doc/api/training/estimators.rst deleted file mode 100644 index a455f43e69..0000000000 --- a/doc/api/training/estimators.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _estimators: - -Estimators ----------- - -A high level interface for SageMaker training - -.. autoclass:: sagemaker.estimator.EstimatorBase - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - -.. autoclass:: sagemaker.estimator.Estimator - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - -.. autoclass:: sagemaker.jumpstart.estimator.JumpStartEstimator - :members: - :undoc-members: - :show-inheritance: - :inherited-members: - -.. autoclass:: sagemaker.estimator.Framework - :members: - :undoc-members: - :show-inheritance: - :inherited-members: diff --git a/doc/api/training/index.rst b/doc/api/training/index.rst deleted file mode 100644 index 0f61cd1931..0000000000 --- a/doc/api/training/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -############# -Training APIs -############# - -.. toctree:: - :maxdepth: 4 - - model_trainer - algorithm - analytics - automl - automlv2 - debugger - estimators - tuner - parameter - processing - profiler diff --git a/doc/api/training/model_trainer.rst b/doc/api/training/model_trainer.rst deleted file mode 100644 index 5b0781f810..0000000000 --- a/doc/api/training/model_trainer.rst +++ /dev/null @@ -1,17 +0,0 @@ -ModelTrainer ------------- - -.. autoclass:: sagemaker.modules.train.model_trainer.ModelTrainer - :members: - -Configs -~~~~~~~ - -.. automodule:: sagemaker.modules.configs - :members: - -Distributed -~~~~~~~~~~~ - -.. automodule:: sagemaker.modules.distributed - :members: diff --git a/doc/api/training/parameter.rst b/doc/api/training/parameter.rst deleted file mode 100644 index 1893a8e889..0000000000 --- a/doc/api/training/parameter.rst +++ /dev/null @@ -1,7 +0,0 @@ -Parameters ----------- - -.. automodule:: sagemaker.parameter - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/training/processing.rst b/doc/api/training/processing.rst deleted file mode 100644 index 7d572aace2..0000000000 --- a/doc/api/training/processing.rst +++ /dev/null @@ -1,17 +0,0 @@ -Processing ----------- - -.. automodule:: sagemaker.processing - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.spark.processing - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.clarify - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/training/profiler.rst b/doc/api/training/profiler.rst deleted file mode 100644 index 0b96bc2ef3..0000000000 --- a/doc/api/training/profiler.rst +++ /dev/null @@ -1,102 +0,0 @@ -Profiler --------- - -Amazon SageMaker Profiler provides full visibility -into provisioned compute resources for training -state-of-the-art deep learning models. -The following SageMaker Profiler classes are -for activating SageMaker Profiler while creating -an estimator object of `:class:sagemaker.pytorch.estimator.PyTorch` -or `:class:sagemaker.tensorflow.estimator.TensorFlow`. - -.. contents:: - -.. currentmodule:: sagemaker.debugger - -Profiler configuration modules -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. class:: sagemaker.Profiler(cpu_profiling_duration=3600) - - A configuration class to activate - `Amazon SageMaker Profiler `_. - - To adjust the Profiler configuration instead of using the default configuration, use the following parameters. - - **Parameters:** - - - **cpu_profiling_duration** (*str*): Specify the time duration in seconds for - profiling CPU activities. The default value is 3600 seconds. - - **Example usage:** - - .. code:: python - - import sagemaker - from sagemaker.pytorch import PyTorch - from sagemaker import ProfilerConfig, Profiler - - profiler_config = ProfilerConfig( - profiler_params = Profiler(cpu_profiling_duration=3600) - ) - - estimator = PyTorch( - framework_version="2.0.0", - ... # Set up other essential parameters for the estimator class - profiler_config=profiler_config - ) - - For a complete instruction on activating and using SageMaker Profiler, see - `Use Amazon SageMaker Profiler to profile activities on AWS compute resources - `_. - -.. autoclass:: sagemaker.ProfilerConfig - - -Profiler Rule APIs -~~~~~~~~~~~~~~~~~~ - -The following API is for setting up SageMaker Debugger's profiler rules -to detect computational performance issues from training jobs. - -.. autoclass:: ProfilerRule - :inherited-members: - - -Debugger Configuration APIs for Framework Profiling (Deprecated) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. warning:: - - In favor of `Amazon SageMaker Profiler `_, - SageMaker Debugger deprecates the framework profiling feature starting from TensorFlow 2.11 and PyTorch 2.0. You can still use the feature in the previous versions of the frameworks and SDKs as follows. - - * SageMaker Python SDK <= v2.130.0 - * PyTorch >= v1.6.0, < v2.0 - * TensorFlow >= v2.3.1, < v2.11 - - With the deprecation, SageMaker Debugger discontinues support for the APIs below this note. - - See also `Amazon SageMaker Debugger Release Notes: March 16, 2023 `_. - -.. autoclass:: FrameworkProfile - :show-inheritance: - -.. autoclass:: DetailedProfilingConfig - :show-inheritance: - -.. autoclass:: DataloaderProfilingConfig - :show-inheritance: - -.. autoclass:: PythonProfilingConfig - :show-inheritance: - -.. autoclass:: PythonProfiler - :show-inheritance: - -.. autoclass:: cProfileTimer - :show-inheritance: - -.. automodule:: sagemaker.debugger.metrics_config - :members: StepRange, TimeRange - :undoc-members: diff --git a/doc/api/training/sdp_versions/archives.rst b/doc/api/training/sdp_versions/archives.rst deleted file mode 100644 index 98b14b92b3..0000000000 --- a/doc/api/training/sdp_versions/archives.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _smddp-version-archive: - -.. toctree:: - :maxdepth: 1 - - v1_2_x.rst - v1_1_x.rst - v1_0_0.rst diff --git a/doc/api/training/sdp_versions/latest.rst b/doc/api/training/sdp_versions/latest.rst deleted file mode 100644 index adaa8eefc9..0000000000 --- a/doc/api/training/sdp_versions/latest.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _sdp_api_docs: - -############################################# -Use the Library to Adapt Your Training Script -############################################# - -This section contains the SageMaker distributed data parallel API documentation. -If you are a new user of this library, it is recommended you use this guide alongside -`SageMaker's Distributed Data Parallel Library -`_. - -The library provides framework-specific APIs for TensorFlow and PyTorch. - -Select the latest or one of the previous versions of the API documentation -depending on the version of the library you use. - -.. important:: - - The distributed data parallel library supports training jobs using CUDA 11 or later. - When you define a :class:`sagemaker.tensorflow.estimator.TensorFlow` or - :class:`sagemaker.pytorch.estimator.PyTorch` - estimator with the data parallel library enabled, - SageMaker uses CUDA 11. When you extend or customize your own training image, - you must use a base image with CUDA 11 or later. See - `SageMaker Python SDK's distributed data parallel library APIs - `_ - for more information. - -For versions between 1.4.0 and 1.8.0 (Latest) -============================================= - -.. toctree:: - :maxdepth: 1 - - latest/smd_data_parallel_pytorch - latest/smd_data_parallel_tensorflow - -Documentation Archive -===================== - -To find the API documentation for the previous versions of the library, -choose one of the following: - -.. toctree:: - :maxdepth: 1 - - archives diff --git a/doc/api/training/sdp_versions/latest/smd_data_parallel_pytorch.rst b/doc/api/training/sdp_versions/latest/smd_data_parallel_pytorch.rst deleted file mode 100644 index cdc4d0c950..0000000000 --- a/doc/api/training/sdp_versions/latest/smd_data_parallel_pytorch.rst +++ /dev/null @@ -1,165 +0,0 @@ -################# -Guide for PyTorch -################# - -Use this guide to learn how to use the SageMaker distributed -data parallel library API for PyTorch. - -.. contents:: Topics - :depth: 3 - :local: - -.. _pytorch-sdp-modify: - -Use the SageMaker Distributed Data Parallel Library as a Backend of ``torch.distributed`` -=========================================================================================== - -To use the SageMaker distributed data parallel library, -the only thing you need to do is to import the SageMaker distributed data -parallel library’s PyTorch client (``smdistributed.dataparallel.torch.torch_smddp``). -The client registers ``smddp`` as a backend for PyTorch. -When you initialize the PyTorch distributed process group using -the ``torch.distributed.init_process_group`` API, -make sure you specify ``'smddp'`` to the backend argument. - -.. code:: python - - import smdistributed.dataparallel.torch.torch_smddp - import torch.distributed as dist - - dist.init_process_group(backend='smddp') - - -If you already have a working PyTorch script and only need to add the -backend specification, you can proceed to :ref:`sdp_api_docs_launch_training_job`. - -.. note:: - - The ``smddp`` backend currently does not support creating subprocess groups - with the ``torch.distributed.new_group()`` API. - You cannot use the ``smddp`` backend concurrently with other backends. - -.. seealso:: - - If you still need to modify your training script to properly use - the PyTorch distributed package, see `Preparing a PyTorch Training Script for Distributed Training `_ - in the *Amazon SageMaker Developer Guide*. - -.. _pytorch-sdp-api: - -PyTorch API -=========== - -Since v1.4.0, the SageMaker distributed data parallel library -supports the PyTorch distributed package as a backend option. -To use the library with PyTorch in SageMaker, -you simply specify the backend of -the PyTorch distributed package as ``'smddp'`` when initializing process group. - -.. code:: Python - - torch.distributed.init_process_group(backend='smddp') - -You don't need to modify your script using -the ``smdistributed`` implementation of the PyTorch distributed modules -that are supported in the library v1.3.0 and before. - -.. warning:: - - The following APIs for ``smdistributed`` implementation of the PyTorch distributed modules - are deprecated. - - -.. class:: smdistributed.dataparallel.torch.parallel.DistributedDataParallel(module, device_ids=None, output_device=None, broadcast_buffers=True, process_group=None, bucket_cap_mb=None) - - .. deprecated:: 1.4.0 - - Use the `torch.nn.parallel.DistributedDataParallel `_ - API instead. - - -.. function:: smdistributed.dataparallel.torch.distributed.is_available() - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. For more information, see `Initialization `_ - in the *PyTorch documentation*. - -.. function:: smdistributed.dataparallel.torch.distributed.init_process_group(*args, **kwargs) - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. For more information, see `Initialization `_ - in the *PyTorch documentation*. - - -.. function:: smdistributed.dataparallel.torch.distributed.is_initialized() - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. For more information, see `Initialization `_ - in the *PyTorch documentation*. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_world_size(group=smdistributed.dataparallel.torch.distributed.group.WORLD) - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. For more information, see `Post-Initialization `_ - in the *PyTorch documentation*. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_rank(group=smdistributed.dataparallel.torch.distributed.group.WORLD) - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. For more information, see `Post-Initialization `_ - in the *PyTorch documentation*. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_local_rank() - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_reduce(tensor, op=smdistributed.dataparallel.torch.distributed.ReduceOp.SUM, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. - - -.. function:: smdistributed.dataparallel.torch.distributed.broadcast(tensor, src=0, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_gather(tensor_list, tensor, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. - -.. function:: smdistributed.dataparallel.torch.distributed.all_to_all_single(output_t, input_t, output_split_sizes=None, input_split_sizes=None, group=group.WORLD, async_op=False) - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. - - -.. function:: smdistributed.dataparallel.torch.distributed.barrier(group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. - - -.. class:: smdistributed.dataparallel.torch.distributed.ReduceOp - - .. deprecated:: 1.4.0 - Use the `torch.distributed `_ package - instead. diff --git a/doc/api/training/sdp_versions/latest/smd_data_parallel_tensorflow.rst b/doc/api/training/sdp_versions/latest/smd_data_parallel_tensorflow.rst deleted file mode 100644 index 662e9af0f1..0000000000 --- a/doc/api/training/sdp_versions/latest/smd_data_parallel_tensorflow.rst +++ /dev/null @@ -1,555 +0,0 @@ -#################### -Guide for TensorFlow -#################### - -Use this guide to learn how to use the SageMaker distributed -data parallel library API for TensorFlow. - -.. contents:: Topics - :depth: 3 - :local: - -.. _tensorflow-sdp-modify: - -Modify a TensorFlow 2.x training script to use the SageMaker data parallel library -================================================================================== - -The following steps show you how to convert a TensorFlow 2.x training -script to utilize the distributed data parallel library. - -The distributed data parallel library APIs are designed to be close to Horovod APIs. -See `SageMaker distributed data parallel TensorFlow examples -`__ -for additional details on how to implement the data parallel library. - -- First import the distributed data parallel library’s TensorFlow client and initialize it: - - .. code:: python - - import smdistributed.dataparallel.tensorflow as sdp - sdp.init() - - -- Pin each GPU to a single smdistributed.dataparallel process - with ``local_rank`` - this refers to the relative rank of the - process within a given node. ``sdp.tensorflow.local_rank()`` API - provides you the local rank of the device. The leader node will be - rank 0, and the worker nodes will be rank 1, 2, 3, and so on. This is - invoked in the next code block as ``sdp.local_rank()``. - ``set_memory_growth`` is not directly related to SMD, but must be set - for distributed training with TensorFlow. - - .. code:: python - - gpus = tf.config.experimental.list_physical_devices('GPU') - for gpu in gpus: -     tf.config.experimental.set_memory_growth(gpu, True) - if gpus: -     tf.config.experimental.set_visible_devices(gpus[sdp.local_rank()], 'GPU') - - -- Scale the learning rate by the number of workers. - ``sdp.tensorflow.size()`` API provides you number of workers in the - cluster. This is invoked in the next code block as ``sdp.size()``. - - .. code:: python - - learning_rate = learning_rate * sdp.size() - - -- Use the library’s ``DistributedGradientTape`` to optimize AllReduce - operations during training. This wraps ``tf.GradientTape``. - - .. code:: python - - with tf.GradientTape() as tape: -       output = model(input) -       loss_value = loss(label, output) - - # Wrap tf.GradientTape with the library's DistributedGradientTape - tape = sdp.DistributedGradientTape(tape) - - -- Broadcast initial model variables from the leader node (rank 0) to - all the worker nodes (ranks 1 through n). This is needed to ensure a - consistent initialization across all the worker ranks. For this, you - use ``sdp.tensorflow.broadcast_variables`` API after the - model and optimizer variables are initialized. This is invoked in the - next code block as ``sdp.broadcast_variables()``. - - .. code:: python - - sdp.broadcast_variables(model.variables, root_rank=0) - sdp.broadcast_variables(opt.variables(), root_rank=0) - - -- Finally, modify your script to save checkpoints only on the leader - node. The leader node will have a synchronized model. This also - avoids worker nodes overwriting the checkpoints and possibly - corrupting the checkpoints. - - .. code:: python - - if sdp.rank() == 0: -     checkpoint.save(checkpoint_dir) - - -All put together, the following is an example TensorFlow2 training -script you will have for distributed training with the library. - -.. code:: python - - import tensorflow as tf - - # Import the library's TF API - import smdistributed.dataparallel.tensorflow as sdp - - # Initialize the library - sdp.init() - - gpus = tf.config.experimental.list_physical_devices('GPU') - for gpu in gpus: -     tf.config.experimental.set_memory_growth(gpu, True) - if gpus: -     # Pin GPUs to a single process -     tf.config.experimental.set_visible_devices(gpus[sdp.local_rank()], 'GPU') - - # Prepare Dataset - dataset = tf.data.Dataset.from_tensor_slices(...) - - # Define Model - mnist_model = tf.keras.Sequential(...) - loss = tf.losses.SparseCategoricalCrossentropy() - - # Scale Learning Rate - # LR for 8 node run : 0.000125 - # LR for single node run : 0.001 - opt = tf.optimizers.Adam(0.000125 * sdp.size()) - - @tf.function - def training_step(images, labels, first_batch): -     with tf.GradientTape() as tape: -         probs = mnist_model(images, training=True) -         loss_value = loss(labels, probs) - -     # Wrap tf.GradientTape with the library's DistributedGradientTape -     tape = sdp.DistributedGradientTape(tape) - -     grads = tape.gradient(loss_value, mnist_model.trainable_variables) -     opt.apply_gradients(zip(grads, mnist_model.trainable_variables)) - -     if first_batch: -        # Broadcast model and optimizer variables -        sdp.broadcast_variables(mnist_model.variables, root_rank=0) -        sdp.broadcast_variables(opt.variables(), root_rank=0) - -     return loss_value - - ... - - # Save checkpoints only from master node. - if sdp.rank() == 0: -     checkpoint.save(checkpoint_dir) - - -.. _tensorflow-sdp-api: - -TensorFlow API -============== - -.. function:: smdistributed.dataparallel.tensorflow.init() - - Initialize ``smdistributed.dataparallel``. Must be called at the - beginning of the training script. - - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - - .. rubric:: Notes - - ``init()`` needs to be called only once. It will throw an error if - called more than once: - - ``init() called more than once. smdistributed.dataparallel is already initialized.`` - - -.. function:: smdistributed.dataparallel.tensorflow.size() - - The total number of GPUs across all the nodes in the cluster. For - example, in a 8 node cluster with 8 GPUs each, ``size`` will be equal - to 64. - - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the total number of GPUs, across all - nodes in the cluster. - - -.. function:: smdistributed.dataparallel.tensorflow.local_size() - - The total number of GPUs on a node. For example, on a node with 8 - GPUs, ``local_size`` will be equal to 8. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the total number of GPUs on itself. - - -.. function:: smdistributed.dataparallel.tensorflow.rank() - - The rank of the node in the cluster. The rank ranges from 0 to number of - nodes - 1. This is similar to MPI's World Rank. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the node. - - -.. function:: smdistributed.dataparallel.tensorflow.local_rank() - - Local rank refers to the relative rank of the - GPUs’ ``smdistributed.dataparallel`` processes within the node. For - example, if a node contains 8 GPUs, it has - 8 ``smdistributed.dataparallel`` processes, then each process will - get a local rank ranging from 0 to 7. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the GPU and - its ``smdistributed.dataparallel`` process. - - -.. function:: smdistributed.dataparallel.tensorflow.allreduce(tensor, param_index, num_params, compression=Compression.none, op=ReduceOp.AVERAGE) - - Performs an ``allreduce`` operation on a tensor (``tf.Tensor``). - - The ``smdistributed.dataparallel`` package's AllReduce API for TensorFlow to allreduce - gradient tensors. By default, ``smdistributed.dataparallel`` allreduce averages the - gradient tensors across participating workers. - - .. note:: - - :class:`smdistributed.dataparallel.tensorflow.allreduce()` should - only be used to allreduce gradient tensors. - For other (non-gradient) tensors, you must use - :class:`smdistributed.dataparallel.tensorflow.oob_allreduce()`. - If you use :class:`smdistributed.dataparallel.tensorflow.allreduce()` - for non-gradient tensors, - the distributed training job might stall or stop. - - **Inputs:** - - - ``tensor (tf.Tensor)(required)``: The tensor to be allreduced. The shape of the input must be identical across all ranks. - - ``param_index (int)(required):`` 0 if you are reducing a single tensor. Index of the tensor if you are reducing a list of tensors. - - ``num_params (int)(required):`` len(tensor). - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``op (optional)(smdistributed.dataparallel.tensorflow.ReduceOp)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``SUM``, ``MIN``, ``MAX``, ``AVERAGE`` - - **Returns:** - - - A tensor of the same shape and type as input ``tensor``, all-reduced across all the processes. - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast_global_variables(root_rank) - - Broadcasts all global variables from root rank to all other processes. - - **Inputs:** - - - ``root_rank (int)(required):`` Rank of the process from which global - variables will be broadcasted to all other processes. - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast_variables(variables, root_rank) - - Applicable for TensorFlow 2.x only. - ​ - Broadcasts variables from root rank to all other processes. - ​ - With TensorFlow 2.x, ``broadcast_variables`` is used to - broadcast ``model.variables`` and ``optimizer.variables`` post - initialization from the leader node to all the worker nodes. This - ensures a consistent initialization across all the worker ranks. - - **Inputs:** - - - ``variables (tf.Variable)(required):`` Variables to be broadcasted. - - ``root_rank (int)(required):`` Rank of the process from which - variables will be broadcasted to all other processes. - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.oob_allreduce(tensor, compression=Compression.none, op=ReduceOp.AVERAGE) - - Out-of-band (oob) AllReduce is simplified AllReduce function for use-cases - such as calculating total loss across all the GPUs in the training. - ``oob_allreduce`` average the tensors, as reduction operation, across the - worker nodes. - - **Inputs:** - - - ``tensor (tf.Tensor)(required)``: The tensor to be all-reduced. The shape of the input must be identical across all worker nodes. - - ``compression`` (optional): Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different worker nodes. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - **Returns:** - - - ``None`` - - .. note:: - - In most cases, the :class:`smdistributed.dataparallel.tensorflow.oob_allreduce()` - function is ~2x slower - than :class:`smdistributed.dataparallel.tensorflow.allreduce()`. It is not - recommended to use the :class:`smdistributed.dataparallel.tensorflow.oob_allreduce()` - function for performing gradient - reduction during the training process. - ``smdistributed.dataparallel.tensorflow.oob_allreduce`` internally - uses NCCL AllReduce with ``ncclSum`` as the reduction operation. - - .. note:: - - :class:`smdistributed.dataparallel.tensorflow.oob_allreduce()` should - only be used to allreduce non-gradient tensors. - If you use :class:`smdistributed.dataparallel.tensorflow.allreduce()` - for non-gradient tensors, - the distributed training job might stall or stop. - To allreduce gradients, use :class:`smdistributed.dataparallel.tensorflow.allreduce()`. - - -.. function:: smdistributed.dataparallel.tensorflow.overlap(tensor) - - This function is applicable only for models compiled with XLA. Use this - function to enable ``smdistributed.dataparallel`` to efficiently - overlap backward pass with the all reduce operation. - - Example usage: - - .. code:: python - - layer = tf.nn.dropout(...) # Or any other layer - layer = smdistributed.dataparallel.tensorflow.overlap(layer) - - The overlap operation is inserted into the TF graph as a node. It - behaves as an identity operation, and helps in achieving the - communication overlap with backward pass operation. - - **Inputs:** - - - ``tensor (tf.Tensor)(required):`` The tensor to be all-reduced. - - **Returns:** - - - ``None`` - - .. rubric:: Notes - - This operation helps in speeding up distributed training, as - the AllReduce operation does not have to wait for all the gradients to - be ready. Backward propagation proceeds sequentially from the output - layer of the network to the input layer. When the gradient computation - for a layer finishes, ``smdistributed.dataparallel`` adds them to a - fusion buffer. As soon as the size of the fusion buffer reaches a - predefined threshold (25 Mb), ``smdistributed.dataparallel`` starts - the AllReduce operation. - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast(tensor, root_rank) - - Broadcasts the input tensor on root rank to the same input tensor on all - other ``smdistributed.dataparallel`` processes. - ​ - The broadcast will not start until all processes are ready to send and - receive the tensor. - - **Inputs:** - - - ``tensor (tf.Tensor)(required):`` The tensor to be broadcasted. - - ``root_rank (int)(required):`` Rank of the process from which - tensor will be broadcasted to all other processes. - - **Returns:** - - - A tensor of the same shape and type as tensor, with the value - broadcasted from root rank. - - -.. function:: smdistributed.dataparallel.tensorflow.shutdown() - - Shuts down ``smdistributed.dataparallel``. Optional to call at the end - of the training script. - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.DistributedOptimizer - - Applicable if you use the ``tf.estimator`` API in TensorFlow 2.x (2.3.1). - ​ - Construct a new ``DistributedOptimizer`` , which uses TensorFlow - optimizer under the hood for computing single-process gradient values - and applying gradient updates after the gradient values have been - combined across all ``smdistributed.dataparallel`` workers. - ​ - Example usage: - - .. code:: python - - opt = ... # existing optimizer from tf.train package or your custom optimizer - opt = smdistributed.dataparallel.tensorflow.DistributedOptimizer(opt) - - - - ``optimizer (tf.train.Optimizer)(required):`` TF Optimizer to use for computing gradients and applying updates. - - - ``name (str)(optional):`` Name prefix for the operations created when applying gradients. Defaults to ``smdistributed.dataparallel`` followed by provided optimizer type. - - - ``use_locking (bool)(optional):`` Whether to use locking when updating variables. Defaults to ``False``. - - - ``device_dense:`` Not supported. Raises not supported error. - - - ``device_sparse:`` Not supported. Raises not supported error. - - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``sparse_as_dense:`` Treats sparse gradient tensor as dense tensor. Defaults to ``False``. - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - - ``bucket_cap_mb (int)(optional):`` Size of ``smdistributed.dataparallel`` fusion buffer size. Defaults to 25MB that works optimally for most case. If you provide a value, expects the (value * 1024 * 1024) i.e., bytes to be multiple of 128. - - -.. function:: smdistributed.dataparallel.tensorflow.DistributedGradientTape - - Applicable to TensorFlow 2.x only. - - Construct a new ``DistributedGradientTape``, which uses - TensorFlow’s ``GradientTape`` under the hood, using an AllReduce to - combine gradient values before applying gradients to model weights. - ​ - Example Usage: - - .. code:: python - - with tf.GradientTape() as tape: -       output = model(input) -       loss_value = loss(label, output) - - # Wrap in smdistributed.dataparallel's DistributedGradientTape - tape = smdistributed.dataparallel.tensorflow.DistributedGradientTape(tape) - - - - ``gradtape (tf.GradientTape)(required):`` GradientTape to use for computing gradients and applying updates. - - - ``device_dense:`` Not supported. Raises not supported error. - - - ``device_sparse:`` Not supported. Raises not supported error. - - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``sparse_as_dense:`` Treats sparse gradient tensor as dense tensor. Defaults to ``False``. - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - -.. function:: smdistributed.dataparallel.tensorflow.BroadcastGlobalVariablesHook - - Applicable if you use the ``tf.estimator`` API in TensorFlow 2.x (2.3.1). - - - ``SessionRunHook`` that will broadcast all global variables from root - rank to all other processes during initialization. - ​ - This is necessary to ensure consistent initialization of all workers - when training is started with random weights or restored from a - checkpoint. - ​ - Example Usage: - - .. code:: python - - hooks = [smdistributed.dataparallel.tensorflow.BroadcastGlobalVariablesHook(root_rank=0)] - ... - with tf.train.MonitoredTrainingSession(checkpoint_dir=checkpoint_dir, -                                        hooks=hooks, -                                        config=config) as mon_sess: -      ... - - - - ``root_rank (int)(required):`` Rank of the process from which global - variables will be broadcasted to all other processes. - - -.. function:: smdistributed.dataparallel.tensorflow.Compression - - Optional Gradient Compression algorithm that can be used in AllReduce - operation. - - - ``none``: alias for ``NoneCompression``. Do not compression gradient - tensors. - - ``fp16``: alias for ``FP16Compression``. Compress the floating point - gradient tensors to 16-bit (FP16) - - -.. function:: smdistributed.dataparallel.tensorflow.ReduceOp - - Supported reduction operations in ``smdistributed.dataparallel``. - - - ``AVERAGE`` - - ``SUM`` - - ``MIN`` - - ``MAX`` diff --git a/doc/api/training/sdp_versions/v1.0.0/smd_data_parallel_pytorch.rst b/doc/api/training/sdp_versions/v1.0.0/smd_data_parallel_pytorch.rst deleted file mode 100644 index 1e18472ca0..0000000000 --- a/doc/api/training/sdp_versions/v1.0.0/smd_data_parallel_pytorch.rst +++ /dev/null @@ -1,531 +0,0 @@ -############################################################## -PyTorch Guide to SageMaker's distributed data parallel library -############################################################## - -.. admonition:: Contents - - - :ref:`pytorch-sdp-modify-1.0.0` - - :ref:`pytorch-sdp-api-1.0.0` - -.. _pytorch-sdp-modify-1.0.0: - -Modify a PyTorch training script to use SageMaker data parallel -====================================================================== - -The following steps show you how to convert a PyTorch training script to -utilize SageMaker's distributed data parallel library. - -The distributed data parallel library APIs are designed to be close to PyTorch Distributed Data -Parallel (DDP) APIs. -See `SageMaker distributed data parallel PyTorch examples `__ for additional details on how to implement the data parallel library -API offered for PyTorch. - - -- First import the distributed data parallel library’s PyTorch client and initialize it. You also import - the distributed data parallel library module for distributed training. - - .. code:: python - - import smdistributed.dataparallel.torch.distributed as dist - - from smdistributed.dataparallel.torch.parallel.distributed import DistributedDataParallel as DDP - - dist.init_process_group() - - -- Pin each GPU to a single distributed data parallel library process with ``local_rank`` - this - refers to the relative rank of the process within a given node. - ``smdistributed.dataparallel.torch.get_local_rank()`` API provides - you the local rank of the device. The leader node will be rank 0, and - the worker nodes will be rank 1, 2, 3, and so on. This is invoked in - the next code block as ``dist.get_local_rank()``. - - .. code:: python - - torch.cuda.set_device(dist.get_local_rank()) - - -- Then wrap the PyTorch model with the distributed data parallel library’s DDP. - - .. code:: python - - model = ... - # Wrap model with SageMaker's DistributedDataParallel - model = DDP(model) - - -- Modify the ``torch.utils.data.distributed.DistributedSampler`` to - include the cluster’s information. Set``num_replicas`` to the - total number of GPUs participating in training across all the nodes - in the cluster. This is called ``world_size``. You can get - ``world_size`` with - ``smdistributed.dataparallel.torch.get_world_size()`` API. This is - invoked in the following code as ``dist.get_world_size()``. Also - supply the node rank using - ``smdistributed.dataparallel.torch.get_rank()``. This is invoked as - ``dist.get_rank()``. - - .. code:: python - - train_sampler = DistributedSampler(train_dataset, num_replicas=dist.get_world_size(), rank=dist.get_rank()) - - -- Finally, modify your script to save checkpoints only on the leader - node. The leader node will have a synchronized model. This also - avoids worker nodes overwriting the checkpoints and possibly - corrupting the checkpoints. - -.. code:: python - - if dist.get_rank() == 0: - torch.save(...) - - -All put together, the following is an example PyTorch training script -you will have for distributed training with the distributed data parallel library: - -.. code:: python - - # Import distributed data parallel library PyTorch API - import smdistributed.dataparallel.torch.distributed as dist - - # Import distributed data parallel library PyTorch DDP - from smdistributed.dataparallel.torch.parallel.distributed import DistributedDataParallel as DDP - - # Initialize distributed data parallel library - dist.init_process_group() - - class Net(nn.Module): -     ... -     # Define model - - def train(...): -     ... -     # Model training - - def test(...): -     ... -     # Model evaluation - - def main(): - -     # Scale batch size by world size -     batch_size //= dist.get_world_size() // 8 -     batch_size = max(batch_size, 1) - -     # Prepare dataset -     train_dataset = torchvision.datasets.MNIST(...) - -     # Set num_replicas and rank in DistributedSampler -     train_sampler = torch.utils.data.distributed.DistributedSampler( -             train_dataset, -             num_replicas=dist.get_world_size(), -             rank=dist.get_rank()) - -     train_loader = torch.utils.data.DataLoader(..) - -     # Wrap the PyTorch model with distributed data parallel library’s DDP -     model = DDP(Net().to(device)) - -     # Pin each GPU to a single distributed data parallel library process. -     torch.cuda.set_device(local_rank) -     model.cuda(local_rank) - -     # Train -     optimizer = optim.Adadelta(...) -     scheduler = StepLR(...) -     for epoch in range(1, args.epochs + 1): -         train(...) -         if rank == 0: -             test(...) -         scheduler.step() - -     # Save model on master node. -     if dist.get_rank() == 0: -         torch.save(...) - - if __name__ == '__main__': -     main() - - -.. _pytorch-sdp-api-1.0.0: - -PyTorch API -=========== - -.. rubric:: Supported versions - -**PyTorch 1.6.0, 1.7.1** - - -.. function:: smdistributed.dataparallel.torch.distributed.is_available() - :noindex: - - Check if script started as a distributed job. For local runs user can - check that is_available returns False and run the training script - without calls to ``smdistributed.dataparallel``. - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``True`` if started as a distributed job, ``False`` otherwise - - -.. function:: smdistributed.dataparallel.torch.distributed.init_process_group(*args, **kwargs) - :noindex: - - Initialize ``smdistributed.dataparallel``. Must be called at the - beginning of the training script, before calling any other methods. - ​ - Process group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with ``torch.distributed`` only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - ​ - After this - call, ``smdistributed.dataparallel.torch.distributed.is_initialized()`` will - return ``True``. - ​ - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.torch.distributed.is_initialized() - :noindex: - - Checks if the default process group has been initialized. - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``True`` if initialized, else ``False``. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_world_size(group=smdistributed.dataparallel.torch.distributed.group.WORLD) - :noindex: - - The total number of GPUs across all the nodes in the cluster. For - example, in a 8 node cluster with 8 GPU each, size will be equal to 64. - - **Inputs:** - - - ``group (smdistributed.dataparallel.torch.distributed.group) (optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - **Returns:** - - - An integer scalar containing the total number of GPUs in the training - job, across all nodes in the cluster. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_rank(group=smdistributed.dataparallel.torch.distributed.group.WORLD) - :noindex: - - The rank of the node in the cluster. The rank ranges from 0 to number of - nodes - 1. This is similar to MPI's World Rank. - - - **Inputs:** - - - ``group (smdistributed.dataparallel.torch.distributed.group) (optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - **Returns:** - - - An integer scalar containing the rank of the worker node. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_local_rank() - :noindex: - - Local rank refers to the relative rank of - the ``smdistributed.dataparallel`` process within the node the current - process is running on. For example, if a node contains 8 GPUs, it has - 8 ``smdistributed.dataparallel`` processes. Each process has - a ``local_rank`` ranging from 0 to 7. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the GPU and - its ``smdistributed.dataparallel`` process. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_reduce(tensor, op=smdistributed.dataparallel.torch.distributed.ReduceOp.SUM, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Performs an all-reduce operation on a tensor (torch.tensor) across - all ``smdistributed.dataparallel`` workers - - ``smdistributed.dataparallel`` AllReduce API can be used for all - reducing gradient tensors or any other tensors.  By - default, ``smdistributed.dataparallel`` AllReduce reduces the tensor - data across all ``smdistributed.dataparallel`` workers in such a way - that all get the final result. - - After the call ``tensor`` is going to be bitwise identical in all - processes. - - **Inputs:** - - - ``tensor (torch.tensor) (required):`` Input and output of the collective. The function operates in-place. - - - ``op (smdistributed.dataparallel.torch.distributed.ReduceOp) (optional)``: The reduction operation to combine tensors across different ranks.  Defaults to ``SUM`` if None is given. - - * Supported ops: ``AVERAGE``, ``SUM``, ``MIN``, ``MAX`` - - - ``group (smdistributed.dataparallel.torch.distributed.group) (optional):`` Process group is not supported in ``smdistributed.dataparallel``. This parameter exists for API parity with torch.distributed only. - - * Only supported value is ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - - ``async_op (bool) (optional):`` Whether this op should be an async op. Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - .. rubric:: Notes - - ``smdistributed.dataparallel.torch.distributed.allreduce``, in most - cases, is ~2X slower than all-reducing - with ``smdistributed.dataparallel.torch.parallel.distributed.DistributedDataParallel`` and - hence, it is not recommended to be used for performing gradient - reduction during the training - process. ``smdistributed.dataparallel.torch.distributed.allreduce`` internally - uses NCCL AllReduce with ``ncclSum`` as the reduction operation. - - -.. function:: smdistributed.dataparallel.torch.distributed.broadcast(tensor, src=0, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Broadcasts the tensor (torch.tensor) to the whole group. - - ``tensor`` must have the same number of elements as GPUs in the - cluster. - - **Inputs:** - - - ``tensor (torch.tensor)(required)`` - - - ``src (int)(optional)`` - - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process group is not supported in ``smdistributed.dataparallel``. This parameter exists for API parity with ``torch.distributed`` only. - - * Only supported value is ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - - ``async_op (bool)(optional):`` Whether this op should be an async op. Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, otherwise. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_gather(tensor_list, tensor, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Gathers tensors from the whole group in a list. - - - **Inputs:** - - - ``tensor_list (list[torch.tensor])(required):`` Output list. It - should contain correctly-sized tensors to be used for output of the - collective. - - ``tensor (torch.tensor)(required):`` Tensor to be broadcast from - current process. - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - ``async_op (bool)(optional):`` Whether this op should be an async op. - Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_to_all_single(output_t, input_t, output_split_sizes=None, input_split_sizes=None, group=group.WORLD, async_op=False) - :noindex: - - Each process scatters input tensor to all processes in a group and return gathered tensor in output. - - **Inputs:** - - - output_t - - input_t - - output_split_sizes - - input_split_sizes - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - ``async_op (bool)(optional):`` Whether this op should be an async op. - Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - -.. function:: smdistributed.dataparallel.torch.distributed.barrier(group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Synchronizes all ``smdistributed.dataparallel`` processes. - - **Inputs:** - - - tensor (torch.tensor)(required): Data to be sent if src is the rank of current process, and tensor to be used to save received data otherwise. - - - src (int)(optional): Source rank. - - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. - - * Only supported value is ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - - ``async_op (bool)(optional):`` Whether this op should be an async op. - Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - -.. class:: smdistributed.dataparallel.torch.parallel.DistributedDataParallel(module, device_ids=None, output_device=None, broadcast_buffers=True, process_group=None, bucket_cap_mb=None) - :noindex: - - ``smdistributed.dataparallel's`` implementation of distributed data - parallelism for PyTorch. In most cases, wrapping your PyTorch Module - with ``smdistributed.dataparallel's`` ``DistributedDataParallel (DDP)`` is - all you need to do to use ``smdistributed.dataparallel``. - - Creation of this DDP class requires ``smdistributed.dataparallel`` - already initialized - with ``smdistributed.dataparallel.torch.distributed.init_process_group()``. - - This container parallelizes the application of the given module by - splitting the input across the specified devices by chunking in the - batch dimension. The module is replicated on each machine and each - device, and each such replica handles a portion of the input. During the - backwards pass, gradients from each node are averaged. - - The batch size should be larger than the number of GPUs used locally. - ​ - Example usage - of ``smdistributed.dataparallel.torch.parallel.DistributedDataParallel``: - - .. code:: python - - import torch - import smdistributed.dataparallel.torch.distributed as dist - from smdistributed.dataparallel.torch.parallel import DistributedDataParallel as DDP - - dist.init_process_group() - - # Pin GPU to be used to process local rank (one GPU per process) - torch.cuda.set_device(dist.get_local_rank()) - - # Build model and optimizer - model = ... - optimizer = torch.optim.SGD(model.parameters(), -                             lr=1e-3 * dist.get_world_size()) - # Wrap model with smdistributed.dataparallel's DistributedDataParallel - model = DDP(model) - - **Parameters:** - - - ``module (torch.nn.Module)(required):`` PyTorch NN Module to be - parallelized - - ``device_ids (list[int])(optional):`` CUDA devices. This should only - be provided when the input module resides on a single CUDA device. - For single-device modules, - the ``ith module replica is placed on device_ids[i]``. For - multi-device modules and CPU modules, device_ids must be None or an - empty list, and input data for the forward pass must be placed on the - correct device. Defaults to ``None``. - - ``output_device (int)(optional):`` Device location of output for - single-device CUDA modules. For multi-device modules and CPU modules, - it must be None, and the module itself dictates the output location. - (default: device_ids[0] for single-device modules).  Defaults - to ``None``. - - ``broadcast_buffers (bool)(optional):`` Flag that enables syncing - (broadcasting) buffers of the module at beginning of the forward - function. ``smdistributed.dataparallel`` does not support broadcast - buffer yet. Please set this to ``False``. - - ``process_group(smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` Defaults - to ``None.`` - - ``bucket_cap_mb (int)(optional):`` DistributedDataParallel will - bucket parameters into multiple buckets so that gradient reduction of - each bucket can potentially overlap with backward - computation. ``bucket_cap_mb`` controls the bucket size in - MegaBytes (MB) (default: 25). - - .. rubric:: Notes - - - This module assumes all parameters are registered in the model by the - time it is created. No parameters should be added nor removed later. - - This module assumes all parameters are registered in the model of - each distributed processes are in the same order. The module itself - will conduct gradient all-reduction following the reverse order of - the registered parameters of the model. In other words, it is users’ - responsibility to ensure that each distributed process has the exact - same model and thus the exact same parameter registration order. - - You should never change the set of your model’s parameters after - wrapping up your model with DistributedDataParallel. In other words, - when wrapping up your model with DistributedDataParallel, the - constructor of DistributedDataParallel will register the additional - gradient reduction functions on all the parameters of the model - itself at the time of construction. If you change the model’s - parameters after the DistributedDataParallel construction, this is - not supported and unexpected behaviors can happen, since some - parameters’ gradient reduction functions might not get called. - - -.. class:: smdistributed.dataparallel.torch.distributed.ReduceOp - :noindex: - - An enum-like class for supported reduction operations - in ``smdistributed.dataparallel``. - - The values of this class can be accessed as attributes, for - example, ``ReduceOp.SUM``. They are used in specifying strategies for - reduction collectives such as -  ``smdistributed.dataparallel.torch.distributed.all_reduce(...)``. - - - ``AVERAGE`` - - ``SUM`` - - ``MIN`` - - ``MAX`` diff --git a/doc/api/training/sdp_versions/v1.0.0/smd_data_parallel_tensorflow.rst b/doc/api/training/sdp_versions/v1.0.0/smd_data_parallel_tensorflow.rst deleted file mode 100644 index 43e4d8f26d..0000000000 --- a/doc/api/training/sdp_versions/v1.0.0/smd_data_parallel_tensorflow.rst +++ /dev/null @@ -1,555 +0,0 @@ -################################################################# -TensorFlow Guide to SageMaker's distributed data parallel library -################################################################# - -.. admonition:: Contents - - - :ref:`tensorflow-sdp-modify-1.0.0` - - :ref:`tensorflow-sdp-api-1.0.0` - -.. _tensorflow-sdp-modify-1.0.0: - -Modify a TensorFlow 2.x training script to use SageMaker data parallel -====================================================================== - -The following steps show you how to convert a TensorFlow 2.x training -script to utilize the distributed data parallel library. - -The distributed data parallel library APIs are designed to be close to Horovod APIs. -See `SageMaker distributed data parallel TensorFlow examples `__ for additional details on how to implement the data parallel library -API offered for TensorFlow. - -- First import the distributed data parallel library’s TensorFlow client and initialize it: - - .. code:: python - - import smdistributed.dataparallel.tensorflow as sdp - sdp.init() - - -- Pin each GPU to a single smdistributed.dataparallel process - with ``local_rank`` - this refers to the relative rank of the - process within a given node. ``sdp.tensorflow.local_rank()`` API - provides you the local rank of the device. The leader node will be - rank 0, and the worker nodes will be rank 1, 2, 3, and so on. This is - invoked in the next code block as ``sdp.local_rank()``. - ``set_memory_growth`` is not directly related to SMD, but must be set - for distributed training with TensorFlow. - - .. code:: python - - gpus = tf.config.experimental.list_physical_devices('GPU') - for gpu in gpus: -     tf.config.experimental.set_memory_growth(gpu, True) - if gpus: -     tf.config.experimental.set_visible_devices(gpus[sdp.local_rank()], 'GPU') - - -- Scale the learning rate by the number of workers. - ``sdp.tensorflow.size()`` API provides you number of workers in the - cluster. This is invoked in the next code block as ``sdp.size()``. - - .. code:: python - - learning_rate = learning_rate * sdp.size() - - -- Use the library’s ``DistributedGradientTape`` to optimize AllReduce - operations during training. This wraps ``tf.GradientTape``. - - .. code:: python - - with tf.GradientTape() as tape: -       output = model(input) -       loss_value = loss(label, output) - - # Wrap tf.GradientTape with the library's DistributedGradientTape - tape = sdp.DistributedGradientTape(tape) - - -- Broadcast initial model variables from the leader node (rank 0) to - all the worker nodes (ranks 1 through n). This is needed to ensure a - consistent initialization across all the worker ranks. For this, you - use ``sdp.tensorflow.broadcast_variables`` API after the - model and optimizer variables are initialized. This is invoked in the - next code block as ``sdp.broadcast_variables()``. - - .. code:: python - - sdp.broadcast_variables(model.variables, root_rank=0) - sdp.broadcast_variables(opt.variables(), root_rank=0) - - -- Finally, modify your script to save checkpoints only on the leader - node. The leader node will have a synchronized model. This also - avoids worker nodes overwriting the checkpoints and possibly - corrupting the checkpoints. - - .. code:: python - - if sdp.rank() == 0: -     checkpoint.save(checkpoint_dir) - - -All put together, the following is an example TensorFlow2 training -script you will have for distributed training with the library. - -.. code:: python - - import tensorflow as tf - - # Import the library's TF API - import smdistributed.dataparallel.tensorflow as sdp - - # Initialize the library - sdp.init() - - gpus = tf.config.experimental.list_physical_devices('GPU') - for gpu in gpus: -     tf.config.experimental.set_memory_growth(gpu, True) - if gpus: -     # Pin GPUs to a single process -     tf.config.experimental.set_visible_devices(gpus[sdp.local_rank()], 'GPU') - - # Prepare Dataset - dataset = tf.data.Dataset.from_tensor_slices(...) - - # Define Model - mnist_model = tf.keras.Sequential(...) - loss = tf.losses.SparseCategoricalCrossentropy() - - # Scale Learning Rate - # LR for 8 node run : 0.000125 - # LR for single node run : 0.001 - opt = tf.optimizers.Adam(0.000125 * sdp.size()) - - @tf.function - def training_step(images, labels, first_batch): -     with tf.GradientTape() as tape: -         probs = mnist_model(images, training=True) -         loss_value = loss(labels, probs) - -     # Wrap tf.GradientTape with the library's DistributedGradientTape -     tape = sdp.DistributedGradientTape(tape) - -     grads = tape.gradient(loss_value, mnist_model.trainable_variables) -     opt.apply_gradients(zip(grads, mnist_model.trainable_variables)) - -     if first_batch: -        # Broadcast model and optimizer variables -        sdp.broadcast_variables(mnist_model.variables, root_rank=0) -        sdp.broadcast_variables(opt.variables(), root_rank=0) - -     return loss_value - - ... - - # Save checkpoints only from master node. - if sdp.rank() == 0: -     checkpoint.save(checkpoint_dir) - - -.. _tensorflow-sdp-api-1.0.0: - -TensorFlow API -============== - -.. rubric:: Supported versions - -**TensorFlow 2.3.x - 2.4.1** - - -.. function:: smdistributed.dataparallel.tensorflow.init() - :noindex: - - Initialize ``smdistributed.dataparallel``. Must be called at the - beginning of the training script. - - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - - .. rubric:: Notes - - ``init()`` needs to be called only once. It will throw an error if - called more than once: - - ``init() called more than once. smdistributed.dataparallel is already initialized.`` - - -.. function:: smdistributed.dataparallel.tensorflow.size() - :noindex: - - The total number of GPUs across all the nodes in the cluster. For - example, in a 8 node cluster with 8 GPUs each, ``size`` will be equal - to 64. - - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the total number of GPUs, across all - nodes in the cluster. - - -.. function:: smdistributed.dataparallel.tensorflow.local_size() - :noindex: - - The total number of GPUs on a node. For example, on a node with 8 - GPUs, ``local_size`` will be equal to 8. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the total number of GPUs on itself. - - -.. function:: smdistributed.dataparallel.tensorflow.rank() - :noindex: - - The rank of the node in the cluster. The rank ranges from 0 to number of - nodes - 1. This is similar to MPI's World Rank. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the node. - - -.. function:: smdistributed.dataparallel.tensorflow.local_rank() - :noindex: - - Local rank refers to the relative rank of the - GPUs’ ``smdistributed.dataparallel`` processes within the node. For - example, if a node contains 8 GPUs, it has - 8 ``smdistributed.dataparallel`` processes, then each process will - get a local rank ranging from 0 to 7. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the GPU and - its ``smdistributed.dataparallel`` process. - - -.. function:: smdistributed.dataparallel.tensorflow.allreduce(tensor, param_index, num_params, compression=Compression.none, op=ReduceOp.AVERAGE) - :noindex: - - Performs an all-reduce operation on a tensor (``tf.Tensor``). - - ``smdistributed.dataparallel`` AllReduce API can be used for all - reducing gradient tensors or any other tensors. By - default, ``smdistributed.dataparallel`` AllReduce averages the - tensors across the participating workers. - ​ - **Inputs:** - - - ``tensor (tf.Tensor)(required)``: The tensor to be all-reduced. The shape of the input must be identical across all ranks. - - ``param_index (int)(required):`` 0 if you are reducing a single tensor. Index of the tensor if you are reducing a list of tensors. - - ``num_params (int)(required):`` len(tensor). - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``op (optional)(smdistributed.dataparallel.tensorflow.ReduceOp)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``SUM``, ``MIN``, ``MAX``, ``AVERAGE`` - - **Returns:** - - - A tensor of the same shape and type as input ``tensor``, all-reduced across all the processes. - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast_global_variables(root_rank) - :noindex: - - Broadcasts all global variables from root rank to all other processes. - - **Inputs:** - - - ``root_rank (int)(required):`` Rank of the process from which global - variables will be broadcasted to all other processes. - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast_variables(variables, root_rank) - :noindex: - - Applicable for TensorFlow 2.x only. - ​ - Broadcasts variables from root rank to all other processes. - ​ - With TensorFlow 2.x, ``broadcast_variables`` is used to - broadcast ``model.variables`` and ``optimizer.variables`` post - initialization from the leader node to all the worker nodes. This - ensures a consistent initialization across all the worker ranks. - - **Inputs:** - - - ``variables (tf.Variable)(required):`` Variables to be broadcasted. - - ``root_rank (int)(required):`` Rank of the process from which - variables will be broadcasted to all other processes. - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.oob_allreduce(tensor, compression=Compression.none, op=ReduceOp.AVERAGE) - :noindex: - - OutOfBand (oob) AllReduce is simplified AllReduce function for use cases - such as calculating total loss across all the GPUs in the training. - oob_allreduce average the tensors, as reduction operation, across the - worker nodes. - - **Inputs:** - - - ``tensor (tf.Tensor)(required)``: The tensor to be all-reduced. The shape of the input must be identical across all worker nodes. - - ``compression`` (optional): Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different worker nodes. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - **Returns:** - - - ``None`` - - .. rubric:: Notes - - ``smdistributed.dataparallel.tensorflow.oob_allreduce``, in most - cases, is ~2x slower - than ``smdistributed.dataparallel.tensorflow.allreduce``  so it is not - recommended to be used for performing gradient reduction during the - training - process. ``smdistributed.dataparallel.tensorflow.oob_allreduce`` internally - uses NCCL AllReduce with ``ncclSum`` as the reduction operation. - - -.. function:: smdistributed.dataparallel.tensorflow.overlap(tensor) - :noindex: - - This function is applicable only for models compiled with XLA. Use this - function to enable ``smdistributed.dataparallel`` to efficiently - overlap backward pass with the all reduce operation. - - Example usage: - - .. code:: python - - layer = tf.nn.dropout(...) # Or any other layer - layer = smdistributed.dataparallel.tensorflow.overlap(layer) - - The overlap operation is inserted into the TF graph as a node. It - behaves as an identity operation, and helps in achieving the - communication overlap with backward pass operation. - - **Inputs:** - - - ``tensor (tf.Tensor)(required):`` The tensor to be all-reduced. - - **Returns:** - - - ``None`` - - .. rubric:: Notes - - This operation helps in speeding up distributed training, as - the AllReduce operation does not have to wait for all the gradients to - be ready. Backward propagation proceeds sequentially from the output - layer of the network to the input layer. When the gradient computation - for a layer finishes, ``smdistributed.dataparallel`` adds them to a - fusion buffer. As soon as the size of the fusion buffer reaches a - predefined threshold (25 Mb), ``smdistributed.dataparallel`` starts - the AllReduce operation. - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast(tensor, root_rank) - :noindex: - - Broadcasts the input tensor on root rank to the same input tensor on all - other ``smdistributed.dataparallel`` processes. - ​ - The broadcast will not start until all processes are ready to send and - receive the tensor. - - **Inputs:** - - - ``tensor (tf.Tensor)(required):`` The tensor to be broadcasted. - - ``root_rank (int)(required):`` Rank of the process from which - tensor will be broadcasted to all other processes. - - **Returns:** - - - A tensor of the same shape and type as tensor, with the value - broadcasted from root rank. - - -.. function:: smdistributed.dataparallel.tensorflow.shutdown() - :noindex: - - Shuts down ``smdistributed.dataparallel``. Optional to call at the end - of the training script. - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.DistributedOptimizer - :noindex: - - Applicable if you use the ``tf.estimator`` API in TensorFlow 2.x (2.3.1). - ​ - Construct a new ``DistributedOptimizer`` , which uses TensorFlow - optimizer under the hood for computing single-process gradient values - and applying gradient updates after the gradient values have been - combined across all ``smdistributed.dataparallel`` workers. - ​ - Example usage: - - .. code:: python - - opt = ... # existing optimizer from tf.train package or your custom optimizer - opt = smdistributed.dataparallel.tensorflow.DistributedOptimizer(opt) - - - - ``optimizer (tf.train.Optimizer)(required):`` TF Optimizer to use for computing gradients and applying updates. - - - ``name (str)(optional):`` Name prefix for the operations created when applying gradients. Defaults to ``smdistributed.dataparallel`` followed by provided optimizer type. - - - ``use_locking (bool)(optional):`` Whether to use locking when updating variables. Defaults to ``False``. - - - ``device_dense:`` Not supported. Raises not supported error. - - - ``device_sparse:`` Not supported. Raises not supported error. - - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``sparse_as_dense:`` Treats sparse gradient tensor as dense tensor. Defaults to ``False``. - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - - ``bucket_cap_mb (int)(optional):`` Size of ``smdistributed.dataparallel`` fusion buffer size. Defaults to 25MB that works optimally for most case. If you provide a value, expects the (value * 1024 * 1024) i.e., bytes to be multiple of 128. - - -.. function:: smdistributed.dataparallel.tensorflow.DistributedGradientTape - :noindex: - - Applicable to TensorFlow 2.x only. - - Construct a new ``DistributedGradientTape``, which uses - TensorFlow’s ``GradientTape`` under the hood, using an AllReduce to - combine gradient values before applying gradients to model weights. - ​ - Example Usage: - - .. code:: python - - with tf.GradientTape() as tape: -       output = model(input) -       loss_value = loss(label, output) - - # Wrap in smdistributed.dataparallel's DistributedGradientTape - tape = smdistributed.dataparallel.tensorflow.DistributedGradientTape(tape) - - - - ``gradtape (tf.GradientTape)(required):`` GradientTape to use for computing gradients and applying updates. - - - ``device_dense:`` Not supported. Raises not supported error. - - - ``device_sparse:`` Not supported. Raises not supported error. - - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``sparse_as_dense:`` Treats sparse gradient tensor as dense tensor. Defaults to ``False``. - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - -.. function:: smdistributed.dataparallel.tensorflow.BroadcastGlobalVariablesHook - :noindex: - - Applicable if you use the ``tf.estimator`` API in TensorFlow 2.x (2.3.1). - - - ``SessionRunHook`` that will broadcast all global variables from root - rank to all other processes during initialization. - ​ - This is necessary to ensure consistent initialization of all workers - when training is started with random weights or restored from a - checkpoint. - ​ - Example Usage: - - .. code:: python - - hooks = [smdistributed.dataparallel.tensorflow.BroadcastGlobalVariablesHook(root_rank=0)] - ... - with tf.train.MonitoredTrainingSession(checkpoint_dir=checkpoint_dir, -                                        hooks=hooks, -                                        config=config) as mon_sess: -      ... - - - - ``root_rank (int)(required):`` Rank of the process from which global - variables will be broadcasted to all other processes. - - -.. function:: smdistributed.dataparallel.tensorflow.Compression - :noindex: - - Optional Gradient Compression algorithm that can be used in AllReduce - operation. - - - ``none``: alias for ``NoneCompression``. Do not compression gradient - tensors. - - ``fp16``: alias for ``FP16Compression``. Compress the floating point - gradient tensors to 16-bit (FP16) - - -.. function:: smdistributed.dataparallel.tensorflow.ReduceOp - :noindex: - - Supported reduction operations in ``smdistributed.dataparallel``. - - - ``AVERAGE`` - - ``SUM`` - - ``MIN`` - - ``MAX`` diff --git a/doc/api/training/sdp_versions/v1.1.x/smd_data_parallel_pytorch.rst b/doc/api/training/sdp_versions/v1.1.x/smd_data_parallel_pytorch.rst deleted file mode 100644 index d8de621147..0000000000 --- a/doc/api/training/sdp_versions/v1.1.x/smd_data_parallel_pytorch.rst +++ /dev/null @@ -1,533 +0,0 @@ -############################################################## -PyTorch Guide to SageMaker's distributed data parallel library -############################################################## - -.. admonition:: Contents - - - :ref:`pytorch-sdp-modify-11x` - - :ref:`pytorch-sdp-api-11x` - -.. _pytorch-sdp-modify-11x: - - -Modify a PyTorch training script to use SageMaker data parallel -====================================================================== - -The following steps show you how to convert a PyTorch training script to -utilize SageMaker's distributed data parallel library. - -The distributed data parallel library APIs are designed to be close to PyTorch Distributed Data -Parallel (DDP) APIs. -See `SageMaker distributed data parallel PyTorch examples `__ for additional details on how to implement the data parallel library -API offered for PyTorch. - - -- First import the distributed data parallel library’s PyTorch client and initialize it. You also import - the distributed data parallel library module for distributed training. - - .. code:: python - - import smdistributed.dataparallel.torch.distributed as dist - - from smdistributed.dataparallel.torch.parallel.distributed import DistributedDataParallel as DDP - - dist.init_process_group() - - -- Pin each GPU to a single distributed data parallel library process with ``local_rank`` - this - refers to the relative rank of the process within a given node. - ``smdistributed.dataparallel.torch.get_local_rank()`` API provides - you the local rank of the device. The leader node will be rank 0, and - the worker nodes will be rank 1, 2, 3, and so on. This is invoked in - the next code block as ``dist.get_local_rank()``. - - .. code:: python - - torch.cuda.set_device(dist.get_local_rank()) - - -- Then wrap the PyTorch model with the distributed data parallel library’s DDP. - - .. code:: python - - model = ... - # Wrap model with SageMaker's DistributedDataParallel - model = DDP(model) - - -- Modify the ``torch.utils.data.distributed.DistributedSampler`` to - include the cluster’s information. Set``num_replicas`` to the - total number of GPUs participating in training across all the nodes - in the cluster. This is called ``world_size``. You can get - ``world_size`` with - ``smdistributed.dataparallel.torch.get_world_size()`` API. This is - invoked in the following code as ``dist.get_world_size()``. Also - supply the node rank using - ``smdistributed.dataparallel.torch.get_rank()``. This is invoked as - ``dist.get_rank()``. - - .. code:: python - - train_sampler = DistributedSampler(train_dataset, num_replicas=dist.get_world_size(), rank=dist.get_rank()) - - -- Finally, modify your script to save checkpoints only on the leader - node. The leader node will have a synchronized model. This also - avoids worker nodes overwriting the checkpoints and possibly - corrupting the checkpoints. - -.. code:: python - - if dist.get_rank() == 0: - torch.save(...) - - -All put together, the following is an example PyTorch training script -you will have for distributed training with the distributed data parallel library: - -.. code:: python - - # Import distributed data parallel library PyTorch API - import smdistributed.dataparallel.torch.distributed as dist - - # Import distributed data parallel library PyTorch DDP - from smdistributed.dataparallel.torch.parallel.distributed import DistributedDataParallel as DDP - - # Initialize distributed data parallel library - dist.init_process_group() - - class Net(nn.Module): -     ... -     # Define model - - def train(...): -     ... -     # Model training - - def test(...): -     ... -     # Model evaluation - - def main(): - -     # Scale batch size by world size -     batch_size //= dist.get_world_size() // 8 -     batch_size = max(batch_size, 1) - -     # Prepare dataset -     train_dataset = torchvision.datasets.MNIST(...) - -     # Set num_replicas and rank in DistributedSampler -     train_sampler = torch.utils.data.distributed.DistributedSampler( -             train_dataset, -             num_replicas=dist.get_world_size(), -             rank=dist.get_rank()) - -     train_loader = torch.utils.data.DataLoader(..) - -     # Wrap the PyTorch model with distributed data parallel library’s DDP -     model = DDP(Net().to(device)) - -     # Pin each GPU to a single distributed data parallel library process. -     torch.cuda.set_device(local_rank) -     model.cuda(local_rank) - -     # Train -     optimizer = optim.Adadelta(...) -     scheduler = StepLR(...) -     for epoch in range(1, args.epochs + 1): -         train(...) -         if rank == 0: -             test(...) -         scheduler.step() - -     # Save model on master node. -     if dist.get_rank() == 0: -         torch.save(...) - - if __name__ == '__main__': -     main() - - -.. _pytorch-sdp-api-11x: - - -PyTorch API -=========== - -.. rubric:: Supported versions - -**PyTorch 1.7.1, 1.8.1** - - -.. function:: smdistributed.dataparallel.torch.distributed.is_available() - :noindex: - - Check if script started as a distributed job. For local runs user can - check that is_available returns False and run the training script - without calls to ``smdistributed.dataparallel``. - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``True`` if started as a distributed job, ``False`` otherwise - - -.. function:: smdistributed.dataparallel.torch.distributed.init_process_group(*args, **kwargs) - :noindex: - - Initialize ``smdistributed.dataparallel``. Must be called at the - beginning of the training script, before calling any other methods. - ​ - Process group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with ``torch.distributed`` only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - ​ - After this - call, ``smdistributed.dataparallel.torch.distributed.is_initialized()`` will - return ``True``. - ​ - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.torch.distributed.is_initialized() - :noindex: - - Checks if the default process group has been initialized. - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``True`` if initialized, else ``False``. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_world_size(group=smdistributed.dataparallel.torch.distributed.group.WORLD) - :noindex: - - The total number of GPUs across all the nodes in the cluster. For - example, in a 8 node cluster with 8 GPU each, size will be equal to 64. - - **Inputs:** - - - ``group (smdistributed.dataparallel.torch.distributed.group) (optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - **Returns:** - - - An integer scalar containing the total number of GPUs in the training - job, across all nodes in the cluster. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_rank(group=smdistributed.dataparallel.torch.distributed.group.WORLD) - :noindex: - - The rank of the node in the cluster. The rank ranges from 0 to number of - nodes - 1. This is similar to MPI's World Rank. - - - **Inputs:** - - - ``group (smdistributed.dataparallel.torch.distributed.group) (optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - **Returns:** - - - An integer scalar containing the rank of the worker node. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_local_rank() - :noindex: - - Local rank refers to the relative rank of - the ``smdistributed.dataparallel`` process within the node the current - process is running on. For example, if a node contains 8 GPUs, it has - 8 ``smdistributed.dataparallel`` processes. Each process has - a ``local_rank`` ranging from 0 to 7. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the GPU and - its ``smdistributed.dataparallel`` process. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_reduce(tensor, op=smdistributed.dataparallel.torch.distributed.ReduceOp.SUM, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Performs an all-reduce operation on a tensor (torch.tensor) across - all ``smdistributed.dataparallel`` workers - - ``smdistributed.dataparallel`` AllReduce API can be used for all - reducing gradient tensors or any other tensors.  By - default, ``smdistributed.dataparallel`` AllReduce reduces the tensor - data across all ``smdistributed.dataparallel`` workers in such a way - that all get the final result. - - After the call ``tensor`` is going to be bitwise identical in all - processes. - - **Inputs:** - - - ``tensor (torch.tensor) (required):`` Input and output of the collective. The function operates in-place. - - - ``op (smdistributed.dataparallel.torch.distributed.ReduceOp) (optional)``: The reduction operation to combine tensors across different ranks.  Defaults to ``SUM`` if None is given. - - * Supported ops: ``AVERAGE``, ``SUM``, ``MIN``, ``MAX`` - - - ``group (smdistributed.dataparallel.torch.distributed.group) (optional):`` Process group is not supported in ``smdistributed.dataparallel``. This parameter exists for API parity with torch.distributed only. - - * Only supported value is ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - - ``async_op (bool) (optional):`` Whether this op should be an async op. Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - .. rubric:: Notes - - ``smdistributed.dataparallel.torch.distributed.allreduce``, in most - cases, is ~2X slower than all-reducing - with ``smdistributed.dataparallel.torch.parallel.distributed.DistributedDataParallel`` and - hence, it is not recommended to be used for performing gradient - reduction during the training - process. ``smdistributed.dataparallel.torch.distributed.allreduce`` internally - uses NCCL AllReduce with ``ncclSum`` as the reduction operation. - - -.. function:: smdistributed.dataparallel.torch.distributed.broadcast(tensor, src=0, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Broadcasts the tensor (torch.tensor) to the whole group. - - ``tensor`` must have the same number of elements as GPUs in the - cluster. - - **Inputs:** - - - ``tensor (torch.tensor)(required)`` - - - ``src (int)(optional)`` - - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process group is not supported in ``smdistributed.dataparallel``. This parameter exists for API parity with ``torch.distributed`` only. - - * Only supported value is ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - - ``async_op (bool)(optional):`` Whether this op should be an async op. Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, otherwise. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_gather(tensor_list, tensor, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Gathers tensors from the whole group in a list. - - - **Inputs:** - - - ``tensor_list (list[torch.tensor])(required):`` Output list. It - should contain correctly-sized tensors to be used for output of the - collective. - - ``tensor (torch.tensor)(required):`` Tensor to be broadcast from - current process. - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - ``async_op (bool)(optional):`` Whether this op should be an async op. - Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_to_all_single(output_t, input_t, output_split_sizes=None, input_split_sizes=None, group=group.WORLD, async_op=False) - :noindex: - - Each process scatters input tensor to all processes in a group and return gathered tensor in output. - - **Inputs:** - - - output_t - - input_t - - output_split_sizes - - input_split_sizes - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - ``async_op (bool)(optional):`` Whether this op should be an async op. - Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - -.. function:: smdistributed.dataparallel.torch.distributed.barrier(group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Synchronizes all ``smdistributed.dataparallel`` processes. - - **Inputs:** - - - tensor (torch.tensor)(required): Data to be sent if src is the rank of current process, and tensor to be used to save received data otherwise. - - - src (int)(optional): Source rank. - - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. - - * Only supported value is ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - - ``async_op (bool)(optional):`` Whether this op should be an async op. - Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - -.. class:: smdistributed.dataparallel.torch.parallel.DistributedDataParallel(module, device_ids=None, output_device=None, broadcast_buffers=True, process_group=None, bucket_cap_mb=None) - :noindex: - - ``smdistributed.dataparallel's`` implementation of distributed data - parallelism for PyTorch. In most cases, wrapping your PyTorch Module - with ``smdistributed.dataparallel's`` ``DistributedDataParallel (DDP)`` is - all you need to do to use ``smdistributed.dataparallel``. - - Creation of this DDP class requires ``smdistributed.dataparallel`` - already initialized - with ``smdistributed.dataparallel.torch.distributed.init_process_group()``. - - This container parallelizes the application of the given module by - splitting the input across the specified devices by chunking in the - batch dimension. The module is replicated on each machine and each - device, and each such replica handles a portion of the input. During the - backwards pass, gradients from each node are averaged. - - The batch size should be larger than the number of GPUs used locally. - ​ - Example usage - of ``smdistributed.dataparallel.torch.parallel.DistributedDataParallel``: - - .. code:: python - - import torch - import smdistributed.dataparallel.torch.distributed as dist - from smdistributed.dataparallel.torch.parallel import DistributedDataParallel as DDP - - dist.init_process_group() - - # Pin GPU to be used to process local rank (one GPU per process) - torch.cuda.set_device(dist.get_local_rank()) - - # Build model and optimizer - model = ... - optimizer = torch.optim.SGD(model.parameters(), -                             lr=1e-3 * dist.get_world_size()) - # Wrap model with smdistributed.dataparallel's DistributedDataParallel - model = DDP(model) - - **Parameters:** - - - ``module (torch.nn.Module)(required):`` PyTorch NN Module to be - parallelized - - ``device_ids (list[int])(optional):`` CUDA devices. This should only - be provided when the input module resides on a single CUDA device. - For single-device modules, - the ``ith module replica is placed on device_ids[i]``. For - multi-device modules and CPU modules, device_ids must be None or an - empty list, and input data for the forward pass must be placed on the - correct device. Defaults to ``None``. - - ``output_device (int)(optional):`` Device location of output for - single-device CUDA modules. For multi-device modules and CPU modules, - it must be None, and the module itself dictates the output location. - (default: device_ids[0] for single-device modules).  Defaults - to ``None``. - - ``broadcast_buffers (bool)(optional):`` Flag that enables syncing - (broadcasting) buffers of the module at beginning of the forward - function. ``smdistributed.dataparallel`` does not support broadcast - buffer yet. Please set this to ``False``. - - ``process_group(smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` Defaults - to ``None.`` - - ``bucket_cap_mb (int)(optional):`` DistributedDataParallel will - bucket parameters into multiple buckets so that gradient reduction of - each bucket can potentially overlap with backward - computation. ``bucket_cap_mb`` controls the bucket size in - MegaBytes (MB) (default: 25). - - .. rubric:: Notes - - - This module assumes all parameters are registered in the model by the - time it is created. No parameters should be added nor removed later. - - This module assumes all parameters are registered in the model of - each distributed processes are in the same order. The module itself - will conduct gradient all-reduction following the reverse order of - the registered parameters of the model. In other words, it is users’ - responsibility to ensure that each distributed process has the exact - same model and thus the exact same parameter registration order. - - You should never change the set of your model’s parameters after - wrapping up your model with DistributedDataParallel. In other words, - when wrapping up your model with DistributedDataParallel, the - constructor of DistributedDataParallel will register the additional - gradient reduction functions on all the parameters of the model - itself at the time of construction. If you change the model’s - parameters after the DistributedDataParallel construction, this is - not supported and unexpected behaviors can happen, since some - parameters’ gradient reduction functions might not get called. - - -.. class:: smdistributed.dataparallel.torch.distributed.ReduceOp - :noindex: - - An enum-like class for supported reduction operations - in ``smdistributed.dataparallel``. - - The values of this class can be accessed as attributes, for - example, ``ReduceOp.SUM``. They are used in specifying strategies for - reduction collectives such as -  ``smdistributed.dataparallel.torch.distributed.all_reduce(...)``. - - - ``AVERAGE`` - - ``SUM`` - - ``MIN`` - - ``MAX`` diff --git a/doc/api/training/sdp_versions/v1.1.x/smd_data_parallel_tensorflow.rst b/doc/api/training/sdp_versions/v1.1.x/smd_data_parallel_tensorflow.rst deleted file mode 100644 index 09120b2ded..0000000000 --- a/doc/api/training/sdp_versions/v1.1.x/smd_data_parallel_tensorflow.rst +++ /dev/null @@ -1,558 +0,0 @@ -################################################################# -TensorFlow Guide to SageMaker's distributed data parallel library -################################################################# - -.. admonition:: Contents - - - :ref:`tensorflow-sdp-modify-11x` - - :ref:`tensorflow-sdp-api-11x` - -.. _tensorflow-sdp-modify-11x: - - -Modify a TensorFlow 2.x training script to use SageMaker data parallel -====================================================================== - -The following steps show you how to convert a TensorFlow 2.x training -script to utilize the distributed data parallel library. - -The distributed data parallel library APIs are designed to be close to Horovod APIs. -See `SageMaker distributed data parallel TensorFlow examples -`__ -for additional details on how to implement the data parallel library. - -- First import the distributed data parallel library’s TensorFlow client and initialize it: - - .. code:: python - - import smdistributed.dataparallel.tensorflow as sdp - sdp.init() - - -- Pin each GPU to a single smdistributed.dataparallel process - with ``local_rank`` - this refers to the relative rank of the - process within a given node. ``sdp.tensorflow.local_rank()`` API - provides you the local rank of the device. The leader node will be - rank 0, and the worker nodes will be rank 1, 2, 3, and so on. This is - invoked in the next code block as ``sdp.local_rank()``. - ``set_memory_growth`` is not directly related to SMD, but must be set - for distributed training with TensorFlow. - - .. code:: python - - gpus = tf.config.experimental.list_physical_devices('GPU') - for gpu in gpus: -     tf.config.experimental.set_memory_growth(gpu, True) - if gpus: -     tf.config.experimental.set_visible_devices(gpus[sdp.local_rank()], 'GPU') - - -- Scale the learning rate by the number of workers. - ``sdp.tensorflow.size()`` API provides you number of workers in the - cluster. This is invoked in the next code block as ``sdp.size()``. - - .. code:: python - - learning_rate = learning_rate * sdp.size() - - -- Use the library’s ``DistributedGradientTape`` to optimize AllReduce - operations during training. This wraps ``tf.GradientTape``. - - .. code:: python - - with tf.GradientTape() as tape: -       output = model(input) -       loss_value = loss(label, output) - - # Wrap tf.GradientTape with the library's DistributedGradientTape - tape = sdp.DistributedGradientTape(tape) - - -- Broadcast initial model variables from the leader node (rank 0) to - all the worker nodes (ranks 1 through n). This is needed to ensure a - consistent initialization across all the worker ranks. For this, you - use ``sdp.tensorflow.broadcast_variables`` API after the - model and optimizer variables are initialized. This is invoked in the - next code block as ``sdp.broadcast_variables()``. - - .. code:: python - - sdp.broadcast_variables(model.variables, root_rank=0) - sdp.broadcast_variables(opt.variables(), root_rank=0) - - -- Finally, modify your script to save checkpoints only on the leader - node. The leader node will have a synchronized model. This also - avoids worker nodes overwriting the checkpoints and possibly - corrupting the checkpoints. - - .. code:: python - - if sdp.rank() == 0: -     checkpoint.save(checkpoint_dir) - - -All put together, the following is an example TensorFlow2 training -script you will have for distributed training with the library. - -.. code:: python - - import tensorflow as tf - - # Import the library's TF API - import smdistributed.dataparallel.tensorflow as sdp - - # Initialize the library - sdp.init() - - gpus = tf.config.experimental.list_physical_devices('GPU') - for gpu in gpus: -     tf.config.experimental.set_memory_growth(gpu, True) - if gpus: -     # Pin GPUs to a single process -     tf.config.experimental.set_visible_devices(gpus[sdp.local_rank()], 'GPU') - - # Prepare Dataset - dataset = tf.data.Dataset.from_tensor_slices(...) - - # Define Model - mnist_model = tf.keras.Sequential(...) - loss = tf.losses.SparseCategoricalCrossentropy() - - # Scale Learning Rate - # LR for 8 node run : 0.000125 - # LR for single node run : 0.001 - opt = tf.optimizers.Adam(0.000125 * sdp.size()) - - @tf.function - def training_step(images, labels, first_batch): -     with tf.GradientTape() as tape: -         probs = mnist_model(images, training=True) -         loss_value = loss(labels, probs) - -     # Wrap tf.GradientTape with the library's DistributedGradientTape -     tape = sdp.DistributedGradientTape(tape) - -     grads = tape.gradient(loss_value, mnist_model.trainable_variables) -     opt.apply_gradients(zip(grads, mnist_model.trainable_variables)) - -     if first_batch: -        # Broadcast model and optimizer variables -        sdp.broadcast_variables(mnist_model.variables, root_rank=0) -        sdp.broadcast_variables(opt.variables(), root_rank=0) - -     return loss_value - - ... - - # Save checkpoints only from master node. - if sdp.rank() == 0: -     checkpoint.save(checkpoint_dir) - - -.. _tensorflow-sdp-api-11x: - - -TensorFlow API -============== - -.. rubric:: Supported versions - -Use version 1.0.0 or version 1.2.0 or later of ``smdistributed.dataparallel`` to use this -library with TensorFlow. - -.. function:: smdistributed.dataparallel.tensorflow.init() - :noindex: - - Initialize ``smdistributed.dataparallel``. Must be called at the - beginning of the training script. - - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - - .. rubric:: Notes - - ``init()`` needs to be called only once. It will throw an error if - called more than once: - - ``init() called more than once. smdistributed.dataparallel is already initialized.`` - - -.. function:: smdistributed.dataparallel.tensorflow.size() - :noindex: - - The total number of GPUs across all the nodes in the cluster. For - example, in a 8 node cluster with 8 GPUs each, ``size`` will be equal - to 64. - - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the total number of GPUs, across all - nodes in the cluster. - - -.. function:: smdistributed.dataparallel.tensorflow.local_size() - :noindex: - - The total number of GPUs on a node. For example, on a node with 8 - GPUs, ``local_size`` will be equal to 8. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the total number of GPUs on itself. - - -.. function:: smdistributed.dataparallel.tensorflow.rank() - :noindex: - - The rank of the node in the cluster. The rank ranges from 0 to number of - nodes - 1. This is similar to MPI's World Rank. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the node. - - -.. function:: smdistributed.dataparallel.tensorflow.local_rank() - :noindex: - - Local rank refers to the relative rank of the - GPUs’ ``smdistributed.dataparallel`` processes within the node. For - example, if a node contains 8 GPUs, it has - 8 ``smdistributed.dataparallel`` processes, then each process will - get a local rank ranging from 0 to 7. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the GPU and - its ``smdistributed.dataparallel`` process. - - -.. function:: smdistributed.dataparallel.tensorflow.allreduce(tensor, param_index, num_params, compression=Compression.none, op=ReduceOp.AVERAGE) - :noindex: - - Performs an all-reduce operation on a tensor (``tf.Tensor``). - - ``smdistributed.dataparallel`` AllReduce API can be used for all - reducing gradient tensors or any other tensors. By - default, ``smdistributed.dataparallel`` AllReduce averages the - tensors across the participating workers. - ​ - **Inputs:** - - - ``tensor (tf.Tensor)(required)``: The tensor to be all-reduced. The shape of the input must be identical across all ranks. - - ``param_index (int)(required):`` 0 if you are reducing a single tensor. Index of the tensor if you are reducing a list of tensors. - - ``num_params (int)(required):`` len(tensor). - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``op (optional)(smdistributed.dataparallel.tensorflow.ReduceOp)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``SUM``, ``MIN``, ``MAX``, ``AVERAGE`` - - **Returns:** - - - A tensor of the same shape and type as input ``tensor``, all-reduced across all the processes. - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast_global_variables(root_rank) - :noindex: - - Broadcasts all global variables from root rank to all other processes. - - **Inputs:** - - - ``root_rank (int)(required):`` Rank of the process from which global - variables will be broadcasted to all other processes. - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast_variables(variables, root_rank) - :noindex: - - Applicable for TensorFlow 2.x only. - ​ - Broadcasts variables from root rank to all other processes. - ​ - With TensorFlow 2.x, ``broadcast_variables`` is used to - broadcast ``model.variables`` and ``optimizer.variables`` post - initialization from the leader node to all the worker nodes. This - ensures a consistent initialization across all the worker ranks. - - **Inputs:** - - - ``variables (tf.Variable)(required):`` Variables to be broadcasted. - - ``root_rank (int)(required):`` Rank of the process from which - variables will be broadcasted to all other processes. - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.oob_allreduce(tensor, compression=Compression.none, op=ReduceOp.AVERAGE) - :noindex: - - OutOfBand (oob) AllReduce is simplified AllReduce function for use cases - such as calculating total loss across all the GPUs in the training. - oob_allreduce average the tensors, as reduction operation, across the - worker nodes. - - **Inputs:** - - - ``tensor (tf.Tensor)(required)``: The tensor to be all-reduced. The shape of the input must be identical across all worker nodes. - - ``compression`` (optional): Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different worker nodes. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - **Returns:** - - - ``None`` - - .. rubric:: Notes - - ``smdistributed.dataparallel.tensorflow.oob_allreduce``, in most - cases, is ~2x slower - than ``smdistributed.dataparallel.tensorflow.allreduce``  so it is not - recommended to be used for performing gradient reduction during the - training - process. ``smdistributed.dataparallel.tensorflow.oob_allreduce`` internally - uses NCCL AllReduce with ``ncclSum`` as the reduction operation. - - -.. function:: smdistributed.dataparallel.tensorflow.overlap(tensor) - :noindex: - - This function is applicable only for models compiled with XLA. Use this - function to enable ``smdistributed.dataparallel`` to efficiently - overlap backward pass with the all reduce operation. - - Example usage: - - .. code:: python - - layer = tf.nn.dropout(...) # Or any other layer - layer = smdistributed.dataparallel.tensorflow.overlap(layer) - - The overlap operation is inserted into the TF graph as a node. It - behaves as an identity operation, and helps in achieving the - communication overlap with backward pass operation. - - **Inputs:** - - - ``tensor (tf.Tensor)(required):`` The tensor to be all-reduced. - - **Returns:** - - - ``None`` - - .. rubric:: Notes - - This operation helps in speeding up distributed training, as - the AllReduce operation does not have to wait for all the gradients to - be ready. Backward propagation proceeds sequentially from the output - layer of the network to the input layer. When the gradient computation - for a layer finishes, ``smdistributed.dataparallel`` adds them to a - fusion buffer. As soon as the size of the fusion buffer reaches a - predefined threshold (25 Mb), ``smdistributed.dataparallel`` starts - the AllReduce operation. - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast(tensor, root_rank) - :noindex: - - Broadcasts the input tensor on root rank to the same input tensor on all - other ``smdistributed.dataparallel`` processes. - ​ - The broadcast will not start until all processes are ready to send and - receive the tensor. - - **Inputs:** - - - ``tensor (tf.Tensor)(required):`` The tensor to be broadcasted. - - ``root_rank (int)(required):`` Rank of the process from which - tensor will be broadcasted to all other processes. - - **Returns:** - - - A tensor of the same shape and type as tensor, with the value - broadcasted from root rank. - - -.. function:: smdistributed.dataparallel.tensorflow.shutdown() - :noindex: - - Shuts down ``smdistributed.dataparallel``. Optional to call at the end - of the training script. - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.DistributedOptimizer - :noindex: - - Applicable if you use the ``tf.estimator`` API in TensorFlow 2.x (2.3.1). - ​ - Construct a new ``DistributedOptimizer`` , which uses TensorFlow - optimizer under the hood for computing single-process gradient values - and applying gradient updates after the gradient values have been - combined across all ``smdistributed.dataparallel`` workers. - ​ - Example usage: - - .. code:: python - - opt = ... # existing optimizer from tf.train package or your custom optimizer - opt = smdistributed.dataparallel.tensorflow.DistributedOptimizer(opt) - - - - ``optimizer (tf.train.Optimizer)(required):`` TF Optimizer to use for computing gradients and applying updates. - - - ``name (str)(optional):`` Name prefix for the operations created when applying gradients. Defaults to ``smdistributed.dataparallel`` followed by provided optimizer type. - - - ``use_locking (bool)(optional):`` Whether to use locking when updating variables. Defaults to ``False``. - - - ``device_dense:`` Not supported. Raises not supported error. - - - ``device_sparse:`` Not supported. Raises not supported error. - - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``sparse_as_dense:`` Treats sparse gradient tensor as dense tensor. Defaults to ``False``. - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - - ``bucket_cap_mb (int)(optional):`` Size of ``smdistributed.dataparallel`` fusion buffer size. Defaults to 25MB that works optimally for most case. If you provide a value, expects the (value * 1024 * 1024) i.e., bytes to be multiple of 128. - - -.. function:: smdistributed.dataparallel.tensorflow.DistributedGradientTape - :noindex: - - Applicable to TensorFlow 2.x only. - - Construct a new ``DistributedGradientTape``, which uses - TensorFlow’s ``GradientTape`` under the hood, using an AllReduce to - combine gradient values before applying gradients to model weights. - ​ - Example Usage: - - .. code:: python - - with tf.GradientTape() as tape: -       output = model(input) -       loss_value = loss(label, output) - - # Wrap in smdistributed.dataparallel's DistributedGradientTape - tape = smdistributed.dataparallel.tensorflow.DistributedGradientTape(tape) - - - - ``gradtape (tf.GradientTape)(required):`` GradientTape to use for computing gradients and applying updates. - - - ``device_dense:`` Not supported. Raises not supported error. - - - ``device_sparse:`` Not supported. Raises not supported error. - - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``sparse_as_dense:`` Treats sparse gradient tensor as dense tensor. Defaults to ``False``. - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - -.. function:: smdistributed.dataparallel.tensorflow.BroadcastGlobalVariablesHook - :noindex: - - Applicable if you use the ``tf.estimator`` API in TensorFlow 2.x (2.3.1). - - - ``SessionRunHook`` that will broadcast all global variables from root - rank to all other processes during initialization. - ​ - This is necessary to ensure consistent initialization of all workers - when training is started with random weights or restored from a - checkpoint. - ​ - Example Usage: - - .. code:: python - - hooks = [smdistributed.dataparallel.tensorflow.BroadcastGlobalVariablesHook(root_rank=0)] - ... - with tf.train.MonitoredTrainingSession(checkpoint_dir=checkpoint_dir, -                                        hooks=hooks, -                                        config=config) as mon_sess: -      ... - - - - ``root_rank (int)(required):`` Rank of the process from which global - variables will be broadcasted to all other processes. - - -.. function:: smdistributed.dataparallel.tensorflow.Compression - :noindex: - - Optional Gradient Compression algorithm that can be used in AllReduce - operation. - - - ``none``: alias for ``NoneCompression``. Do not compression gradient - tensors. - - ``fp16``: alias for ``FP16Compression``. Compress the floating point - gradient tensors to 16-bit (FP16) - - -.. function:: smdistributed.dataparallel.tensorflow.ReduceOp - :noindex: - - Supported reduction operations in ``smdistributed.dataparallel``. - - - ``AVERAGE`` - - ``SUM`` - - ``MIN`` - - ``MAX`` diff --git a/doc/api/training/sdp_versions/v1.2.x/smd_data_parallel_pytorch.rst b/doc/api/training/sdp_versions/v1.2.x/smd_data_parallel_pytorch.rst deleted file mode 100644 index 6075a3cf1c..0000000000 --- a/doc/api/training/sdp_versions/v1.2.x/smd_data_parallel_pytorch.rst +++ /dev/null @@ -1,566 +0,0 @@ -############################################################## -PyTorch Guide to SageMaker's distributed data parallel library -############################################################## - -Use this guide to learn about the SageMaker distributed -data parallel library API for PyTorch. - -.. contents:: Topics - :depth: 3 - :local: - -.. _pytorch-sdp-modify: - :noindex: - -Modify a PyTorch training script to use SageMaker data parallel -====================================================================== - -The following steps show you how to convert a PyTorch training script to -utilize SageMaker's distributed data parallel library. - -The distributed data parallel library APIs are designed to be close to PyTorch Distributed Data -Parallel (DDP) APIs. -See `SageMaker distributed data parallel PyTorch examples `__ for additional details on how to implement the data parallel library -API offered for PyTorch. - - -- First import the distributed data parallel library’s PyTorch client and initialize it. You also import - the distributed data parallel library module for distributed training. - - .. code:: python - - import smdistributed.dataparallel.torch.distributed as dist - - from smdistributed.dataparallel.torch.parallel.distributed import DistributedDataParallel as DDP - - dist.init_process_group() - - -- Pin each GPU to a single distributed data parallel library process with ``local_rank`` - this - refers to the relative rank of the process within a given node. - ``smdistributed.dataparallel.torch.get_local_rank()`` API provides - you the local rank of the device. The leader node will be rank 0, and - the worker nodes will be rank 1, 2, 3, and so on. This is invoked in - the next code block as ``dist.get_local_rank()``. - - .. code:: python - - torch.cuda.set_device(dist.get_local_rank()) - - -- Then wrap the PyTorch model with the distributed data parallel library’s DDP. - - .. code:: python - - model = ... - # Wrap model with SageMaker's DistributedDataParallel - model = DDP(model) - - -- Modify the ``torch.utils.data.distributed.DistributedSampler`` to - include the cluster’s information. Set ``num_replicas`` to the - total number of GPUs participating in training across all the nodes - in the cluster. This is called ``world_size``. You can get - ``world_size`` with - ``smdistributed.dataparallel.torch.get_world_size()`` API. This is - invoked in the following code as ``dist.get_world_size()``. Also - supply the node rank using - ``smdistributed.dataparallel.torch.get_rank()``. This is invoked as - ``dist.get_rank()``. - - .. code:: python - - train_sampler = DistributedSampler(train_dataset, num_replicas=dist.get_world_size(), rank=dist.get_rank()) - - -- Finally, modify your script to save checkpoints only on the leader - node. The leader node will have a synchronized model. This also - avoids worker nodes overwriting the checkpoints and possibly - corrupting the checkpoints. - -.. code:: python - - if dist.get_rank() == 0: - torch.save(...) - - -All put together, the following is an example PyTorch training script -you will have for distributed training with the distributed data parallel library: - -.. code:: python - - # Import distributed data parallel library PyTorch API - import smdistributed.dataparallel.torch.distributed as dist - - # Import distributed data parallel library PyTorch DDP - from smdistributed.dataparallel.torch.parallel.distributed import DistributedDataParallel as DDP - - # Initialize distributed data parallel library - dist.init_process_group() - - class Net(nn.Module): -     ... -     # Define model - - def train(...): -     ... -     # Model training - - def test(...): -     ... -     # Model evaluation - - def main(): - -     # Scale batch size by world size -     batch_size //= dist.get_world_size() -     batch_size = max(batch_size, 1) - -     # Prepare dataset -     train_dataset = torchvision.datasets.MNIST(...) - -     # Set num_replicas and rank in DistributedSampler -     train_sampler = torch.utils.data.distributed.DistributedSampler( -             train_dataset, -             num_replicas=dist.get_world_size(), -             rank=dist.get_rank()) - -     train_loader = torch.utils.data.DataLoader(..) - -     # Wrap the PyTorch model with distributed data parallel library’s DDP -     model = DDP(Net().to(device)) - -     # Pin each GPU to a single distributed data parallel library process. -     torch.cuda.set_device(local_rank) -     model.cuda(local_rank) - -     # Train -     optimizer = optim.Adadelta(...) -     scheduler = StepLR(...) -     for epoch in range(1, args.epochs + 1): -         train(...) -         if rank == 0: -             test(...) -         scheduler.step() - -     # Save model on master node. -     if dist.get_rank() == 0: -         torch.save(...) - - if __name__ == '__main__': -     main() - - -.. _pytorch-sdp-api: - :noindex: - -PyTorch API -=========== - -.. class:: smdistributed.dataparallel.torch.parallel.DistributedDataParallel(module, device_ids=None, output_device=None, broadcast_buffers=True, process_group=None, bucket_cap_mb=None) - :noindex: - - ``smdistributed.dataparallel``'s implementation of distributed data - parallelism for PyTorch. In most cases, wrapping your PyTorch Module - with ``smdistributed.dataparallel``'s ``DistributedDataParallel`` (DDP) is - all you need to do to use ``smdistributed.dataparallel``. - - Creation of this DDP class requires ``smdistributed.dataparallel`` - already initialized - with ``smdistributed.dataparallel.torch.distributed.init_process_group()``. - - This container parallelizes the application of the given module by - splitting the input across the specified devices by chunking in the - batch dimension. The module is replicated on each machine and each - device, and each such replica handles a portion of the input. During the - backwards pass, gradients from each node are averaged. - - The batch size should be larger than the number of GPUs used locally. - ​ - Example usage - of ``smdistributed.dataparallel.torch.parallel.DistributedDataParallel``: - - .. code:: python - - import torch - import smdistributed.dataparallel.torch.distributed as dist - from smdistributed.dataparallel.torch.parallel import DistributedDataParallel as DDP - - dist.init_process_group() - - # Pin GPU to be used to process local rank (one GPU per process) - torch.cuda.set_device(dist.get_local_rank()) - - # Build model and optimizer - model = ... - optimizer = torch.optim.SGD(model.parameters(), -                             lr=1e-3 * dist.get_world_size()) - # Wrap model with smdistributed.dataparallel's DistributedDataParallel - model = DDP(model) - - **Parameters:** - - - ``module (torch.nn.Module)(required):`` PyTorch NN Module to be - parallelized - - ``device_ids (list[int])(optional):`` CUDA devices. This should only - be provided when the input module resides on a single CUDA device. - For single-device modules, - the ``ith module replica is placed on device_ids[i]``. For - multi-device modules and CPU modules, device_ids must be None or an - empty list, and input data for the forward pass must be placed on the - correct device. Defaults to ``None``. - - ``output_device (int)(optional):`` Device location of output for - single-device CUDA modules. For multi-device modules and CPU modules, - it must be None, and the module itself dictates the output location. - (default: device_ids[0] for single-device modules).  Defaults - to ``None``. - - ``broadcast_buffers (bool)(optional):`` Flag that enables syncing - (broadcasting) buffers of the module at beginning of the forward - function. ``smdistributed.dataparallel`` does not support broadcast - buffer yet. Please set this to ``False``. - - ``process_group(smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` Defaults - to ``None.`` - - ``bucket_cap_mb (int)(optional):`` DistributedDataParallel will - bucket parameters into multiple buckets so that gradient reduction of - each bucket can potentially overlap with backward - computation. ``bucket_cap_mb`` controls the bucket size in - MegaBytes (MB) (default: 25). - - .. note:: - - This module assumes all parameters are registered in the model by the - time it is created. No parameters should be added nor removed later. - - .. note:: - - This module assumes all parameters are registered in the model of - each distributed processes are in the same order. The module itself - will conduct gradient all-reduction following the reverse order of - the registered parameters of the model. In other words, it is users’ - responsibility to ensure that each distributed process has the exact - same model and thus the exact same parameter registration order. - - .. note:: - - You should never change the set of your model’s parameters after - wrapping up your model with DistributedDataParallel. In other words, - when wrapping up your model with DistributedDataParallel, the - constructor of DistributedDataParallel will register the additional - gradient reduction functions on all the parameters of the model - itself at the time of construction. If you change the model’s - parameters after the DistributedDataParallel construction, this is - not supported and unexpected behaviors can happen, since some - parameters’ gradient reduction functions might not get called. - - .. method:: no_sync() - :noindex: - - ``smdistributed.dataparallel`` supports the `PyTorch DDP no_sync() `_ - context manager. It enables gradient accumulation by skipping AllReduce - during training iterations inside the context. - - .. note:: - - The ``no_sync()`` context manager is available from smdistributed-dataparallel v1.2.2. - To find the release note, see :ref:`sdp_release_note`. - - **Example:** - - .. code:: python - - # Gradients are accumulated while inside no_sync context - with model.no_sync(): - ... - loss.backward() - - # First iteration upon exiting context - # Incoming gradients are added to the accumulated gradients and then synchronized via AllReduce - ... - loss.backward() - - # Update weights and reset gradients to zero after accumulation is finished - optimizer.step() - optimizer.zero_grad() - - -.. function:: smdistributed.dataparallel.torch.distributed.is_available() - :noindex: - - Check if script started as a distributed job. For local runs user can - check that is_available returns False and run the training script - without calls to ``smdistributed.dataparallel``. - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``True`` if started as a distributed job, ``False`` otherwise - - -.. function:: smdistributed.dataparallel.torch.distributed.init_process_group(*args, **kwargs) - :noindex: - - Initialize ``smdistributed.dataparallel``. Must be called at the - beginning of the training script, before calling any other methods. - ​ - Process group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with ``torch.distributed`` only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - ​ - After this - call, ``smdistributed.dataparallel.torch.distributed.is_initialized()`` will - return ``True``. - ​ - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.torch.distributed.is_initialized() - :noindex: - - Checks if the default process group has been initialized. - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``True`` if initialized, else ``False``. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_world_size(group=smdistributed.dataparallel.torch.distributed.group.WORLD) - :noindex: - - The total number of GPUs across all the nodes in the cluster. For - example, in a 8 node cluster with 8 GPU each, size will be equal to 64. - - **Inputs:** - - - ``group (smdistributed.dataparallel.torch.distributed.group) (optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - **Returns:** - - - An integer scalar containing the total number of GPUs in the training - job, across all nodes in the cluster. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_rank(group=smdistributed.dataparallel.torch.distributed.group.WORLD) - :noindex: - - The rank of the node in the cluster. The rank ranges from 0 to number of - nodes - 1. This is similar to MPI's World Rank. - - - **Inputs:** - - - ``group (smdistributed.dataparallel.torch.distributed.group) (optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - **Returns:** - - - An integer scalar containing the rank of the worker node. - - -.. function:: smdistributed.dataparallel.torch.distributed.get_local_rank() - :noindex: - - Local rank refers to the relative rank of - the ``smdistributed.dataparallel`` process within the node the current - process is running on. For example, if a node contains 8 GPUs, it has - 8 ``smdistributed.dataparallel`` processes. Each process has - a ``local_rank`` ranging from 0 to 7. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the GPU and - its ``smdistributed.dataparallel`` process. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_reduce(tensor, op=smdistributed.dataparallel.torch.distributed.ReduceOp.SUM, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Performs an all-reduce operation on a tensor (torch.tensor) across - all ``smdistributed.dataparallel`` workers - - ``smdistributed.dataparallel`` AllReduce API can be used for all - reducing gradient tensors or any other tensors.  By - default, ``smdistributed.dataparallel`` AllReduce reduces the tensor - data across all ``smdistributed.dataparallel`` workers in such a way - that all get the final result. - - After the call ``tensor`` is going to be bitwise identical in all - processes. - - **Inputs:** - - - ``tensor (torch.tensor) (required):`` Input and output of the collective. The function operates in-place. - - - ``op (smdistributed.dataparallel.torch.distributed.ReduceOp) (optional)``: The reduction operation to combine tensors across different ranks.  Defaults to ``SUM`` if None is given. - - * Supported ops: ``AVERAGE``, ``SUM``, ``MIN``, ``MAX`` - - - ``group (smdistributed.dataparallel.torch.distributed.group) (optional):`` Process group is not supported in ``smdistributed.dataparallel``. This parameter exists for API parity with torch.distributed only. - - * Only supported value is ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - - ``async_op (bool) (optional):`` Whether this op should be an async op. Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - .. rubric:: Notes - - ``smdistributed.dataparallel.torch.distributed.allreduce``, in most - cases, is ~2X slower than all-reducing - with ``smdistributed.dataparallel.torch.parallel.distributed.DistributedDataParallel`` and - hence, it is not recommended to be used for performing gradient - reduction during the training - process. ``smdistributed.dataparallel.torch.distributed.allreduce`` internally - uses NCCL AllReduce with ``ncclSum`` as the reduction operation. - - -.. function:: smdistributed.dataparallel.torch.distributed.broadcast(tensor, src=0, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Broadcasts the tensor (torch.tensor) to the whole group. - - ``tensor`` must have the same number of elements as GPUs in the - cluster. - - **Inputs:** - - - ``tensor (torch.tensor)(required)`` - - - ``src (int)(optional)`` - - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process group is not supported in ``smdistributed.dataparallel``. This parameter exists for API parity with ``torch.distributed`` only. - - * Only supported value is ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - - ``async_op (bool)(optional):`` Whether this op should be an async op. Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, otherwise. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_gather(tensor_list, tensor, group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Gathers tensors from the whole group in a list. - - - **Inputs:** - - - ``tensor_list (list[torch.tensor])(required):`` Output list. It - should contain correctly-sized tensors to be used for output of the - collective. - - ``tensor (torch.tensor)(required):`` Tensor to be broadcast from - current process. - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - ``async_op (bool)(optional):`` Whether this op should be an async op. - Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - -.. function:: smdistributed.dataparallel.torch.distributed.all_to_all_single(output_t, input_t, output_split_sizes=None, input_split_sizes=None, group=group.WORLD, async_op=False) - :noindex: - - Each process scatters input tensor to all processes in a group and return gathered tensor in output. - - **Inputs:** - - - output_t - - input_t - - output_split_sizes - - input_split_sizes - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. Only - supported value is - ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - ``async_op (bool)(optional):`` Whether this op should be an async op. - Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - -.. function:: smdistributed.dataparallel.torch.distributed.barrier(group=smdistributed.dataparallel.torch.distributed.group.WORLD, async_op=False) - :noindex: - - Synchronizes all ``smdistributed.dataparallel`` processes. - - **Inputs:** - - - tensor (torch.tensor)(required): Data to be sent if src is the rank of current process, and tensor to be used to save received data otherwise. - - - src (int)(optional): Source rank. - - - ``group (smdistributed.dataparallel.torch.distributed.group)(optional):`` Process - group is not supported in ``smdistributed.dataparallel``. This - parameter exists for API parity with torch.distributed only. - - * Only supported value is ``smdistributed.dataparallel.torch.distributed.group.WORLD.`` - - - ``async_op (bool)(optional):`` Whether this op should be an async op. - Defaults to ``False``. - - **Returns:** - - - Async op work handle, if async_op is set to True. ``None``, - otherwise. - - -.. class:: smdistributed.dataparallel.torch.distributed.ReduceOp - :noindex: - - An enum-like class for supported reduction operations - in ``smdistributed.dataparallel``. - - The values of this class can be accessed as attributes, for - example, ``ReduceOp.SUM``. They are used in specifying strategies for - reduction collectives such as -  ``smdistributed.dataparallel.torch.distributed.all_reduce(...)``. - - - ``AVERAGE`` - - ``SUM`` - - ``MIN`` - - ``MAX`` diff --git a/doc/api/training/sdp_versions/v1.2.x/smd_data_parallel_tensorflow.rst b/doc/api/training/sdp_versions/v1.2.x/smd_data_parallel_tensorflow.rst deleted file mode 100644 index dc7b51bddb..0000000000 --- a/doc/api/training/sdp_versions/v1.2.x/smd_data_parallel_tensorflow.rst +++ /dev/null @@ -1,553 +0,0 @@ -################################################################# -TensorFlow Guide to SageMaker's distributed data parallel library -################################################################# - -.. admonition:: Contents - - - :ref:`tensorflow-sdp-modify` - - :ref:`tensorflow-sdp-api` - -.. _tensorflow-sdp-modify: - :noindex: - -Modify a TensorFlow 2.x training script to use SageMaker data parallel -====================================================================== - -The following steps show you how to convert a TensorFlow 2.x training -script to utilize the distributed data parallel library. - -The distributed data parallel library APIs are designed to be close to Horovod APIs. -See `SageMaker distributed data parallel TensorFlow examples -`__ -for additional details on how to implement the data parallel library. - -- First import the distributed data parallel library’s TensorFlow client and initialize it: - - .. code:: python - - import smdistributed.dataparallel.tensorflow as sdp - sdp.init() - - -- Pin each GPU to a single smdistributed.dataparallel process - with ``local_rank`` - this refers to the relative rank of the - process within a given node. ``sdp.tensorflow.local_rank()`` API - provides you the local rank of the device. The leader node will be - rank 0, and the worker nodes will be rank 1, 2, 3, and so on. This is - invoked in the next code block as ``sdp.local_rank()``. - ``set_memory_growth`` is not directly related to SMD, but must be set - for distributed training with TensorFlow. - - .. code:: python - - gpus = tf.config.experimental.list_physical_devices('GPU') - for gpu in gpus: -     tf.config.experimental.set_memory_growth(gpu, True) - if gpus: -     tf.config.experimental.set_visible_devices(gpus[sdp.local_rank()], 'GPU') - - -- Scale the learning rate by the number of workers. - ``sdp.tensorflow.size()`` API provides you number of workers in the - cluster. This is invoked in the next code block as ``sdp.size()``. - - .. code:: python - - learning_rate = learning_rate * sdp.size() - - -- Use the library’s ``DistributedGradientTape`` to optimize AllReduce - operations during training. This wraps ``tf.GradientTape``. - - .. code:: python - - with tf.GradientTape() as tape: -       output = model(input) -       loss_value = loss(label, output) - - # Wrap tf.GradientTape with the library's DistributedGradientTape - tape = sdp.DistributedGradientTape(tape) - - -- Broadcast initial model variables from the leader node (rank 0) to - all the worker nodes (ranks 1 through n). This is needed to ensure a - consistent initialization across all the worker ranks. For this, you - use ``sdp.tensorflow.broadcast_variables`` API after the - model and optimizer variables are initialized. This is invoked in the - next code block as ``sdp.broadcast_variables()``. - - .. code:: python - - sdp.broadcast_variables(model.variables, root_rank=0) - sdp.broadcast_variables(opt.variables(), root_rank=0) - - -- Finally, modify your script to save checkpoints only on the leader - node. The leader node will have a synchronized model. This also - avoids worker nodes overwriting the checkpoints and possibly - corrupting the checkpoints. - - .. code:: python - - if sdp.rank() == 0: -     checkpoint.save(checkpoint_dir) - - -All put together, the following is an example TensorFlow2 training -script you will have for distributed training with the library. - -.. code:: python - - import tensorflow as tf - - # Import the library's TF API - import smdistributed.dataparallel.tensorflow as sdp - - # Initialize the library - sdp.init() - - gpus = tf.config.experimental.list_physical_devices('GPU') - for gpu in gpus: -     tf.config.experimental.set_memory_growth(gpu, True) - if gpus: -     # Pin GPUs to a single process -     tf.config.experimental.set_visible_devices(gpus[sdp.local_rank()], 'GPU') - - # Prepare Dataset - dataset = tf.data.Dataset.from_tensor_slices(...) - - # Define Model - mnist_model = tf.keras.Sequential(...) - loss = tf.losses.SparseCategoricalCrossentropy() - - # Scale Learning Rate - # LR for 8 node run : 0.000125 - # LR for single node run : 0.001 - opt = tf.optimizers.Adam(0.000125 * sdp.size()) - - @tf.function - def training_step(images, labels, first_batch): -     with tf.GradientTape() as tape: -         probs = mnist_model(images, training=True) -         loss_value = loss(labels, probs) - -     # Wrap tf.GradientTape with the library's DistributedGradientTape -     tape = sdp.DistributedGradientTape(tape) - -     grads = tape.gradient(loss_value, mnist_model.trainable_variables) -     opt.apply_gradients(zip(grads, mnist_model.trainable_variables)) - -     if first_batch: -        # Broadcast model and optimizer variables -        sdp.broadcast_variables(mnist_model.variables, root_rank=0) -        sdp.broadcast_variables(opt.variables(), root_rank=0) - -     return loss_value - - ... - - # Save checkpoints only from master node. - if sdp.rank() == 0: -     checkpoint.save(checkpoint_dir) - - -.. _tensorflow-sdp-api: - :noindex: - -TensorFlow API -============== - -.. function:: smdistributed.dataparallel.tensorflow.init() - :noindex: - - Initialize ``smdistributed.dataparallel``. Must be called at the - beginning of the training script. - - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - - .. rubric:: Notes - - ``init()`` needs to be called only once. It will throw an error if - called more than once: - - ``init() called more than once. smdistributed.dataparallel is already initialized.`` - - -.. function:: smdistributed.dataparallel.tensorflow.size() - :noindex: - - The total number of GPUs across all the nodes in the cluster. For - example, in a 8 node cluster with 8 GPUs each, ``size`` will be equal - to 64. - - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the total number of GPUs, across all - nodes in the cluster. - - -.. function:: smdistributed.dataparallel.tensorflow.local_size() - :noindex: - - The total number of GPUs on a node. For example, on a node with 8 - GPUs, ``local_size`` will be equal to 8. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the total number of GPUs on itself. - - -.. function:: smdistributed.dataparallel.tensorflow.rank() - :noindex: - - The rank of the node in the cluster. The rank ranges from 0 to number of - nodes - 1. This is similar to MPI's World Rank. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the node. - - -.. function:: smdistributed.dataparallel.tensorflow.local_rank() - :noindex: - - Local rank refers to the relative rank of the - GPUs’ ``smdistributed.dataparallel`` processes within the node. For - example, if a node contains 8 GPUs, it has - 8 ``smdistributed.dataparallel`` processes, then each process will - get a local rank ranging from 0 to 7. - - **Inputs:** - - - ``None`` - - **Returns:** - - - An integer scalar containing the rank of the GPU and - its ``smdistributed.dataparallel`` process. - - -.. function:: smdistributed.dataparallel.tensorflow.allreduce(tensor, param_index, num_params, compression=Compression.none, op=ReduceOp.AVERAGE) - :noindex: - - Performs an all-reduce operation on a tensor (``tf.Tensor``). - - ``smdistributed.dataparallel`` AllReduce API can be used for all - reducing gradient tensors or any other tensors. By - default, ``smdistributed.dataparallel`` AllReduce averages the - tensors across the participating workers. - ​ - **Inputs:** - - - ``tensor (tf.Tensor)(required)``: The tensor to be all-reduced. The shape of the input must be identical across all ranks. - - ``param_index (int)(required):`` 0 if you are reducing a single tensor. Index of the tensor if you are reducing a list of tensors. - - ``num_params (int)(required):`` len(tensor). - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``op (optional)(smdistributed.dataparallel.tensorflow.ReduceOp)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``SUM``, ``MIN``, ``MAX``, ``AVERAGE`` - - **Returns:** - - - A tensor of the same shape and type as input ``tensor``, all-reduced across all the processes. - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast_global_variables(root_rank) - :noindex: - - Broadcasts all global variables from root rank to all other processes. - - **Inputs:** - - - ``root_rank (int)(required):`` Rank of the process from which global - variables will be broadcasted to all other processes. - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast_variables(variables, root_rank) - :noindex: - - Applicable for TensorFlow 2.x only. - ​ - Broadcasts variables from root rank to all other processes. - ​ - With TensorFlow 2.x, ``broadcast_variables`` is used to - broadcast ``model.variables`` and ``optimizer.variables`` post - initialization from the leader node to all the worker nodes. This - ensures a consistent initialization across all the worker ranks. - - **Inputs:** - - - ``variables (tf.Variable)(required):`` Variables to be broadcasted. - - ``root_rank (int)(required):`` Rank of the process from which - variables will be broadcasted to all other processes. - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.oob_allreduce(tensor, compression=Compression.none, op=ReduceOp.AVERAGE) - :noindex: - - OutOfBand (oob) AllReduce is simplified AllReduce function for use cases - such as calculating total loss across all the GPUs in the training. - oob_allreduce average the tensors, as reduction operation, across the - worker nodes. - - **Inputs:** - - - ``tensor (tf.Tensor)(required)``: The tensor to be all-reduced. The shape of the input must be identical across all worker nodes. - - ``compression`` (optional): Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different worker nodes. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - **Returns:** - - - ``None`` - - .. rubric:: Notes - - ``smdistributed.dataparallel.tensorflow.oob_allreduce``, in most - cases, is ~2x slower - than ``smdistributed.dataparallel.tensorflow.allreduce``  so it is not - recommended to be used for performing gradient reduction during the - training - process. ``smdistributed.dataparallel.tensorflow.oob_allreduce`` internally - uses NCCL AllReduce with ``ncclSum`` as the reduction operation. - - -.. function:: smdistributed.dataparallel.tensorflow.overlap(tensor) - :noindex: - - This function is applicable only for models compiled with XLA. Use this - function to enable ``smdistributed.dataparallel`` to efficiently - overlap backward pass with the all reduce operation. - - Example usage: - - .. code:: python - - layer = tf.nn.dropout(...) # Or any other layer - layer = smdistributed.dataparallel.tensorflow.overlap(layer) - - The overlap operation is inserted into the TF graph as a node. It - behaves as an identity operation, and helps in achieving the - communication overlap with backward pass operation. - - **Inputs:** - - - ``tensor (tf.Tensor)(required):`` The tensor to be all-reduced. - - **Returns:** - - - ``None`` - - .. rubric:: Notes - - This operation helps in speeding up distributed training, as - the AllReduce operation does not have to wait for all the gradients to - be ready. Backward propagation proceeds sequentially from the output - layer of the network to the input layer. When the gradient computation - for a layer finishes, ``smdistributed.dataparallel`` adds them to a - fusion buffer. As soon as the size of the fusion buffer reaches a - predefined threshold (25 Mb), ``smdistributed.dataparallel`` starts - the AllReduce operation. - - -.. function:: smdistributed.dataparallel.tensorflow.broadcast(tensor, root_rank) - :noindex: - - Broadcasts the input tensor on root rank to the same input tensor on all - other ``smdistributed.dataparallel`` processes. - ​ - The broadcast will not start until all processes are ready to send and - receive the tensor. - - **Inputs:** - - - ``tensor (tf.Tensor)(required):`` The tensor to be broadcasted. - - ``root_rank (int)(required):`` Rank of the process from which - tensor will be broadcasted to all other processes. - - **Returns:** - - - A tensor of the same shape and type as tensor, with the value - broadcasted from root rank. - - -.. function:: smdistributed.dataparallel.tensorflow.shutdown() - :noindex: - - Shuts down ``smdistributed.dataparallel``. Optional to call at the end - of the training script. - - **Inputs:** - - - ``None`` - - **Returns:** - - - ``None`` - - -.. function:: smdistributed.dataparallel.tensorflow.DistributedOptimizer - :noindex: - - Applicable if you use the ``tf.estimator`` API in TensorFlow 2.x (2.3.1). - ​ - Construct a new ``DistributedOptimizer`` , which uses TensorFlow - optimizer under the hood for computing single-process gradient values - and applying gradient updates after the gradient values have been - combined across all ``smdistributed.dataparallel`` workers. - ​ - Example usage: - - .. code:: python - - opt = ... # existing optimizer from tf.train package or your custom optimizer - opt = smdistributed.dataparallel.tensorflow.DistributedOptimizer(opt) - - - - ``optimizer (tf.train.Optimizer)(required):`` TF Optimizer to use for computing gradients and applying updates. - - - ``name (str)(optional):`` Name prefix for the operations created when applying gradients. Defaults to ``smdistributed.dataparallel`` followed by provided optimizer type. - - - ``use_locking (bool)(optional):`` Whether to use locking when updating variables. Defaults to ``False``. - - - ``device_dense:`` Not supported. Raises not supported error. - - - ``device_sparse:`` Not supported. Raises not supported error. - - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``sparse_as_dense:`` Treats sparse gradient tensor as dense tensor. Defaults to ``False``. - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - - ``bucket_cap_mb (int)(optional):`` Size of ``smdistributed.dataparallel`` fusion buffer size. Defaults to 25MB that works optimally for most case. If you provide a value, expects the (value * 1024 * 1024) i.e., bytes to be multiple of 128. - - -.. function:: smdistributed.dataparallel.tensorflow.DistributedGradientTape - :noindex: - - Applicable to TensorFlow 2.x only. - - Construct a new ``DistributedGradientTape``, which uses - TensorFlow’s ``GradientTape`` under the hood, using an AllReduce to - combine gradient values before applying gradients to model weights. - ​ - Example Usage: - - .. code:: python - - with tf.GradientTape() as tape: -       output = model(input) -       loss_value = loss(label, output) - - # Wrap in smdistributed.dataparallel's DistributedGradientTape - tape = smdistributed.dataparallel.tensorflow.DistributedGradientTape(tape) - - - - ``gradtape (tf.GradientTape)(required):`` GradientTape to use for computing gradients and applying updates. - - - ``device_dense:`` Not supported. Raises not supported error. - - - ``device_sparse:`` Not supported. Raises not supported error. - - - ``compression (smdistributed.dataparallel.tensorflow.Compression)(optional)``: Compression algorithm used to reduce the amount of data sent and received by each worker node. Defaults to not using compression. - - *  Supported compression types - ``none``, ``fp16`` - - - ``sparse_as_dense:`` Treats sparse gradient tensor as dense tensor. Defaults to ``False``. - - - ``op (smdistributed.dataparallel.tensorflow.ReduceOp)(optional)``: The reduction operation to combine tensors across different ranks. Defaults to ``Average`` if None is given. - - * Supported ops: ``AVERAGE`` - - -.. function:: smdistributed.dataparallel.tensorflow.BroadcastGlobalVariablesHook - :noindex: - - Applicable if you use the ``tf.estimator`` API in TensorFlow 2.x (2.3.1). - - - ``SessionRunHook`` that will broadcast all global variables from root - rank to all other processes during initialization. - ​ - This is necessary to ensure consistent initialization of all workers - when training is started with random weights or restored from a - checkpoint. - ​ - Example Usage: - - .. code:: python - - hooks = [smdistributed.dataparallel.tensorflow.BroadcastGlobalVariablesHook(root_rank=0)] - ... - with tf.train.MonitoredTrainingSession(checkpoint_dir=checkpoint_dir, -                                        hooks=hooks, -                                        config=config) as mon_sess: -      ... - - - - ``root_rank (int)(required):`` Rank of the process from which global - variables will be broadcasted to all other processes. - - -.. function:: smdistributed.dataparallel.tensorflow.Compression - :noindex: - - Optional Gradient Compression algorithm that can be used in AllReduce - operation. - - - ``none``: alias for ``NoneCompression``. Do not compression gradient - tensors. - - ``fp16``: alias for ``FP16Compression``. Compress the floating point - gradient tensors to 16-bit (FP16) - - -.. function:: smdistributed.dataparallel.tensorflow.ReduceOp - :noindex: - - Supported reduction operations in ``smdistributed.dataparallel``. - - - ``AVERAGE`` - - ``SUM`` - - ``MIN`` - - ``MAX`` diff --git a/doc/api/training/sdp_versions/v1_0_0.rst b/doc/api/training/sdp_versions/v1_0_0.rst deleted file mode 100644 index 291e89921d..0000000000 --- a/doc/api/training/sdp_versions/v1_0_0.rst +++ /dev/null @@ -1,9 +0,0 @@ - -Version 1.0.0 -============= - -.. toctree:: - :maxdepth: 1 - - v1.0.0/smd_data_parallel_pytorch.rst - v1.0.0/smd_data_parallel_tensorflow.rst diff --git a/doc/api/training/sdp_versions/v1_1_x.rst b/doc/api/training/sdp_versions/v1_1_x.rst deleted file mode 100644 index 90c3a984a7..0000000000 --- a/doc/api/training/sdp_versions/v1_1_x.rst +++ /dev/null @@ -1,9 +0,0 @@ - -Version 1.1.x -============= - -.. toctree:: - :maxdepth: 1 - - v1.1.x/smd_data_parallel_pytorch.rst - v1.1.x/smd_data_parallel_tensorflow.rst diff --git a/doc/api/training/sdp_versions/v1_2_x.rst b/doc/api/training/sdp_versions/v1_2_x.rst deleted file mode 100644 index 706f37f113..0000000000 --- a/doc/api/training/sdp_versions/v1_2_x.rst +++ /dev/null @@ -1,9 +0,0 @@ - -Version 1.2.x and 1.3.0 -======================= - -.. toctree:: - :maxdepth: 1 - - v1.2.x/smd_data_parallel_pytorch.rst - v1.2.x/smd_data_parallel_tensorflow.rst diff --git a/doc/api/training/smd_data_parallel.rst b/doc/api/training/smd_data_parallel.rst deleted file mode 100644 index db7424c0d0..0000000000 --- a/doc/api/training/smd_data_parallel.rst +++ /dev/null @@ -1,29 +0,0 @@ -######################################################## -The SageMaker Distributed Data Parallel Library Overview -######################################################## - -SageMaker's distributed data parallel library extends SageMaker’s training -capabilities on deep learning models with near-linear scaling efficiency, -achieving fast time-to-train with minimal code changes. - -When training a model on a large amount of data, machine learning practitioners -will often turn to distributed training to reduce the time to train. -In some cases, where time is of the essence, -the business requirement is to finish training as quickly as possible or at -least within a constrained time period. -Then, distributed training is scaled to use a cluster of multiple nodes, -meaning not just multiple GPUs in a computing instance, but multiple instances -with multiple GPUs. However, as the cluster size increases, it is possible to see a significant drop -in performance due to communications overhead between nodes in a cluster. - -SageMaker's distributed data parallel library addresses communications overhead in two ways: - -1. The library performs AllReduce, a key operation during distributed training that is responsible for a - large portion of communication overhead. -2. The library performs optimized node-to-node communication by fully utilizing AWS’s network - infrastructure and Amazon EC2 instance topology. - -To learn more about the core features of this library, see -`Introduction to SageMaker's Distributed Data Parallel Library -`_ -in the SageMaker Developer Guide. diff --git a/doc/api/training/smd_data_parallel_release_notes/smd_data_parallel_change_log.rst b/doc/api/training/smd_data_parallel_release_notes/smd_data_parallel_change_log.rst deleted file mode 100644 index 4ccaa0f110..0000000000 --- a/doc/api/training/smd_data_parallel_release_notes/smd_data_parallel_change_log.rst +++ /dev/null @@ -1,428 +0,0 @@ -.. _sdp_release_note: - -############# -Release Notes -############# - -New features, bug fixes, and improvements are regularly made to the SageMaker -data parallelism library. - -SageMaker Distributed Data Parallel 1.8.0 Release Notes -======================================================= - -*Date: Apr. 17. 2023* - -**Currency Updates** - -* Added support for PyTorch 2.0.0. - -**Migration to AWS Deep Learning Containers** - -This version passed benchmark testing and is migrated to the following AWS Deep Learning Containers (DLC): - -- PyTorch 2.0.0 DLC - - .. code:: - - 763104351884.dkr.ecr.us-east-1.amazonaws.com/pytorch-training:2.0.0-gpu-py310-cu118-ubuntu20.04-sagemaker - -Binary file of this version of the library for custom container users: - - .. code:: - - https://smdataparallel.s3.amazonaws.com/binary/pytorch/2.0.0/cu118/2023-03-20/smdistributed_dataparallel-1.8.0-cp310-cp310-linux_x86_64.whl - - ----- - -Release History -=============== - -SageMaker Distributed Data Parallel 1.7.0 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Date: Feb. 10. 2023* - -**Currency Updates** - -* Added support for PyTorch 1.13.1. - -**Migration to AWS Deep Learning Containers** - -This version passed benchmark testing and is migrated to the following AWS Deep Learning Containers (DLC): - -- PyTorch 1.13.1 DLC - - .. code:: - - 763104351884.dkr.ecr.us-east-1.amazonaws.com/pytorch-training:1.13.1-gpu-py39-cu117-ubuntu20.04-sagemaker - -Binary file of this version of the library for custom container users: - - .. code:: - - https://smdataparallel.s3.amazonaws.com/binary/pytorch/1.13.1/cu117/2023-01-09/smdistributed_dataparallel-1.7.0-cp39-cp39-linux_x86_64.whl - -SageMaker Distributed Data Parallel 1.6.0 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Date: Dec. 15. 2022* - -**New Features** - -* New optimized SMDDP AllGather collective to complement the sharded data parallelism technique - in the SageMaker model parallelism library. For more information, see `Sharded data parallelism with SMDDP Collectives - `_ - in the *Amazon SageMaker Developer Guide*. -* Added support for Amazon EC2 ``ml.p4de.24xlarge`` instances. You can run data parallel training jobs - on ``ml.p4de.24xlarge`` instances with the SageMaker data parallelism library’s AllReduce collective. - -**Improvements** - -* General performance improvements of the SMDDP AllReduce collective communication operation. - -**Migration to AWS Deep Learning Containers** - -This version passed benchmark testing and is migrated to the following AWS Deep Learning Containers (DLC): - -- SageMaker training container for PyTorch v1.12.1 - - .. code:: - - 763104351884.dkr.ecr..amazonaws.com/pytorch-training:1.12.1-gpu-py38-cu113-ubuntu20.04-sagemaker - - -Binary file of this version of the library for `custom container -`_ users: - - .. code:: - - https://smdataparallel.s3.amazonaws.com/binary/pytorch/1.12.1/cu113/2022-12-05/smdistributed_dataparallel-1.6.0-cp38-cp38-linux_x86_64.whl - - -SageMaker Distributed Data Parallel 1.5.0 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Date: Jul. 26. 2022* - -**Currency Updates** - -* Added support for PyTorch 1.12.0. - -**Bug Fixes** - -* Improved stability for long-running training jobs. - - -**Migration to AWS Deep Learning Containers** - -This version passed benchmark testing and is migrated to the following AWS Deep Learning Containers (DLC): - -- PyTorch 1.12.0 DLC - - .. code:: - - 763104351884.dkr.ecr..amazonaws.com/pytorch-training:1.12.0-gpu-py38-cu113-ubuntu20.04-sagemaker - -Binary file of this version of the library for `custom container -`_ users: - - .. code:: - - https://smdataparallel.s3.amazonaws.com/binary/pytorch/1.12.0/cu113/2022-07-01/smdistributed_dataparallel-1.5.0-cp38-cp38-linux_x86_64.whl - -SageMaker Distributed Data Parallel 1.4.1 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Date: May. 3. 2022* - -**Currency Updates** - -* Added support for PyTorch 1.11.0 - -**Known Issues** - -* The library currently does not support the PyTorch sub-process groups API - (`torch.distributed.new_group - `_). - - -**Migration to AWS Deep Learning Containers** - -This version passed benchmark testing and is migrated to the following AWS Deep Learning Containers (DLC): - -- PyTorch 1.11.0 DLC - - .. code:: - - 763104351884.dkr.ecr..amazonaws.com/pytorch-training:1.11.0-gpu-py38-cu113-ubuntu20.04-sagemaker - -Binary file of this version of the library for custom container users: - - .. code:: - - https://smdataparallel.s3.amazonaws.com/binary/pytorch/1.11.0/cu113/2022-04-14/smdistributed_dataparallel-1.4.1-cp38-cp38-linux_x86_64.whl - - -SageMaker Distributed Data Parallel 1.4.0 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Date: Feb. 24. 2022* - -**New Features** - -* Integrated to PyTorch DDP as a backend option -* Added support for PyTorch 1.10.2 - -**Breaking Changes** - -* As the library is migrated into the PyTorch distributed package as a backend, - the following smdistributed implementation APIs are deprecated in - the SageMaker data parallal library v1.4.0 and later. - Please use the `PyTorch distributed APIs `_ instead. - - * ``smdistributed.dataparallel.torch.distributed`` - * ``smdistributed.dataparallel.torch.parallel.DistributedDataParallel`` - * Please note the slight differences between the deprecated - ``smdistributed.dataparallel.torch`` APIs and the - `PyTorch distributed APIs `_. - - * `torch.distributed.barrier `_ - takes ``device_ids``, which the ``smddp`` backend does not support. - * The ``gradient_accumulation_steps`` option in - ``smdistributed.dataparallel.torch.parallel.DistributedDataParallel`` - is no longer supported. Please use the PyTorch - `no_sync `_ API. - - -* If you want to find documentation for the previous versions of the library - (v1.3.0 or before), see the `archived SageMaker distributed data parallel library documentation `_. - -**Improvements** - -* Support for AllReduce Large Tensors -* Support for the following new arguments in the `PyTorch DDP class - `_. - - * ``broadcast_buffers`` - * ``find_unused_parameters`` - * ``gradient_as_bucket_view`` - -**Bug Fixes** - -* Fixed stalling issues when training on ``ml.p3.16xlarge``. - -**Known Issues** - -* The library currently does not support the PyTorch sub-process groups API (`torch.distributed.new_group `_). - This means that you cannot use the ``smddp`` backend concurrently with other - process group backends such as NCCL and Gloo. - -**Migration to AWS Deep Learning Containers** - -This version passed benchmark testing and is migrated to the following AWS Deep Learning Containers (DLC): - -- PyTorch 1.10.2 DLC - - .. code:: - - 763104351884.dkr.ecr..amazonaws.com/pytorch-training:1.10.2-gpu-py38-cu113-ubuntu20.04-sagemaker - - -SageMaker Distributed Data Parallel 1.2.2 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Date: November. 24. 2021* - -**New Features** - -* Added support for PyTorch 1.10 -* PyTorch ``no_sync`` API support for DistributedDataParallel -* Timeout when training stalls due to allreduce and broadcast collective calls - -**Bug Fixes** - -* Fixed a bug that would impact correctness in the mixed dtype case -* Fixed a bug related to the timeline writer that would cause a crash when SageMaker Profiler is enabled for single node jobs. - -**Improvements** - -* Performance optimizations for small models on small clusters - -**Migration to AWS Deep Learning Containers** - -This version passed benchmark testing and is migrated to the following AWS Deep Learning Containers: - -- PyTorch 1.10 DLC release: `v1.0-pt-sagemaker-1.10.0-py38 `_ - - .. code:: - - 763104351884.dkr.ecr..amazonaws.com/pytorch-training:1.10.0-gpu-py38-cu113-ubuntu20.04-sagemaker - - -SageMaker Distributed Data Parallel 1.2.1 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Date: June. 29. 2021* - -**New Features:** - -- Added support for TensorFlow 2.5.0. - -**Improvements** - -- Improved performance on a single node and small clusters (2-4 nodes). - -**Bug fixes** - -- Enable ``sparse_as_dense`` by default for SageMaker distributed data - parallel library for TensorFlow APIs: ``DistributedGradientTape`` and - ``DistributedOptimizer``. - -**Migration to AWS Deep Learning Containers** - -This version passed benchmark testing and is migrated to the following AWS Deep Learning Containers: - -- TensorFlow 2.5.0 DLC release: `v1.0-tf-2.5.0-tr-py37 - `__ - - .. code:: - - 763104351884.dkr.ecr..amazonaws.com/tensorflow-training:2.5.0-gpu-py37-cu112-ubuntu18.04-v1.0 - - -SageMaker Distributed Data Parallel 1.2.0 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- New features -- Bug Fixes - -**New features:** - -- Support of `EFA network - interface `__ for distributed - AllReduce. For best performance, it is recommended you use an - instance type that supports Amazon Elastic Fabric Adapter - (ml.p3dn.24xlarge and ml.p4d.24xlarge) when you train a model using - SageMaker Distributed data parallel. - -**Bug Fixes:** - -- Improved performance on single node and small clusters. - ----- - -SageMaker Distributed Data Parallel 1.1.2 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Bug Fixes -- Known Issues - -**Bug Fixes:** - -- Fixed a bug that caused some TensorFlow operations to not work with - certain data types. Operations forwarded from C++ have been extended - to support every dtype supported by NCCL. - -**Known Issues:** - -- SageMaker Distributed data parallel has slower throughput than NCCL - when run using a single node. For the best performance, use - multi-node distributed training with smdistributed.dataparallel. Use - a single node only for experimental runs while preparing your - training pipeline. - ----- - -SageMaker Distributed Data Parallel 1.1.1 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- New Features -- Bug Fixes -- Known Issues - -**New Features:** - -- Adds support for PyTorch 1.8.1 - -**Bug Fixes:** - -- Fixes a bug that was causing gradients from one of the worker nodes - to be added twice resulting in incorrect ``all_reduce`` results under - some conditions. - -**Known Issues:** - -- SageMaker distributed data parallel still is not efficient when run - using a single node. For the best performance, use multi-node - distributed training with ``smdistributed.dataparallel``. Use a - single node only for experimental runs while preparing your training - pipeline. - ----- - -SageMaker Distributed Data Parallel 1.1.0 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- New Features -- Bug Fixes -- Improvements -- Known Issues - -**New Features:** - -- Adds support for PyTorch 1.8.0 with CUDA 11.1 and CUDNN 8 - -**Bug Fixes:** - -- Fixes crash issue when importing ``smdataparallel`` before PyTorch - -**Improvements:** - -- Update ``smdataparallel`` name in python packages, descriptions, and - log outputs - -**Known Issues:** - -- SageMaker DataParallel is not efficient when run using a single node. - For the best performance, use multi-node distributed training with - ``smdataparallel``. Use a single node only for experimental runs - while preparing your training pipeline. - -Getting Started - -For getting started, refer to SageMaker Distributed Data Parallel Python -SDK Guide -(https://docs.aws.amazon.com/sagemaker/latest/dg/data-parallel-use-api.html#data-parallel-use-python-skd-api). - ----- - -SageMaker Distributed Data Parallel 1.0.0 Release Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- First Release -- Getting Started - -First Release -------------- - -SageMaker’s distributed data parallel library extends SageMaker’s -training capabilities on deep learning models with near-linear scaling -efficiency, achieving fast time-to-train with minimal code changes. -SageMaker Distributed Data Parallel: - -- optimizes your training job for AWS network infrastructure and EC2 - instance topology. -- takes advantage of gradient update to communicate between nodes with - a custom AllReduce algorithm. - -The library currently supports TensorFlow v2 and PyTorch via `AWS Deep -Learning -Containers `__. - -Getting Started ---------------- - -For getting started, refer to `SageMaker Distributed Data Parallel -Python SDK -Guide `__. diff --git a/doc/api/training/smd_data_parallel_use_sm_pysdk.rst b/doc/api/training/smd_data_parallel_use_sm_pysdk.rst deleted file mode 100644 index f2643f4a41..0000000000 --- a/doc/api/training/smd_data_parallel_use_sm_pysdk.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _sdp_api_docs_launch_training_job: - -Launch a Distributed Training Job Using the SageMaker Python SDK -================================================================ - -To use the SageMaker distributed data parallel library with the SageMaker Python SDK, -you will need the following: - -- A TensorFlow or PyTorch training script that is - adapted to use the distributed data parallel library. Make sure you read through - the previous topic at - :ref:`sdp_api_docs`, which includes instructions on how to modify your script and - framework-specific examples. -- Your input data must be in an S3 bucket or in FSx in the AWS region - that you will use to launch your training job. If you use the Jupyter - notebooks provided, create a SageMaker notebook instance in the same - region as the bucket that contains your input data. For more - information about storing your training data, refer to - the `SageMaker Python SDK data - inputs `__ documentation. - -When you define -a :class:`sagemaker.tensorflow.estimator.TensorFlow` or :class:`sagemaker.pytorch.estimator.PyTorch` estimator, -you must select ``smdistributed`` and then ``dataparallel`` as your ``distribution`` strategy. - -.. code:: python - - distribution = { "smdistributed": { "dataparallel": { "enabled": True } } } - -.. seealso:: - - To learn more, see `Step 2: Launch a SageMaker Distributed Training Job Using the SageMaker Python SDK - `_ - in the *Amazon SageMaker Developer Guide*. - -We recommend you use one of the example notebooks as your template to launch a training job. When -you use an example notebook you’ll need to swap your training script with the one that came with the -notebook and modify any input functions as necessary. For instructions on how to get started using a -Jupyter Notebook example, see `Distributed Training Jupyter Notebook Examples -`_. - -Once you have launched a training job, you can monitor it using CloudWatch. To learn more, see -`Monitor and Analyze Training Jobs Using Metrics -`_. - -After you train a model, you can see how to deploy your trained model to an endpoint for inference by -following one of the `example notebooks for deploying a model -`_. -For more information, see `Deploy Models for Inference -`_. diff --git a/doc/api/training/tuner.rst b/doc/api/training/tuner.rst deleted file mode 100644 index 89ca4a7bab..0000000000 --- a/doc/api/training/tuner.rst +++ /dev/null @@ -1,22 +0,0 @@ -HyperparameterTuner -------------------- - -.. autoclass:: sagemaker.tuner.HyperparameterTuner - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.tuner.ContinuousParameter - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.tuner.IntegerParameter - :members: - :undoc-members: - :show-inheritance: - -.. autoclass:: sagemaker.tuner.CategoricalParameter - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/accept_types.rst b/doc/api/utility/accept_types.rst deleted file mode 100644 index 94f8a5278c..0000000000 --- a/doc/api/utility/accept_types.rst +++ /dev/null @@ -1,8 +0,0 @@ -Accept Types ------------- - -.. automodule:: sagemaker.accept_types - :members: - :undoc-members: - :show-inheritance: - :private-members: diff --git a/doc/api/utility/config.rst b/doc/api/utility/config.rst deleted file mode 100644 index b88fd3c223..0000000000 --- a/doc/api/utility/config.rst +++ /dev/null @@ -1,7 +0,0 @@ -Config -------- - -.. automodule:: sagemaker.config.config - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/content_types.rst b/doc/api/utility/content_types.rst deleted file mode 100644 index 86af3d8950..0000000000 --- a/doc/api/utility/content_types.rst +++ /dev/null @@ -1,8 +0,0 @@ -Content Types -------------- - -.. automodule:: sagemaker.content_types - :members: - :undoc-members: - :show-inheritance: - :private-members: diff --git a/doc/api/utility/environment_variables.rst b/doc/api/utility/environment_variables.rst deleted file mode 100644 index 8fcc61d013..0000000000 --- a/doc/api/utility/environment_variables.rst +++ /dev/null @@ -1,7 +0,0 @@ -Environment Variables ---------------------- - -.. automodule:: sagemaker.environment_variables - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/featuregroup_utils.rst b/doc/api/utility/featuregroup_utils.rst deleted file mode 100644 index 35bc8b9f09..0000000000 --- a/doc/api/utility/featuregroup_utils.rst +++ /dev/null @@ -1,7 +0,0 @@ -FeatureGroup Utilities ----------------------- - -.. automodule:: sagemaker.feature_store.feature_utils - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/hyperparameters.rst b/doc/api/utility/hyperparameters.rst deleted file mode 100644 index f6fa793bc8..0000000000 --- a/doc/api/utility/hyperparameters.rst +++ /dev/null @@ -1,8 +0,0 @@ -Hyperparameters ---------------- - -.. automodule:: sagemaker.hyperparameters - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/api/utility/image_uris.rst b/doc/api/utility/image_uris.rst deleted file mode 100644 index e6be7e8424..0000000000 --- a/doc/api/utility/image_uris.rst +++ /dev/null @@ -1,7 +0,0 @@ -Image URIs ----------- - -.. automodule:: sagemaker.image_uris - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/index.rst b/doc/api/utility/index.rst deleted file mode 100644 index f097b44c8a..0000000000 --- a/doc/api/utility/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -############ -Utility APIs -############ - -.. toctree:: - :maxdepth: 1 - :glob: - - * diff --git a/doc/api/utility/inputs.rst b/doc/api/utility/inputs.rst deleted file mode 100644 index 0ac3907b3d..0000000000 --- a/doc/api/utility/inputs.rst +++ /dev/null @@ -1,12 +0,0 @@ -Inputs ------- - -.. automodule:: sagemaker.inputs - :members: - :undoc-members: - :show-inheritance: - -.. automodule:: sagemaker.dataset_definition.inputs - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/instance_group.rst b/doc/api/utility/instance_group.rst deleted file mode 100644 index 141c756b0e..0000000000 --- a/doc/api/utility/instance_group.rst +++ /dev/null @@ -1,8 +0,0 @@ -Instance Group --------------- - -.. automodule:: sagemaker.instance_group - :members: - :undoc-members: - :show-inheritance: - :private-members: diff --git a/doc/api/utility/instance_types.rst b/doc/api/utility/instance_types.rst deleted file mode 100644 index 14810fe179..0000000000 --- a/doc/api/utility/instance_types.rst +++ /dev/null @@ -1,8 +0,0 @@ -Instance Types --------------- - -.. automodule:: sagemaker.instance_types - :members: - :undoc-members: - :show-inheritance: - :private-members: diff --git a/doc/api/utility/interactive_apps.rst b/doc/api/utility/interactive_apps.rst deleted file mode 100644 index 818b234f6d..0000000000 --- a/doc/api/utility/interactive_apps.rst +++ /dev/null @@ -1,19 +0,0 @@ -Interactive Apps ----------------- - -TensorBoard on SageMaker -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: sagemaker.interactive_apps.tensorboard - :members: - :undoc-members: - :show-inheritance: - -SageMaker Profiler UI application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: sagemaker.interactive_apps.detail_profiler_app - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/api/utility/lambda_helper.rst b/doc/api/utility/lambda_helper.rst deleted file mode 100644 index 709f75c4c0..0000000000 --- a/doc/api/utility/lambda_helper.rst +++ /dev/null @@ -1,7 +0,0 @@ -Lambda Utilities ----------------- - -.. automodule:: sagemaker.lambda_helper - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/metric_definitions.rst b/doc/api/utility/metric_definitions.rst deleted file mode 100644 index 8c56639c7e..0000000000 --- a/doc/api/utility/metric_definitions.rst +++ /dev/null @@ -1,8 +0,0 @@ -Metric Definitions ------------------- - -.. automodule:: sagemaker.metric_definitions - :members: - :undoc-members: - :show-inheritance: - :private-members: diff --git a/doc/api/utility/model_uris.rst b/doc/api/utility/model_uris.rst deleted file mode 100644 index 9c3674540d..0000000000 --- a/doc/api/utility/model_uris.rst +++ /dev/null @@ -1,7 +0,0 @@ -Model URIs ----------- - -.. automodule:: sagemaker.model_uris - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/network.rst b/doc/api/utility/network.rst deleted file mode 100644 index 8fb56c5e6d..0000000000 --- a/doc/api/utility/network.rst +++ /dev/null @@ -1,7 +0,0 @@ -Network Configuration ---------------------- - -.. automodule:: sagemaker.network - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/s3.rst b/doc/api/utility/s3.rst deleted file mode 100644 index 4846b66a6d..0000000000 --- a/doc/api/utility/s3.rst +++ /dev/null @@ -1,7 +0,0 @@ -S3 Utilities ------------- - -.. automodule:: sagemaker.s3 - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/script_uris.rst b/doc/api/utility/script_uris.rst deleted file mode 100644 index 4e1a5b5f7f..0000000000 --- a/doc/api/utility/script_uris.rst +++ /dev/null @@ -1,7 +0,0 @@ -Script URIs ------------ - -.. automodule:: sagemaker.script_uris - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/api/utility/session.rst b/doc/api/utility/session.rst deleted file mode 100644 index bde42a48d6..0000000000 --- a/doc/api/utility/session.rst +++ /dev/null @@ -1,7 +0,0 @@ -Session ------------------- - -.. automodule:: sagemaker.session - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/conf.py b/doc/conf.py deleted file mode 100644 index 94a5c4d9c6..0000000000 --- a/doc/conf.py +++ /dev/null @@ -1,118 +0,0 @@ -# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"). You -# may not use this file except in compliance with the License. A copy of -# the License is located at -# -# http://aws.amazon.com/apache2.0/ -# -# or in the "license" file accompanying this file. This file is -# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF -# ANY KIND, either express or implied. See the License for the specific -# language governing permissions and limitations under the License. -"""Configuration for generating readthedocs docstrings.""" -from __future__ import absolute_import - -import pkg_resources -from datetime import datetime -import sys -import os - -sys.path.append(os.path.join(os.path.dirname(__file__), ".")) -from doc_utils.jumpstart_doc_utils import create_jumpstart_model_table # noqa: E402 - -project = "sagemaker" -version = pkg_resources.require(project)[0].version - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.doctest", - "sphinx.ext.intersphinx", - "sphinx.ext.todo", - "sphinx.ext.coverage", - "sphinx.ext.autosummary", - "sphinx.ext.napoleon", - "sphinx.ext.autosectionlabel", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -source_suffix = ".rst" # The suffix of source filenames. -master_doc = "index" # The master toctree document. - -copyright = "%s, Amazon" % datetime.now().year - -# The full version, including alpha/beta/rc tags. -release = version - -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees = ["_build"] - -pygments_style = "default" - -autoclass_content = "both" -autodoc_default_flags = ["show-inheritance", "members", "undoc-members"] -autodoc_member_order = "bysource" - -html_theme = "sphinx_rtd_theme" - -html_theme_options = { - "collapse_navigation": True, - "sticky_navigation": True, - "navigation_depth": 6, - "includehidden": True, - "titles_only": False, -} - - -html_static_path = ["_static"] - -htmlhelp_basename = "%sdoc" % project - -# For Adobe Analytics -html_js_files = [ - "https://a0.awsstatic.com/s_code/js/3.0/awshome_s_code.js", - "https://cdn.datatables.net/1.10.23/js/jquery.dataTables.min.js", - "https://kit.fontawesome.com/a076d05399.js", - "js/datatable.js", -] - -html_css_files = [ - "https://cdn.datatables.net/1.10.23/css/jquery.dataTables.min.css", -] - -html_context = { - "css_files": [ - "_static/theme_overrides.css", - "_static/pagination.css", - "_static/search_accessories.css", - ] -} - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"python": ("http://docs.python.org/", None)} - -# -- Options for autodoc ---------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration - -# Automatically extract typehints when specified and place them in -# descriptions of the relevant function/method. -autodoc_typehints = "description" - -# autosummary -autosummary_generate = True - -# autosectionlabel -autosectionlabel_prefix_document = True - -autodoc_mock_imports = ["pyspark", "feature_store_pyspark", "py4j"] - - -def setup(app): - sys.stdout.write("Generating JumpStart model table...") - sys.stdout.flush() - create_jumpstart_model_table() diff --git a/doc/doc_utils/jumpstart_doc_utils.py b/doc/doc_utils/jumpstart_doc_utils.py deleted file mode 100644 index 458da694d5..0000000000 --- a/doc/doc_utils/jumpstart_doc_utils.py +++ /dev/null @@ -1,358 +0,0 @@ -# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"). You -# may not use this file except in compliance with the License. A copy of -# the License is located at -# -# http://aws.amazon.com/apache2.0/ -# -# or in the "license" file accompanying this file. This file is -# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF -# ANY KIND, either express or implied. See the License for the specific -# language governing permissions and limitations under the License. -from __future__ import absolute_import -from urllib import request -import json -from packaging.version import Version -from enum import Enum - - -class Tasks(str, Enum): - """The ML task name as referenced in the infix of the model ID.""" - - IC = "ic" - OD = "od" - OD1 = "od1" - SEMSEG = "semseg" - IS = "is" - TC = "tc" - SPC = "spc" - EQA = "eqa" - TEXT_GENERATION = "textgeneration" - IC_EMBEDDING = "icembedding" - TC_EMBEDDING = "tcembedding" - NER = "ner" - SUMMARIZATION = "summarization" - TRANSLATION = "translation" - TABULAR_REGRESSION = "regression" - TABULAR_CLASSIFICATION = "classification" - - -class ProblemTypes(str, Enum): - """Possible problem types for JumpStart models.""" - - IMAGE_CLASSIFICATION = "Image Classification" - IMAGE_EMBEDDING = "Image Embedding" - OBJECT_DETECTION = "Object Detection" - SEMANTIC_SEGMENTATION = "Semantic Segmentation" - INSTANCE_SEGMENTATION = "Instance Segmentation" - TEXT_CLASSIFICATION = "Text Classification" - TEXT_EMBEDDING = "Text Embedding" - QUESTION_ANSWERING = "Question Answering" - SENTENCE_PAIR_CLASSIFICATION = "Sentence Pair Classification" - TEXT_GENERATION = "Text Generation" - TEXT_SUMMARIZATION = "Text Summarization" - MACHINE_TRANSLATION = "Machine Translation" - NAMED_ENTITY_RECOGNITION = "Named Entity Recognition" - TABULAR_REGRESSION = "Regression" - TABULAR_CLASSIFICATION = "Classification" - - -class Frameworks(str, Enum): - """Possible frameworks for JumpStart models""" - - TENSORFLOW = "Tensorflow Hub" - PYTORCH = "Pytorch Hub" - HUGGINGFACE = "HuggingFace" - CATBOOST = "Catboost" - GLUONCV = "GluonCV" - LIGHTGBM = "LightGBM" - XGBOOST = "XGBoost" - SCIKIT_LEARN = "ScikitLearn" - SOURCE = "Source" - - -JUMPSTART_REGION = "eu-west-2" -SDK_MANIFEST_FILE = "models_manifest.json" -PROPRIETARY_SDK_MANIFEST_FILE = "proprietary-sdk-manifest.json" -JUMPSTART_BUCKET_BASE_URL = "https://jumpstart-cache-prod-{}.s3.{}.amazonaws.com".format( - JUMPSTART_REGION, JUMPSTART_REGION -) -PROPRIETARY_DOC_BUCKET = "https://jumpstart-cache-prod-us-west-2.s3.us-west-2.amazonaws.com" - -TASK_MAP = { - Tasks.IC: ProblemTypes.IMAGE_CLASSIFICATION, - Tasks.IC_EMBEDDING: ProblemTypes.IMAGE_EMBEDDING, - Tasks.OD: ProblemTypes.OBJECT_DETECTION, - Tasks.OD1: ProblemTypes.OBJECT_DETECTION, - Tasks.SEMSEG: ProblemTypes.SEMANTIC_SEGMENTATION, - Tasks.IS: ProblemTypes.INSTANCE_SEGMENTATION, - Tasks.TC: ProblemTypes.TEXT_CLASSIFICATION, - Tasks.TC_EMBEDDING: ProblemTypes.TEXT_EMBEDDING, - Tasks.EQA: ProblemTypes.QUESTION_ANSWERING, - Tasks.SPC: ProblemTypes.SENTENCE_PAIR_CLASSIFICATION, - Tasks.TEXT_GENERATION: ProblemTypes.TEXT_GENERATION, - Tasks.SUMMARIZATION: ProblemTypes.TEXT_SUMMARIZATION, - Tasks.TRANSLATION: ProblemTypes.MACHINE_TRANSLATION, - Tasks.NER: ProblemTypes.NAMED_ENTITY_RECOGNITION, - Tasks.TABULAR_REGRESSION: ProblemTypes.TABULAR_REGRESSION, - Tasks.TABULAR_CLASSIFICATION: ProblemTypes.TABULAR_CLASSIFICATION, -} - -TO_FRAMEWORK = { - "Tensorflow Hub": Frameworks.TENSORFLOW, - "Pytorch Hub": Frameworks.PYTORCH, - "HuggingFace": Frameworks.HUGGINGFACE, - "Catboost": Frameworks.CATBOOST, - "GluonCV": Frameworks.GLUONCV, - "LightGBM": Frameworks.LIGHTGBM, - "XGBoost": Frameworks.XGBOOST, - "ScikitLearn": Frameworks.SCIKIT_LEARN, - "Source": Frameworks.SOURCE, -} - - -MODALITY_MAP = { - (Tasks.IC, Frameworks.PYTORCH): "algorithms/vision/image_classification_pytorch.rst", - (Tasks.IC, Frameworks.TENSORFLOW): "algorithms/vision/image_classification_tensorflow.rst", - (Tasks.IC_EMBEDDING, Frameworks.TENSORFLOW): "algorithms/vision/image_embedding_tensorflow.rst", - (Tasks.IS, Frameworks.GLUONCV): "algorithms/vision/instance_segmentation_mxnet.rst", - (Tasks.OD, Frameworks.GLUONCV): "algorithms/vision/object_detection_mxnet.rst", - (Tasks.OD, Frameworks.PYTORCH): "algorithms/vision/object_detection_pytorch.rst", - (Tasks.OD, Frameworks.TENSORFLOW): "algorithms/vision/object_detection_tensorflow.rst", - (Tasks.SEMSEG, Frameworks.GLUONCV): "algorithms/vision/semantic_segmentation_mxnet.rst", - ( - Tasks.TRANSLATION, - Frameworks.HUGGINGFACE, - ): "algorithms/text/machine_translation_hugging_face.rst", - (Tasks.NER, Frameworks.GLUONCV): "algorithms/text/named_entity_recognition_hugging_face.rst", - (Tasks.EQA, Frameworks.PYTORCH): "algorithms/text/question_answering_pytorch.rst", - ( - Tasks.SPC, - Frameworks.HUGGINGFACE, - ): "algorithms/text/sentence_pair_classification_hugging_face.rst", - ( - Tasks.SPC, - Frameworks.TENSORFLOW, - ): "algorithms/text/sentence_pair_classification_tensorflow.rst", - (Tasks.TC, Frameworks.TENSORFLOW): "algorithms/text/text_classification_tensorflow.rst", - ( - Tasks.TC_EMBEDDING, - Frameworks.GLUONCV, - ): "algorithms/vision/text_embedding_tensorflow_mxnet.rst", - ( - Tasks.TC_EMBEDDING, - Frameworks.TENSORFLOW, - ): "algorithms/vision/text_embedding_tensorflow_mxnet.rst", - ( - Tasks.TEXT_GENERATION, - Frameworks.HUGGINGFACE, - ): "algorithms/text/text_generation_hugging_face.rst", - ( - Tasks.SUMMARIZATION, - Frameworks.HUGGINGFACE, - ): "algorithms/text/text_summarization_hugging_face.rst", -} - - -def get_public_s3_json_object(url): - with request.urlopen(url) as f: - models_manifest = f.read().decode("utf-8") - return json.loads(models_manifest) - - -def get_jumpstart_sdk_manifest(): - return get_public_s3_json_object(f"{JUMPSTART_BUCKET_BASE_URL}/{SDK_MANIFEST_FILE}") - - -def get_proprietary_sdk_manifest(): - return get_public_s3_json_object(f"{PROPRIETARY_DOC_BUCKET}/{PROPRIETARY_SDK_MANIFEST_FILE}") - - -def get_jumpstart_sdk_spec(s3_key: str): - return get_public_s3_json_object(f"{JUMPSTART_BUCKET_BASE_URL}/{s3_key}") - - -def get_proprietary_sdk_spec(s3_key: str): - return get_public_s3_json_object(f"{PROPRIETARY_DOC_BUCKET}/{s3_key}") - - -def get_model_task(id): - task_short = id.split("-")[1] - return TASK_MAP[task_short] if task_short in TASK_MAP else "Source" - - -def get_string_model_task(id): - return id.split("-")[1] - - -def get_model_source(url): - if "tfhub" in url: - return "Tensorflow Hub" - if "pytorch" in url: - return "Pytorch Hub" - if "huggingface" in url: - return "HuggingFace" - if "catboost" in url: - return "Catboost" - if "gluon" in url: - return "GluonCV" - if "lightgbm" in url: - return "LightGBM" - if "xgboost" in url: - return "XGBoost" - if "scikit" in url: - return "ScikitLearn" - else: - return "Source" - - -def create_proprietary_model_table(): - proprietary_content_intro = [] - proprietary_content_intro.append("\n") - proprietary_content_intro.append(".. list-table:: Available Proprietary Models\n") - proprietary_content_intro.append(" :widths: 50 20 20 20 20\n") - proprietary_content_intro.append(" :header-rows: 1\n") - proprietary_content_intro.append(" :class: datatable\n") - proprietary_content_intro.append("\n") - proprietary_content_intro.append(" * - Model ID\n") - proprietary_content_intro.append(" - Fine Tunable?\n") - proprietary_content_intro.append(" - Supported Version\n") - proprietary_content_intro.append(" - Min SDK Version\n") - proprietary_content_intro.append(" - Source\n") - - sdk_manifest = get_proprietary_sdk_manifest() - sdk_manifest_top_versions_for_models = {} - - for model in sdk_manifest: - if model["model_id"] not in sdk_manifest_top_versions_for_models: - sdk_manifest_top_versions_for_models[model["model_id"]] = model - else: - if str(sdk_manifest_top_versions_for_models[model["model_id"]]["version"]) < str( - model["version"] - ): - sdk_manifest_top_versions_for_models[model["model_id"]] = model - - proprietary_content_entries = [] - for model in sdk_manifest_top_versions_for_models.values(): - model_spec = get_proprietary_sdk_spec(model["spec_key"]) - proprietary_content_entries.append(" * - {}\n".format(model_spec["model_id"])) - proprietary_content_entries.append(" - {}\n".format(False)) # TODO: support training - proprietary_content_entries.append(" - {}\n".format(model["version"])) - proprietary_content_entries.append(" - {}\n".format(model["min_version"])) - proprietary_content_entries.append( - " - `{} <{}>`__ |external-link|\n".format("Source", model_spec.get("url")) - ) - return proprietary_content_intro + proprietary_content_entries + ["\n"] - - -def create_jumpstart_model_table(): - sdk_manifest = get_jumpstart_sdk_manifest() - sdk_manifest_top_versions_for_models = {} - - for model in sdk_manifest: - if model["model_id"] not in sdk_manifest_top_versions_for_models: - sdk_manifest_top_versions_for_models[model["model_id"]] = model - else: - if Version( - sdk_manifest_top_versions_for_models[model["model_id"]]["version"] - ) < Version(model["version"]): - sdk_manifest_top_versions_for_models[model["model_id"]] = model - - file_content_intro = [] - - file_content_intro.append(".. _all-pretrained-models:\n\n") - file_content_intro.append(".. |external-link| raw:: html\n\n") - file_content_intro.append(' \n\n') - - file_content_intro.append("================================================\n") - file_content_intro.append("Built-in Algorithms with pre-trained Model Table\n") - file_content_intro.append("================================================\n") - file_content_intro.append( - """ - The SageMaker Python SDK uses model IDs and model versions to access the necessary - utilities for pre-trained models. This table serves to provide the core material plus - some extra information that can be useful in selecting the correct model ID and - corresponding parameters.\n""" - ) - file_content_intro.append( - """ - If you want to automatically use the latest version of the model, use "*" for the `model_version` attribute. - We highly suggest pinning an exact model version however.\n""" - ) - file_content_intro.append( - """ - These models are also available through the - `JumpStart UI in SageMaker Studio `__\n""" - ) - file_content_intro.append("\n") - file_content_intro.append(".. list-table:: Available Models\n") - file_content_intro.append(" :widths: 50 20 20 20 30 20\n") - file_content_intro.append(" :header-rows: 1\n") - file_content_intro.append(" :class: datatable\n") - file_content_intro.append("\n") - file_content_intro.append(" * - Model ID\n") - file_content_intro.append(" - Fine Tunable?\n") - file_content_intro.append(" - Latest Version\n") - file_content_intro.append(" - Min SDK Version\n") - file_content_intro.append(" - Problem Type\n") - file_content_intro.append(" - Source\n") - - dynamic_table_files = [] - open_weight_content_entries = [] - - for model in sdk_manifest_top_versions_for_models.values(): - model_spec = get_jumpstart_sdk_spec(model["spec_key"]) - model_task = get_model_task(model_spec["model_id"]) - string_model_task = get_string_model_task(model_spec["model_id"]) - model_source = get_model_source(model_spec["url"]) - open_weight_content_entries.append(" * - {}\n".format(model_spec["model_id"])) - open_weight_content_entries.append(" - {}\n".format(model_spec["training_supported"])) - open_weight_content_entries.append(" - {}\n".format(model["version"])) - open_weight_content_entries.append(" - {}\n".format(model["min_version"])) - open_weight_content_entries.append(" - {}\n".format(model_task)) - open_weight_content_entries.append( - " - `{} <{}>`__ |external-link|\n".format(model_source, model_spec["url"]) - ) - - if (string_model_task, TO_FRAMEWORK[model_source]) in MODALITY_MAP: - file_content_single_entry = [] - - if ( - MODALITY_MAP[(string_model_task, TO_FRAMEWORK[model_source])] - not in dynamic_table_files - ): - file_content_single_entry.append("\n") - file_content_single_entry.append(".. list-table:: Available Models\n") - file_content_single_entry.append(" :widths: 50 20 20 20 20\n") - file_content_single_entry.append(" :header-rows: 1\n") - file_content_single_entry.append(" :class: datatable\n") - file_content_single_entry.append("\n") - file_content_single_entry.append(" * - Model ID\n") - file_content_single_entry.append(" - Fine Tunable?\n") - file_content_single_entry.append(" - Latest Version\n") - file_content_single_entry.append(" - Min SDK Version\n") - file_content_single_entry.append(" - Source\n") - - dynamic_table_files.append( - MODALITY_MAP[(string_model_task, TO_FRAMEWORK[model_source])] - ) - - file_content_single_entry.append(" * - {}\n".format(model_spec["model_id"])) - file_content_single_entry.append(" - {}\n".format(model_spec["training_supported"])) - file_content_single_entry.append(" - {}\n".format(model["version"])) - file_content_single_entry.append(" - {}\n".format(model["min_version"])) - file_content_single_entry.append( - " - `{} <{}>`__\n".format(model_source, model_spec["url"]) - ) - f = open(MODALITY_MAP[(string_model_task, TO_FRAMEWORK[model_source])], "a") - f.writelines(file_content_single_entry) - f.close() - - proprietary_content_entries = create_proprietary_model_table() - - f = open("doc_utils/pretrainedmodels.rst", "a") - f.writelines(file_content_intro) - f.writelines(open_weight_content_entries) - f.writelines(proprietary_content_entries) - f.close() diff --git a/doc/experiments/index.rst b/doc/experiments/index.rst deleted file mode 100644 index 8c12f30edc..0000000000 --- a/doc/experiments/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -############################ -Amazon SageMaker Experiments -############################ - -The SageMaker Python SDK supports to track and organize your machine learning workflow across SageMaker with jobs, such as Processing, Training and Transform, or locally. - -.. toctree:: - :maxdepth: 2 - - sagemaker.experiments diff --git a/doc/experiments/sagemaker.experiments.rst b/doc/experiments/sagemaker.experiments.rst deleted file mode 100644 index 148dd00284..0000000000 --- a/doc/experiments/sagemaker.experiments.rst +++ /dev/null @@ -1,29 +0,0 @@ -Experiments -============ - -Run -------------- - -.. autoclass:: sagemaker.experiments.Run - :members: - -.. automethod:: sagemaker.experiments.run.load_run - -.. automethod:: sagemaker.experiments.list_runs - -Experiment -------------- - -.. autoclass:: sagemaker.experiments.Experiment - :members: - -Other -------------- - -.. autoclass:: sagemaker.experiments.SortByType - :members: - :undoc-members: - -.. autoclass:: sagemaker.experiments.SortOrderType - :members: - :undoc-members: diff --git a/doc/frameworks/chainer/index.rst b/doc/frameworks/chainer/index.rst deleted file mode 100644 index 6c91f34d6f..0000000000 --- a/doc/frameworks/chainer/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -########################## -Chainer -########################## - -A managed environment for Chainer training and hosting on Amazon SageMaker - -.. toctree:: - :maxdepth: 1 - - using_chainer - -.. toctree:: - :maxdepth: 2 - - sagemaker.chainer diff --git a/doc/frameworks/chainer/sagemaker.chainer.rst b/doc/frameworks/chainer/sagemaker.chainer.rst deleted file mode 100644 index 26a0c56c73..0000000000 --- a/doc/frameworks/chainer/sagemaker.chainer.rst +++ /dev/null @@ -1,26 +0,0 @@ -Chainer -======= - -Chainer Estimator ------------------ - -.. autoclass:: sagemaker.chainer.estimator.Chainer - :members: - :undoc-members: - :show-inheritance: - -Chainer Model -------------- - -.. autoclass:: sagemaker.chainer.model.ChainerModel - :members: - :undoc-members: - :show-inheritance: - -Chainer Predictor ------------------ - -.. autoclass:: sagemaker.chainer.model.ChainerPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/frameworks/chainer/using_chainer.rst b/doc/frameworks/chainer/using_chainer.rst deleted file mode 100644 index 85c197350d..0000000000 --- a/doc/frameworks/chainer/using_chainer.rst +++ /dev/null @@ -1,590 +0,0 @@ -########################################### -Using Chainer with the SageMaker Python SDK -########################################### - -With Chainer Estimators, you can train and host Chainer models on Amazon SageMaker. - -Supported versions of Chainer: ``4.0.0``, ``4.1.0``, ``5.0.0``. - -We recommend that you use the latest supported version because that's where we focus most of our development efforts. - -For more information about Chainer, see https://github.com/chainer/chainer. - -For general information about using the SageMaker Python SDK, see :ref:`overview:Using the SageMaker Python SDK`. - -.. contents:: - -************************** -Train a Model with Chainer -************************** - -To train a Chainer model by using the SageMaker Python SDK: - -.. |create chainer estimator| replace:: Create a ``sagemaker.chainer.Chainer`` Estimator -.. _create chainer estimator: #create-an-estimator - -.. |call fit| replace:: Call the estimator's ``fit`` method -.. _call fit: #call-the-fit-method - -1. `Prepare a training script <#prepare-a-chainer-training-script>`_ -2. |create chainer estimator|_ -3. |call fit|_ - - -Prepare a Chainer training script -================================= - -Your Chainer training script must be a Python 2.7 or 3.5 compatible source file. - -The training script is similar to a training script you might run outside of SageMaker, but you -can access useful properties about the training environment through various environment variables, -such as the following: - -* ``SM_MODEL_DIR``: A string representing the path to the directory to write model artifacts to. - These artifacts are uploaded to S3 for model hosting. -* ``SM_NUM_GPUS``: An integer representing the number of GPUs available to the host. -* ``SM_OUTPUT_DATA_DIR``: A string representing the filesystem path to write output artifacts to. Output artifacts may - include checkpoints, graphs, and other files to save, not including model artifacts. These artifacts are compressed - and uploaded to S3 to the same S3 prefix as the model artifacts. - -Suppose you use two input channels, named 'train' and 'test', in the call to the Chainer estimator's ``fit()`` method. -The following environment variables are set, following the format "SM_CHANNEL_[channel_name]": - -* ``SM_CHANNEL_TRAIN``: A string representing the path to the directory containing data in the 'train' channel -* ``SM_CHANNEL_TEST``: Same as above, but for the 'test' channel. - -A typical training script loads data from the input channels, configures training with hyperparameters, trains a model, -and saves a model to model_dir so that it can be hosted later. Hyperparameters are passed to your script as arguments -and can be retrieved with an argparse.ArgumentParser instance. For example, a training script might start -with the following: - -.. code:: python - - import argparse - import os - - if __name__ =='__main__': - - parser = argparse.ArgumentParser() - - # hyperparameters sent by the client are passed as command-line arguments to the script. - parser.add_argument('--epochs', type=int, default=50) - parser.add_argument('--batch-size', type=int, default=64) - parser.add_argument('--learning-rate', type=float, default=0.05) - - # Data, model, and output directories - parser.add_argument('--output-data-dir', type=str, default=os.environ['SM_OUTPUT_DATA_DIR']) - parser.add_argument('--model-dir', type=str, default=os.environ['SM_MODEL_DIR']) - parser.add_argument('--train', type=str, default=os.environ['SM_CHANNEL_TRAIN']) - parser.add_argument('--test', type=str, default=os.environ['SM_CHANNEL_TEST']) - - args, _ = parser.parse_known_args() - - # ... load from args.train and args.test, train a model, write model to args.model_dir. - -Because the SageMaker imports your training script, you should put your training code in a main guard -(``if __name__=='__main__':``) if you are using the same script to host your model, so that SageMaker does not -inadvertently run your training code at the wrong point in execution. - -For more on training environment variables, please visit https://github.com/aws/sagemaker-containers. - -Save the Model --------------- - -In order to save your trained Chainer model for deployment on SageMaker, your training script should save your model -to a certain filesystem path called `model_dir`. This value is accessible through the environment variable -``SM_MODEL_DIR``. The following code demonstrates how to save a trained Chainer model named ``model`` as -``model.npz`` at the end of training: - -.. code:: python - - import chainer - import argparse - import os - - if __name__=='__main__': - # default to the value in environment variable `SM_MODEL_DIR`. Using args makes the script more portable. - parser.add_argument('--model-dir', type=str, default=os.environ['SM_MODEL_DIR']) - args, _ = parser.parse_known_args() - - # ... train `model`, then save it to `model_dir` as file 'model.npz' - chainer.serializers.save_npz(os.path.join(args.model_dir, 'model.npz'), model) - -After your training job is complete, SageMaker will compress and upload the serialized model to S3, and your model data -will available in the s3 ``output_path`` you specified when you created the Chainer Estimator. - -Using third-party libraries ---------------------------- - -When running your training script on SageMaker, it will have access to some pre-installed third-party libraries including ``chainer``, ``numpy``, and ``cupy``. -For more information on the runtime environment, including specific package versions, see `SageMaker Chainer Docker containers <#sagemaker-chainer-docker-containers>`__. - -If there are other packages you want to use with your script, you can include a ``requirements.txt`` file in the same directory as your training script to install other dependencies at runtime. -Both ``requirements.txt`` and your training script should be put in the same folder. -You must specify this folder in ``source_dir`` argument when creating a Chainer estimator. -A ``requirements.txt`` file is a text file that contains a list of items that are installed by using ``pip install``. -You can also specify the version of an item to install. -For information about the format of a ``requirements.txt`` file, see `Requirements Files `__ in the pip documentation. - -Create an Estimator -=================== - -You run Chainer training scripts on SageMaker by creating ``Chainer`` Estimators. -SageMaker training of your script is invoked when you call ``fit`` on a ``Chainer`` Estimator. -The following code sample shows how you train a custom Chainer script "chainer-train.py", passing -in three hyperparameters ('epochs', 'batch-size', and 'learning-rate'), and using two input channel -directories ('train' and 'test'). - -.. code:: python - - chainer_estimator = Chainer('chainer-train.py', - instance_type='ml.p3.2xlarge', - instance_count=1, - framework_version='5.0.0', - py_version='py3', - hyperparameters = {'epochs': 20, 'batch-size': 64, 'learning-rate': 0.1}) - chainer_estimator.fit({'train': 's3://my-data-bucket/path/to/my/training/data', - 'test': 's3://my-data-bucket/path/to/my/test/data'}) - - -Call the fit Method -=================== - -You start your training script by calling ``fit`` on a ``Chainer`` Estimator. ``fit`` takes both required and optional -arguments. - -fit Required arguments ----------------------- - -- ``inputs``: This can take one of the following forms: A string - s3 URI, for example ``s3://my-bucket/my-training-data``. In this - case, the s3 objects rooted at the ``my-training-data`` prefix will - be available in the default ``train`` channel. A dict from - string channel names to s3 URIs. In this case, the objects rooted at - each s3 prefix will available as files in each channel directory. - -For example: - -.. code:: python - - {'train':'s3://my-bucket/my-training-data', - 'eval':'s3://my-bucket/my-evaluation-data'} - -.. optional-arguments-1: - -fit Optional arguments ----------------------- - -- ``wait``: Defaults to True, whether to block and wait for the - training script to complete before returning. -- ``logs``: Defaults to True, whether to show logs produced by training - job in the Python session. Only meaningful when wait is True. - -Distributed Training -==================== - - -Chainer allows you to train a model on multiple nodes using ChainerMN_, which distributes training with MPI. - -.. _ChainerMN: https://github.com/chainer/chainermn - -In order to run distributed Chainer training on SageMaker, your training script should use a ``chainermn`` Communicator -object to coordinate training between multiple hosts. - -SageMaker runs your script with ``mpirun`` if ``instance_count`` is greater than two. -The following are optional arguments modify how MPI runs your distributed training script. - -- ``use_mpi`` Boolean that overrides whether to run your training script with MPI. -- ``num_processes`` Integer that determines how many total processes to run with MPI. By default, this is equal to ``process_slots_per_host`` times the number of nodes. -- ``process_slots_per_host`` Integer that determines how many processes can be run on each host. By default, this is equal to one process per host on CPU instances, or one process per GPU on GPU instances. -- ``additional_mpi_options`` String of additional options to pass to the ``mpirun`` command. - - -********************* -Deploy Chainer models -********************* - -After an Chainer Estimator has been fit, you can host the newly created model in SageMaker. - -After calling ``fit``, you can call ``deploy`` on a ``Chainer`` Estimator to create a SageMaker Endpoint. -The Endpoint runs a SageMaker-provided Chainer model server and hosts the model produced by your training script, -which was run when you called ``fit``. This was the model you saved to ``model_dir``. - -``deploy`` returns a ``Predictor`` object, which you can use to do inference on the Endpoint hosting your Chainer model. -Each ``Predictor`` provides a ``predict`` method which can do inference with numpy arrays or Python lists. -Inference arrays or lists are serialized and sent to the Chainer model server by an ``InvokeEndpoint`` SageMaker -operation. - -``predict`` returns the result of inference against your model. By default, the inference result a NumPy array. - -.. code:: python - - # Train my estimator - chainer_estimator = Chainer(entry_point='train_and_deploy.py', - instance_type='ml.p3.2xlarge', - instance_count=1, - framework_version='5.0.0', - py_version='py3') - chainer_estimator.fit('s3://my_bucket/my_training_data/') - - # Deploy my estimator to a SageMaker Endpoint and get a Predictor - predictor = chainer_estimator.deploy(instance_type='ml.m4.xlarge', - initial_instance_count=1) - - # `data` is a NumPy array or a Python list. - # `response` is a NumPy array. - response = predictor.predict(data) - -You use the SageMaker Chainer model server to host your Chainer model when you call ``deploy`` on an ``Chainer`` -Estimator. The model server runs inside a SageMaker Endpoint, which your call to ``deploy`` creates. -You can access the name of the Endpoint by the ``name`` property on the returned ``Predictor``. - - -The SageMaker Chainer Model Server -================================== - -The Chainer Endpoint you create with ``deploy`` runs a SageMaker Chainer model server. -The model server loads the model that was saved by your training script and performs inference on the model in response -to SageMaker InvokeEndpoint API calls. - -You can configure two components of the SageMaker Chainer model server: Model loading and model serving. -Model loading is the process of deserializing your saved model back into an Chainer model. -Serving is the process of translating InvokeEndpoint requests to inference calls on the loaded model. - -You configure the Chainer model server by defining functions in the Python source file you passed to the Chainer constructor. - -Load a Model ------------- - -Before a model can be served, it must be loaded. The SageMaker Chainer model server loads your model by invoking a -``model_fn`` function that you must provide in your script. The ``model_fn`` should have the following signature: - -.. code:: python - - def model_fn(model_dir) - -SageMaker will inject the directory where your model files and sub-directories, saved by ``save``, have been mounted. -Your model function should return a model object that can be used for model serving. - -SageMaker provides automated serving functions that work with Gluon API ``net`` objects and Module API ``Module`` objects. If you return either of these types of objects, then you will be able to use the default serving request handling functions. - -The following code-snippet shows an example ``model_fn`` implementation. -This loads returns a Chainer Classifier from a multi-layer perceptron class ``MLP`` that extends ``chainer.Chain``. -It loads the model parameters from a ``model.npz`` file in the SageMaker model directory ``model_dir``. - -.. code:: python - - import chainer - import os - - def model_fn(model_dir): - chainer.config.train = False - model = chainer.links.Classifier(MLP(1000, 10)) - chainer.serializers.load_npz(os.path.join(model_dir, 'model.npz'), model) - return model.predictor - -Serve a Model -------------- - -After the SageMaker model server has loaded your model by calling ``model_fn``, SageMaker will serve your model. -Model serving is the process of responding to inference requests, received by SageMaker InvokeEndpoint API calls. -The SageMaker Chainer model server breaks request handling into three steps: - - -- input processing, -- prediction, and -- output processing. - -In a similar way to model loading, you configure these steps by defining functions in your Python source file. - -Each step involves invoking a python function, with information about the request and the return-value from the previous -function in the chain. Inside the SageMaker Chainer model server, the process looks like: - -.. code:: python - - # Deserialize the Invoke request body into an object we can perform prediction on - input_object = input_fn(request_body, request_content_type) - - # Perform prediction on the deserialized object, with the loaded model - prediction = predict_fn(input_object, model) - - # Serialize the prediction result into the desired response content type - output = output_fn(prediction, response_content_type) - -The above code-sample shows the three function definitions: - -- ``input_fn``: Takes request data and deserializes the data into an - object for prediction. -- ``predict_fn``: Takes the deserialized request object and performs - inference against the loaded model. -- ``output_fn``: Takes the result of prediction and serializes this - according to the response content type. - -The SageMaker Chainer model server provides default implementations of these functions. -You can provide your own implementations for these functions in your hosting script. -If you omit any definition then the SageMaker Chainer model server will use its default implementation for that -function. - -The ``Predictor`` used by Chainer in the SageMaker Python SDK serializes NumPy arrays to the `NPY `_ format -by default, with Content-Type ``application/x-npy``. The SageMaker Chainer model server can deserialize NPY-formatted -data (along with JSON and CSV data). - -If you rely solely on the SageMaker Chainer model server defaults, you get the following functionality: - -- Prediction on models that implement the ``__call__`` method -- Serialization and deserialization of NumPy arrays. - -The default ``input_fn`` and ``output_fn`` are meant to make it easy to predict on NumPy arrays. If your model expects -a NumPy array and returns a NumPy array, then these functions do not have to be overridden when sending NPY-formatted -data. - -In the following sections we describe the default implementations of input_fn, predict_fn, and output_fn. -We describe the input arguments and expected return types of each, so you can define your own implementations. - -Process Input -^^^^^^^^^^^^^ - -When an InvokeEndpoint operation is made against an Endpoint running a SageMaker Chainer model server, -the model server receives two pieces of information: - -- The request Content-Type, for example "application/x-npy" -- The request data body, a byte array - -The SageMaker Chainer model server will invoke an "input_fn" function in your hosting script, -passing in this information. If you define an ``input_fn`` function definition, -it should return an object that can be passed to ``predict_fn`` and have the following signature: - -.. code:: python - - def input_fn(request_body, request_content_type) - -Where ``request_body`` is a byte buffer and ``request_content_type`` is a Python string - -The SageMaker Chainer model server provides a default implementation of ``input_fn``. -This function deserializes JSON, CSV, or NPY encoded data into a NumPy array. - -Default NPY deserialization requires ``request_body`` to follow the `NPY `_ format. For Chainer, the Python SDK -defaults to sending prediction requests with this format. - -Default json deserialization requires ``request_body`` contain a single json list. -Sending multiple json objects within the same ``request_body`` is not supported. -The list must have a dimensionality compatible with the model loaded in ``model_fn``. -The list's shape must be identical to the model's input shape, for all dimensions after the first (which first -dimension is the batch size). - -Default csv deserialization requires ``request_body`` contain one or more lines of CSV numerical data. -The data is loaded into a two-dimensional array, where each line break defines the boundaries of the first dimension. - -The example below shows a custom ``input_fn`` for preparing pickled NumPy arrays. - -.. code:: python - - import numpy as np - - def input_fn(request_body, request_content_type): - """An input_fn that loads a pickled numpy array""" - if request_content_type == "application/python-pickle": - array = np.load(StringIO(request_body)) - return array - else: - # Handle other content-types here or raise an Exception - # if the content type is not supported. - pass - - - -Get Predictions ---------------- - -After the inference request has been deserialized by ``input_fn``, the SageMaker Chainer model server invokes -``predict_fn`` on the return value of ``input_fn``. - -As with ``input_fn``, you can define your own ``predict_fn`` or use the SageMaker Chainer model server default. - -The ``predict_fn`` function has the following signature: - -.. code:: python - - def predict_fn(input_object, model) - -Where ``input_object`` is the object returned from ``input_fn`` and -``model`` is the model loaded by ``model_fn``. - -The default implementation of ``predict_fn`` invokes the loaded model's ``__call__`` function on ``input_object``, -and returns the resulting value. The return-type should be a NumPy array to be compatible with the default -``output_fn``. - -The example below shows an overridden ``predict_fn``. This model accepts a Python list and returns a tuple of -bounding boxes, labels, and scores from the model in a NumPy array. This ``predict_fn`` can rely on the default -``input_fn`` and ``output_fn`` because ``input_data`` is a NumPy array, and the return value of this function is -a NumPy array. - -.. code:: python - - import chainer - import numpy as np - - def predict_fn(input_data, model): - with chainer.using_config('train', False), chainer.no_backprop_mode(): - bboxes, labels, scores = model.predict([input_data]) - bbox, label, score = bboxes[0], labels[0], scores[0] - return np.array([bbox.tolist(), label, score]) - -If you implement your own prediction function, you should take care to ensure that: - -- The first argument is expected to be the return value from input_fn. - If you use the default input_fn, this will be a NumPy array. -- The second argument is the loaded model. -- The return value should be of the correct type to be passed as the - first argument to ``output_fn``. If you use the default - ``output_fn``, this should be a NumPy array. - -Process Output -^^^^^^^^^^^^^^ - -After invoking ``predict_fn``, the model server invokes ``output_fn``, passing in the return-value from ``predict_fn`` -and the InvokeEndpoint requested response content-type. - -The ``output_fn`` has the following signature: - -.. code:: python - - def output_fn(prediction, content_type) - -Where ``prediction`` is the result of invoking ``predict_fn`` and -``content_type`` is the InvokeEndpoint requested response content-type. -The function should return a byte array of data serialized to content_type. - -The default implementation expects ``prediction`` to be an NumPy and can serialize the result to JSON, CSV, or NPY. -It accepts response content types of "application/json", "text/csv", and "application/x-npy". - -Working with existing model data and training jobs -================================================== - -Attach to Existing Training Jobs --------------------------------- - -You can attach an Chainer Estimator to an existing training job using the -``attach`` method. - -.. code:: python - - my_training_job_name = "MyAwesomeChainerTrainingJob" - chainer_estimator = Chainer.attach(my_training_job_name) - -After attaching, if the training job is in a Complete status, it can be -``deploy``\ ed to create a SageMaker Endpoint and return a -``Predictor``. If the training job is in progress, -attach will block and display log messages from the training job, until the training job completes. - -The ``attach`` method accepts the following arguments: - -- ``training_job_name (str):`` The name of the training job to attach - to. -- ``sagemaker_session (sagemaker.Session or None):`` The Session used - to interact with SageMaker - -Deploy Endpoints from Model Data --------------------------------- - -As well as attaching to existing training jobs, you can deploy models directly from model data in S3. -The following code sample shows how to do this, using the ``ChainerModel`` class. - -.. code:: python - - chainer_model = ChainerModel( - model_data="s3://bucket/model.tar.gz", - role="SageMakerRole", - entry_point="transform_script.py", - ) - - predictor = chainer_model.deploy(instance_type="ml.c4.xlarge", initial_instance_count=1) - -To see what arguments are accepted by the ``ChainerModel`` constructor, see :class:`sagemaker.chainer.model.ChainerModel`. - -Your model data must be a .tar.gz file in S3. SageMaker Training Job model data is saved to .tar.gz files in S3, -however if you have local data you want to deploy, you can prepare the data yourself. - -Assuming you have a local directory containg your model data named "my_model" you can tar and gzip compress the file and -upload to S3 using the following commands: - -:: - - tar -czf model.tar.gz my_model - aws s3 cp model.tar.gz s3://my-bucket/my-path/model.tar.gz - -This uploads the contents of my_model to a gzip compressed tar file to S3 in the bucket "my-bucket", with the key -"my-path/model.tar.gz". - -To run this command, you'll need the aws cli tool installed. Please refer to our `FAQ <#FAQ>`__ for more information on -installing this. - -******** -Examples -******** - -Amazon provides several example Jupyter notebooks that demonstrate end-to-end training on Amazon SageMaker using Chainer. -Please refer to: - -https://github.com/awslabs/amazon-sagemaker-examples/tree/master/sagemaker-python-sdk - -These are also available in SageMaker Notebook Instance hosted Jupyter notebooks under the "sample notebooks" folder. - -************************* -SageMaker Chainer Classes -************************* - -For information about the different Chainer-related classes in the SageMaker Python SDK, see https://sagemaker.readthedocs.io/en/stable/frameworks/chainer/sagemaker.chainer.html. - -*********************************** -SageMaker Chainer Docker containers -*********************************** - -When training and deploying training scripts, SageMaker runs your Python script in a Docker container with several -libraries installed. When creating the Estimator and calling deploy to create the SageMaker Endpoint, you can control -the environment your script runs in. - -SageMaker runs Chainer Estimator scripts in either Python 2.7 or Python 3.5. You can select the Python version by -passing a py_version keyword arg to the Chainer Estimator constructor. Setting this to py3 (the default) will cause your -training script to be run on Python 3.5. Setting this to py2 will cause your training script to be run on Python 2.7 -This Python version applies to both the Training Job, created by fit, and the Endpoint, created by deploy. - -The Chainer Docker images have the following dependencies installed: - -+-----------------------------+-------------+-------------+-------------+ -| Dependencies | chainer 4.0 | chainer 4.1 | chainer 5.0 | -+-----------------------------+-------------+-------------+-------------+ -| chainer | 4.0.0 | 4.1.0 | 5.0.0 | -+-----------------------------+-------------+-------------+-------------+ -| chainercv | 0.9.0 | 0.10.0 | 0.10.0 | -+-----------------------------+-------------+-------------+-------------+ -| chainermn | 1.2.0 | 1.3.0 | N/A | -+-----------------------------+-------------+-------------+-------------+ -| CUDA (GPU image only) | 9.0 | 9.0 | 9.0 | -+-----------------------------+-------------+-------------+-------------+ -| cupy | 4.0.0 | 4.1.0 | 5.0.0 | -+-----------------------------+-------------+-------------+-------------+ -| matplotlib | 2.2.0 | 2.2.0 | 2.2.0 | -+-----------------------------+-------------+-------------+-------------+ -| mpi4py | 3.0.0 | 3.0.0 | 3.0.0 | -+-----------------------------+-------------+-------------+-------------+ -| numpy | 1.14.3 | 1.15.3 | 1.15.4 | -+-----------------------------+-------------+-------------+-------------+ -| opencv-python | 3.4.0.12 | 3.4.0.12 | 3.4.0.12 | -+-----------------------------+-------------+-------------+-------------+ -| Pillow | 5.1.0 | 5.3.0 | 5.3.0 | -+-----------------------------+-------------+-------------+-------------+ -| Python | 2.7 or 3.5 | 2.7 or 3.5 | 2.7 or 3.5 | -+-----------------------------+-------------+-------------+-------------+ - -The Docker images extend Ubuntu 16.04. - -You must select a version of Chainer by passing a ``framework_version`` keyword arg to the Chainer Estimator -constructor. Currently supported versions are listed in the above table. You can also set framework_version to only -specify major and minor version, which will cause your training script to be run on the latest supported patch -version of that minor version. - -Alternatively, you can build your own image by following the instructions in the SageMaker Chainer containers -repository, and passing ``image_uri`` to the Chainer Estimator constructor. - -You can visit the SageMaker Chainer containers repository at https://github.com/aws/sagemaker-chainer-container diff --git a/doc/frameworks/djl/index.rst b/doc/frameworks/djl/index.rst deleted file mode 100644 index 06b27d0af7..0000000000 --- a/doc/frameworks/djl/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -######################## -Deep Java Library (DJL) -######################## - -A managed environment for inference using Deep Java Library (DJL) on Amazon SageMaker. -For general information about using the SageMaker Python SDK, see :ref:`overview:Using the SageMaker Python SDK`. - -.. toctree:: - :maxdepth: 1 - - using_djl - -.. toctree:: - :maxdepth: 2 - - sagemaker.djl_inference diff --git a/doc/frameworks/djl/sagemaker.djl_inference.rst b/doc/frameworks/djl/sagemaker.djl_inference.rst deleted file mode 100644 index 5b4d138776..0000000000 --- a/doc/frameworks/djl/sagemaker.djl_inference.rst +++ /dev/null @@ -1,19 +0,0 @@ -DJL Classes -================= - - -DJLModel ---------------------------- - -.. autoclass:: sagemaker.djl_inference.DJLModel - :members: - :undoc-members: - :show-inheritance: - -DJLPredictor ---------------------------- - -.. autoclass:: sagemaker.djl_inference.DJLPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/frameworks/djl/using_djl.rst b/doc/frameworks/djl/using_djl.rst deleted file mode 100644 index 63b8acd684..0000000000 --- a/doc/frameworks/djl/using_djl.rst +++ /dev/null @@ -1,77 +0,0 @@ -####################################### -Use DJL with the SageMaker Python SDK -####################################### - -`Deep Java Library (DJL) Serving `_ is a high performance universal stand-alone model serving solution powered by `DJL `_. -DJL Serving supports loading models trained with a variety of different frameworks. With the SageMaker Python SDK you can -use DJL Serving to host large language models for text-generation and text-embedding use-cases. - -You can learn more about Large Model Inference using DJLServing on the `docs site `_. - -For general information about using the SageMaker Python SDK, see :ref:`overview:Using the SageMaker Python SDK`. - -.. contents:: - -******************* -Deploy DJL models -******************* - -With the SageMaker Python SDK, you can use DJL Serving to host text-generation and text-embedding models that have been saved in the HuggingFace pretrained format. -These can either be models you have trained/fine-tuned yourself, or models available publicly from the HuggingFace Hub. - -.. code:: python - - # DJLModel will infer which container to use, and apply some starter configuration - djl_model = DJLModel( - model_id="", - role="my_sagemaker_role", - task="text-generation", - ) - - # Deploy the model to an Amazon SageMaker Endpoint and get a Predictor - predictor = djl_model.deploy("ml.g5.12xlarge", - initial_instance_count=1) - -Alternatively, you can provide full specifications to the DJLModel to have full control over the model configuration: - -.. code:: python - - djl_model = DJLModel( - model_id="", - role="my_sagemaker_role", - task="text-generation", - engine="Python", - env={ - "OPTION_ROLLING_BATCH": "lmi-dist", - "TENSOR_PARALLEL_DEGREE": "2", - "OPTION_DTYPE": "bf16", - "OPTION_MAX_ROLLING_BATCH_SIZE": "64", - }, - image_uri=, - ) - # Deploy the model to an Amazon SageMaker Endpoint and get a Predictor - predictor = djl_model.deploy("ml.g5.12xlarge", - initial_instance_count=1) - -Regardless of how you create your model, a ``Predictor`` object is returned. -Each ``Predictor`` provides a ``predict`` method, which can do inference with json data, numpy arrays, or Python lists. -Inference data are serialized and sent to the DJL Serving model server by an ``InvokeEndpoint`` SageMaker operation. The -``predict`` method returns the result of inference against your model. - -By default, the inference data is serialized to a json string, and the inference result is a Python dictionary. - -************************************** -DJL Serving for Large Model Inference -************************************** - -You can learn more about using DJL Serving for Large Model Inference use-cases on our `documentation site `_. - - - -******************************** -SageMaker DJL Serving Containers -******************************** - -For information about the SageMaker DJL Serving containers, see: - -- `Deep Learning Container (DLC) Images `_ and `release notes `_ diff --git a/doc/frameworks/huggingface/index.rst b/doc/frameworks/huggingface/index.rst deleted file mode 100644 index 3549f80977..0000000000 --- a/doc/frameworks/huggingface/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -############ -Hugging Face -############ - -A managed environment for training using Hugging Face on Amazon SageMaker. For more information about Hugging Face on Amazon SageMaker, as well as sample Jupyter notebooks, see `Use Hugging Face with Amazon SageMaker `_. -For general information about using the SageMaker Python SDK, see :ref:`overview:Using the SageMaker Python SDK`. - -.. toctree:: - :maxdepth: 2 - - sagemaker.huggingface - Train Hugging Face models on Amazon SageMaker with the SageMaker Python SDK - Deploy Hugging Face models to Amazon SageMaker with the SageMaker Python SDK diff --git a/doc/frameworks/huggingface/sagemaker.huggingface.rst b/doc/frameworks/huggingface/sagemaker.huggingface.rst deleted file mode 100644 index 37c949f60d..0000000000 --- a/doc/frameworks/huggingface/sagemaker.huggingface.rst +++ /dev/null @@ -1,42 +0,0 @@ -Hugging Face -============ - -Hugging Face Estimator ----------------------- - -.. autoclass:: sagemaker.huggingface.HuggingFace - :members: - :undoc-members: - :show-inheritance: - -Hugging Face Training Compiler Configuration --------------------------------------------- - -.. autoclass:: sagemaker.huggingface.TrainingCompilerConfig - :members: - :undoc-members: - :show-inheritance: - -Hugging Face Model ------------------- - -.. autoclass:: sagemaker.huggingface.model.HuggingFaceModel - :members: - :undoc-members: - :show-inheritance: - -Hugging Face Predictor ----------------------- - -.. autoclass:: sagemaker.huggingface.model.HuggingFacePredictor - :members: - :undoc-members: - :show-inheritance: - -Hugging Face Processor ----------------------- - -.. autoclass:: sagemaker.huggingface.processing.HuggingFaceProcessor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/frameworks/index.rst b/doc/frameworks/index.rst deleted file mode 100644 index a646536954..0000000000 --- a/doc/frameworks/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -########## -Frameworks -########## - -The SageMaker Python SDK supports managed training and inference for a variety of machine learning frameworks: - -.. toctree:: - :maxdepth: 2 - - mxnet/index - chainer/index - huggingface/index - pytorch/index - rl/index - sklearn/index - sparkml/index - tensorflow/index - xgboost/index - djl/index diff --git a/doc/frameworks/mxnet/index.rst b/doc/frameworks/mxnet/index.rst deleted file mode 100644 index fcb792c176..0000000000 --- a/doc/frameworks/mxnet/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -######################## -Apache MXNet -######################## - -A managed environment for MXNet training and hosting on Amazon SageMaker - -.. toctree:: - :maxdepth: 1 - - using_mxnet - -.. toctree:: - :maxdepth: 2 - - sagemaker.mxnet diff --git a/doc/frameworks/mxnet/sagemaker.mxnet.rst b/doc/frameworks/mxnet/sagemaker.mxnet.rst deleted file mode 100644 index 10ecb4e708..0000000000 --- a/doc/frameworks/mxnet/sagemaker.mxnet.rst +++ /dev/null @@ -1,35 +0,0 @@ -MXNet Classes -================= - - -MXNet Estimator ---------------- - -.. autoclass:: sagemaker.mxnet.estimator.MXNet - :members: - :undoc-members: - :show-inheritance: - -MXNet Model ------------ - -.. autoclass:: sagemaker.mxnet.model.MXNetModel - :members: - :undoc-members: - :show-inheritance: - -MXNet Predictor ---------------- - -.. autoclass:: sagemaker.mxnet.model.MXNetPredictor - :members: - :undoc-members: - :show-inheritance: - -MXNet Processor ---------------- - -.. autoclass:: sagemaker.mxnet.processing.MXNetProcessor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/frameworks/mxnet/using_mxnet.rst b/doc/frameworks/mxnet/using_mxnet.rst deleted file mode 100644 index 0e78b92d57..0000000000 --- a/doc/frameworks/mxnet/using_mxnet.rst +++ /dev/null @@ -1,657 +0,0 @@ -####################################### -Use MXNet with the SageMaker Python SDK -####################################### - -With the SageMaker Python SDK, you can train and host MXNet models on Amazon SageMaker. - -For information about supported versions of MXNet, see the `AWS documentation `__. -We recommend that you use the latest supported version because that's where we focus our development efforts. - -For general information about using the SageMaker Python SDK, see :ref:`overview:Using the SageMaker Python SDK`. - -.. contents:: - -************************ -Train a Model with MXNet -************************ - -To train an MXNet model by using the SageMaker Python SDK: - -.. |create mxnet estimator| replace:: Create a ``sagemaker.mxnet.MXNet`` Estimator -.. _create mxnet estimator: #create-an-estimator - -.. |call fit| replace:: Call the estimator's ``fit`` method -.. _call fit: #call-the-fit-method - -1. `Prepare a training script <#prepare-an-mxnet-training-script>`_ -2. |create mxnet estimator|_ -3. |call fit|_ - -Prepare an MXNet Training Script -================================ - -The training script is very similar to a training script you might run outside of Amazon SageMaker, but you can access useful properties about the training environment through various environment variables, including the following: - -* ``SM_MODEL_DIR``: A string that represents the path where the training job writes the model artifacts to. - After training, artifacts in this directory are uploaded to Amazon S3 for model hosting. -* ``SM_NUM_GPUS``: An integer representing the number of GPUs available to the host. -* ``SM_CHANNEL_XXXX``: A string that represents the path to the directory that contains the input data for the specified channel. - For example, if you specify two input channels in the MXNet estimator's ``fit`` call, named 'train' and 'test', the environment variables ``SM_CHANNEL_TRAIN`` and ``SM_CHANNEL_TEST`` are set. -* ``SM_HPS``: A JSON dump of the hyperparameters preserving JSON types (boolean, integer, etc.) - -For the exhaustive list of available environment variables, see the `SageMaker Containers documentation `__. - -A typical training script loads data from the input channels, configures training with hyperparameters, trains a model, and saves a model to ``model_dir`` so that it can be deployed for inference later. -Hyperparameters are passed to your script as arguments and can be retrieved with an ``argparse.ArgumentParser`` instance. -For example, a training script might start with the following: - -.. code:: python - - import argparse - import os - import json - - if __name__ =='__main__': - - parser = argparse.ArgumentParser() - - # hyperparameters sent by the client are passed as command-line arguments to the script. - parser.add_argument('--epochs', type=int, default=10) - parser.add_argument('--batch-size', type=int, default=100) - parser.add_argument('--learning-rate', type=float, default=0.1) - - # an alternative way to load hyperparameters via SM_HPS environment variable. - parser.add_argument('--sm-hps', type=json.loads, default=os.environ['SM_HPS']) - - # input data and model directories - parser.add_argument('--model-dir', type=str, default=os.environ['SM_MODEL_DIR']) - parser.add_argument('--train', type=str, default=os.environ['SM_CHANNEL_TRAIN']) - parser.add_argument('--test', type=str, default=os.environ['SM_CHANNEL_TEST']) - - args, _ = parser.parse_known_args() - - # ... load from args.train and args.test, train a model, write model to args.model_dir. - -Because Amazon SageMaker imports your training script, you should put your training code in a main guard (``if __name__=='__main__':``) if you are using the same script to host your model, -so that Amazon SageMaker does not inadvertently run your training code at the wrong point in execution. - -Note that Amazon SageMaker doesn't support argparse actions. -If you want to use, for example, boolean hyperparameters, you need to specify ``type`` as ``bool`` in your script and provide an explicit ``True`` or ``False`` value for this hyperparameter when instantiating your MXNet estimator. - -For more on training environment variables, please visit `SageMaker Containers `_. - -.. note:: - If you want to use MXNet 1.2 or lower, see `an older version of this page `_. - -Save a Checkpoint ------------------ - -It is good practice to save the best model after each training epoch, -so that you can resume a training job if it gets interrupted. -This is particularly important if you are using Managed Spot training. - -To save MXNet model checkpoints, do the following in your training script: - -* Set the ``CHECKPOINTS_DIR`` environment variable and enable checkpoints. - - .. code:: python - - CHECKPOINTS_DIR = '/opt/ml/checkpoints' - checkpoints_enabled = os.path.exists(CHECKPOINTS_DIR) - -* Make sure you are emitting a validation metric to test the model. For information, see `Evaluation Metric API `_. -* After each training epoch, test whether the current model performs the best with respect to the validation metric, and if it does, save that model to ``CHECKPOINTS_DIR``. - - .. code:: python - - if checkpoints_enabled and current_host == hosts[0]: - if val_acc > best_accuracy: - best_accuracy = val_acc - logging.info('Saving the model, params and optimizer state') - net.export(CHECKPOINTS_DIR + "/%.4f-cifar10"%(best_accuracy), epoch) - trainer.save_states(CHECKPOINTS_DIR + '/%.4f-cifar10-%d.states'%(best_accuracy, epoch)) - -For a complete example of an MXNet training script that impelements checkpointing, see https://github.com/awslabs/amazon-sagemaker-examples/blob/master/sagemaker-python-sdk/mxnet_gluon_cifar10/cifar10.py. - -Save the Model --------------- - -There is a default save method that can be imported when training on SageMaker: - -.. code:: python - - from sagemaker_mxnet_training.training_utils import save - - if __name__ == '__main__': - # arg parsing and training (shown above) goes here - - save(args.model_dir, model) - -The default serialization system generates three files: - -- ``model-shapes.json``: A JSON list, containing a serialization of the - ``Module`` ``data_shapes`` property. Each object in the list contains - the serialization of one ``DataShape`` in the returned ``Module``. - Each object has a ``name`` property, containing the ``DataShape`` - name and a ``shape`` property, which is a list of that dimensions for - the shape of that ``DataShape``. For example: - -.. code:: javascript - - [ - {"name":"images", "shape":[100, 1, 28, 28]}, - {"name":"labels", "shape":[100, 1]} - ] - -- ``model-symbol.json``: The MXNet ``Module`` ``Symbol`` serialization, - produced by invoking ``save`` on the ``symbol`` property of the - ``Module`` being saved. -- ``modle.params``: The MXNet ``Module`` parameters, produced by - invoking ``save_params`` on the ``Module`` being saved. - -Use third-party libraries -========================= - -When running your training script on Amazon SageMaker, it has access to some pre-installed third-party libraries, including ``mxnet``, ``numpy``, ``onnx``, and ``keras-mxnet``. -For more information on the runtime environment, including specific package versions, see `SageMaker MXNet Containers <#sagemaker-mxnet-containers>`__. - -If there are other packages you want to use with your script, you can include a ``requirements.txt`` file in the same directory as your training script to install other dependencies at runtime. -Both ``requirements.txt`` and your training script should be put in the same folder. -You must specify this folder in ``source_dir`` argument when creating an MXNet estimator. - -The function of installing packages using ``requirements.txt`` is supported for MXNet versions 1.3.0 and higher during training. - -When serving an MXNet model, support for this function varies with MXNet versions. -For MXNet 1.6.0 or newer, ``requirements.txt`` must be under folder ``code``. -The SageMaker MXNet Estimator automatically saves ``code`` in ``model.tar.gz`` after training (assuming you set up your script and ``requirements.txt`` correctly as stipulated in the previous paragraph). -In the case of bringing your own trained model for deployment, you must save ``requirements.txt`` under folder ``code`` in ``model.tar.gz`` yourself or specify it through ``dependencies``. -For MXNet 0.12.1-1.2.1, 1.4.0-1.4.1, ``requirements.txt`` is not supported for inference. -For MXNet 1.3.0, ``requirements.txt`` must be in ``source_dir``. - -A ``requirements.txt`` file is a text file that contains a list of items that are installed by using ``pip install``. -You can also specify the version of an item to install. -For information about the format of a ``requirements.txt`` file, see `Requirements Files `__ in the pip documentation. - -Create an Estimator -=================== - -You run MXNet training scripts on Amazon SageMaker by creating an ``MXNet`` estimator. -When you call ``fit`` on an ``MXNet`` estimator, Amazon SageMaker starts a training job using your script as training code. -The following code sample shows how you train a custom MXNet script "train.py". - -.. code:: python - - mxnet_estimator = MXNet('train.py', - instance_type='ml.p2.xlarge', - instance_count=1, - framework_version='1.6.0', - py_version='py3', - hyperparameters={'batch-size': 100, - 'epochs': 10, - 'learning-rate': 0.1}) - mxnet_estimator.fit('s3://my_bucket/my_training_data/') - -For more information about the sagemaker.mxnet.MXNet estimator, see `SageMaker MXNet Classes`_. - - -Distributed training -==================== - -If you want to use parameter servers for distributed training, set the following parameter in your ``MXNet`` constructor: - -.. code:: python - - distribution={'parameter_server': {'enabled': True}} - -Then, when writing a distributed training script, use an MXNet kvstore to store and share model parameters. -During training, Amazon SageMaker automatically starts an MXNet kvstore server and scheduler processes on hosts in your training job cluster. -Your script runs as an MXNet worker task, with one server process on each host in your cluster. -One host is selected arbitrarily to run the scheduler process. - -To learn more about writing distributed MXNet programs, please see `Distributed Training `__ in the MXNet docs. - - -Call the fit Method -=================== - -Start your training script by calling ``fit`` on an ``MXNet`` Estimator. -``fit`` takes both required and optional arguments. -For what arguments can be passed into ``fit``, see the `API reference `_. - -******************* -Deploy MXNet models -******************* - -Once you have a trained MXNet model, you can host it in Amazon SageMaker by creating an Amazon SageMaker Endpoint. -The endpoint runs a SageMaker-provided MXNet model server and hosts the model produced by your training script. -This model can be one you trained in Amazon SageMaker or a pretrained one from somewhere else. - -If you use the ``MXNet`` estimator to train the model, you can call ``deploy`` to create an Amazon SageMaker Endpoint: - -.. code:: python - - # Train my estimator - mxnet_estimator = MXNet('train.py', - framework_version='1.6.0', - py_version='py3', - instance_type='ml.p2.xlarge', - instance_count=1) - mxnet_estimator.fit('s3://my_bucket/my_training_data/') - - # Deploy my estimator to an Amazon SageMaker Endpoint and get a Predictor - predictor = mxnet_estimator.deploy(instance_type='ml.m4.xlarge', - initial_instance_count=1) - -If using a pretrained model, create an ``MXNetModel`` object, and then call ``deploy`` to create the Amazon SageMaker Endpoint: - -.. code:: python - - mxnet_model = MXNetModel(model_data='s3://my_bucket/pretrained_model/model.tar.gz', - role=role, - entry_point='inference.py', - framework_version='1.6.0', - py_version='py3') - predictor = mxnet_model.deploy(instance_type='ml.m4.xlarge', - initial_instance_count=1) - -In both cases, ``deploy`` returns a ``Predictor`` object, which you can use to do inference on the endpoint hosting your MXNet model. - -Each ``Predictor`` provides a ``predict`` method, which can do inference with numpy arrays or Python lists. -Inference arrays or lists are serialized and sent to the MXNet model server by an ``InvokeEndpoint`` SageMaker operation. -``predict`` returns the result of inference against your model. -By default, the inference result is either a Python list or dictionary. - -Elastic Inference -================= - -MXNet on Amazon SageMaker has support for `Elastic Inference `_, which allows for inference acceleration to a hosted endpoint for a fraction of the cost of using a full GPU instance. -In order to attach an Elastic Inference accelerator to your endpoint provide the accelerator type to ``accelerator_type`` to your ``deploy`` call. - -.. code:: python - - predictor = mxnet_estimator.deploy(instance_type='ml.m4.xlarge', - initial_instance_count=1, - accelerator_type='ml.eia1.medium') - -Model Directory Structure -========================= - -In general, if you use the same version of MXNet for both training and inference with the SageMaker Python SDK, -the SDK should take care of ensuring that the contents of your ``model.tar.gz`` file are organized correctly. - -For versions 1.4 and higher ---------------------------- - -For MXNet versions 1.4 and higher, the contents of ``model.tar.gz`` should be organized as follows: - -- Model files in the top-level directory -- Inference script (and any other source files) in a directory named ``code/`` (for more about the inference script, see `The SageMaker MXNet Model Server <#the-sagemaker-mxnet-model-server>`_) -- Optional requirements file located at ``code/requirements.txt`` (for more about requirements files, see `Use third-party libraries <#use-third-party-libraries>`_) - -For example: - -.. code:: - - model.tar.gz/ - |- model-symbol.json - |- model-shapes.json - |- model-0000.params - |- code/ - |- inference.py - |- requirements.txt # only for versions 1.6.0 and higher - -In this example, ``model-symbol.json``, ``model-shapes.json``, and ``model-0000.params`` are the model files saved from training, -``inference.py`` is the inference script, and ``requirements.txt`` is a requirements file. - -The ``MXNet`` and ``MXNetModel`` classes repack ``model.tar.gz`` to include the inference script (and related files), -as long as the ``framework_version`` is set to 1.4 or higher. - -For versions 1.3 and lower --------------------------- - -For MXNet versions 1.3 and lower, ``model.tar.gz`` should contain only the model files, -while your inference script and optional requirements file are packed in a separate tarball, named ``sourcedir.tar.gz`` by default. - -For example: - -.. code:: - - model.tar.gz/ - |- model-symbol.json - |- model-shapes.json - |- model-0000.params - - sourcedir.tar.gz/ - |- script.py - |- requirements.txt # only for versions 0.12.1-1.3.0 - -In this example, ``model-symbol.json``, ``model-shapes.json``, and ``model-0000.params`` are the model files saved from training, -``script.py`` is the inference script, and ``requirements.txt`` is a requirements file. - -The SageMaker MXNet Model Server -================================ - -The MXNet endpoint you create with ``deploy`` runs a SageMaker MXNet model server. -The model server loads the model provided and performs inference on the model in response to SageMaker ``InvokeEndpoint`` API calls. - -You can configure two components of the model server: model loading and model serving. -Model loading is the process of deserializing your saved model back into an MXNet model. -Serving is the process of translating ``InvokeEndpoint`` requests to inference calls on the loaded model. -These are configured by defining functions in the Python source file you pass to the ``MXNet`` or ``MXNetModel`` constructor. - -Load a Model ------------- - -Before a model can be served, it must be loaded. -The model server loads your model by invoking the ``model_fn`` function in your inference script. -If you don't provide a ``model_fn`` function, the model server uses a default ``model_fn`` function. -The default function works with MXNet Module model objects saved via the default ``save`` function. - -If you wrote your own save logic, then you may need to write a custom ``model_fn`` function. -The ``model_fn`` function must have the following signature: - -.. code:: python - - def model_fn(model_dir) - -Amazon SageMaker injects the directory where your model files and sub-directories have been mounted. -Your model function should return a model object that can be used for model serving. - -The following code snippet shows an example custom ``model_fn`` implementation. -This returns an MXNet Gluon net model for resnet-34 inference. -It loads the model parameters from a ``model.params`` file in the SageMaker model directory. - -.. code:: python - - def model_fn(model_dir): - """Load the Gluon model. Called when the hosting service starts. - - Args: - model_dir (str): The directory where model files are stored. - - Returns: - mxnet.gluon.nn.Block: a Gluon network (for this example) - """ - net = models.get_model('resnet34_v2', ctx=mx.cpu(), pretrained=False, classes=10) - net.load_params('%s/model.params' % model_dir, ctx=mx.cpu()) - return net - -MXNet on Amazon SageMaker has support for `Elastic Inference `__, which allows for inference acceleration to a hosted endpoint for a fraction of the cost of using a full GPU instance. -In order to load and serve your MXNet model through Amazon Elastic Inference, import the ``eimx`` Python package and make one change in the code to partition your model and optimize it for the ``EIA`` back end, as shown `here `__. - -Based on the example above, the following code-snippet shows an example custom ``model_fn`` implementation, which enables loading and serving our MXNet model through Amazon Elastic Inference. - -.. code:: python - - def model_fn(model_dir): - """Load the Gluon model. Called when the hosting service starts. - - Args: - model_dir (str): The directory where model files are stored. - - Returns: - mxnet.gluon.nn.Block: a Gluon network (for this example) - """ - net = models.get_model('resnet34_v2', ctx=mx.cpu(), pretrained=False, classes=10) - net.load_params('%s/model.params' % model_dir, ctx=mx.cpu()) - net.hybridize(backend='EIA', static_alloc=True, static_shape=True) - return net - -If you are using MXNet 1.5.1 and earlier, the `default_model_fn `__ loads and serve your model through Elastic Inference, if applicable, within the Amazon SageMaker MXNet containers. - -For more information on how to enable MXNet to interact with Amazon Elastic Inference, see `Use Elastic Inference with MXNet `__. - -Serve an MXNet Model --------------------- - -After the MXNet model server loads your model by calling either the default ``model_fn`` or the implementation in your script, it serves your model. -Model serving is the process of responding to inference requests received by SageMaker ``InvokeEndpoint`` API calls. -Defining how to handle these requests can be done in one of two ways: - -- using ``input_fn``, ``predict_fn``, and ``output_fn``, some of which may be your own implementations -- writing your own ``transform_fn`` for handling input processing, prediction, and output processing - -Use ``input_fn``, ``predict_fn``, and ``output_fn`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The SageMaker MXNet model server breaks request handling into three steps: - -- input processing -- prediction -- output processing - -Just like with ``model_fn``, you configure these steps by defining functions in your Python source file. - -Each step has its own Python function, which takes in information about the request and the return value from the previous function in the chain. -Inside the MXNet model server, the process looks like: - -.. code:: python - - # Deserialize the Invoke request body into an object we can perform prediction on - input_object = input_fn(request_body, request_content_type) - - # Perform prediction on the deserialized object, with the loaded model - prediction = predict_fn(input_object, model) - - # Serialize the prediction result into the desired response content type - ouput = output_fn(prediction, response_content_type) - -The above code sample shows the three function definitions that correlate to the three steps mentioned above: - -- ``input_fn``: Takes request data and deserializes the data into an - object for prediction. -- ``predict_fn``: Takes the deserialized request object and performs - inference against the loaded model. -- ``output_fn``: Takes the result of prediction and serializes this - according to the response content type. - -The MXNet model server provides default implementations of these functions. -These work with both Gluon API and Module API model objects. -The following content types are supported: - -- Gluon API: 'application/json', 'application/x-npy' -- Module API: 'application/json', 'application/x-npy', 'text-csv' - -You can also provide your own implementations for these functions in your training script. -If you omit any definition, the MXNet model server uses its default implementation for that function. - -If you rely solely on the SageMaker MXNet model server defaults, you get the following functionality: - -- Prediction on MXNet Gluon API ``net`` and Module API ``Module`` objects. -- Deserialization from CSV and JSON to NDArrayIters. -- Serialization of NDArrayIters to CSV or JSON. - -In the following sections, we describe the default implementations of ``input_fn``, ``predict_fn``, and ``output_fn``. -We describe the input arguments and expected return types of each, so you can define your own implementations. - -Process Model Input -~~~~~~~~~~~~~~~~~~~ - -When an ``InvokeEndpoint`` operation is made against an endpoint running an MXNet model server, the model server receives two pieces of information: - -- The request's content type, e.g. 'application/json' -- The request data body as a byte array - -The MXNet model server invokes ``input_fn``, passing in this information. -If you define an ``input_fn`` function definition, it should return an object that can be passed to ``predict_fn`` and have the following signature: - -.. code:: python - - def input_fn(request_body, request_content_type) - -Where ``request_body`` is a byte buffer and ``request_content_type`` is the content type of the request. - -The MXNet model server provides a default implementation of ``input_fn``. This function deserializes JSON or CSV encoded data into an MXNet ``NDArrayIter`` `(external API docs) `__ multi-dimensional array iterator. This works with the default ``predict_fn`` implementation, which expects an ``NDArrayIter`` as input. - -Default JSON deserialization requires ``request_body`` contain a single JSON list. Sending multiple JSON objects within the same ``request_body`` is not supported. The list must have a dimensionality compatible with the MXNet ``net`` or ``Module`` object. Specifically, after the list is loaded, it's either padded or split to fit the first dimension of the model input shape. The list's shape must be identical to the model's input shape, for all dimensions after the first. - -Default CSV deserialization requires ``request_body`` contain one or more lines of CSV numerical data. The data is loaded into a two-dimensional array, where each line break defines the boundaries of the first dimension. This two-dimensional array is then re-shaped to be compatible with the shape expected by the model object. Specifically, the first dimension is kept unchanged, but the second dimension is reshaped to be consistent with the shape of all dimensions in the model, following the first dimension. - -If you provide your own implementation of input_fn, you should abide by the ``input_fn`` signature. If you want to use this with the default -``predict_fn``, then you should return an ``NDArrayIter``. The ``NDArrayIter`` should have a shape identical to the shape of the model being predicted on. The example below shows a custom ``input_fn`` for preparing pickled numpy arrays. - -.. code:: python - - import numpy as np - import mxnet as mx - - def input_fn(request_body, request_content_type): - """An input_fn that loads a pickled numpy array""" - if request_content_type == 'application/python-pickle': - array = np.load(StringIO(request_body)) - array.reshape(model.data_shapes[0]) - return mx.io.NDArrayIter(mx.ndarray(array)) - else: - # Handle other content-types here or raise an Exception - # if the content type is not supported. - pass - -Predict from a Deployed Model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -After the inference request has been deserialized by ``input_fn``, the MXNet model server invokes ``predict_fn``. -As with the other functions, you can define your own ``predict_fn`` or use the model server's default. - -The ``predict_fn`` function has the following signature: - -.. code:: python - - def predict_fn(input_object, model) - -Where ``input_object`` is the object returned from ``input_fn`` and -``model`` is the model loaded by ``model_fn``. - -The default implementation of ``predict_fn`` requires ``input_object`` be an ``NDArrayIter``, which is the return-type of the default -``input_fn``. It also requires that ``model`` be either an MXNet Gluon API ``net`` object or a Module API ``Module`` object. - -The default implementation performs inference with the input -``NDArrayIter`` on the Gluon or Module object. If the model is a Gluon -``net`` it performs: ``net.forward(input_object)``. If the model is a Module object it performs ``module.predict(input_object)``. In both cases, it returns the result of that call. - -If you implement your own prediction function, you should take care to ensure that: - -- The first argument is expected to be the return value from input_fn. - If you use the default input_fn, this is an ``NDArrayIter``. -- The second argument is the loaded model. If you use the default - ``model_fn`` implementation, this is an MXNet Module object. - Otherwise, it is the return value of your ``model_fn`` implementation. -- The return value should be of the correct type to be passed as the - first argument to ``output_fn``. If you use the default - ``output_fn``, this should be an ``NDArrayIter``. - -Process Model Output -~~~~~~~~~~~~~~~~~~~~ - -After invoking ``predict_fn``, the model server invokes ``output_fn``, passing in the return value from ``predict_fn`` and the ``InvokeEndpoint`` requested response content type. - -The ``output_fn`` has the following signature: - -.. code:: python - - def output_fn(prediction, content_type) - -Where ``prediction`` is the result of invoking ``predict_fn`` and ``content_type`` is the requested response content type for ``InvokeEndpoint``. -The function should return an array of bytes serialized to the expected content type. - -The default implementation expects ``prediction`` to be an ``NDArray`` and can serialize the result to either JSON or CSV. It accepts response content types of "application/json" and "text/csv". - -Use ``transform_fn`` -^^^^^^^^^^^^^^^^^^^^ - -If you would rather not structure your code around the three methods described above, you can instead define your own ``transform_fn`` to handle inference requests. -An error is thrown if a ``transform_fn`` is present in conjunction with any ``input_fn``, ``predict_fn``, and/or ``output_fn``. -``transform_fn`` has the following signature: - -.. code:: python - - def transform_fn(model, request_body, content_type, accept_type) - -Where ``model`` is the model objected loaded by ``model_fn``, ``request_body`` is the data from the inference request, ``content_type`` is the content type of the request, and ``accept_type`` is the request content type for the response. - -This one function should handle processing the input, performing a prediction, and processing the output. -The return object should be one of the following: - -For versions 1.4 and higher: - -- a tuple with two items: the response data and ``accept_type`` (the content type of the response data), or -- the response data: (the content type of the response is set to either the accept header in the initial request or default to "application/json") - -For versions 1.3 and lower: - -- a tuple with two items: the response data and ``accept_type`` (the content type of the response data), or -- a Flask response object: http://flask.pocoo.org/docs/1.0/api/#response-objects - -For an example inference script using this structure, see the `mxnet_gluon_sentiment `__ notebook. - -*********************************************** -Work with Existing Model Data and Training Jobs -*********************************************** - -Attach to Existing Training Jobs -================================ - -You can attach an MXNet Estimator to an existing training job using the -``attach`` method. - -.. code:: python - - my_training_job_name = 'MyAwesomeMXNetTrainingJob' - mxnet_estimator = MXNet.attach(my_training_job_name) - -After attaching, if the training job's status is "Complete", it can be ``deploy``\ ed to create an Amazon SageMaker Endpoint and return a ``Predictor``. -If the training job is in progress, ``attach`` blocks and displays log messages from the training job until the training job completes. - -For information about arguments that ``attach`` accepts, see `the function's API reference `_. - -Deploy Endpoints from Model Data -================================ - -As well as attaching to existing training jobs, you can deploy models directly from model data in Amazon S3. The following code sample shows how to do this, using the ``MXNetModel`` class. - -.. code:: python - - mxnet_model = MXNetModel(model_data='s3://bucket/model.tar.gz', role='SageMakerRole', entry_point='trasform_script.py') - - predictor = mxnet_model.deploy(instance_type='ml.c4.xlarge', initial_instance_count=1) - -For information about arguments that the ``MXNetModel`` constructor accepts, see `the class's API reference `_. - -Your model data must be a .tar.gz file in Amazon S3. Amazon SageMaker Training Job model data is saved to .tar.gz files in Amazon S3, however if you have local data you want to deploy, you can prepare the data yourself. - -Assuming you have a local directory containing your model data named "my_model" you can tar and gzip compress the file and upload to Amazon S3 using the following commands: - -:: - - tar -czf model.tar.gz my_model - aws s3 cp model.tar.gz s3://my-bucket/my-path/model.tar.gz - -This uploads the contents of my_model to a gzip-compressed tar file to Amazon S3 in the bucket "my-bucket", with the key "my-path/model.tar.gz". - -To run this command, you need the AWS CLI tool installed. Please refer to our `FAQ <#FAQ>`__ for more information on installing this. - -******** -Examples -******** - -Amazon provides several example Jupyter notebooks that demonstrate end-to-end training on Amazon SageMaker using MXNet. Please refer to: - -https://github.com/awslabs/amazon-sagemaker-examples/tree/master/sagemaker-python-sdk - -These are also available in Amazon SageMaker Notebook Instance hosted Jupyter notebooks under the "sample notebooks" folder. - -*********************** -SageMaker MXNet Classes -*********************** - -For information about the different MXNet-related classes in the SageMaker Python SDK, see https://sagemaker.readthedocs.io/en/stable/sagemaker.mxnet.html. - -************************** -SageMaker MXNet Containers -************************** - -For information about the SageMaker MXNet containers, see: - -- `SageMaker MXNet training toolkit `_ -- `SageMaker MXNet serving toolkit `_ -- `Deep Learning Container (DLC) Dockerfiles for MXNet `_ -- `Deep Learning Container (DLC) Images `_ and `release notes `_ diff --git a/doc/frameworks/pytorch/index.rst b/doc/frameworks/pytorch/index.rst deleted file mode 100644 index aa6c69baa2..0000000000 --- a/doc/frameworks/pytorch/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -########################## -PyTorch -########################## - -.. toctree:: - :maxdepth: 1 - :glob: - - * diff --git a/doc/frameworks/pytorch/sagemaker.pytorch.rst b/doc/frameworks/pytorch/sagemaker.pytorch.rst deleted file mode 100644 index c7fcde6f93..0000000000 --- a/doc/frameworks/pytorch/sagemaker.pytorch.rst +++ /dev/null @@ -1,34 +0,0 @@ -PyTorch -======= - -PyTorch Estimator ------------------ - -.. autoclass:: sagemaker.pytorch.estimator.PyTorch - :members: - :undoc-members: - :show-inheritance: - -PyTorch Model -------------- - -.. autoclass:: sagemaker.pytorch.model.PyTorchModel - :members: - :undoc-members: - :show-inheritance: - -PyTorch Predictor ------------------ - -.. autoclass:: sagemaker.pytorch.model.PyTorchPredictor - :members: - :undoc-members: - :show-inheritance: - -PyTorch Processor ------------------ - -.. autoclass:: sagemaker.pytorch.processing.PyTorchProcessor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/frameworks/pytorch/using_pytorch.rst b/doc/frameworks/pytorch/using_pytorch.rst deleted file mode 100644 index d415f38c27..0000000000 --- a/doc/frameworks/pytorch/using_pytorch.rst +++ /dev/null @@ -1,1118 +0,0 @@ -######################################### -Use PyTorch with the SageMaker Python SDK -######################################### - -With PyTorch Estimators and Models, you can train and host PyTorch models on Amazon SageMaker. - -For information about supported versions of PyTorch, see the `AWS documentation `__. - -We recommend that you use the latest supported version because that's where we focus our development efforts. - -You can visit the PyTorch repository at https://github.com/pytorch/pytorch. - -.. contents:: - -************************** -Train a Model with PyTorch -************************** - -To train a PyTorch model by using the SageMaker Python SDK: - -.. |create pytorch estimator| replace:: Create a ``sagemaker.pytorch.PyTorch`` Estimator -.. _create pytorch estimator: #create-an-estimator - -1. `Prepare a training script <#prepare-a-pytorch-training-script>`_ OR `Choose an Amazon SageMaker HyperPod recipe`_ -2. |create pytorch estimator|_ -3. `Call the estimator's fit method or ModelTrainer's train method`_ - -Prepare a PyTorch Training Script -================================= - -Your PyTorch training script must be a Python 3.6 compatible source file. - -Prepare your script in a separate source file than the notebook, terminal session, or source file you're -using to submit the script to SageMaker via a ``PyTorch`` Estimator. This will be discussed in further detail below. - -The training script is very similar to a training script you might run outside of SageMaker, but you -can access useful properties about the training environment through various environment variables. -For example: - -* ``SM_NUM_GPUS``: An integer representing the number of GPUs available to the host. -* ``SM_MODEL_DIR``: A string representing the path to the directory to write model artifacts to. - These artifacts are uploaded to S3 for model hosting. -* ``SM_OUTPUT_DATA_DIR``: A string representing the filesystem path to write output artifacts to. Output artifacts may - include checkpoints, graphs, and other files to save, not including model artifacts. These artifacts are compressed - and uploaded to S3 to the same S3 prefix as the model artifacts. -* ``SM_CHANNEL_XXXX``: A string that represents the path to the directory that contains the input data for the specified channel. - For example, if you specify two input channels in the PyTorch estimator's ``fit`` call, named 'train' and 'test', - the environment variables ``SM_CHANNEL_TRAIN`` and ``SM_CHANNEL_TEST`` are set. - -A typical training script loads data from the input channels, configures training with hyperparameters, trains a model, -and saves a model to ``model_dir`` so that it can be hosted later. Hyperparameters are passed to your script as arguments -and can be retrieved with an argparse.ArgumentParser instance. For example, a training script might start -with the following: - -.. code:: python - - import argparse - import os - - if __name__ =='__main__': - - parser = argparse.ArgumentParser() - - # hyperparameters sent by the client are passed as command-line arguments to the script. - parser.add_argument('--epochs', type=int, default=50) - parser.add_argument('--batch-size', type=int, default=64) - parser.add_argument('--learning-rate', type=float, default=0.05) - parser.add_argument('--use-cuda', type=bool, default=False) - - # Data, model, and output directories - parser.add_argument('--output-data-dir', type=str, default=os.environ['SM_OUTPUT_DATA_DIR']) - parser.add_argument('--model-dir', type=str, default=os.environ['SM_MODEL_DIR']) - parser.add_argument('--train', type=str, default=os.environ['SM_CHANNEL_TRAIN']) - parser.add_argument('--test', type=str, default=os.environ['SM_CHANNEL_TEST']) - - args, _ = parser.parse_known_args() - - # ... load from args.train and args.test, train a model, write model to args.model_dir. - -Because SageMaker imports your training script, you should put your training code in a main guard -(``if __name__=='__main__':``) if you are using the same script to host your model, so that SageMaker does not -inadvertently run your training code at the wrong point in execution. - -Note that SageMaker doesn't support argparse actions. If you want to use, for example, boolean hyperparameters, -you need to specify `type` as `bool` in your script and provide an explicit `True` or `False` value for this hyperparameter -when instantiating PyTorch Estimator. - -For more on training environment variables, see the `SageMaker Training Toolkit `_. - -Save the Model --------------- - -In order to save your trained PyTorch model for deployment on SageMaker, your training script should save your model -to a certain filesystem path called ``model_dir``. This value is accessible through the environment variable -``SM_MODEL_DIR``. The following code demonstrates how to save a trained PyTorch model named ``model`` as -``model.pth`` at the : - -.. code:: python - - import argparse - import os - import torch - - if __name__=='__main__': - # default to the value in environment variable `SM_MODEL_DIR`. Using args makes the script more portable. - parser.add_argument('--model-dir', type=str, default=os.environ['SM_MODEL_DIR']) - args, _ = parser.parse_known_args() - - # ... train `model`, then save it to `model_dir` - with open(os.path.join(args.model_dir, 'model.pth'), 'wb') as f: - torch.save(model.state_dict(), f) - -After your training job is complete, SageMaker compresses and uploads the serialized model to S3, and your model data -will be available in the S3 ``output_path`` you specified when you created the PyTorch Estimator. - -If you are using Elastic Inference, you must convert your models to the TorchScript format and use ``torch.jit.save`` to save the model. -For example: - -.. code:: python - - import os - import torch - - # ... train `model`, then save it to `model_dir` - model_dir = os.path.join(model_dir, "model.pt") - torch.jit.save(model, model_dir) - -Using third-party libraries ---------------------------- - -When running your training script on SageMaker, it will have access to some pre-installed third-party libraries including ``torch``, ``torchvision``, and ``numpy``. - -If there are other packages you want to use with your script, you can include a ``requirements.txt`` file in the same directory as your training script to install other dependencies at runtime. Both ``requirements.txt`` and your training script should be put in the same folder. You must specify this folder in ``source_dir`` argument when creating PyTorch estimator. - -The function of installing packages using ``requirements.txt`` is supported for all PyTorch versions during training. When serving a PyTorch model, support for this function varies with PyTorch versions. For PyTorch 1.3.1 or newer, ``requirements.txt`` must be under folder ``code``. The SageMaker PyTorch Estimator will automatically save ``code`` in ``model.tar.gz`` after training (assuming you set up your script and ``requirements.txt`` correctly as stipulated in the previous paragraph). In the case of bringing your own trained model for deployment, you must save ``requirements.txt`` under folder ``code`` in ``model.tar.gz`` yourself or specify it through ``dependencies``. For PyTorch 1.2.0, ``requirements.txt`` is not supported for inference. For PyTorch 0.4.0 to 1.1.0, ``requirements.txt`` must be in ``source_dir``. - -A ``requirements.txt`` file is a text file that contains a list of items that are installed by using ``pip install``. You can also specify the version of an item to install. For information about the format of a ``requirements.txt`` file, see `Requirements Files `__ in the pip documentation. - -If you were to use your own custom Docker Image, the `SageMaker Python SDK` and the `SageMaker Training Toolkit `__ need to be installed. - -To do so, you can add the following lines to your ``requirements.txt`` file: - -.. code:: text - - sagemaker - sagemaker-training - -Deep Learning Framework-Specific SageMaker Toolkits and Containers ------------------------------------------------------------------- - -Framework-specific Toolkits exist. You might want to use them in your applications for framework-specific features. - -For Training Toolkits, see: - -- `SageMaker PyTorch Training Toolkit `__ -- `SageMaker MXNet Training Toolkit `__ -- `SageMaker TensorFlow Training Toolkit `__ - -For Inference Toolkits, see: - -- `SageMaker PyTorch Inference Toolkit `__ -- `SageMaker MXNet Inference Toolkit `__ -- `SageMaker TensorFlow Inference Toolkit `__ -- `SageMaker HuggingFace Inference Toolkit `__ - -Moreover, for more information on the container runtime environment, including specific framework versions and configurations, -see `AWS Deep Learning Containers `_. More specifically, see: - -- `Images for PyTorch `__ -- `Images for MXNet `__ -- `Images for TensorFlow `__ -- `Images for HuggingFace `__ - - -Choose an Amazon Sagemaker HyperPod recipe -========================================== - -Alternatively, instead of using your own training script, you can choose an -`Amazon SageMaker HyperPod recipe `_ to launch training for a supported model. -If using a recipe, you do not need to provide your own training script. You only need to determine -which recipe you want to run. You can modify a recipe as explained in the next section. - - - -Create an Estimator -=================== - -You run PyTorch training scripts on SageMaker by creating ``PyTorch`` Estimators. -SageMaker training of your script is invoked when you call ``fit`` on a ``PyTorch`` Estimator. -The following code sample shows how you train a custom PyTorch script "pytorch-train.py", passing -in three hyperparameters ('epochs', 'batch-size', and 'learning-rate'), and using two input channel -directories ('train' and 'test'). - -.. code:: python - - pytorch_estimator = PyTorch('pytorch-train.py', - instance_type='ml.p3.2xlarge', - instance_count=1, - framework_version='1.8.0', - py_version='py3', - hyperparameters = {'epochs': 20, 'batch-size': 64, 'learning-rate': 0.1}) - pytorch_estimator.fit({'train': 's3://my-data-bucket/path/to/my/training/data', - 'test': 's3://my-data-bucket/path/to/my/test/data'}) - - -Amazon Sagemaker HyperPod recipes ---------------------------------- -Alternatively, if you are using Amazon SageMaker HyperPod recipes, you can follow the following instructions: - -Prerequisites: you need ``git`` installed on your client to access Amazon SageMaker HyperPod recipes code. - -When using a recipe, you must set the ``training_recipe`` arg in place of providing a training script. -This can be a recipe from `here `_ -or a local file or a custom url. Please note that you must override the following using -``recipe_overrides``: - -* directory paths for the local container in the recipe as appropriate for Python SDK -* the output s3 URIs -* Huggingface access token -* any other recipe fields you wish to edit - -The code snippet below shows an example. -Please refer to `SageMaker docs `_ -for more details about the expected local paths in the container and the Amazon SageMaker -HyperPod recipes tutorial for more examples. -You can override the fields by either setting ``recipe_overrides`` or -providing a modified ``training_recipe`` through a local file or a custom url. -When using the recipe, any provided ``entry_point`` will be ignored. - -SageMaker will automatically set up the distribution args. -It will also determine the image to use for your model and device type, -but you can override this with the ``image_uri`` arg. - -You can also override the number of nodes in the recipe with the ``instance_count`` arg to estimator. -``source_dir`` will default to current working directory unless specified. -A local copy of training scripts and recipe will be saved in the ``source_dir``. -You can specify any additional packages you want to install for training in an optional ``requirements.txt`` in the ``source_dir``. - -Note for llama3.2 multi-modal models, you need to upgrade transformers library by providing a ``requirements.txt`` in the source file with ``transformers==4.45.2``. -Please refer to the Amazon SageMaker HyperPod recipes documentation for more details. - - -Here is an example usage for recipe ``hf_llama3_8b_seq8k_gpu_p5x16_pretrain``. - - -.. code:: python - - overrides = { - "run": { - "results_dir": "/opt/ml/model", - }, - "exp_manager": { - "exp_dir": "", - "explicit_log_dir": "/opt/ml/output/tensorboard", - "checkpoint_dir": "/opt/ml/checkpoints", - }, - "model": { - "data": { - "train_dir": "/opt/ml/input/data/train", - "val_dir": "/opt/ml/input/data/val", - }, - }, - } - pytorch_estimator = PyTorch( - output_path=output_path, - base_job_name=f"llama-recipe", - role=role, - instance_type="ml.p5.48xlarge", - training_recipe="hf_llama3_8b_seq8k_gpu_p5x16_pretrain", - recipe_overrides=recipe_overrides, - sagemaker_session=sagemaker_session, - tensorboard_output_config=tensorboard_output_config, - ) - pytorch_estimator.fit({'train': 's3://my-data-bucket/path/to/my/training/data', - 'test': 's3://my-data-bucket/path/to/my/test/data'}) - - # Or alternatively with ModelTrainer - recipe_overrides = { - "run": { - "results_dir": "/opt/ml/model", - }, - "exp_manager": { - "exp_dir": "", - "explicit_log_dir": "/opt/ml/output/tensorboard", - "checkpoint_dir": "/opt/ml/checkpoints", - }, - "model": { - "data": { - "train_dir": "/opt/ml/input/data/train", - "val_dir": "/opt/ml/input/data/val", - }, - }, - } - - model_trainer = ModelTrainer.from_recipe( - output_path=output_path, - base_job_name=f"llama-recipe", - training_recipe="training/llama/hf_llama3_8b_seq8k_gpu_p5x16_pretrain", - recipe_overrides=recipe_overrides, - compute=Compute(instance_type="ml.p5.48xlarge"), - sagemaker_session=sagemaker_session - ).with_tensorboard_output_config( - tensorboard_output_config=tensorboard_output_config - ) - - train_input = Input( - channel_name="train", - data_source="s3://my-data-bucket/path/to/my/training/data" - ) - - test_input = Input( - channel_name="test", - data_source="s3://my-data-bucket/path/to/my/test/data" - ) - - model_trainer.train(input_data_config=[train_input, test_input) - - -Call the estimator's fit method or ModelTrainer's train method -============================================================== - -You start your training script by calling ``fit`` on a ``PyTorch`` Estimator. ``fit`` takes both required and optional -arguments. - -fit Required Arguments ----------------------- - -- ``inputs``: This can take one of the following forms: A string - S3 URI, for example ``s3://my-bucket/my-training-data``. In this - case, the S3 objects rooted at the ``my-training-data`` prefix will - be available in the default ``train`` channel. A dict from - string channel names to S3 URIs. In this case, the objects rooted at - each S3 prefix will be available as files in each channel directory. - -For example: - -.. code:: python - - {'train':'s3://my-bucket/my-training-data', - 'eval':'s3://my-bucket/my-evaluation-data'} - -.. optional-arguments-1: - -fit Optional Arguments ----------------------- - -- ``wait``: Defaults to True, whether to block and wait for the - training script to complete before returning. -- ``logs``: Defaults to True, whether to show logs produced by training - job in the Python session. Only meaningful when wait is True. - ----- - -Distributed PyTorch Training -============================ - -SageMaker supports the `PyTorch DistributedDataParallel (DDP) -`_ -package. You simply need to check the variables in your training script, -such as the world size and the rank of the current host, when initializing -process groups for distributed training. -And then, launch the training job using the -:class:`sagemaker.pytorch.estimator.PyTorch` estimator class -with the ``pytorchddp`` option as the distribution strategy. - -.. note:: - - This PyTorch DDP support is available - in the SageMaker PyTorch Deep Learning Containers v1.12 and later. - -Adapt Your Training Script --------------------------- - -To initialize distributed training in your script, call -`torch.distributed.init_process_group -`_ -with the desired backend and the rank of the current host. - -.. code:: python - - import torch.distributed as dist - - if args.distributed: - # Initialize the distributed environment. - world_size = len(args.hosts) - os.environ['WORLD_SIZE'] = str(world_size) - host_rank = args.hosts.index(args.current_host) - dist.init_process_group(backend=args.backend, rank=host_rank) - -SageMaker sets ``'MASTER_ADDR'`` and ``'MASTER_PORT'`` environment variables for you, -but you can also overwrite them. - -**Supported backends:** - -- ``gloo`` and ``tcp`` for CPU instances -- ``gloo`` and ``nccl`` for GPU instances - -Launching a Distributed Training Job ------------------------------------- - -You can run multi-node distributed PyTorch training jobs using the -:class:`sagemaker.pytorch.estimator.PyTorch` estimator class. -With ``instance_count=1``, the estimator submits a -single-node training job to SageMaker; with ``instance_count`` greater -than one, a multi-node training job is launched. - -To run a distributed training script that adopts -the `PyTorch DistributedDataParallel (DDP) package -`_, -choose the ``pytorchddp`` as the distributed training option in the ``PyTorch`` estimator. - -With the ``pytorchddp`` option, the SageMaker PyTorch estimator runs a SageMaker -training container for PyTorch, sets up the environment for MPI, and launches -the training job using the ``mpirun`` command on each worker with the given information -during the PyTorch DDP initialization. - -.. note:: - - The SageMaker PyTorch estimator can operate both ``mpirun`` (for PyTorch 1.12.0 and later) - and ``torchrun`` (for PyTorch 1.13.1 and later) in the backend for distributed training. - -For more information about setting up PyTorch DDP in your training script, -see `Getting Started with Distributed Data Parallel -`_ in the -PyTorch documentation. - -The following examples show how to set a PyTorch estimator -to run a distributed training job on two ``ml.p4d.24xlarge`` instances. - -**Using PyTorch DDP with the mpirun backend** - -.. code:: python - - from sagemaker.pytorch import PyTorch - - pt_estimator = PyTorch( - entry_point="train_ptddp.py", - role="SageMakerRole", - framework_version="1.12.0", - py_version="py38", - instance_count=2, - instance_type="ml.p4d.24xlarge", - distribution={ - "pytorchddp": { - "enabled": True - } - } - ) - -**Using PyTorch DDP with the torchrun backend** - -.. code:: python - - from sagemaker.pytorch import PyTorch - - pt_estimator = PyTorch( - entry_point="train_ptddp.py", - role="SageMakerRole", - framework_version="1.13.1", - py_version="py38", - instance_count=2, - instance_type="ml.p4d.24xlarge", - distribution={ - "torch_distributed": { - "enabled": True - } - } - ) - - -.. note:: - - For more information about setting up ``torchrun`` in your training script, - see `torchrun (Elastic Launch) `_ in *the - PyTorch documentation*. - ----- - -.. _distributed-pytorch-training-on-trainium: - -Distributed Training with PyTorch Neuron on Trn1 instances -========================================================== - -SageMaker Training supports Amazon EC2 Trn1 instances powered by -`AWS Trainium `_ device, -the second generation purpose-built machine learning accelerator from AWS. -Each Trn1 instance consists of up to 16 Trainium devices, and each -Trainium device consists of two `NeuronCores -`_ -in the *AWS Neuron Documentation*. - -You can run distributed training job on Trn1 instances. -SageMaker supports the ``xla`` package through ``torchrun``. -With this, you do not need to manually pass ``RANK``, -``WORLD_SIZE``, ``MASTER_ADDR``, and ``MASTER_PORT``. -You can launch the training job using the -:class:`sagemaker.pytorch.estimator.PyTorch` estimator class -with the ``torch_distributed`` option as the distribution strategy. - -.. note:: - - This ``torch_distributed`` support is available - in the AWS Deep Learning Containers for PyTorch Neuron starting v1.11.0. - To find a complete list of supported versions of PyTorch Neuron, see - `Neuron Containers `_ - in the *AWS Deep Learning Containers GitHub repository*. - -.. note:: - - SageMaker Debugger is not compatible with Trn1 instances. - -Adapt Your Training Script to Initialize with the XLA backend -------------------------------------------------------------- - -To initialize distributed training in your script, call -`torch.distributed.init_process_group -`_ -with the ``xla`` backend as shown below. - -.. code:: python - - import torch.distributed as dist - - dist.init_process_group('xla') - -SageMaker takes care of ``'MASTER_ADDR'`` and ``'MASTER_PORT'`` for you via ``torchrun`` - -For detailed documentation about modifying your training script for Trainium, see `Multi-worker data-parallel MLP training using torchrun `_ in the *AWS Neuron Documentation*. - -**Currently Supported backends:** - -- ``xla`` for Trainium (Trn1) instances - -For up-to-date information on supported backends for Trn1 instances, see `AWS Neuron Documentation `_. - -Launching a Distributed Training Job on Trainium ------------------------------------------------- - -You can run multi-node distributed PyTorch training jobs on Trn1 instances using the -:class:`sagemaker.pytorch.estimator.PyTorch` estimator class. -With ``instance_count=1``, the estimator submits a -single-node training job to SageMaker; with ``instance_count`` greater -than one, a multi-node training job is launched. - -With the ``torch_distributed`` option, the SageMaker PyTorch estimator runs a SageMaker -training container for PyTorch Neuron, sets up the environment, and launches -the training job using the ``torchrun`` command on each worker with the given information. - -**Examples** - -The following examples show how to run a PyTorch training using ``torch_distributed`` in SageMaker -on one ``ml.trn1.2xlarge`` instance and two ``ml.trn1.32xlarge`` instances: - -.. code:: python - - from sagemaker.pytorch import PyTorch - - pt_estimator = PyTorch( - entry_point="train_torch_distributed.py", - role="SageMakerRole", - framework_version="1.11.0", - py_version="py38", - instance_count=1, - instance_type="ml.trn1.2xlarge", - distribution={ - "torch_distributed": { - "enabled": True - } - } - ) - - pt_estimator.fit("s3://bucket/path/to/training/data") - -.. code:: python - - from sagemaker.pytorch import PyTorch - - pt_estimator = PyTorch( - entry_point="train_torch_distributed.py", - role="SageMakerRole", - framework_version="1.11.0", - py_version="py38", - instance_count=2, - instance_type="ml.trn1.32xlarge", - distribution={ - "torch_distributed": { - "enabled": True - } - } - ) - - pt_estimator.fit("s3://bucket/path/to/training/data") - -********************* -Deploy PyTorch Models -********************* - -After a PyTorch Estimator has been fit, you can host the newly created model in SageMaker. - -After calling ``fit``, you can call ``deploy`` on a ``PyTorch`` Estimator to create a SageMaker Endpoint. -The Endpoint runs a SageMaker-provided PyTorch model server and hosts the model produced by your training script, -which was run when you called ``fit``. This was the model you saved to ``model_dir``. - -``deploy`` returns a ``Predictor`` object, which you can use to do inference on the Endpoint hosting your PyTorch model. -Each ``Predictor`` provides a ``predict`` method which can do inference with numpy arrays or Python lists. -Inference arrays or lists are serialized and sent to the PyTorch model server by an ``InvokeEndpoint`` SageMaker -operation. - -``predict`` returns the result of inference against your model. By default, the inference result a NumPy array. - -.. code:: python - - # Train my estimator - pytorch_estimator = PyTorch(entry_point='train_and_deploy.py', - instance_type='ml.p3.2xlarge', - instance_count=1, - framework_version='1.8.0', - py_version='py3') - pytorch_estimator.fit('s3://my_bucket/my_training_data/') - - # Deploy my estimator to a SageMaker Endpoint and get a Predictor - predictor = pytorch_estimator.deploy(instance_type='ml.m4.xlarge', - initial_instance_count=1) - - # `data` is a NumPy array or a Python list. - # `response` is a NumPy array. - response = predictor.predict(data) - -You use the SageMaker PyTorch model server to host your PyTorch model when you call ``deploy`` on an ``PyTorch`` -Estimator. The model server runs inside a SageMaker Endpoint, which your call to ``deploy`` creates. -You can access the name of the Endpoint by the ``name`` property on the returned ``Predictor``. - -Elastic Inference -================= - -PyTorch on Amazon SageMaker has support for `Elastic Inference `_, which allows for inference acceleration to a hosted endpoint for a fraction of the cost of using a full GPU instance. -In order to attach an Elastic Inference accelerator to your endpoint provide the accelerator type to ``accelerator_type`` to your ``deploy`` call. - -.. code:: python - - predictor = pytorch_estimator.deploy(instance_type='ml.m4.xlarge', - initial_instance_count=1, - accelerator_type='ml.eia2.medium') - -Model Directory Structure -========================= - -In general, if you use the same version of PyTorch for both training and inference with the SageMaker Python SDK, -the SDK should take care of ensuring that the contents of your ``model.tar.gz`` file are organized correctly. - -For versions 1.2 and higher ---------------------------- - -For PyTorch versions 1.2 and higher, the contents of ``model.tar.gz`` should be organized as follows: - -- Model files in the top-level directory -- Inference script (and any other source files) in a directory named ``code/`` (for more about the inference script, see `The SageMaker PyTorch Model Server <#the-sagemaker-pytorch-model-server>`_) -- Optional requirements file located at ``code/requirements.txt`` (for more about requirements files, see `Using third-party libraries <#using-third-party-libraries>`_) - -For example: - -.. code:: - - model.tar.gz/ - |- model.pth - |- code/ - |- inference.py - |- requirements.txt # only for versions 1.3.1 and higher - -In this example, ``model.pth`` is the model file saved from training, ``inference.py`` is the inference script, and ``requirements.txt`` is a requirements file. - -The ``PyTorch`` and ``PyTorchModel`` classes repack ``model.tar.gz`` to include the inference script (and related files), -as long as the ``framework_version`` is set to 1.2 or higher. - -For versions 1.1 and lower --------------------------- - -For PyTorch versions 1.1 and lower, ``model.tar.gz`` should contain only the model files, -while your inference script and optional requirements file are packed in a separate tarball, named ``sourcedir.tar.gz`` by default. - -For example: - -.. code:: - - model.tar.gz/ - |- model.pth - - sourcedir.tar.gz/ - |- script.py - |- requirements.txt - -In this example, ``model.pth`` is the model file saved from training, ``script.py`` is the inference script, and ``requirements.txt`` is a requirements file. - -The SageMaker PyTorch Model Server -================================== - -The PyTorch Endpoint you create with ``deploy`` runs a SageMaker PyTorch model server. -The model server loads the model that was saved by your training script and performs inference on the model in response -to SageMaker InvokeEndpoint API calls. - -You can configure two components of the SageMaker PyTorch model server: Model loading and model serving. -Model loading is the process of deserializing your saved model back into a PyTorch model. -Serving is the process of translating InvokeEndpoint requests to inference calls on the loaded model. - -You configure the PyTorch model server by defining functions in the Python source file you passed to the PyTorch constructor. - -Load a Model ------------- - -Before a model can be served, it must be loaded. The SageMaker PyTorch model server loads your model by invoking a -``model_fn`` function that you must provide in your script when you are not using Elastic Inference. The ``model_fn`` should have the following signature: - -.. code:: python - - def model_fn(model_dir, context) - -``context`` is an optional argument that contains additional serving information, such as the GPU ID and batch size. -If specified in the function declaration, the context will be created and passed to the function by SageMaker. -For more information about ``context``, see the `Serving Context class `_. - -SageMaker will inject the directory where your model files and sub-directories, saved by ``save``, have been mounted. -Your model function should return a model object that can be used for model serving. - -The following code-snippet shows an example ``model_fn`` implementation. -It loads the model parameters from a ``model.pth`` file in the SageMaker model directory ``model_dir``. As explained in the preceding example, -``context`` is an optional argument that passes additional information. - -.. code:: python - - import torch - import os - - def model_fn(model_dir, context): - model = Your_Model() - with open(os.path.join(model_dir, 'model.pth'), 'rb') as f: - model.load_state_dict(torch.load(f)) - return model - -However, if you are using PyTorch Elastic Inference 1.3.1, you do not have to provide a ``model_fn`` since the PyTorch serving -container has a default one for you. But please note that if you are utilizing the default ``model_fn``, please save -your ScriptModule as ``model.pt``. If you are implementing your own ``model_fn``, please use TorchScript and ``torch.jit.save`` -to save your ScriptModule, then load it in your ``model_fn`` with ``torch.jit.load(..., map_location=torch.device('cpu'))``. - -If you are using PyTorch Elastic Inference 1.5.1, you should provide ``model_fn`` like below in your script to use new api ``attach_eia``. Reference can be find in `Elastic Inference documentation `_. - - -.. code:: python - - import torch - - - def model_fn(model_dir): - model = torch.jit.load('model.pth', map_location=torch.device('cpu')) - if torch.__version__ == '1.5.1': - import torcheia - model = model.eval() - # attach_eia() is introduced in PyTorch Elastic Inference 1.5.1, - model = torcheia.jit.attach_eia(model, 0) - return model - - -The client-side Elastic Inference framework is CPU-only, even though inference still happens in a CUDA context on the server. Thus, the default ``model_fn`` for Elastic Inference loads the model to CPU. Tracing models may lead to tensor creation on a specific device, which may cause device-related errors when loading a model onto a different device. Providing an explicit ``map_location=torch.device('cpu')`` argument forces all tensors to CPU. - -For more information on the default inference handler functions, please refer to: -`SageMaker PyTorch Default Inference Handler `_. - -Serve a PyTorch Model ---------------------- - -After the SageMaker model server has loaded your model by calling ``model_fn``, SageMaker will serve your model. -Model serving is the process of responding to inference requests, received by SageMaker InvokeEndpoint API calls. -The SageMaker PyTorch model server breaks request handling into three steps: - - -- input processing, -- prediction, and -- output processing. - -In a similar way to model loading, you configure these steps by defining functions in your Python source file. - -Each step involves invoking a python function, with information about the request and the return value from the previous -function in the chain. Inside the SageMaker PyTorch model server, the process looks like: - -.. code:: python - - # Deserialize the Invoke request body into an object we can perform prediction on - input_object = input_fn(request_body, request_content_type, context) - - # Perform prediction on the deserialized object, with the loaded model - prediction = predict_fn(input_object, model, context) - - # Serialize the prediction result into the desired response content type - output = output_fn(prediction, response_content_type, context) - -The above code sample shows the three function definitions: - -- ``input_fn``: Takes request data and deserializes the data into an - object for prediction. -- ``predict_fn``: Takes the deserialized request object and performs - inference against the loaded model. -- ``output_fn``: Takes the result of prediction and serializes this - according to the response content type. - -The SageMaker PyTorch model server provides default implementations of these functions. -You can provide your own implementations for these functions in your hosting script. -If you omit any definition then the SageMaker PyTorch model server will use its default implementation for that -function. -If you use PyTorch Elastic Inference 1.5.1, remember to implement ``predict_fn`` yourself. - -The ``Predictor`` used by PyTorch in the SageMaker Python SDK serializes NumPy arrays to the `NPY `_ format -by default, with Content-Type ``application/x-npy``. The SageMaker PyTorch model server can deserialize NPY-formatted -data (along with JSON and CSV data). - -If you rely solely on the SageMaker PyTorch model server defaults, you get the following functionality: - -- Prediction on models that implement the ``__call__`` method -- Serialization and deserialization of torch.Tensor. - -The default ``input_fn`` and ``output_fn`` are meant to make it easy to predict on torch.Tensors. If your model expects -a torch.Tensor and returns a torch.Tensor, then these functions do not have to be overridden when sending NPY-formatted -data. - -In the following sections we describe the default implementations of input_fn, predict_fn, and output_fn. -We describe the input arguments and expected return types of each, so you can define your own implementations. - -Process Model Input -^^^^^^^^^^^^^^^^^^^ - -When an InvokeEndpoint operation is made against an Endpoint running a SageMaker PyTorch model server, -the model server receives two pieces of information: - -- The request Content-Type, for example "application/x-npy" -- The request data body, a byte array - -The SageMaker PyTorch model server will invoke an ``input_fn`` function in your hosting script, -passing in this information. If you define an ``input_fn`` function definition, -it should return an object that can be passed to ``predict_fn`` and have the following signature: - -.. code:: python - - def input_fn(request_body, request_content_type, context) - -Where ``request_body`` is a byte buffer and ``request_content_type`` is a Python string. - -``context`` is an optional argument that contains additional serving information, such as the GPU ID and batch size. -If specified in the function declaration, the context will be created and passed to the function by SageMaker. -For more information about ``context``, see the `Serving Context class `_. - -The SageMaker PyTorch model server provides a default implementation of ``input_fn``. -This function deserializes JSON, CSV, or NPY encoded data into a torch.Tensor. - -Default NPY deserialization requires ``request_body`` to follow the `NPY `_ format. For PyTorch, the Python SDK -defaults to sending prediction requests with this format. - -Default JSON deserialization requires ``request_body`` contain a single json list. -Sending multiple JSON objects within the same ``request_body`` is not supported. -The list must have a dimensionality compatible with the model loaded in ``model_fn``. -The list's shape must be identical to the model's input shape, for all dimensions after the first (which first -dimension is the batch size). - -Default csv deserialization requires ``request_body`` contain one or more lines of CSV numerical data. -The data is loaded into a two-dimensional array, where each line break defines the boundaries of the first dimension. - -The example below shows a custom ``input_fn`` for preparing pickled torch.Tensor. - -.. code:: python - - import numpy as np - import torch - from six import BytesIO - - def input_fn(request_body, request_content_type): - """An input_fn that loads a pickled tensor""" - if request_content_type == 'application/python-pickle': - return torch.load(BytesIO(request_body)) - else: - # Handle other content-types here or raise an Exception - # if the content type is not supported. - pass - - - -Get Predictions from a PyTorch Model -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -After the inference request has been deserialized by ``input_fn``, the SageMaker PyTorch model server invokes -``predict_fn`` on the return value of ``input_fn``. - -As with ``input_fn``, you can define your own ``predict_fn`` or use the SageMaker PyTorch model server default. - -The ``predict_fn`` function has the following signature: - -.. code:: python - - def predict_fn(input_object, model, context) - -Where ``input_object`` is the object returned from ``input_fn`` and -``model`` is the model loaded by ``model_fn``. -If you are using multiple GPUs, then specify the ``context`` argument, which contains information such as the GPU ID for a dynamically-selected GPU and the batch size. -One of the examples below demonstrates how to configure ``predict_fn`` with the ``context`` argument to handle multiple GPUs. For more information about ``context``, see the `Serving Context class `_. -If you are using CPUs or a single GPU, then you do not need to specify the ``context`` argument. - -The default implementation of ``predict_fn`` invokes the loaded model's ``__call__`` function on ``input_object``, -and returns the resulting value. The return-type should be a torch.Tensor to be compatible with the default -``output_fn``. - -The following example shows an overridden ``predict_fn``: - -.. code:: python - - import torch - import numpy as np - - def predict_fn(input_data, model): - device = torch.device('cuda' if torch.cuda.is_available() else 'cpu') - model.to(device) - model.eval() - with torch.no_grad(): - return model(input_data.to(device)) - -The following example is for use cases with multiple GPUs and shows an overridden ``predict_fn`` that uses the ``context`` argument to dynamically select a GPU device for making predictions: - -.. code:: python - - import torch - import numpy as np - - def predict_fn(input_data, model, context): - device = torch.device("cuda:" + str(context.system_properties.get("gpu_id")) if torch.cuda.is_available() else "cpu") - model.to(device) - model.eval() - with torch.no_grad(): - return model(input_data.to(device)) - -If you implement your own prediction function, you should take care to ensure that: - -- The first argument is expected to be the return value from input_fn. - If you use the default input_fn, this will be a torch.Tensor. -- The second argument is the loaded model. -- The return value should be of the correct type to be passed as the - first argument to ``output_fn``. If you use the default - ``output_fn``, this should be a torch.Tensor. - -The default Elastic Inference ``predict_fn`` is similar but runs the TorchScript model using ``torch.jit.optimized_execution``. -If you are implementing your own ``predict_fn``, please also use the ``torch.jit.optimized_execution`` -block, for example: - -.. code:: python - - import torch - import numpy as np - - def predict_fn(input_data, model): - device = torch.device("cpu") - model = model.to(device) - input_data = data.to(device) - model.eval() - with torch.jit.optimized_execution(True, {"target_device": "eia:0"}): - output = model(input_data) - -If you use PyTorch Elastic Inference 1.5.1, please implement your own ``predict_fn`` like below. - -.. code:: python - - import numpy as np - import torch - - - def predict_fn(input_data, model): - device = torch.device("cpu") - input_data = data.to(device) - # make sure torcheia is imported so that Elastic Inference api call will be invoked - import torcheia - # we need to set the profiling executor for EIA - torch._C._jit_set_profiling_executor(False) - with torch.jit.optimized_execution(True): - output = model.forward(input_data) - - -Process Model Output -^^^^^^^^^^^^^^^^^^^^ - -After invoking ``predict_fn``, the model server invokes ``output_fn``, passing in the return value from ``predict_fn`` -and the content type for the response, as specified by the InvokeEndpoint request. - -The ``output_fn`` has the following signature: - -.. code:: python - - def output_fn(prediction, content_type, context) - -Where ``prediction`` is the result of invoking ``predict_fn`` and -the content type for the response, as specified by the InvokeEndpoint request. The function should return a byte array of data serialized to ``content_type``. - -``context`` is an optional argument that contains additional serving information, such as the GPU ID and batch size. -If specified in the function declaration, the context will be created and passed to the function by SageMaker. -For more information about ``context``, see the `Serving Context class `_. - -The default implementation expects ``prediction`` to be a torch.Tensor and can serialize the result to JSON, CSV, or NPY. -It accepts response content types of "application/json", "text/csv", and "application/x-npy". - - -Bring your own model -==================== - -You can deploy a PyTorch model that you trained outside of SageMaker by using the ``PyTorchModel`` class. -Typically, you save a PyTorch model as a file with extension ``.pt`` or ``.pth``. -To do this, you need to: - -* Write an inference script. -* Create the directory structure for your model files. -* Create the ``PyTorchModel`` object. - -Write an inference script -------------------------- - -You must create an inference script that implements (at least) the ``model_fn`` function that calls the loaded model to get a prediction. - -**Note**: If you use elastic inference with PyTorch, you can use the default ``model_fn`` implementation provided in the serving container. - -Optionally, you can also implement ``input_fn`` and ``output_fn`` to process input and output, -and ``predict_fn`` to customize how the model server gets predictions from the loaded model. -For information about how to write an inference script, see `Serve a PyTorch Model <#serve-a-pytorch-model>`_. -Save the inference script in the same folder where you saved your PyTorch model. -Pass the filename of the inference script as the ``entry_point`` parameter when you create the ``PyTorchModel`` object. - -Create the directory structure for your model files ---------------------------------------------------- - -You have to create a directory structure and place your model files in the correct location. -The ``PyTorchModel`` constructor packs the files into a ``tar.gz`` file and uploads it to S3. - -The directory structure where you saved your PyTorch model should look something like the following: - -**Note:** This directory struture is for PyTorch versions 1.2 and higher. -For the directory structure for versions 1.1 and lower, -see `For versions 1.1 and lower <#for-versions-1.1-and-lower>`_. - -:: - - | my_model - | |--model.pth - | - | code - | |--inference.py - | |--requirements.txt - -Where ``requirements.txt`` is an optional file that specifies dependencies on third-party libraries. - -Create a ``PyTorchModel`` object --------------------------------- - -Now call the :class:`sagemaker.pytorch.model.PyTorchModel` constructor to create a model object, and then call its ``deploy()`` method to deploy your model for inference. - -.. code:: python - - from sagemaker import get_execution_role - role = get_execution_role() - - pytorch_model = PyTorchModel(model_data='s3://my-bucket/my-path/model.tar.gz', role=role, - entry_point='inference.py') - - predictor = pytorch_model.deploy(instance_type='ml.c4.xlarge', initial_instance_count=1) - - -Now you can call the ``predict()`` method to get predictions from your deployed model. - -*********************************************** -Attach an estimator to an existing training job -*********************************************** - -You can attach a PyTorch Estimator to an existing training job using the -``attach`` method. - -.. code:: python - - my_training_job_name = 'MyAwesomePyTorchTrainingJob' - pytorch_estimator = PyTorch.attach(my_training_job_name) - -After attaching, if the training job has finished with job status "Completed", it can be -``deploy``\ ed to create a SageMaker Endpoint and return a -``Predictor``. If the training job is in progress, -attach will block and display log messages from the training job, until the training job completes. - -The ``attach`` method accepts the following arguments: - -- ``training_job_name:`` The name of the training job to attach - to. -- ``sagemaker_session:`` The Session used - to interact with SageMaker - -************************* -PyTorch Training Examples -************************* - -Amazon provides several example Jupyter notebooks that demonstrate end-to-end training on Amazon SageMaker using PyTorch. -Please refer to: - -https://github.com/awslabs/amazon-sagemaker-examples/tree/master/sagemaker-python-sdk - -These are also available in SageMaker Notebook Instance hosted Jupyter notebooks under the sample notebooks folder. - -************************* -SageMaker PyTorch Classes -************************* - -For information about the different PyTorch-related classes in the SageMaker Python SDK, see https://sagemaker.readthedocs.io/en/stable/frameworks/pytorch/sagemaker.pytorch.html. - -*********************************** -SageMaker PyTorch Docker Containers -*********************************** - -For information about the SageMaker PyTorch containers, see: - -- `SageMaker PyTorch training toolkit `_ -- `SageMaker PyTorch serving toolkit `_ -- `Deep Learning Container (DLC) Dockerfiles for PyTorch `_ -- `Deep Learning Container (DLC) Images `_ and `release notes `_ diff --git a/doc/frameworks/rl/index.rst b/doc/frameworks/rl/index.rst deleted file mode 100644 index ce8385aabb..0000000000 --- a/doc/frameworks/rl/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -######################################### -Reinforcement Learning -######################################### - -A managed environment for Reinforcement Learning (RL) on Amazon SageMaker - -.. toctree:: - :maxdepth: 1 - - using_rl - -.. toctree:: - :maxdepth: 2 - - sagemaker.rl diff --git a/doc/frameworks/rl/sagemaker.rl.rst b/doc/frameworks/rl/sagemaker.rl.rst deleted file mode 100644 index 123ca87b4e..0000000000 --- a/doc/frameworks/rl/sagemaker.rl.rst +++ /dev/null @@ -1,10 +0,0 @@ -RLEstimator -=========== - -RLEstimator Estimator ---------------------- - -.. autoclass:: sagemaker.rl.estimator.RLEstimator - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/frameworks/rl/using_rl.rst b/doc/frameworks/rl/using_rl.rst deleted file mode 100644 index 8937f18cb3..0000000000 --- a/doc/frameworks/rl/using_rl.rst +++ /dev/null @@ -1,215 +0,0 @@ -========================================================== -Using Reinforcement Learning with the SageMaker Python SDK -========================================================== - -.. contents:: - -With Reinforcement Learning (RL) Estimators, you can train reinforcement learning models on Amazon SageMaker. - -For supported RL toolkits and their versions, see https://github.com/aws/sagemaker-rl-container/#rl-images-provided-by-sagemaker - -RL Training ------------ - -Training RL models using ``RLEstimator`` is a two-step process: - -1. Prepare a training script to run on SageMaker -2. Run this script on SageMaker via an ``RLEstimator``. - -You should prepare your script in a separate source file than the notebook, terminal session, or source file you're -using to submit the script to SageMaker via an ``RLEstimator``. This will be discussed in further detail below. - -Suppose that you already have a training script called ``coach-train.py``. -You can then create an ``RLEstimator`` with keyword arguments to point to this script and define how SageMaker runs it: - -.. code:: python - - from sagemaker.rl import RLEstimator, RLToolkit, RLFramework - - rl_estimator = RLEstimator(entry_point='coach-train.py', - toolkit=RLToolkit.COACH, - toolkit_version='0.11.1', - framework=RLFramework.TENSORFLOW, - role='SageMakerRole', - instance_type='ml.p3.2xlarge', - instance_count=1) - -After that, you simply tell the estimator to start a training job: - -.. code:: python - - rl_estimator.fit() - -In the following sections, we'll discuss how to prepare a training script for execution on SageMaker -and how to run that script on SageMaker using ``RLEstimator``. - - -Preparing the RL Training Script -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Your RL training script must be a Python 3.5 compatible source file from MXNet framework or Python 3.6 for TensorFlow. - -The training script is very similar to a training script you might run outside of SageMaker, but you -can access useful properties about the training environment through various environment variables, such as - -* ``SM_MODEL_DIR``: A string representing the path to the directory to write model artifacts to. - These artifacts are uploaded to S3 for model hosting. -* ``SM_NUM_GPUS``: An integer representing the number of GPUs available to the host. -* ``SM_OUTPUT_DATA_DIR``: A string representing the filesystem path to write output artifacts to. Output artifacts may - include checkpoints, graphs, and other files to save, not including model artifacts. These artifacts are compressed - and uploaded to S3 to the same S3 prefix as the model artifacts. - -For the exhaustive list of available environment variables, see the -`SageMaker Containers documentation `__. - - -RL Estimators -------------- - -The ``RLEstimator`` constructor takes both required and optional arguments. - -Required arguments -~~~~~~~~~~~~~~~~~~ - -The following are required arguments to the ``RLEstimator`` constructor. When you create an instance of ``RLEstimator``, you must include -these in the constructor, either positionally or as keyword arguments. - -- ``entry_point`` Path (absolute or relative) to the Python file which - should be executed as the entry point to training. -- ``role`` An AWS IAM role (either name or full ARN). The Amazon - SageMaker training jobs and APIs that create Amazon SageMaker - endpoints use this role to access training data and model artifacts. - After the endpoint is created, the inference code might use the IAM - role, if accessing AWS resource. -- ``instance_count`` Number of Amazon EC2 instances to use for - training. -- ``instance_type`` Type of EC2 instance to use for training, for - example, 'ml.m4.xlarge'. - -You must as well include either: - -- ``toolkit`` RL toolkit (Ray RLlib or Coach) you want to use for executing your model training code. - -- ``toolkit_version`` RL toolkit version you want to be use for executing your model training code. - -- ``framework`` Framework (MXNet or TensorFlow) you want to be used as - a toolkit backed for reinforcement learning training. - -or provide: - -- ``image_uri`` An alternative Docker image to use for training and - serving. If specified, the estimator will use this image for training and - hosting, instead of selecting the appropriate SageMaker official image based on - framework_version and py_version. Refer to: `SageMaker RL Docker Containers - <#sagemaker-rl-docker-containers>`_ for details on what the Official images support - and where to find the source code to build your custom image. - - -Optional arguments -~~~~~~~~~~~~~~~~~~ - -When you create an ``RLEstimator`` object, you can specify a number of optional arguments. -For more information, see :class:`sagemaker.rl.estimator.RLEstimator`. - -Calling fit -~~~~~~~~~~~ - -You start your training script by calling ``fit`` on an ``RLEstimator``. -For more information about what arguments can be passed to ``fit``, see :func:`sagemaker.estimator.EstimatorBase.fit`. - -Distributed RL Training ------------------------ - -Amazon SageMaker RL supports multi-core and multi-instance distributed training. -Depending on your use case, training and/or environment rollout can be distributed. - -Please see the `Amazon SageMaker examples `_ -on how it can be done using different RL toolkits. - - -Saving models -------------- - -In order to save your trained PyTorch model for deployment on SageMaker, your training script should save your model -to a certain filesystem path ``/opt/ml/model``. This value is also accessible through the environment variable -``SM_MODEL_DIR``. - -Deploying RL Models -------------------- - -After an RL Estimator has been fit, you can host the newly created model in SageMaker. - -After calling ``fit``, you can call ``deploy`` on an ``RLEstimator`` Estimator to create a SageMaker Endpoint. -The Endpoint runs one of the SageMaker-provided model server based on the ``framework`` parameter -specified in the ``RLEstimator`` constructor and hosts the model produced by your training script, -which was run when you called ``fit``. This was the model you saved to ``model_dir``. -In case if ``image_uri`` was specified it would use provided image for the deployment. - -``deploy`` returns a ``sagemaker.mxnet.MXNetPredictor`` for MXNet or -``sagemaker.tensorflow.TensorFlowPredictor`` for TensorFlow. - -``predict`` returns the result of inference against your model. - -.. code:: python - - # Train my estimator - rl_estimator = RLEstimator(entry_point='coach-train.py', - toolkit=RLToolkit.COACH, - toolkit_version='0.11.0', - framework=RLFramework.MXNET, - role='SageMakerRole', - instance_type='ml.c4.2xlarge', - instance_count=1) - - rl_estimator.fit() - - # Deploy my estimator to a SageMaker Endpoint and get a MXNetPredictor - predictor = rl_estimator.deploy(instance_type='ml.m4.xlarge', - initial_instance_count=1) - - response = predictor.predict(data) - -For more information please see `The SageMaker MXNet Model Server `_ -and `Deploying to TensorFlow Serving Endpoints `_ documentation. - - -Working with Existing Training Jobs ------------------------------------ - -Attaching to existing training jobs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can attach an RL Estimator to an existing training job using the -``attach`` method. - -.. code:: python - - my_training_job_name = 'MyAwesomeRLTrainingJob' - rl_estimator = RLEstimator.attach(my_training_job_name) - -After attaching, if the training job has finished with job status "Completed", it can be -``deploy``\ ed to create a SageMaker Endpoint and return a ``Predictor``. If the training job is in progress, -attach will block and display log messages from the training job, until the training job completes. - -The ``attach`` method accepts the following arguments: - -- ``training_job_name:`` The name of the training job to attach - to. -- ``sagemaker_session:`` The Session used - to interact with SageMaker - -RL Training Examples --------------------- - -Amazon provides several example Jupyter notebooks that demonstrate end-to-end training on Amazon SageMaker using RL. -Please refer to: - -https://github.com/awslabs/amazon-sagemaker-examples/tree/master/reinforcement_learning - -These are also available in SageMaker Notebook Instance hosted Jupyter notebooks under the sample notebooks folder. - - -SageMaker RL Docker Containers ------------------------------- - -For more about the Docker images themselves, visit `the SageMaker RL containers repository `_. diff --git a/doc/frameworks/sklearn/index.rst b/doc/frameworks/sklearn/index.rst deleted file mode 100644 index 638ce6e286..0000000000 --- a/doc/frameworks/sklearn/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -############################### -Scikit-Learn -############################### - -A managed environment for Scikit-Learn training and hosting on Amazon SageMaker - -.. toctree:: - :maxdepth: 1 - - using_sklearn - -.. toctree:: - :maxdepth: 2 - - sagemaker.sklearn diff --git a/doc/frameworks/sklearn/sagemaker.sklearn.rst b/doc/frameworks/sklearn/sagemaker.sklearn.rst deleted file mode 100644 index 3ca55113e8..0000000000 --- a/doc/frameworks/sklearn/sagemaker.sklearn.rst +++ /dev/null @@ -1,34 +0,0 @@ -Scikit Learn -============ - -Scikit Learn Estimator ----------------------- - -.. autoclass:: sagemaker.sklearn.estimator.SKLearn - :members: - :undoc-members: - :show-inheritance: - -Scikit Learn Model ------------------- - -.. autoclass:: sagemaker.sklearn.model.SKLearnModel - :members: - :undoc-members: - :show-inheritance: - -Scikit Learn Predictor ----------------------- - -.. autoclass:: sagemaker.sklearn.model.SKLearnPredictor - :members: - :undoc-members: - :show-inheritance: - -Scikit Learn Processor ----------------------- - -.. autoclass:: sagemaker.sklearn.processing.SKLearnProcessor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/frameworks/sklearn/using_sklearn.rst b/doc/frameworks/sklearn/using_sklearn.rst deleted file mode 100644 index 954ab36fb8..0000000000 --- a/doc/frameworks/sklearn/using_sklearn.rst +++ /dev/null @@ -1,525 +0,0 @@ -################################################ -Using Scikit-learn with the SageMaker Python SDK -################################################ - -With Scikit-learn Estimators, you can train and host Scikit-learn models on Amazon SageMaker. - -For information about supported versions of Scikit-learn, see the `AWS documentation `__. -We recommend that you use the latest supported version because that's where we focus most of our development efforts. - -For more information about the framework, see the `Scikit-Learn `_ repository. -For general information about using the SageMaker Python SDK, see :ref:`overview:Using the SageMaker Python SDK`. - -.. contents:: - -******************************* -Train a Model with Scikit-learn -******************************* - -To train a Scikit-learn model by using the SageMaker Python SDK: - -.. |create sklearn estimator| replace:: Create a ``sagemaker.sklearn.SKLearn`` Estimator -.. _create sklearn estimator: #create-an-estimator - -.. |call fit| replace:: Call the estimator's ``fit`` method -.. _call fit: #call-the-fit-method - -1. `Prepare a training script <#prepare-a-scikit-learn-training-script>`_ -2. |create sklearn estimator|_ -3. |call fit|_ - -Prepare a Scikit-learn Training Script -====================================== - -Your Scikit-learn training script must be a Python 3.7 compatible source file. - -The training script is similar to a training script you might run outside of SageMaker, but you -can access useful properties about the training environment through various environment variables. -For example: - -* ``SM_MODEL_DIR``: A string representing the path to the directory to write model artifacts to. - These artifacts are uploaded to S3 for model hosting. -* ``SM_OUTPUT_DATA_DIR``: A string representing the filesystem path to write output artifacts to. Output artifacts may - include checkpoints, graphs, and other files to save, not including model artifacts. These artifacts are compressed - and uploaded to S3 to the same S3 prefix as the model artifacts. - -Supposing two input channels, 'train' and 'test', were used in the call to the Scikit-learn estimator's ``fit()`` method, -the following will be set, following the format "SM_CHANNEL_[channel_name]": - -* ``SM_CHANNEL_TRAIN``: A string representing the path to the directory containing data in the 'train' channel -* ``SM_CHANNEL_TEST``: Same as above, but for the 'test' channel. - -A typical training script loads data from the input channels, configures training with hyperparameters, trains a model, -and saves a model to model_dir so that it can be hosted later. Hyperparameters are passed to your script as arguments -and can be retrieved with an argparse.ArgumentParser instance. For example, a training script might start -with the following: - -.. code:: python - - import argparse - import os - - if __name__ =='__main__': - - parser = argparse.ArgumentParser() - - # hyperparameters sent by the client are passed as command-line arguments to the script. - parser.add_argument('--epochs', type=int, default=50) - parser.add_argument('--batch-size', type=int, default=64) - parser.add_argument('--learning-rate', type=float, default=0.05) - - # Data, model, and output directories - parser.add_argument('--output-data-dir', type=str, default=os.environ.get('SM_OUTPUT_DATA_DIR')) - parser.add_argument('--model-dir', type=str, default=os.environ.get('SM_MODEL_DIR')) - parser.add_argument('--train', type=str, default=os.environ.get('SM_CHANNEL_TRAIN')) - parser.add_argument('--test', type=str, default=os.environ.get('SM_CHANNEL_TEST')) - - args, _ = parser.parse_known_args() - - # ... load from args.train and args.test, train a model, write model to args.model_dir. - -Because the SageMaker imports your training script, you should put your training code in a main guard -(``if __name__=='__main__':``) if you are using the same script to host your model, so that SageMaker does not -inadvertently run your training code at the wrong point in execution. - -For more on training environment variables, please visit -`SageMaker Training Toolkit `_. - -.. important:: - The sagemaker-containers repository has been deprecated, - however it is still used to define Scikit-learn and XGBoost environment variables. - -Save the Model --------------- - -In order to save your trained Scikit-learn model for deployment on SageMaker, your training script should save your -model to a certain filesystem path called `model_dir`. This value is accessible through the environment variable -``SM_MODEL_DIR``. The following code demonstrates how to save a trained Scikit-learn model named ``model`` as -``model.joblib`` at the end of training: - -.. code:: python - - from sklearn.externals import joblib - import argparse - import os - - if __name__=='__main__': - # default to the value in environment variable `SM_MODEL_DIR`. Using args makes the script more portable. - parser.add_argument('--model-dir', type=str, default=os.environ['SM_MODEL_DIR']) - args, _ = parser.parse_known_args() - - # ... train classifier `clf`, then save it to `model_dir` as file 'model.joblib' - joblib.dump(clf, os.path.join(args.model_dir, "model.joblib")) - -After your training job is complete, SageMaker will compress and upload the serialized model to S3, and your model data -will available in the s3 ``output_path`` you specified when you created the Scikit-learn Estimator. - -Using third-party libraries ---------------------------- - -When running your training script on SageMaker, it has access to some pre-installed third-party libraries including ``scikit-learn``, ``numpy``, and ``pandas``. -For more information on the runtime environment, including specific package versions, see `SageMaker Scikit-learn Docker Container `__. - -If there are other packages you want to use with your script, you can include a ``requirements.txt`` file in the same directory as your training script to install other dependencies at runtime. -Both ``requirements.txt`` and your training script should be put in the same folder. -You must specify this folder in ``source_dir`` argument when creating a Scikit-learn estimator. -A ``requirements.txt`` file is a text file that contains a list of items that are installed by using ``pip install``. -You can also specify the version of an item to install. -For information about the format of a ``requirements.txt`` file, see `Requirements Files `__ in the pip documentation. - -Create an Estimator -=================== - -You run Scikit-learn training scripts on SageMaker by creating ``SKLearn`` Estimators. -Call the ``fit`` method on a ``SKLearn`` Estimator to start a SageMaker training job. -The following code sample shows how you train a custom Scikit-learn script named "sklearn-train.py", passing -in three hyperparameters ('epochs', 'batch-size', and 'learning-rate'), and using two input channel -directories ('train' and 'test'). - -.. code:: python - - sklearn_estimator = SKLearn('sklearn-train.py', - instance_type='ml.m4.xlarge', - framework_version='1.0-1', - hyperparameters = {'epochs': 20, 'batch-size': 64, 'learning-rate': 0.1}) - sklearn_estimator.fit({'train': 's3://my-data-bucket/path/to/my/training/data', - 'test': 's3://my-data-bucket/path/to/my/test/data'}) - - - - - -Call the fit Method -=================== - -You start your training script by calling ``fit`` on a ``SKLearn`` Estimator. ``fit`` takes both required and optional -arguments. - -fit Required arguments ----------------------- - -- ``inputs``: This can take one of the following forms: A string - s3 URI, for example ``s3://my-bucket/my-training-data``. In this - case, the s3 objects rooted at the ``my-training-data`` prefix will - be available in the default ``train`` channel. A dict from - string channel names to s3 URIs. In this case, the objects rooted at - each s3 prefix will available as files in each channel directory. - -For example: - -.. code:: python - - {'train':'s3://my-bucket/my-training-data', - 'eval':'s3://my-bucket/my-evaluation-data'} - -.. optional-arguments-1: - -fit Optional arguments ----------------------- - -- ``wait``: Defaults to True, whether to block and wait for the - training script to complete before returning. -- ``logs``: Defaults to True, whether to show logs produced by training - job in the Python session. Only meaningful when wait is True. - -*************************** -Deploy a Scikit-learn Model -*************************** - -After you fit a Scikit-learn Estimator, you can host the newly created model in SageMaker. - -After you call ``fit``, you can call ``deploy`` on an ``SKLearn`` estimator to create a SageMaker endpoint. -The endpoint runs a SageMaker-provided Scikit-learn model server and hosts the model produced by your training script, -which was run when you called ``fit``. This was the model you saved to ``model_dir``. - -``deploy`` returns a ``Predictor`` object, which you can use to do inference on the Endpoint hosting your Scikit-learn -model. Each ``Predictor`` provides a ``predict`` method which can do inference with numpy arrays or Python lists. -Inference arrays or lists are serialized and sent to the Scikit-learn model server by an ``InvokeEndpoint`` SageMaker -operation. - -``predict`` returns the result of inference against your model. By default, the inference result a NumPy array. - -.. code:: python - - # Train my estimator - sklearn_estimator = SKLearn(entry_point='train_and_deploy.py', - instance_type='ml.m4.xlarge', - framework_version='1.0-1') - sklearn_estimator.fit('s3://my_bucket/my_training_data/') - - # Deploy my estimator to a SageMaker Endpoint and get a Predictor - predictor = sklearn_estimator.deploy(instance_type='ml.m4.xlarge', - initial_instance_count=1) - - # `data` is a NumPy array or a Python list. - # `response` is a NumPy array. - response = predictor.predict(data) - -You use the SageMaker Scikit-learn model server to host your Scikit-learn model when you call ``deploy`` -on an ``SKLearn`` Estimator. The model server runs inside a SageMaker Endpoint, which your call to ``deploy`` creates. -You can access the name of the Endpoint by the ``name`` property on the returned ``Predictor``. - - -SageMaker Scikit-learn Model Server -=================================== - -The Scikit-learn Endpoint you create with ``deploy`` runs a SageMaker Scikit-learn model server. -The model server loads the model that was saved by your training script and performs inference on the model in response -to SageMaker InvokeEndpoint API calls. - -You can configure two components of the SageMaker Scikit-learn model server: Model loading and model serving. -Model loading is the process of deserializing your saved model back into an Scikit-learn model. -Serving is the process of translating InvokeEndpoint requests to inference calls on the loaded model. - -You configure the Scikit-learn model server by defining functions in the Python source file you passed to the -Scikit-learn constructor. - -Load a Model ------------- - -Before a model can be served, it must be loaded. The SageMaker Scikit-learn model server loads your model by invoking a -``model_fn`` function that you must provide in your script. The ``model_fn`` should have the following signature: - -.. code:: python - - def model_fn(model_dir): - ... - -SageMaker will inject the directory where your model files and sub-directories, saved by ``save``, have been mounted. -Your model function should return a model object that can be used for model serving. - -SageMaker provides automated serving functions that work with Gluon API ``net`` objects and Module API ``Module`` objects. If you return either of these types of objects, then you will be able to use the default serving request handling functions. - -The following code-snippet shows an example ``model_fn`` implementation. -This loads returns a Scikit-learn Classifier from a ``model.joblib`` file in the SageMaker model directory -``model_dir``. - -.. code:: python - - from sklearn.externals import joblib - import os - - def model_fn(model_dir): - clf = joblib.load(os.path.join(model_dir, "model.joblib")) - return clf - -Serve a Model -------------- - -After the SageMaker model server has loaded your model by calling ``model_fn``, SageMaker will serve your model. -Model serving is the process of responding to inference requests, received by SageMaker InvokeEndpoint API calls. -The SageMaker Scikit-learn model server breaks request handling into three steps: - - -- input processing, -- prediction, and -- output processing. - -In a similar way to model loading, you configure these steps by defining functions in your Python source file. - -Each step involves invoking a python function, with information about the request and the return-value from the previous -function in the chain. Inside the SageMaker Scikit-learn model server, the process looks like: - -.. code:: python - - # Deserialize the Invoke request body into an object we can perform prediction on - input_object = input_fn(request_body, request_content_type) - - # Perform prediction on the deserialized object, with the loaded model - prediction = predict_fn(input_object, model) - - # Serialize the prediction result into the desired response content type - output = output_fn(prediction, response_content_type) - -The above code-sample shows the three function definitions: - -- ``input_fn``: Takes request data and deserializes the data into an - object for prediction. -- ``predict_fn``: Takes the deserialized request object and performs - inference against the loaded model. -- ``output_fn``: Takes the result of prediction and serializes this - according to the response content type. - -The SageMaker Scikit-learn model server provides default implementations of these functions. -You can provide your own implementations for these functions in your hosting script. -If you omit any definition then the SageMaker Scikit-learn model server will use its default implementation for that -function. - -The ``Predictor`` used by Scikit-learn in the SageMaker Python SDK serializes NumPy arrays to the `NPY `_ format -by default, with Content-Type ``application/x-npy``. The SageMaker Scikit-learn model server can deserialize NPY-formatted -data (along with JSON and CSV data). - -If you rely solely on the SageMaker Scikit-learn model server defaults, you get the following functionality: - -- Prediction on models that implement the ``__call__`` method -- Serialization and deserialization of NumPy arrays. - -The default ``input_fn`` and ``output_fn`` are meant to make it easy to predict on NumPy arrays. If your model expects -a NumPy array and returns a NumPy array, then these functions do not have to be overridden when sending NPY-formatted -data. - -In the following sections we describe the default implementations of input_fn, predict_fn, and output_fn. -We describe the input arguments and expected return types of each, so you can define your own implementations. - -Process Input -^^^^^^^^^^^^^ - -When an InvokeEndpoint operation is made against an Endpoint running a SageMaker Scikit-learn model server, -the model server receives two pieces of information: - -- The request Content-Type, for example "application/x-npy" -- The request data body, a byte array - -The SageMaker Scikit-learn model server will invoke an "input_fn" function in your hosting script, -passing in this information. If you define an ``input_fn`` function definition, -it should return an object that can be passed to ``predict_fn`` and have the following signature: - -.. code:: python - - def input_fn(request_body, request_content_type): - ... - -where ``request_body`` is a byte buffer and ``request_content_type`` is a Python string. - -The SageMaker Scikit-learn model server provides a default implementation of ``input_fn``. -This function deserializes JSON, CSV, or NPY encoded data into a NumPy array. - -Default NPY deserialization requires ``request_body`` to follow the -`NPY `_ format. For Scikit-learn, the Python SDK -defaults to sending prediction requests with this format. - -Default json deserialization requires ``request_body`` contain a single json list. -Sending multiple json objects within the same ``request_body`` is not supported. -The list must have a dimensionality compatible with the model loaded in ``model_fn``. -The list's shape must be identical to the model's input shape, for all dimensions after the first (which first -dimension is the batch size). - -Default csv deserialization requires ``request_body`` contain one or more lines of CSV numerical data. -The data is loaded into a two-dimensional array, where each line break defines the boundaries of the first dimension. - -The example below shows a custom ``input_fn`` for preparing pickled NumPy arrays. - -.. code:: python - - import numpy as np - - def input_fn(request_body, request_content_type): - """An input_fn that loads a pickled numpy array""" - if request_content_type == "application/python-pickle": - array = np.load(StringIO(request_body)) - return array - else: - # Handle other content-types here or raise an Exception - # if the content type is not supported. - pass - - - -Get Predictions ---------------- - -After the inference request has been deserialized by ``input_fn``, the SageMaker Scikit-learn model server invokes -``predict_fn`` on the return value of ``input_fn``. - -As with ``input_fn``, you can define your own ``predict_fn`` or use the SageMaker Scikit-learn model server default. - -The ``predict_fn`` function has the following signature: - -.. code:: python - - def predict_fn(input_object, model): - ... - -Where ``input_object`` is the object returned from ``input_fn`` and -``model`` is the model loaded by ``model_fn``. - -The default implementation of ``predict_fn`` invokes the loaded model's ``predict`` function on ``input_object``, -and returns the resulting value. The return-type should be a NumPy array to be compatible with the default -``output_fn``. - -The example below shows an overridden ``predict_fn`` for a Logistic Regression classifier. This model accepts a -Python list and returns a tuple of predictions and prediction probabilities from the model in a NumPy array. -This ``predict_fn`` can rely on the default ``input_fn`` and ``output_fn`` because ``input_data`` is a NumPy array, -and the return value of this function is a NumPy array. - -.. code:: python - - import sklearn - import numpy as np - - def predict_fn(input_data, model): - prediction = model.predict(input_data) - pred_prob = model.predict_proba(input_data) - return np.array([prediction, pred_prob]) - -If you implement your own prediction function, you should take care to ensure that: - -- The first argument is expected to be the return value from input_fn. - If you use the default input_fn, this will be a NumPy array. -- The second argument is the loaded model. -- The return value should be of the correct type to be passed as the - first argument to ``output_fn``. If you use the default - ``output_fn``, this should be a NumPy array. - -Process Output -^^^^^^^^^^^^^^ - -After invoking ``predict_fn``, the model server invokes ``output_fn``, passing in the return-value from ``predict_fn`` -and the InvokeEndpoint requested response content-type. - -The ``output_fn`` has the following signature: - -.. code:: python - - def output_fn(prediction, content_type): - ... - -Where ``prediction`` is the result of invoking ``predict_fn`` and -``content_type`` is the InvokeEndpoint requested response content-type. -The function should return a byte array of data serialized to content_type. - -The default implementation expects ``prediction`` to be an NumPy and can serialize the result to JSON, CSV, or NPY. -It accepts response content types of "application/json", "text/csv", and "application/x-npy". - -Working with existing model data and training jobs -================================================== - -Attach to Existing Training Jobs --------------------------------- - -You can attach an Scikit-learn Estimator to an existing training job using the -``attach`` method. - -.. code:: python - - my_training_job_name = "MyAwesomeSKLearnTrainingJob" - sklearn_estimator = SKLearn.attach(my_training_job_name) - -After attaching, if the training job is in a Complete status, it can be -``deploy``\ ed to create a SageMaker Endpoint and return a -``Predictor``. If the training job is in progress, -attach will block and display log messages from the training job, until the training job completes. - -The ``attach`` method accepts the following arguments: - -- ``training_job_name (str):`` The name of the training job to attach - to. -- ``sagemaker_session (sagemaker.Session or None):`` The Session used - to interact with SageMaker - -Deploy an Endpoint from Model Data ----------------------------------- - -As well as attaching to existing training jobs, you can deploy models directly from model data in S3. -The following code sample shows how to do this, using the ``SKLearnModel`` class. - -.. code:: python - - sklearn_model = SKLearnModel(model_data="s3://bucket/model.tar.gz", - role="SageMakerRole", - entry_point="transform_script.py", - framework_version="1.0-1") - - predictor = sklearn_model.deploy(instance_type="ml.c4.xlarge", initial_instance_count=1) - -To see what arguments are accepted by the ``SKLearnModel`` constructor, see :class:`sagemaker.sklearn.model.SKLearnModel`. - -Your model data must be a .tar.gz file in S3. SageMaker Training Job model data is saved to .tar.gz files in S3, -however if you have local data you want to deploy, you can prepare the data yourself. - -Assuming you have a local directory containing your model data named "my_model", you can tar and gzip compress the file and -upload to S3 using the following commands: - -.. code:: - - tar -czf model.tar.gz my_model - aws s3 cp model.tar.gz s3://my-bucket/my-path/model.tar.gz - -This uploads the contents of my_model to a gzip compressed tar file to S3 in the bucket "my-bucket", with the key -"my-path/model.tar.gz". - -To run this command, you'll need the AWS CLI tool installed. Please refer to our `FAQ <#FAQ>`__ for more information on -installing this. - -****************************** -Scikit-learn Training Examples -****************************** - -To find example notebooks that demonstrate end-to-end training on Amazon SageMaker using Scikit-learn, -see the `Amazon SageMaker example notebooks repository -`_. - -These are also available in SageMaker Notebook Instance hosted Jupyter notebooks under the "sample notebooks" folder. - -****************************** -SageMaker Scikit-learn Classes -****************************** - -For information about the different Scikit-learn classes in the SageMaker Python SDK, see https://sagemaker.readthedocs.io/en/stable/frameworks/sklearn/sagemaker.sklearn.html. - -**************************************** -SageMaker Scikit-learn Docker Containers -**************************************** - -To find the SageMaker-managed Scikit-learn containers, -visit the `SageMaker Scikit-Learn containers repository `_. diff --git a/doc/frameworks/sparkml/index.rst b/doc/frameworks/sparkml/index.rst deleted file mode 100644 index 3001318e06..0000000000 --- a/doc/frameworks/sparkml/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -################################## -SparkML Serving -################################## - -A managed environment for SparkML Serving on Amazon SageMaker - -.. toctree:: - :maxdepth: 2 - - sagemaker.sparkml diff --git a/doc/frameworks/sparkml/sagemaker.sparkml.rst b/doc/frameworks/sparkml/sagemaker.sparkml.rst deleted file mode 100644 index f3a0eae2ef..0000000000 --- a/doc/frameworks/sparkml/sagemaker.sparkml.rst +++ /dev/null @@ -1,18 +0,0 @@ -SparkML Serving -=============== - -SparkML Model -------------- - -.. autoclass:: sagemaker.sparkml.model.SparkMLModel - :members: - :undoc-members: - :show-inheritance: - -SparkML Predictor ------------------ - -.. autoclass:: sagemaker.sparkml.model.SparkMLPredictor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/frameworks/tensorflow/deploying_tensorflow_serving.rst b/doc/frameworks/tensorflow/deploying_tensorflow_serving.rst deleted file mode 100644 index 1d7344fbbb..0000000000 --- a/doc/frameworks/tensorflow/deploying_tensorflow_serving.rst +++ /dev/null @@ -1,655 +0,0 @@ -Deploying to TensorFlow Serving Endpoints -========================================= - -Table of Contents -~~~~~~~~~~~~~~~~~ - -- `Deploying from an Estimator`_ -- `Deploying directly from model artifacts`_ -- `Making predictions against a SageMaker Endpoint`_ -- `Deploying more than one model to your Endpoint`_ -- `Making predictions with the AWS CLI`_ - -Deploying from an Estimator -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -After a TensorFlow estimator has been fit, it saves a TensorFlow -`SavedModel `_ bundle in -the S3 location defined by ``output_path``. You can call ``deploy`` on a TensorFlow -estimator object to create a SageMaker Endpoint: - -.. code:: python - - from sagemaker.tensorflow import TensorFlow - - estimator = TensorFlow( - entry_point="tf-train.py", - ..., - instance_count=1, - instance_type="ml.c4.xlarge", - framework_version="2.2", - py_version="py37", - ) - - estimator.fit(inputs) - - predictor = estimator.deploy(initial_instance_count=1, instance_type="ml.c5.xlarge") - - -The code block above deploys a SageMaker Endpoint with one instance of the type "ml.c5.xlarge". - -What happens when deploy is called -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Calling ``deploy`` starts the process of creating a SageMaker Endpoint. This process includes the following steps. - -- Starts ``initial_instance_count`` EC2 instances of the type ``instance_type``. -- On each instance, it will do the following steps: - - - start a Docker container optimized for TensorFlow Serving, see `SageMaker TensorFlow Serving containers `_. - - start a `TensorFlow Serving` process configured to run your model. - - start an HTTP server that provides access to TensorFlow Server through the SageMaker InvokeEndpoint API. - - -When the ``deploy`` call finishes, the created SageMaker Endpoint is ready for prediction requests. The -`Making predictions against a SageMaker Endpoint`_ section will explain how to make prediction requests -against the Endpoint. - -Deploying directly from model artifacts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you already have existing model artifacts in S3, you can skip training and deploy them directly to an endpoint: - -.. code:: python - - from sagemaker.tensorflow import TensorFlowModel - - model = TensorFlowModel(model_data='s3://mybucket/model.tar.gz', role='MySageMakerRole') - - predictor = model.deploy(initial_instance_count=1, instance_type='ml.c5.xlarge') - -Python-based TensorFlow serving on SageMaker has support for `Elastic Inference `__, which allows for inference acceleration to a hosted endpoint for a fraction of the cost of using a full GPU instance. In order to attach an Elastic Inference accelerator to your endpoint provide the accelerator type to accelerator_type to your deploy call. - -.. code:: python - - from sagemaker.tensorflow import TensorFlowModel - - model = TensorFlowModel(model_data='s3://mybucket/model.tar.gz', role='MySageMakerRole') - - predictor = model.deploy(initial_instance_count=1, instance_type='ml.c5.xlarge', accelerator_type='ml.eia1.medium') - -Making predictions against a SageMaker Endpoint -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once you have the ``Predictor`` instance returned by ``model.deploy(...)`` or ``estimator.deploy(...)``, you -can send prediction requests to your Endpoint. - -The following code shows how to make a prediction request: - -.. code:: python - - input = { - 'instances': [1.0, 2.0, 5.0] - } - result = predictor.predict(input) - -The result object will contain a Python dict like this: - -.. code:: python - - { - 'predictions': [3.5, 4.0, 5.5] - } - -The formats of the input and the output data correspond directly to the request and response formats -of the ``Predict`` method in the `TensorFlow Serving REST API `_. - -If your SavedModel includes the right ``signature_def``, you can also make Classify or Regress requests: - -.. code:: python - - # input matches the Classify and Regress API - input = { - 'signature_name': 'tensorflow/serving/regress', - 'examples': [{'x': 1.0}, {'x': 2.0}] - } - - result = predictor.regress(input) # or predictor.classify(...) - - # result contains: - { - 'results': [3.5, 4.0] - } - -You can include multiple ``instances`` in your predict request (or multiple ``examples`` in -classify/regress requests) to get multiple prediction results in one request to your Endpoint: - -.. code:: python - - input = { - 'instances': [ - [1.0, 2.0, 5.0], - [1.0, 2.0, 5.0], - [1.0, 2.0, 5.0] - ] - } - result = predictor.predict(input) - - # result contains: - { - 'predictions': [ - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5] - ] - } - -If your application allows request grouping like this, it is **much** more efficient than making separate requests. - -Other input formats -^^^^^^^^^^^^^^^^^^^ - -SageMaker's TensforFlow Serving endpoints can also accept some additional input formats that are not part of the -TensorFlow REST API, including a simplified json format, line-delimited json objects ("jsons" or "jsonlines"), and -CSV data. - -**Simplified JSON Input** - -The Endpoint will accept simplified JSON input that doesn't match the TensorFlow REST API's Predict request format. -When the Endpoint receives data like this, it will attempt to transform it into a valid -Predict request, using a few simple rules: - -- python value, dict, or one-dimensional arrays are treated as the input value in a single 'instance' Predict request. -- multidimensional arrays are treated as a multiple values in a multi-instance Predict request. - -Combined with the client-side ``Predictor`` object's JSON serialization, this allows you to make simple -requests like this: - -.. code:: python - - input = [ - [1.0, 2.0, 5.0], - [1.0, 2.0, 5.0] - ] - result = predictor.predict(input) - - # result contains: - { - 'predictions': [ - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5] - ] - } - -Or this: - -.. code:: python - - # 'x' must match name of input tensor in your SavedModel graph - # for models with multiple named inputs, just include all the keys in the input dict - input = { - 'x': [1.0, 2.0, 5.0] - } - - # result contains: - { - 'predictions': [ - [3.5, 4.0, 5.5] - ] - } - - -**Line-delimited JSON** - -The Endpoint will accept line-delimited JSON objects (also known as "jsons" or "jsonlines" data). -The Endpoint treats each line as a separate instance in a multi-instance Predict request. To use -this feature from your python code, you need to create a ``Predictor`` instance that does not -try to serialize your input to JSON: - -.. code:: python - - # create a Predictor without JSON serialization - - predictor = Predictor('endpoint-name', serializer=None, content_type='application/jsonlines') - - input = '''{'x': [1.0, 2.0, 5.0]} - {'x': [1.0, 2.0, 5.0]} - {'x': [1.0, 2.0, 5.0]}''' - - result = predictor.predict(input) - - # result contains: - { - 'predictions': [ - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5] - ] - } - -This feature is especially useful if you are reading data from a file containing jsonlines data. - -**CSV (comma-separated values)** - -The Endpoint will accept CSV data. Each line is treated as a separate instance. This is a -compact format for representing multiple instances of 1-d array data. To use this feature -from your python code, you need to create a ``Predictor`` instance that can serialize -your input data to CSV format: - -.. code:: python - - # create a Predictor with JSON serialization - - predictor = Predictor('endpoint-name', serializer=sagemaker.serializers.CSVSerializer()) - - # CSV-formatted string input - input = '1.0,2.0,5.0\n1.0,2.0,5.0\n1.0,2.0,5.0' - - result = predictor.predict(input) - - # result contains: - { - 'predictions': [ - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5] - ] - } - -You can also use python arrays or numpy arrays as input and let the ``CSVSerializer`` object -convert them to CSV, but the client-size CSV conversion is more sophisticated than the -CSV parsing on the Endpoint, so if you encounter conversion problems, try using one of the -JSON options instead. - - -Specifying the output of a prediction request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The structure of the prediction ``result`` is determined at the end of the training process before SavedModel is created. For example, if -you are using TensorFlow's Estimator API for training, you control inference outputs using the ``export_outputs`` parameter of the `tf.estimator.EstimatorSpec `_ that you return from your ``model_fn``. - -More information on how to create ``export_outputs`` can be found in `specifying the outputs of a custom model `_. You can also -refer to TensorFlow's `Save and Restore `_ documentation for other ways to control the -inference-time behavior of your SavedModels. - -Providing Python scripts for pre/post-processing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can add your customized Python code to process your input and output data. -This customized Python code must be named ``inference.py`` and specified through the ``entry_point`` parameter: - -.. code:: - - from sagemaker.tensorflow import TensorFlowModel - - model = Model(entry_point='inference.py', - model_data='s3://mybucket/model.tar.gz', - role='MySageMakerRole') - -How to implement the pre- and/or post-processing handler(s) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Your entry point file must be named ``inference.py`` and should implement - either a pair of ``input_handler`` and ``output_handler`` functions or - a single ``handler`` function. - Note that if ``handler`` function is implemented, ``input_handler`` - and ``output_handler`` are ignored. - -To implement pre- and/or post-processing handler(s), use the Context -object that the Python service creates. The Context object is a namedtuple with the following attributes: - -- ``model_name (string)``: the name of the model to use for - inference. For example, 'half-plus-three' - -- ``model_version (string)``: version of the model. For example, '5' - -- ``method (string)``: inference method. For example, 'predict', - 'classify' or 'regress', for more information on methods, please see - `Classify and Regress - API `__ - and `Predict - API `__ - -- ``rest_uri (string)``: the TFS REST uri generated by the Python - service. For example, - 'http://localhost:8501/v1/models/half_plus_three:predict' - -- ``grpc_uri (string)``: the GRPC port number generated by the Python - service. For example, '9000' - -- ``custom_attributes (string)``: content of - 'X-Amzn-SageMaker-Custom-Attributes' header from the original - request. For example, - 'tfs-model-name=half*plus*\ three,tfs-method=predict' - -- ``request_content_type (string)``: the original request content type, - defaulted to 'application/json' if not provided - -- ``accept_header (string)``: the original request accept type, - defaulted to 'application/json' if not provided - -- ``content_length (int)``: content length of the original request - -The following code example implements ``input_handler`` and -``output_handler``. By providing these, the Python service posts the -request to the TFS REST URI with the data pre-processed by ``input_handler`` -and passes the response to ``output_handler`` for post-processing. - -.. code:: - - import json - - def input_handler(data, context): - """ Pre-process request input before it is sent to TensorFlow Serving REST API - Args: - data (obj): the request data, in format of dict or string - context (Context): an object containing request and configuration details - Returns: - (dict): a JSON-serializable dict that contains request body and headers - """ - if context.request_content_type == 'application/json': - # pass through json (assumes it's correctly formed) - d = data.read().decode('utf-8') - return d if len(d) else '' - - if context.request_content_type == 'text/csv': - # very simple csv handler - return json.dumps({ - 'instances': [float(x) for x in data.read().decode('utf-8').split(',')] - }) - - raise ValueError('{{"error": "unsupported content type {}"}}'.format( - context.request_content_type or "unknown")) - - - def output_handler(data, context): - """Post-process TensorFlow Serving output before it is returned to the client. - Args: - data (obj): the TensorFlow serving response - context (Context): an object containing request and configuration details - Returns: - (bytes, string): data to return to client, response content type - """ - if data.status_code != 200: - raise ValueError(data.content.decode('utf-8')) - - response_content_type = context.accept_header - prediction = data.content - return prediction, response_content_type - -You might want to have complete control over the request. -For example, you might want to make a TFS request (REST or GRPC) to the first model, -inspect the results, and then make a request to a second model. In this case, implement -the ``handler`` method instead of the ``input_handler`` and ``output_handler`` methods, as demonstrated -in the following code: - -.. code:: - - import json - import requests - - - def handler(data, context): - """Handle request. - Args: - data (obj): the request data - context (Context): an object containing request and configuration details - Returns: - (bytes, string): data to return to client, (optional) response content type - """ - processed_input = _process_input(data, context) - response = requests.post(context.rest_uri, data=processed_input) - return _process_output(response, context) - - - def _process_input(data, context): - if context.request_content_type == 'application/json': - # pass through json (assumes it's correctly formed) - d = data.read().decode('utf-8') - return d if len(d) else '' - - if context.request_content_type == 'text/csv': - # very simple csv handler - return json.dumps({ - 'instances': [float(x) for x in data.read().decode('utf-8').split(',')] - }) - - raise ValueError('{{"error": "unsupported content type {}"}}'.format( - context.request_content_type or "unknown")) - - - def _process_output(data, context): - if data.status_code != 200: - raise ValueError(data.content.decode('utf-8')) - - response_content_type = context.accept_header - prediction = data.content - return prediction, response_content_type - -You can also bring in external dependencies to help with your data -processing. There are 2 ways to do this: - -1. If you included ``requirements.txt`` in your ``source_dir``, the container installs the Python dependencies at runtime using ``pip install -r``: - -.. code:: - - from sagemaker.tensorflow import TensorFlowModel - - model = Model(entry_point='inference.py', - source_dir='source/directory', - model_data='s3://mybucket/model.tar.gz', - role='MySageMakerRole') - - -2. If you are working in a network-isolation situation or if you don't - want to install dependencies at runtime every time your endpoint starts or a batch - transform job runs, you might want to put - pre-downloaded dependencies under a ``lib`` directory and this - directory as dependency. The container adds the modules to the Python - path. Note that if both ``lib`` and ``requirements.txt`` - are present in the model archive, the ``requirements.txt`` is ignored: - -.. code:: - - from sagemaker.tensorflow import TensorFlowModel - - model = Model(entry_point='inference.py', - dependencies=['/path/to/folder/named/lib'], - model_data='s3://mybucket/model.tar.gz', - role='MySageMakerRole') - -For more information, see: https://github.com/aws/sagemaker-tensorflow-serving-container#prepost-processing - -Deploying more than one model to your Endpoint -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -TensorFlow Serving Endpoints allow you to deploy multiple models to the same Endpoint when you create the endpoint. - -To use this feature, you will need to: - -#. create a multi-model archive file -#. create a SageMaker Model and deploy it to an Endpoint -#. create Predictor instances that direct requests to a specific model - -Creating a multi-model archive file -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Creating an archive file that contains multiple SavedModels is simple, but involves a few -steps: - -- obtaining some models -- repackaging the models into a new archive file -- uploading the new archive to S3 - -**Obtaining model files** - -Let's imagine you have already run two Tensorflow training jobs in SageMaker, and they exported -SavedModels to ``s3://mybucket/models/model1.tar.gz`` and ``s3://mybucket/models/model2.tar.gz``. - -First, download the models and extract them: - -.. code:: bash - - aws s3 cp s3://mybucket/models/model1/model.tar.gz model1.tar.gz - aws s3 cp s3://mybucket/models/model2/model.tar.gz model2.tar.gz - mkdir -p multi/model1 - mkdir -p multi/model2 - - tar xvf model1.tar.gz -C ./multi/model1 - tar xvf model2.tar.gz -C ./multi/model2 - -**Repackaging the models** - -Next, examine the directories in ``multi``. If you trained the models using SageMaker's TensorFlow containers, -you are likely to have ``./multi/model1/export/Servo/...`` and ``./multi/model2/export/Servo/...``. In both cases, -"Servo" is the base name for the SaveModel files. When serving multiple models, each model needs a unique -basename, so one or both of these will need to be changed. The ``/export/`` part of the path isn't needed -either, so you can simplify the layout at the same time: - -.. code:: bash - - mv multi/model1/export/Servo/* multi/model1/ - mv multi/model2/export/Servo/* multi/model2/ - rm -fr multi/model1/export - rm -fr multi/model2/export - -You should now have a directory structure like this: - -:: - - └── multi - ├── model1 - │   └── - │   ├── saved_model.pb - │   └── variables - │   └── ... - └── model2 - └── - ├── saved_model.pb - └── variables - └── ... - -To repackage the files into a new archive, use ``tar`` again: - -.. code:: bash - - tar -C "$PWD/multi/" -czvf multi.tar.gz multi/ - -The ``multi.tar.gz`` file is now ready to use. - -**Uploading the new archive to S3** - -.. code:: bash - - aws s3 cp multi.tar.gz s3://mybucket/models/multi.tar.gz - -Creating and Deploying a SageMaker Model -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For the remaining steps, let's return to python code using the SageMaker Python SDK. - -.. code:: python - - from sagemaker.tensorflow import TensorFlowModel, TensorFlowPredictor - - # change this to the name or ARN of your SageMaker execution role - role = 'SageMakerRole' - - model_data = 's3://mybucket/models/multi.tar.gz' - - # For multi-model endpoints, you should set the default model name in - # an environment variable. If it isn't set, the endpoint will work, - # but the model it will select as default is unpredictable. - env = { - 'SAGEMAKER_TFS_DEFAULT_MODEL_NAME': 'model1' - } - - model = Model(model_data=model_data, role=role, framework_version='1.11', env=env) - predictor = model.deploy(initial_instance_count=1, instance_type='ml.c5.xlarge') - -The ``predictor`` object returned by the deploy function is ready to use to make predictions -using the default model (``model1`` in this example). - -Creating Predictor instances for different models -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``predictor`` returned by the ``model.deploy(...)`` function can only send requests to -the default model. To use other models deployed to the same Endpoint, you need to create -additional ``Predictor`` instances. Here's how: - -.. code:: python - - # ... continuing from the previous example - - # get the endpoint name from the default predictor - endpoint = predictor.endpoint_name - - # get a predictor for 'model2' - model2_predictor = Predictor(endpoint, model_name='model2') - - # note: that will for actual SageMaker endpoints, but if you are using - # local mode you need to create the new Predictor this way: - # - # model2_predictor = Predictor(endpoint, model_name='model2' - # sagemaker_session=predictor.sagemaker_session) - - - # result is prediction from 'model2' - result = model2_predictor.predict(...) - -Making predictions with the AWS CLI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The SageMaker Python SDK is not the only way to access your Endpoint. The AWS CLI is simple to -use and a convenient way to test your endpoint. Here are a few examples that show how to use -different features of SageMaker TensorFlow Serving Endpoints using the CLI. - -Note: The ``invoke-endpoint`` command usually writes prediction results to a file. In the examples -below, the ``>(cat) 1>/dev/null`` part is a shell trick to redirect the result to stdout so it -can be seen. - -.. code:: bash - - # TensorFlow Serving REST API - predict request - aws sagemaker-runtime invoke-endpoint \ - --endpoint-name my-endpoint \ - --content-type 'application/json' \ - --body '{"instances": [1.0, 2.0, 5.0]}' \ - >(cat) 1>/dev/null - - # Predict request for specific model name - aws sagemaker-runtime invoke-endpoint \ - --endpoint-name my-endpoint \ - --content-type 'application/json' \ - --body '{"instances": [1.0, 2.0, 5.0]}' \ - --custom-attributes 'tfs-model-name=other_model' \ - >(cat) 1>/dev/null - - # TensorFlow Serving REST API - regress request - aws sagemaker-runtime invoke-endpoint \ - --endpoint-name my-endpoint \ - --content-type 'application/json' \ - --body '{"signature_name": "tensorflow/serving/regress","examples": [{"x": 1.0}]}' \ - --custom-attributes 'tfs-method=regress' \ - >(cat) 1>/dev/null - - # Simple json request (2 instances) - aws sagemaker-runtime invoke-endpoint \ - --endpoint-name my-endpoint \ - --content-type 'application/json' \ - --body '[[1.0, 2.0, 5.0],[2.0, 3.0, 4.0]]' \ - >(cat) 1>/dev/null - - # CSV request (2 rows) - aws sagemaker-runtime invoke-endpoint \ - --endpoint-name my-endpoint \ - --content-type 'text/csv' \ - --body "1.0,2.0,5.0"$'\n'"2.0,3.0,4.0" \ - >(cat) 1>/dev/null - - # Line delimited JSON from an input file - aws sagemaker-runtime invoke-endpoint \ - --endpoint-name my-endpoint \ - --content-type 'application/jsons' \ - --body "$(cat input.jsons)" \ - results.json diff --git a/doc/frameworks/tensorflow/index.rst b/doc/frameworks/tensorflow/index.rst deleted file mode 100644 index 46f535ba1d..0000000000 --- a/doc/frameworks/tensorflow/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -########## -TensorFlow -########## - -A managed environment for TensorFlow training and hosting on Amazon SageMaker - -.. toctree:: - :maxdepth: 1 - - using_tf - deploying_tensorflow_serving - upgrade_from_legacy - -.. toctree:: - :maxdepth: 2 - - sagemaker.tensorflow diff --git a/doc/frameworks/tensorflow/sagemaker.tensorflow.rst b/doc/frameworks/tensorflow/sagemaker.tensorflow.rst deleted file mode 100644 index 5bdde1c4e6..0000000000 --- a/doc/frameworks/tensorflow/sagemaker.tensorflow.rst +++ /dev/null @@ -1,44 +0,0 @@ -TensorFlow -========== - - -TensorFlow Estimator --------------------- - -.. autoclass:: sagemaker.tensorflow.estimator.TensorFlow - :members: - :undoc-members: - :show-inheritance: - -TensorFlow Training Compiler Configuration ------------------------------------------- - -.. autoclass:: sagemaker.tensorflow.TrainingCompilerConfig - :members: - :undoc-members: - :show-inheritance: - -TensorFlow Serving Model ------------------------- - -.. autoclass:: sagemaker.tensorflow.model.TensorFlowModel - :members: - :undoc-members: - :show-inheritance: - -TensorFlow Serving Predictor ----------------------------- - -.. autoclass:: sagemaker.tensorflow.model.TensorFlowPredictor - :members: - :undoc-members: - :show-inheritance: - - -TensorFlow Processor --------------------- - -.. autoclass:: sagemaker.tensorflow.processing.TensorFlowProcessor - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/frameworks/tensorflow/upgrade_from_legacy.rst b/doc/frameworks/tensorflow/upgrade_from_legacy.rst deleted file mode 100644 index 143a1180d0..0000000000 --- a/doc/frameworks/tensorflow/upgrade_from_legacy.rst +++ /dev/null @@ -1,253 +0,0 @@ -###################################### -Upgrade from Legacy TensorFlow Support -###################################### - -With version 2.0 and later of the SageMaker Python SDK, support for legacy SageMaker TensorFlow images has been deprecated. -This guide explains how to upgrade your SageMaker Python SDK usage. - -For more information about using TensorFlow with the SageMaker Python SDK, see `Use TensorFlow with the SageMaker Python SDK `_. - -.. contents:: - -******************************************** -What Constitutes "Legacy TensorFlow Support" -******************************************** - -This guide is relevant if one of the following applies: - -#. You are using TensorFlow versions 1.4-1.10 -#. You are using TensorFlow versions 1.11-1.12 with Python 2, and - - - you do *not* have ``script_mode=True`` when creating your estimator - - you are using ``sagemaker.tensorflow.model.TensorFlowModel`` and/or ``sagemaker.tensorflow.model.TensorFlowPredictor`` - -#. You are using a pre-built SageMaker image whose URI looks like ``520713654638.dkr.ecr..amazonaws.com/sagemaker-tensorflow:`` - -If one of the above applies, then keep reading. - -************** -How to Upgrade -************** - -We recommend that you use the latest supported version of TensorFlow because that's where we focus our development efforts. -For information about supported versions of TensorFlow, see the `AWS documentation `_. - -For general information about using TensorFlow with the SageMaker Python SDK, see `Use TensorFlow with the SageMaker Python SDK `_. - -Training Script -=============== - -Newer versions of TensorFlow require your training script to be runnable as a command-line script, similar to what you might run outside of SageMaker. For more information, including how to adapt a locally-runnable script, see `Prepare a Training Script `_. - -In addition, your training script needs to save your model. If you have your own ``serving_input_fn`` implementation, then that can be passed to an exporter: - -.. code:: python - - import tensorflow as tf - - exporter = tf.estimator.LatestExporter("Servo", serving_input_receiver_fn=serving_input_fn) - -For an example of how to repackage your legacy TensorFlow training script for use with a newer version of TensorFlow, -see `this example notebook `_. - -Inference Script -================ - -Newer versions of TensorFlow Serving require a different format for the inference script. Some key differences: - -- The script must be named ``inference.py``. -- ``input_fn`` has been replaced by ``input_handler``. -- ``output_fn`` has been replaced by ``output_handler``. - -Like with the legacy versions, the pre-built SageMaker TensorFlow Serving images do have default implementations for pre- and post-processing. - -For more information about implementing your own handlers, see `How to implement the pre- and/or post-processing handler(s) `_. - -***************************** -Continue with Legacy Versions -***************************** - -While not recommended, you can still use a legacy TensorFlow version with version 2.0 and later of the SageMaker Python SDK. -In order to do so, you need to change how a few parameters are defined. - -Training -======== - -When creating an estimator, the Python SDK version 2.0 and later requires the following changes: - -#. Explicitly specify the ECR image URI via ``image_uri``. - To determine the URI, you can use :func:`sagemaker.fw_utils.create_image_uri`. -#. Specify ``model_dir=False``. -#. Use hyperparameters for ``training_steps``, ``evaluation_steps``, ``checkpoint_path``, and ``requirements_file``. - -For example, if using TF 1.10.0 with an ml.m4.xlarge instance in us-west-2, -the difference in code would be as follows: - -.. code:: python - - from sagemaker.tensorflow import TensorFlow - - # v1.x - estimator = TensorFlow( - ... - source_dir="code", - framework_version="1.10.0", - train_instance_type="ml.m4.xlarge", - training_steps=100, - evaluation_steps=10, - checkpoint_path="s3://bucket/path", - requirements_file="requirements.txt", - ) - - # v2.0 and later - estimator = TensorFlow( - ... - source_dir="code", - framework_version="1.10.0", - py_version="py2", - instance_type="ml.m4.xlarge", - image_uri="520713654638.dkr.ecr.us-west-2.amazonaws.com/sagemaker-tensorflow:1.10.0-cpu-py2", - hyperparameters={ - "training_steps": 100, - "evaluation_steps": 10, - "checkpoint_path": "s3://bucket/path", - "sagemaker_requirements": "requirements.txt", - }, - model_dir=False, - ) - -Requirements File with Training -------------------------------- - -To provide a requirements file, define a hyperparameter named "sagemaker_requirements" that contains the relative path to the requirements file from ``source_dir``. - -Inference -========= - -Using a legacy TensorFlow version for endpoints and batch transform can be achieved with version 2.0 and later of the SageMaker Python SDK with some minor changes to your code. - -From an Estimator ------------------ - -If you are starting with a training job, you can call :func:`sagemaker.estimator.EstimatorBase.deploy` or :func:`sagemaker.tensorflow.estimator.Estimator.transformer` from your estimator for inference. - -To specify the number of model server workers, you need to set it through an environment variable named ``MODEL_SERVER_WORKERS``: - -.. code:: python - - # v1.x - estimator.deploy(..., model_server_workers=4) - - # v2.0 and later - estimator.deploy(..., env={"MODEL_SERVER_WORKERS": 4}) - -From a Trained Model --------------------- - -If you are starting with a trained model, the Python SDK version 2.0 and later requires the following changes: - -#. Use the the :class:`sagemaker.model.FrameworkModel` class. -#. Explicitly specify the ECR image URI via ``image_uri``. - To determine the URI, you can use :func:`sagemaker.fw_utils.create_image_uri`. -#. Use an environment variable for ``model_server_workers``. - -For example, if using TF 1.10.0 with a CPU instance in us-west-2, -the difference in code would be as follows: - -.. code:: python - - # v1.x - from sagemaker.tensorflow import TensorFlowModel - - model = TensorFlowModel( - ... - py_version="py2", - framework_version="1.10.0", - model_server_workers=4, - ) - - # v2.0 and later - from sagemaker.model import FrameworkModel - - model = FrameworkModel( - ... - image_uri="520713654638.dkr.ecr.us-west-2.amazonaws.com/sagemaker-tensorflow:1.10.0-cpu-py2", - env={"MODEL_SERVER_WORKERS": 4}, - ) - -Requirements File with Inference --------------------------------- - -To provide a requirements file, define an environment variable named ``SAGEMAKER_REQUIREMENTS`` that contains the relative path to the requirements file from ``source_dir``. - -From an estimator: - -.. code:: python - - # for an endpoint - estimator.deploy(..., env={"SAGEMAKER_REQUIREMENTS": "requirements.txt"}) - - # for batch transform - estimator.transformer(..., env={"SAGEMAKER_REQUIREMENTS": "requirements.txt"}) - -From a model: - -.. code:: python - - from sagemaker.model import FrameworkModel - - model = FrameworkModel( - ... - source_dir="code", - env={"SAGEMAKER_REQUIREMENTS": "requirements.txt"}, - ) - - -Predictors ----------- - -If you want to use your model for endpoints, then you can use the :class:`sagemaker.predictor.Predictor` class instead of the legacy ``sagemaker.tensorflow.TensorFlowPredictor`` class: - -.. code:: python - - from sagemaker.model import FrameworkModel - from sagemaker.predictor import Predictor - - model = FrameworkModel( - ... - predictor_cls=Predictor, - ) - - predictor = model.deploy(...) - -If you are using protobuf prediction data, then you need to serialize and deserialize the data yourself. - -For example: - -.. code:: python - - from google.protobuf import json_format - from protobuf_to_dict import protobuf_to_dict - from tensorflow.core.framework import tensor_pb2 - - # Serialize the prediction data - json_format.MessageToJson(data) - - # Get the prediction result - result = predictor.predict(data) - - # Deserialize the prediction result - protobuf_to_dict(json_format.Parse(result, tensor_pb2.TensorProto())) - -Otherwise, you can use the serializers and deserialzers available in the SageMaker Python SDK or write your own. - -For example, if you want to use JSON serialization and deserialization: - -.. code:: python - - from sagemaker.deserializers import JSONDeserializer - from sagemaker.serializers import JSONSerializer - - predictor = model.deploy(..., serializer=JSONSerializer(), deserializer=JSONDeserializer()) - - predictor.predict(data) diff --git a/doc/frameworks/tensorflow/using_tf.rst b/doc/frameworks/tensorflow/using_tf.rst deleted file mode 100644 index 1e51b5f43a..0000000000 --- a/doc/frameworks/tensorflow/using_tf.rst +++ /dev/null @@ -1,963 +0,0 @@ -############################################ -Use TensorFlow with the SageMaker Python SDK -############################################ - -With the SageMaker Python SDK, you can train and host TensorFlow models on Amazon SageMaker. - -For information about supported versions of TensorFlow, see the `AWS documentation `_. -We recommend that you use the latest supported version because that's where we focus our development efforts. - -For general information about using the SageMaker Python SDK, see :ref:`overview:Using the SageMaker Python SDK`. - -.. warning:: - Support for TensorFlow versions 1.4-1.10 has been deprecated. - For information on how to upgrade, see `Upgrade from Legacy TensorFlow Support `_. - -.. contents:: - -***************************** -Train a Model with TensorFlow -***************************** - -To train a TensorFlow model by using the SageMaker Python SDK: - -.. |create tf estimator| replace:: Create a ``sagemaker.tensorflow.TensorFlow estimator`` -.. _create tf estimator: #create-an-estimator - -.. |call fit| replace:: Call the estimator's ``fit`` method -.. _call fit: #call-the-fit-method - -1. `Prepare a training script <#prepare-a-training-script>`_ -2. |create tf estimator|_ -3. |call fit|_ - -Prepare a Training Script -========================= - -The training script is very similar to a training script you might run outside of SageMaker, but you can access useful properties about the training environment through various environment variables, including the following: - -* ``SM_MODEL_DIR``: A string that represents the local path where the training job writes the model artifacts to. - After training, artifacts in this directory are uploaded to S3 for model hosting. This is different than the ``model_dir`` - argument passed in your training script, which can be an S3 location. ``SM_MODEL_DIR`` is always set to ``/opt/ml/model``. -* ``SM_NUM_GPUS``: An integer representing the number of GPUs available to the host. -* ``SM_OUTPUT_DATA_DIR``: A string that represents the path to the directory to write output artifacts to. - Output artifacts might include checkpoints, graphs, and other files to save, but do not include model artifacts. - These artifacts are compressed and uploaded to S3 to an S3 bucket with the same prefix as the model artifacts. -* ``SM_CHANNEL_XXXX``: A string that represents the path to the directory that contains the input data for the specified channel. - For example, if you specify two input channels in the TensorFlow estimator's ``fit`` call, named 'train' and 'test', the environment variables ``SM_CHANNEL_TRAIN`` and ``SM_CHANNEL_TEST`` are set. - -For the exhaustive list of available environment variables, see the `SageMaker Containers documentation `_. - -A typical training script loads data from the input channels, configures training with hyperparameters, trains a model, and saves a model to ``SM_MODEL_DIR`` so that it can be deployed for inference later. -Hyperparameters are passed to your script as arguments and can be retrieved with an ``argparse.ArgumentParser`` instance. -For example, a training script might start with the following: - -.. code:: python - - import argparse - import os - - if __name__ =='__main__': - - parser = argparse.ArgumentParser() - - # hyperparameters sent by the client are passed as command-line arguments to the script. - parser.add_argument('--epochs', type=int, default=10) - parser.add_argument('--batch_size', type=int, default=100) - parser.add_argument('--learning_rate', type=float, default=0.1) - - # input data and model directories - parser.add_argument('--model_dir', type=str) - parser.add_argument('--train', type=str, default=os.environ.get('SM_CHANNEL_TRAIN')) - parser.add_argument('--test', type=str, default=os.environ.get('SM_CHANNEL_TEST')) - - args, _ = parser.parse_known_args() - - # ... load from args.train and args.test, train a model, write model to args.model_dir. - -Because the SageMaker imports your training script, putting your training launching code in a main guard (``if __name__=='__main__':``) -is good practice. - -Note that SageMaker doesn't support argparse actions. -For example, if you want to use a boolean hyperparameter, specify ``type`` as ``bool`` in your script and provide an explicit ``True`` or ``False`` value for this hyperparameter when you create the TensorFlow estimator. - -For a complete example of a TensorFlow training script, see `mnist.py `__. - - -Adapting your local TensorFlow script -------------------------------------- - -If you have a TensorFlow training script that runs outside of SageMaker, do the following to adapt the script to run in SageMaker: - -1. Make sure your script can handle ``--model_dir`` as an additional command line argument. If you did not specify a -location when you created the TensorFlow estimator, an S3 location under the default training job bucket is used. -Distributed training with parameter servers requires you to use the ``tf.estimator.train_and_evaluate`` API and -to provide an S3 location as the model directory during training. Here is an example: - -.. code:: python - - estimator = tf.estimator.Estimator(model_fn=my_model_fn, model_dir=args.model_dir) - ... - train_spec = tf.estimator.TrainSpec(train_input_fn, max_steps=1000) - eval_spec = tf.estimator.EvalSpec(eval_input_fn) - tf.estimator.train_and_evaluate(mnist_classifier, train_spec, eval_spec) - -2. Load input data from the input channels. The input channels are defined when ``fit`` is called. For example: - -.. code:: python - - estimator.fit({'train':'s3://my-bucket/my-training-data', - 'eval':'s3://my-bucket/my-evaluation-data'}) - -In your training script the channels will be stored in environment variables ``SM_CHANNEL_TRAIN`` and -``SM_CHANNEL_EVAL``. You can add them to your argument parsing logic like this: - -.. code:: python - - parser = argparse.ArgumentParser() - parser.add_argument('--train', type=str, default=os.environ.get('SM_CHANNEL_TRAIN')) - parser.add_argument('--eval', type=str, default=os.environ.get('SM_CHANNEL_EVAL')) - -3. Export your final model to path stored in environment variable ``SM_MODEL_DIR`` which should always be - ``/opt/ml/model``. At end of training SageMaker will upload the model file under ``/opt/ml/model`` to - ``output_path``. - - -Use third-party libraries -------------------------- - -If there are other packages you want to use with your script, you can use a ``requirements.txt`` to install other dependencies at runtime. - -For training, support for installing packages using ``requirements.txt`` varies by TensorFlow version as follows: - -- For TensorFlow 1.15.2 with Python 3.7 or newer, and TensorFlow 2.2 or newer: - - Include a ``requirements.txt`` file in the same directory as your training script. - - You must specify this directory using the ``source_dir`` argument when creating a TensorFlow estimator. -- For TensorFlow versions 1.11-1.15.2, 2.0-2.1 with Python 2.7 or 3.6: - - Write a shell script for your entry point that first calls ``pip install -r requirements.txt``, then runs your training script. - - For an example of using shell scripts, see `this example notebook `__. -- For legacy versions of TensorFlow: - - See `Upgrade from Legacy TensorFlow Support `_. - -For serving, support for installing packages using ``requirements.txt`` varies by TensorFlow version as follows: - -- For TensorFlow 1.11 or newer: - - Include a ``requirements.txt`` file in the ``code`` directory. -- For legacy versions of TensorFlow: - - See `Upgrade from Legacy TensorFlow Support `_. - -A ``requirements.txt`` file is a text file that contains a list of items that are installed by using ``pip install``. -You can also specify the version of an item to install. -For information about the format of a ``requirements.txt`` file, see `Requirements Files `__ in the pip documentation. - - -Create an Estimator -=================== - -After you create your training script, create an instance of the :class:`sagemaker.tensorflow.TensorFlow` estimator. - -To use Python 3.7, please specify both of the args: - -- ``py_version='py37'`` -- ``framework_version='1.15.2'`` - -.. code:: python - - from sagemaker.tensorflow import TensorFlow - - tf_estimator = TensorFlow( - entry_point="tf-train.py", - role="SageMakerRole", - instance_count=1, - instance_type="ml.p2.xlarge", - framework_version="2.2", - py_version="py37", - ) - tf_estimator.fit("s3://bucket/path/to/training/data") - -Where the S3 url is a path to your training data within Amazon S3. -The constructor keyword arguments define how SageMaker runs your training script. - -Specify a Docker image using an Estimator ------------------------------------------ - -There are use cases, such as extending an existing pre-built Amazon SageMaker images, that require specifing a Docker image when creating an Estimator by directly specifying the ECR URI instead of the Python and framework version. For a full list of available container URIs, see `Available Deep Learning Containers Images `__ For more information on using Docker containers, see `Use Your Own Algorithms or Models with Amazon SageMaker `__. - -When specifying the image, you must use the ``image_name=''`` arg to replace the following arg: - -- ``py_version=''`` - -You should still specify the ``framework_version=''`` arg because the SageMaker Python SDK accomodates for differences in the images based on the version. - -The following example uses the ``image_name=''`` arg to specify the container image, Python version, and framework version. - -.. code:: python - - tf_estimator = TensorFlow(entry_point='tf-train.py', - role='SageMakerRole', - train_instance_count=1, - train_instance_type='ml.p2.xlarge', - image_name='763104351884.dkr.ecr..amazonaws.com/-:---ubuntu18.04', - script_mode=True) - -For more information about the sagemaker.tensorflow.TensorFlow estimator, see `SageMaker TensorFlow Classes`_. - -Call the fit Method -=================== - -You start your training script by calling the ``fit`` method on a ``TensorFlow`` estimator. - -Calling ``fit`` starts a SageMaker training job. The training job will execute the following. - -- Starts ``instance_count`` EC2 instances of the type ``instance_type``. -- On each instance, it will do the following steps: - - - starts a Docker container optimized for TensorFlow. - - downloads the dataset. - - setup up training related environment varialbes - - setup up distributed training environment if configured to use parameter server - - starts asynchronous training - -If the ``wait=False`` flag is passed to ``fit``, then it returns immediately. The training job continues running -asynchronously. Later, a TensorFlow estimator can be obtained by attaching to the existing training job. -If the training job is not finished, it starts showing the standard output of training and wait until it completes. -After attaching, the estimator can be deployed as usual. - -.. code:: python - - tf_estimator.fit(your_input_data, wait=False) - training_job_name = tf_estimator.latest_training_job.name - - # after some time, or in a separate Python notebook, we can attach to it again. - - tf_estimator = TensorFlow.attach(training_job_name=training_job_name) - -For more information about the options available for ``fit``, see the `API documentation `_. - -Distributed Training -==================== - -To run your training job with multiple instances in a distributed fashion, set ``instance_count`` -to a number larger than 1. We support two different types of distributed training, parameter server and Horovod. -The ``distribution`` parameter is used to configure which distributed training strategy to use. - -Training with parameter servers -------------------------------- - -If you specify parameter_server as the value of the distribution parameter, the container launches a parameter server -thread on each instance in the training cluster, and then executes your training code. You can find more information on -TensorFlow distributed training at `TensorFlow docs `__. -To enable parameter server training: - -.. code:: python - - from sagemaker.tensorflow import TensorFlow - - tf_estimator = TensorFlow( - entry_point="tf-train.py", - role="SageMakerRole", - instance_count=2, - instance_type="ml.p2.xlarge", - framework_version="2.2", - py_version="py37", - distribution={"parameter_server": {"enabled": True}}, - ) - tf_estimator.fit("s3://bucket/path/to/training/data") - -Training with Horovod ---------------------- - -Horovod is a distributed training framework based on MPI. Horovod is only available with TensorFlow version ``1.12`` or newer. -You can find more details at `Horovod README `__. - -The container sets up the MPI environment and executes the ``mpirun`` command, enabling you to run any Horovod -training script. - -Training with ``MPI`` is configured by specifying following fields in ``distribution``: - -- ``enabled (bool)``: If set to ``True``, the MPI setup is performed and ``mpirun`` command is executed. -- ``processes_per_host (int)``: Number of processes MPI should launch on each host. Note, this should not be - greater than the available slots on the selected instance type. This flag should be set for the multi-cpu/gpu - training. -- ``custom_mpi_options (str)``: Any ``mpirun`` flag(s) can be passed in this field that will be added to the ``mpirun`` - command executed by SageMaker to launch distributed horovod training. - - -In the below example we create an estimator to launch Horovod distributed training with 4 processes on one host: - -.. code:: python - - from sagemaker.tensorflow import TensorFlow - - tf_estimator = TensorFlow( - entry_point="tf-train.py", - role="SageMakerRole", - instance_count=1, - instance_type="ml.p3.8xlarge", - framework_version="2.1.0", - py_version="py3", - distribution={ - "mpi": { - "enabled": True, - "processes_per_host": 4, - "custom_mpi_options": "--NCCL_DEBUG INFO" - }, - }, - ) - tf_estimator.fit("s3://bucket/path/to/training/data") - - -Training with Pipe Mode using PipeModeDataset -============================================= - -Amazon SageMaker allows users to create training jobs using Pipe input mode. -With Pipe input mode, your dataset is streamed directly to your training instances instead of being downloaded first. -This means that your training jobs start sooner, finish quicker, and need less disk space. - -SageMaker TensorFlow provides an implementation of ``tf.data.Dataset`` that makes it easy to take advantage of Pipe -input mode in SageMaker. You can replace your ``tf.data.Dataset`` with a ``sagemaker_tensorflow.PipeModeDataset`` to -read TFRecords as they are streamed to your training instances. - -In your ``entry_point`` script, you can use ``PipeModeDataset`` like a ``Dataset``. In this example, we create a -``PipeModeDataset`` to read TFRecords from the 'training' channel: - - -.. code:: python - - from sagemaker_tensorflow import PipeModeDataset - - features = { - 'data': tf.FixedLenFeature([], tf.string), - 'labels': tf.FixedLenFeature([], tf.int64), - } - - def parse(record): - parsed = tf.parse_single_example(record, features) - return ({ - 'data': tf.decode_raw(parsed['data'], tf.float64) - }, parsed['labels']) - - def train_input_fn(training_dir, hyperparameters): - ds = PipeModeDataset(channel='training', record_format='TFRecord') - ds = ds.repeat(20) - ds = ds.prefetch(10) - ds = ds.map(parse, num_parallel_calls=10) - ds = ds.batch(64) - return ds - - -To run training job with Pipe input mode, pass in ``input_mode='Pipe'`` to your TensorFlow Estimator: - - -.. code:: python - - from sagemaker.tensorflow import TensorFlow - - tf_estimator = TensorFlow( - entry_point="tf-train-with-pipemodedataset.py", - role="SageMakerRole", - training_steps=10000, - evaluation_steps=100, - instance_count=1, - instance_type="ml.p2.xlarge", - framework_version="1.10.0", - py_version="py3", - input_mode="Pipe", - ) - - tf_estimator.fit("s3://bucket/path/to/training/data") - - -If your TFRecords are compressed, you can train on Gzipped TF Records by passing in ``compression='Gzip'`` to the call to -``fit()``, and SageMaker will automatically unzip the records as data is streamed to your training instances: - -.. code:: python - - from sagemaker.inputs import TrainingInput - - train_s3_input = TrainingInput('s3://bucket/path/to/training/data', compression='Gzip') - tf_estimator.fit(train_s3_input) - - -You can learn more about ``PipeModeDataset`` in the sagemaker-tensorflow-extensions repository: https://github.com/aws/sagemaker-tensorflow-extensions - - -Training with MKL-DNN disabled -============================== - -SageMaker TensorFlow CPU images use TensorFlow built with Intel® MKL-DNN optimization. - -In certain cases you might be able to get a better performance by disabling this optimization -(for example when using small models). - -You can disable MKL-DNN optimization for TensorFlow ``1.8.0`` and above by setting two following environment variables: - -.. code:: python - - import os - - os.environ['TF_DISABLE_MKL'] = '1' - os.environ['TF_DISABLE_POOL_ALLOCATOR'] = '1' - -******************************** -Deploy TensorFlow Serving models -******************************** - -After a TensorFlow estimator has been fit, it saves a TensorFlow SavedModel in -the S3 location defined by ``output_path``. You can call ``deploy`` on a TensorFlow -estimator to create a SageMaker Endpoint, or you can call ``transformer`` to create a ``Transformer`` that you can use to run a batch transform job. - -Your model will be deployed to a TensorFlow Serving-based server. The server provides a super-set of the -`TensorFlow Serving REST API `_. - - -Deploy to a SageMaker Endpoint -============================== - -Deploying from an Estimator ---------------------------- - -After a TensorFlow estimator has been fit, it saves a TensorFlow -`SavedModel `_ bundle in -the S3 location defined by ``output_path``. You can call ``deploy`` on a TensorFlow -estimator object to create a SageMaker Endpoint: - -.. code:: python - - from sagemaker.tensorflow import TensorFlow - - estimator = TensorFlow( - entry_point="tf-train.py", - ..., - instance_count=1, - instance_type="ml.c4.xlarge", - framework_version="2.2", - py_version="py37", - ) - - estimator.fit(inputs) - - predictor = estimator.deploy(initial_instance_count=1, instance_type="ml.c5.xlarge") - - -The code block above deploys a SageMaker Endpoint with one instance of the type 'ml.c5.xlarge'. - -What happens when deploy is called -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Calling ``deploy`` starts the process of creating a SageMaker Endpoint. This process includes the following steps. - -- Starts ``initial_instance_count`` EC2 instances of the type ``instance_type``. -- On each instance, it will do the following steps: - - - start a Docker container optimized for TensorFlow Serving, see `SageMaker TensorFlow Serving containers `_. - - start a `TensorFlow Serving` process configured to run your model. - - start an HTTP server that provides access to TensorFlow Server through the SageMaker InvokeEndpoint API. - - -When the ``deploy`` call finishes, the created SageMaker Endpoint is ready for prediction requests. The -`Making predictions against a SageMaker Endpoint`_ section will explain how to make prediction requests -against the Endpoint. - -Deploying directly from model artifacts ---------------------------------------- - -If you already have existing model artifacts in S3, you can skip training and deploy them directly to an endpoint: - -.. code:: python - - from sagemaker.tensorflow import TensorFlowModel - - model = TensorFlowModel(model_data='s3://mybucket/model.tar.gz', role='MySageMakerRole') - - predictor = model.deploy(initial_instance_count=1, instance_type='ml.c5.xlarge') - -Python-based TensorFlow serving on SageMaker has support for `Elastic Inference `__, which allows for inference acceleration to a hosted endpoint for a fraction of the cost of using a full GPU instance. In order to attach an Elastic Inference accelerator to your endpoint provide the accelerator type to accelerator_type to your deploy call. - -.. code:: python - - from sagemaker.tensorflow import TensorFlowModel - - model = TensorFlowModel(model_data='s3://mybucket/model.tar.gz', role='MySageMakerRole') - - predictor = model.deploy(initial_instance_count=1, instance_type='ml.c5.xlarge', accelerator_type='ml.eia1.medium') - -Making predictions against a SageMaker Endpoint ------------------------------------------------ - -Once you have the ``Predictor`` instance returned by ``model.deploy(...)`` or ``estimator.deploy(...)``, you -can send prediction requests to your Endpoint. - -The following code shows how to make a prediction request: - -.. code:: python - - input = { - 'instances': [1.0, 2.0, 5.0] - } - result = predictor.predict(input) - -The result object will contain a Python dict like this: - -.. code:: python - - { - 'predictions': [3.5, 4.0, 5.5] - } - -The formats of the input and the output data correspond directly to the request and response formats -of the ``Predict`` method in the `TensorFlow Serving REST API `_. - -If your SavedModel includes the right ``signature_def``, you can also make Classify or Regress requests: - -.. code:: python - - # input matches the Classify and Regress API - input = { - 'signature_name': 'tensorflow/serving/regress', - 'examples': [{'x': 1.0}, {'x': 2.0}] - } - - result = predictor.regress(input) # or predictor.classify(...) - - # result contains: - { - 'results': [3.5, 4.0] - } - -You can include multiple ``instances`` in your predict request (or multiple ``examples`` in -classify/regress requests) to get multiple prediction results in one request to your Endpoint: - -.. code:: python - - input = { - 'instances': [ - [1.0, 2.0, 5.0], - [1.0, 2.0, 5.0], - [1.0, 2.0, 5.0] - ] - } - result = predictor.predict(input) - - # result contains: - { - 'predictions': [ - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5] - ] - } - -If your application allows request grouping like this, it is **much** more efficient than making separate requests. - -See `Deploying to TensorFlow Serving Endpoints `_ to learn how to deploy your model and make inference requests. - -Run a Batch Transform Job -========================= - -Batch transform allows you to get inferences for an entire dataset that is stored in an S3 bucket. - -For general information about using batch transform with the SageMaker Python SDK, see :ref:`overview:SageMaker Batch Transform`. -For information about SageMaker batch transform, see `Get Inferences for an Entire Dataset with Batch Transform ` in the AWS documentation. - -To run a batch transform job, you first create a ``Transformer`` object, and then call that object's ``transform`` method. - -Create a Transformer Object ---------------------------- - -If you used an estimator to train your model, you can call the ``transformer`` method of the estimator to create a ``Transformer`` object. - -For example: - -.. code:: python - - bucket = myBucket # The name of the S3 bucket where the results are stored - prefix = 'batch-results' # The folder in the S3 bucket where the results are stored - - batch_output = 's3://{}/{}/results'.format(bucket, prefix) # The location to store the results - - tf_transformer = tf_estimator.transformer(instance_count=1, instance_type='ml.m4.xlarge', output_path=batch_output) - -To use a model trained outside of SageMaker, you can package the model as a SageMaker model, and call the ``transformer`` method of the SageMaker model. - -For example: - -.. code:: python - - bucket = myBucket # The name of the S3 bucket where the results are stored - prefix = 'batch-results' # The folder in the S3 bucket where the results are stored - - batch_output = 's3://{}/{}/results'.format(bucket, prefix) # The location to store the results - - tf_transformer = tensorflow_serving_model.transformer(instance_count=1, instance_type='ml.m4.xlarge', output_path=batch_output) - -For information about how to package a model as a SageMaker model, see :ref:`overview:BYO Model`. -When you call the ``tranformer`` method, you specify the type and number of instances to use for the batch transform job, and the location where the results are stored in S3. - - - -Call transform --------------- - -After you create a ``Transformer`` object, you call that object's ``transform`` method to start a batch transform job. -For example: - -.. code:: python - - batch_input = 's3://{}/{}/test/examples'.format(bucket, prefix) # The location of the input dataset - - tf_transformer.transform(data=batch_input, data_type='S3Prefix', content_type='text/csv', split_type='Line') - -In the example, the content type is CSV, and each line in the dataset is treated as a record to get a predition for. - -Batch Transform Supported Data Formats --------------------------------------- - -When you call the ``tranform`` method to start a batch transform job, -you specify the data format by providing a MIME type as the value for the ``content_type`` parameter. - -The following content formats are supported without custom intput and output handling: - -* CSV - specify ``text/csv`` as the value of the ``content_type`` parameter. -* JSON - specify ``application/json`` as the value of the ``content_type`` parameter. -* JSON lines - specify ``application/jsonlines`` as the value of the ``content_type`` parameter. - -For detailed information about how TensorFlow Serving formats these data types for input and output, see :ref:`tensorflow-serving-input-output`. - -You can also accept any custom data format by writing input and output functions, and include them in the ``inference.py`` file in your model. -For information, see :ref:`custom-input-output`. - - -.. _tensorflow-serving-input-output: - -TensorFlow Serving Input and Output -=================================== - -The following sections describe the data formats that TensorFlow Serving endpoints and batch transform jobs accept, -and how to write input and output functions to input and output custom data formats. - -Supported Formats ------------------ - -SageMaker's TensforFlow Serving endpoints can also accept some additional input formats that are not part of the -TensorFlow REST API, including a simplified json format, line-delimited json objects ("jsons" or "jsonlines"), and -CSV data. - -Simplified JSON Input -^^^^^^^^^^^^^^^^^^^^^ - -The Endpoint will accept simplified JSON input that doesn't match the TensorFlow REST API's Predict request format. -When the Endpoint receives data like this, it will attempt to transform it into a valid -Predict request, using a few simple rules: - -- python value, dict, or one-dimensional arrays are treated as the input value in a single 'instance' Predict request. -- multidimensional arrays are treated as a multiple values in a multi-instance Predict request. - -Combined with the client-side ``Predictor`` object's JSON serialization, this allows you to make simple -requests like this: - -.. code:: python - - input = [ - [1.0, 2.0, 5.0], - [1.0, 2.0, 5.0] - ] - result = predictor.predict(input) - - # result contains: - { - 'predictions': [ - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5] - ] - } - -Or this: - -.. code:: python - - # 'x' must match name of input tensor in your SavedModel graph - # for models with multiple named inputs, just include all the keys in the input dict - input = { - 'x': [1.0, 2.0, 5.0] - } - - # result contains: - { - 'predictions': [ - [3.5, 4.0, 5.5] - ] - } - - -Line-delimited JSON -^^^^^^^^^^^^^^^^^^^ - -The Endpoint will accept line-delimited JSON objects (also known as "jsons" or "jsonlines" data). -The Endpoint treats each line as a separate instance in a multi-instance Predict request. To use -this feature from your python code, you need to create a ``Predictor`` instance that does not -try to serialize your input to JSON: - -.. code:: python - - # create a Predictor without JSON serialization - - predictor = Predictor('endpoint-name', serializer=None, content_type='application/jsonlines') - - input = '''{'x': [1.0, 2.0, 5.0]} - {'x': [1.0, 2.0, 5.0]} - {'x': [1.0, 2.0, 5.0]}''' - - result = predictor.predict(input) - - # result contains: - { - 'predictions': [ - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5] - ] - } - -This feature is especially useful if you are reading data from a file containing jsonlines data. - -**CSV (comma-separated values)** - -The Endpoint will accept CSV data. Each line is treated as a separate instance. This is a -compact format for representing multiple instances of 1-d array data. To use this feature -from your python code, you need to create a ``Predictor`` instance that can serialize -your input data to CSV format: - -.. code:: python - - # create a Predictor with JSON serialization - - predictor = Predictor('endpoint-name', serializer=sagemaker.serializers.CSVSerializer()) - - # CSV-formatted string input - input = '1.0,2.0,5.0\n1.0,2.0,5.0\n1.0,2.0,5.0' - - result = predictor.predict(input) - - # result contains: - { - 'predictions': [ - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5], - [3.5, 4.0, 5.5] - ] - } - -You can also use python arrays or numpy arrays as input and let the ``CSVSerializer`` object -convert them to CSV, but the client-size CSV conversion is more sophisticated than the -CSV parsing on the Endpoint, so if you encounter conversion problems, try using one of the -JSON options instead. - -.. _custom-input-output: - -Create Python Scripts for Custom Input and Output Formats ---------------------------------------------------------- - -You can add your customized Python code to process your input and output data. -This customized Python code must be named ``inference.py`` and is specified through the ``entry_point`` parameter: - -.. code:: - - from sagemaker.tensorflow import TensorFlowModel - - model = TensorFlowModel(entry_point='inference.py', - model_data='s3://mybucket/model.tar.gz', - role='MySageMakerRole') - -In the example above, ``inference.py`` is assumed to be a file inside ``model.tar.gz``. If you want to use a local file instead, you must add the ``source_dir`` argument. See the documentation on `TensorFlowModel `_. - -How to implement the pre- and/or post-processing handler(s) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Your entry point file must be named ``inference.py`` and should implement -either a pair of ``input_handler`` and ``output_handler`` functions or -a single ``handler`` function. -Note that if ``handler`` function is implemented, ``input_handler`` -and ``output_handler`` are ignored. - -To implement pre- and/or post-processing handler(s), use the Context -object that the Python service creates. The Context object is a namedtuple with the following attributes: - -- ``model_name (string)``: the name of the model to use for - inference. For example, 'half-plus-three' - -- ``model_version (string)``: version of the model. For example, '5' - -- ``method (string)``: inference method. For example, 'predict', - 'classify' or 'regress', for more information on methods, please see - `Classify and Regress - API `__ - and `Predict - API `__ - -- ``rest_uri (string)``: the TFS REST uri generated by the Python - service. For example, - 'http://localhost:8501/v1/models/half_plus_three:predict' - -- ``grpc_uri (string)``: the GRPC port number generated by the Python - service. For example, '9000' - -- ``custom_attributes (string)``: content of - 'X-Amzn-SageMaker-Custom-Attributes' header from the original - request. For example, - 'tfs-model-name=half*plus*\ three,tfs-method=predict' - -- ``request_content_type (string)``: the original request content type, - defaulted to 'application/json' if not provided - -- ``accept_header (string)``: the original request accept type, - defaulted to 'application/json' if not provided - -- ``content_length (int)``: content length of the original request - -The following code example implements ``input_handler`` and -``output_handler``. By providing these, the Python service posts the -request to the TFS REST URI with the data pre-processed by ``input_handler`` -and passes the response to ``output_handler`` for post-processing. - -.. code:: - - import json - - def input_handler(data, context): - """ Pre-process request input before it is sent to TensorFlow Serving REST API - Args: - data (obj): the request data, in format of dict or string - context (Context): an object containing request and configuration details - Returns: - (dict): a JSON-serializable dict that contains request body and headers - """ - if context.request_content_type == 'application/json': - # pass through json (assumes it's correctly formed) - d = data.read().decode('utf-8') - return d if len(d) else '' - - if context.request_content_type == 'text/csv': - # very simple csv handler - return json.dumps({ - 'instances': [float(x) for x in data.read().decode('utf-8').split(',')] - }) - - raise ValueError('{{"error": "unsupported content type {}"}}'.format( - context.request_content_type or "unknown")) - - - def output_handler(data, context): - """Post-process TensorFlow Serving output before it is returned to the client. - Args: - data (obj): the TensorFlow serving response - context (Context): an object containing request and configuration details - Returns: - (bytes, string): data to return to client, response content type - """ - if data.status_code != 200: - raise ValueError(data.content.decode('utf-8')) - - response_content_type = context.accept_header - prediction = data.content - return prediction, response_content_type - -You might want to have complete control over the request. -For example, you might want to make a TFS request (REST or GRPC) to the first model, -inspect the results, and then make a request to a second model. In this case, implement -the ``handler`` method instead of the ``input_handler`` and ``output_handler`` methods, as demonstrated -in the following code: - -.. code:: - - import json - import requests - - - def handler(data, context): - """Handle request. - Args: - data (obj): the request data - context (Context): an object containing request and configuration details - Returns: - (bytes, string): data to return to client, (optional) response content type - """ - processed_input = _process_input(data, context) - response = requests.post(context.rest_uri, data=processed_input) - return _process_output(response, context) - - - def _process_input(data, context): - if context.request_content_type == 'application/json': - # pass through json (assumes it's correctly formed) - d = data.read().decode('utf-8') - return d if len(d) else '' - - if context.request_content_type == 'text/csv': - # very simple csv handler - return json.dumps({ - 'instances': [float(x) for x in data.read().decode('utf-8').split(',')] - }) - - raise ValueError('{{"error": "unsupported content type {}"}}'.format( - context.request_content_type or "unknown")) - - - def _process_output(data, context): - if data.status_code != 200: - raise ValueError(data.content.decode('utf-8')) - - response_content_type = context.accept_header - prediction = data.content - return prediction, response_content_type - -You can also bring in external dependencies to help with your data -processing. There are 2 ways to do this: - -1. If your model archive contains ``code/requirements.txt``, the container will install the Python dependencies at runtime using ``pip install -r``. - -.. code:: - - from sagemaker.tensorflow import TensorFlowModel - - model = TensorFlowModel(entry_point='inference.py', - dependencies=['requirements.txt'], - model_data='s3://mybucket/model.tar.gz', - role='MySageMakerRole') - - -2. If you are working in a network-isolation situation or if you don't - want to install dependencies at runtime every time your endpoint starts or a batch - transform job runs, you might want to put - pre-downloaded dependencies under a ``lib`` directory and this - directory as dependency. The container adds the modules to the Python - path. Note that if both ``lib`` and ``requirements.txt`` - are present in the model archive, the ``requirements.txt`` is ignored: - -.. code:: - - from sagemaker.tensorflow import TensorFlowModel - - model = TensorFlowModel(entry_point='inference.py', - dependencies=['/path/to/folder/named/lib'], - model_data='s3://mybucket/model.tar.gz', - role='MySageMakerRole') - -For more information, see: https://github.com/aws/sagemaker-tensorflow-serving-container#prepost-processing - -**************************** -SageMaker TensorFlow Classes -**************************** - -For information about the different TensorFlow-related classes in the SageMaker Python SDK, see https://sagemaker.readthedocs.io/en/stable/sagemaker.tensorflow.html. - -************************************** -SageMaker TensorFlow Docker containers -************************************** - -For information about the SageMaker TensorFlow containers, see: - -- `SageMaker TensorFlow training toolkit `_ -- `SageMaker TensorFlow serving toolkit `_ -- `Deep Learning Container (DLC) Dockerfiles for TensorFlow `_ -- `Deep Learning Container (DLC) Images `_ and `release notes `_ diff --git a/doc/frameworks/xgboost/index.rst b/doc/frameworks/xgboost/index.rst deleted file mode 100644 index d81a74cc09..0000000000 --- a/doc/frameworks/xgboost/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -########################## -XGBoost -########################## - -.. toctree:: - :maxdepth: 1 - :glob: - - * diff --git a/doc/frameworks/xgboost/using_xgboost.rst b/doc/frameworks/xgboost/using_xgboost.rst deleted file mode 100644 index 2c6c53b6a8..0000000000 --- a/doc/frameworks/xgboost/using_xgboost.rst +++ /dev/null @@ -1,474 +0,0 @@ -######################################### -Use XGBoost with the SageMaker Python SDK -######################################### - -.. contents:: - -eXtreme Gradient Boosting (XGBoost) is a popular and efficient machine learning algorithm used for regression and classification tasks on tabular datasets. -It implements a technique known as gradient boosting on trees, which performs remarkably well in machine learning competitions. - -Amazon SageMaker supports two ways to use the XGBoost algorithm: - - * XGBoost built-in algorithm - * XGBoost open source algorithm - -The XGBoost open source algorithm provides the following benefits over the built-in algorithm: - -* Latest version - The open source XGBoost algorithm typically supports a more recent version of XGBoost. - To see the XGBoost version that is currently supported, - see `XGBoost SageMaker Estimators and Models `__. -* Flexibility - Take advantage of the full range of XGBoost functionality, such as cross-validation support. - You can add custom pre- and post-processing logic and run additional code after training. -* Scalability - The XGBoost open source algorithm has a more efficient implementation of distributed training, - which enables it to scale out to more instances and reduce out-of-memory errors. -* Extensibility - Because the open source XGBoost container is open source, - you can extend the container to install additional libraries and change the version of XGBoost that the container uses. - For an example notebook that shows how to extend SageMaker containers, see `Extending our PyTorch containers `__. - - -*********************************** -Use XGBoost as a Built-in Algortihm -*********************************** - -Amazon SageMaker provides XGBoost as a built-in algorithm that you can use like other built-in algorithms. -Using the built-in algorithm version of XGBoost is simpler than using the open source version, because you don't have to write a training script. -If you don't need the features and flexibility of open source XGBoost, consider using the built-in version. -For information about using the Amazon SageMaker XGBoost built-in algorithm, see `XGBoost Algorithm `__ -in the *Amazon SageMaker Developer Guide*. - -************************************* -Use the Open Source XGBoost Algorithm -************************************* - -If you want the flexibility and additional features that it provides, use the SageMaker open source XGBoost algorithm. - -For which XGBoost versions are supported, see `the AWS documentation `_. -We recommend that you use the latest supported version because that's where we focus most of our development efforts. - -For a complete example of using the open source XGBoost algorithm, see the sample notebook at -https://github.com/awslabs/amazon-sagemaker-examples/blob/master/introduction_to_amazon_algorithms/xgboost_abalone/xgboost_abalone_dist_script_mode.ipynb. - -For more information about XGBoost, see `the XGBoost documentation `_. - -Train a Model with Open Source XGBoost -====================================== - -To train a model by using the Amazon SageMaker open source XGBoost algorithm: - -.. |create xgboost estimator| replace:: Create a ``sagemaker.xgboost.XGBoost estimator`` -.. _create xgboost estimator: #create-an-estimator - -.. |call fit| replace:: Call the estimator's ``fit`` method -.. _call fit: #call-the-fit-method - -1. `Prepare a training script <#prepare-a-training-script>`_ -2. |create xgboost estimator|_ -3. |call fit|_ - -Prepare a Training Script -------------------------- - -A typical training script loads data from the input channels, configures training with hyperparameters, trains a model, -and saves a model to ``model_dir`` so that it can be hosted later. -Hyperparameters are passed to your script as arguments and can be retrieved with an ``argparse.ArgumentParser`` instance. -For information about ``argparse.ArgumentParser``, see `argparse `__ in the Python documentation. - - -For a complete example of an XGBoost training script, see https://github.com/awslabs/amazon-sagemaker-examples/blob/master/introduction_to_amazon_algorithms/xgboost_abalone/abalone.py. - -The training script is very similar to a training script you might run outside of Amazon SageMaker, -but you can access useful properties about the training environment through various environment variables, including the following: - -* ``SM_MODEL_DIR``: A string that represents the path where the training job writes the model artifacts to. - After training, artifacts in this directory are uploaded to Amazon S3 for model hosting. -* ``SM_NUM_GPUS``: An integer representing the number of GPUs available to the host. -* ``SM_CHANNEL_XXXX``: A string that represents the path to the directory that contains the input data for the specified channel. - For example, if you specify two input channels in the MXNet estimator's ``fit`` call, named 'train' and 'test', the environment variables ``SM_CHANNEL_TRAIN`` and ``SM_CHANNEL_TEST`` are set. -* ``SM_HPS``: A JSON dump of the hyperparameters preserving JSON types (boolean, integer, etc.) - -For the exhaustive list of available environment variables, see the `SageMaker Containers documentation `__. - -.. important:: - The sagemaker-containers repository has been deprecated, - however it is still used to define Scikit-learn and XGBoost environment variables. - -Let's look at the main elements of the script. Starting with the ``__main__`` guard, -use a parser to read the hyperparameters passed to the estimator when creating the training job. -These hyperparameters are made available as arguments to our input script. -We also parse a number of Amazon SageMaker-specific environment variables to get information about the training environment, -such as the location of input data and location where we want to save the model. - -.. code:: python - - if __name__ == '__main__': - parser = argparse.ArgumentParser() - - # Hyperparameters are described here - parser.add_argument('--num_round', type=int) - parser.add_argument('--max_depth', type=int, default=5) - parser.add_argument('--eta', type=float, default=0.2) - parser.add_argument('--objective', type=str, default='reg:squarederror') - - # SageMaker specific arguments. Defaults are set in the environment variables. - parser.add_argument('--model_dir', type=str, default=os.environ.get('SM_MODEL_DIR')) - parser.add_argument('--train', type=str, default=os.environ['SM_CHANNEL_TRAIN']) - parser.add_argument('--validation', type=str, default=os.environ['SM_CHANNEL_VALIDATION']) - - args = parser.parse_args() - - train_hp = { - 'max_depth': args.max_depth, - 'eta': args.eta, - 'gamma': args.gamma, - 'min_child_weight': args.min_child_weight, - 'subsample': args.subsample, - 'silent': args.silent, - 'objective': args.objective - } - - dtrain = xgb.DMatrix(args.train) - dval = xgb.DMatrix(args.validation) - watchlist = [(dtrain, 'train'), (dval, 'validation')] if dval is not None else [(dtrain, 'train')] - - callbacks = [] - prev_checkpoint, n_iterations_prev_run = add_checkpointing(callbacks) - # If checkpoint is found then we reduce num_boost_round by previously run number of iterations - - bst = xgb.train( - params=train_hp, - dtrain=dtrain, - evals=watchlist, - num_boost_round=(args.num_round - n_iterations_prev_run), - xgb_model=prev_checkpoint, - callbacks=callbacks - ) - - # Save the model to the location specified by ``model_dir`` - model_location = args.model_dir + '/xgboost-model' - pkl.dump(bst, open(model_location, 'wb')) - logging.info("Stored trained model at {}".format(model_location)) - -Create an Estimator -------------------- -After you create your training script, create an instance of the :class:`sagemaker.xgboost.estimator.XGBoost` estimator. -Pass an IAM role that has the permissions necessary to run an Amazon SageMaker training job, -the type and number of instances to use for the training job, -and a dictionary of the hyperparameters to pass to the training script. - -.. code:: - - from sagemaker.xgboost.estimator import XGBoost - - xgb_estimator = XGBoost( - entry_point="abalone.py", - hyperparameters=hyperparameters, - role=role, - instance_count=1, - instance_type="ml.m5.2xlarge", - framework_version="1.0-1", - ) - - -Call the fit Method -------------------- - -After you create an estimator, call the ``fit`` method to run the training job. - -.. code:: - - xgb_script_mode_estimator.fit({"train": train_input}) - - - -Deploy Open Source XGBoost Models -================================= - -After you fit an XGBoost Estimator, you can host the newly created model in SageMaker. - -After you call ``fit``, you can call ``deploy`` on an ``XGBoost`` estimator to create a SageMaker endpoint. -The endpoint runs a SageMaker-provided XGBoost model server and hosts the model produced by your training script, -which was run when you called ``fit``. This was the model you saved to ``model_dir``. - -``deploy`` returns a ``Predictor`` object, which you can use to do inference on the Endpoint hosting your XGBoost model. -Each ``Predictor`` provides a ``predict`` method which can do inference with numpy arrays, Python lists, or strings. -After inference arrays or lists are serialized and sent to the XGBoost model server, ``predict`` returns the result of -inference against your model. - -.. code:: - - serializer = StringSerializer(content_type="text/libsvm") - - predictor = estimator.deploy( - initial_instance_count=1, - instance_type="ml.m5.xlarge", - serializer=serializer - ) - - with open("abalone") as f: - payload = f.read() - - predictor.predict(payload) - -SageMaker XGBoost Model Server ------------------------------------ - -You can configure two components of the SageMaker XGBoost model server: Model loading and model serving. -Model loading is the process of deserializing your saved model back into an XGBoost model. -Model serving is the process of translating endpoint requests to inference calls on the loaded model. - -You configure the XGBoost model server by defining functions in the Python source file you passed to the XGBoost constructor. - -Load a Model -^^^^^^^^^^^^ - -Before a model can be served, it must be loaded. The SageMaker XGBoost model server loads your model by invoking a -``model_fn`` function that you must provide in your script. The ``model_fn`` should have the following signature: - -.. code:: python - - def model_fn(model_dir) - -SageMaker will inject the directory where your model files and sub-directories, saved by ``save``, have been mounted. -Your model function should return a ``xgboost.Booster`` object that can be used for model serving. - -The following code-snippet shows an example ``model_fn`` implementation. -It loads and returns a pickled XGBoost model from a ``xgboost-model`` file in the SageMaker model directory ``model_dir``. - -.. code:: python - - import pickle as pkl - - def model_fn(model_dir): - with open(os.path.join(model_dir, "xgboost-model"), "rb") as f: - booster = pkl.load(f) - return booster - -Serve a Model -^^^^^^^^^^^^^ - -After the SageMaker model server has loaded your model by calling ``model_fn``, SageMaker will serve your model. -The SageMaker Scikit-learn model server breaks request handling into three steps: - -- input processing, -- prediction, and -- output processing. - -In a similar way to model loading, you can customize the inference behavior by defining functions in your inference -script, which can be either in the same file as your training script or in a separate file, - -Each step involves invoking a python function, with information about the request and the return-value from the previous -function in the chain. -Inside the SageMaker XGBoost model server, the process looks like: - -.. code:: python - - # Deserialize the Invoke request body into an object we can perform prediction on - input_object = input_fn(request_body, request_content_type) - - # Perform prediction on the deserialized object, with the loaded model - prediction = predict_fn(input_object, model) - - # Serialize the prediction result into the desired response content type - output = output_fn(prediction, response_content_type) - -The above code-sample shows the three function definitions: - -- ``input_fn``: Takes request data and deserializes the data into an object for prediction. -- ``predict_fn``: Takes the deserialized request object and performs inference against the loaded model. -- ``output_fn``: Takes the result of prediction and serializes this according to the response content type. - -These functions are optional. -The SageMaker XGBoost model server provides default implementations of these functions. -You can provide your own implementations for these functions in your hosting script. -If you omit any definition then the SageMaker XGBoost model server will use its default implementation for that -function. - -In the following sections we describe the default implementations of ``input_fn``, ``predict_fn``, and ``output_fn``. -We describe the input arguments and expected return types of each, so you can define your own implementations. - -Process Input -""""""""""""" - -When a request is made against an endpoint running a SageMaker XGBoost model server, the model server receives two -pieces of information: - -- The request Content-Type, for example "application/x-npy" or "text/libsvm" -- The request data body, a byte array - -The SageMaker XGBoost model server will invoke an ``input_fn`` function in your inference script, passing in this -information. If you define an ``input_fn`` function definition, it should return an object that can be passed -to ``predict_fn`` and have the following signature: - -.. code:: python - - def input_fn(request_body, request_content_type) - -where ``request_body`` is a byte buffer and ``request_content_type`` is a Python string. - -The SageMaker XGBoost model server provides a default implementation of ``input_fn``. -This function deserializes CSV, LIBSVM, or protobuf recordIO into a ``xgboost.DMatrix``. - -Default csv deserialization requires ``request_body`` contain one or more lines of CSV numerical data. -The data is first loaded into a two-dimensional array, where each line break defines the boundaries of the first -dimension, and then it is converted to an `xgboost.Dmatrix`. It assumes that CSV input does not have the -label column. - -Default LIBSVM deserialization requires ``request_body`` to follow the `LIBSVM `_ format. - -The example below shows a custom ``input_fn`` for preparing pickled NumPy arrays. - -.. code:: python - - from io import BytesIO - import numpy as np - import xgboost as xgb - - def input_fn(request_body, request_content_type): - """An input_fn that loads a numpy array""" - if request_content_type == "application/npy": - array = np.load(BytesIO(request_body)) - return xgb.DMatrix(array) - else: - # Handle other content-types here or raise an Exception - # if the content type is not supported. - pass - -Get Predictions -""""""""""""""" - -After the inference request has been deserialized by ``input_fn``, the SageMaker XGBoost model server invokes -``predict_fn`` on the return value of ``input_fn``. - -As with ``input_fn``, you can define your own ``predict_fn`` or use the SageMaker XGBoost model server default. - -The ``predict_fn`` function has the following signature: - -.. code:: python - - def predict_fn(input_object, model) - -Where ``input_object`` is the object returned from ``input_fn`` and ``model`` is the model loaded by ``model_fn``. - -The default implementation of ``predict_fn`` invokes the loaded model's ``predict`` function on ``input_object``, -and returns the resulting value. The return-type should be a NumPy array to be compatible with the default -``output_fn``. - -The example below shows an overriden ``predict_fn`` that returns a two-dimensional NumPy array where -the first columns are predictions and the remaining columns are the feature contributions -(`SHAP values `_) for that prediction. -When ``pred_contribs`` is ``True`` in ``xgboost.Booster.predict()``, the output will be a matrix of size -(nsample, nfeats + 1) with each record indicating the feature contributions for that prediction. -Note the final column is the bias term. - -.. code:: python - - import numpy as np - - def predict_fn(input_data, model): - prediction = model.predict(input_data) - feature_contribs = model.predict(input_data, pred_contribs=True) - output = np.hstack((prediction[:, np.newaxis], feature_contribs)) - return output - -If you implement your own prediction function, you should take care to ensure that: - -- The first argument is expected to be the return value from input_fn. -- The second argument is the loaded model. -- The return value should be of the correct type to be passed as the first argument to ``output_fn``. - If you use the default ``output_fn``, this should be a NumPy array. - -Process Output -"""""""""""""" - -After invoking ``predict_fn``, the model server invokes ``output_fn``, passing in the return value from -``predict_fn`` and the requested response content-type. - -The ``output_fn`` has the following signature: - -.. code:: python - - def output_fn(prediction, content_type) - -``prediction`` is the result of invoking ``predict_fn`` and ``content_type`` is the requested response content-type. -The function should return a byte array of data serialized to ``content_type``. - -The default implementation expects ``prediction`` to be a NumPy array and can serialize the result to JSON, CSV, or NPY. -It accepts response content types of "application/json", "text/csv", and "application/x-npy". - -Bring Your Own Model --------------------- - -You can deploy an XGBoost model that you trained outside of SageMaker by using the Amazon SageMaker XGBoost container. -Typically, you save an XGBoost model by pickling the ``Booster`` object or calling ``booster.save_model``. -The XGBoost `built-in algorithm mode `_ -supports both a pickled ``Booster`` object and a model produced by ``booster.save_model``. -You can also deploy an XGBoost model by using XGBoost as a framework. -By using XGBoost as a framework, you have more flexibility. -To deploy an XGBoost model by using XGBoost as a framework, you need to: - -- Write an inference script. -- Create the XGBoostModel object. - -Write an Inference Script -^^^^^^^^^^^^^^^^^^^^^^^^^ - -You must create an inference script that implements (at least) the ``model_fn`` function that calls the loaded model to get a prediction. - -Optionally, you can also implement ``input_fn`` and ``output_fn`` to process input and output, -and ``predict_fn`` to customize how the model server gets predictions from the loaded model. -For information about how to write an inference script, see `SageMaker XGBoost Model Server <#sagemaker-xgboost-model-server>`_. -Pass the filename of the inference script as the ``entry_point`` parameter when you create the `XGBoostModel` object. - -Create an XGBoostModel Object -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To create a model object, call the ``sagemaker.xgboost.model.XGBoostModel`` constructor, -and then call its ``deploy()`` method to deploy your model for inference. - -.. code:: python - - xgboost_model = XGBoostModel( - model_data="s3://my-bucket/my-path/model.tar.gz", - role="my-role", - entry_point="inference.py", - framework_version="1.0-1" - ) - - predictor = xgboost_model.deploy( - instance_type='ml.c4.xlarge', - initial_instance_count=1 - ) - - # If payload is a string in LIBSVM format, we need to change serializer. - predictor.serializer = str - predictor.predict("