.. image:: https://github.com/aws/sagemaker-python-sdk/raw/master/branding/icon/sagemaker-banner.png :height: 100px :alt: SageMaker

==================== SageMaker Python SDK

.. image:: https://img.shields.io/pypi/v/sagemaker.svg :target: https://pypi.python.org/pypi/sagemaker :alt: 最新版本

.. image:: https://img.shields.io/pypi/pyversions/sagemaker.svg :target: https://pypi.python.org/pypi/sagemaker :alt: 支持的 Python 版本

.. image:: https://img.shields.io/badge/code_style-black-000000.svg :target: https://github.com/python/black :alt: 代码风格：black

.. image:: https://readthedocs.org/projects/sagemaker/badge/?version=stable :target: https://sagemaker.readthedocs.io/en/stable/ :alt: 文档状态

.. image:: https://github.com/aws/sagemaker-python-sdk/actions/workflows/codebuild-ci-health.yml/badge.svg :target: https://github.com/aws/sagemaker-python-sdk/actions/workflows/codebuild-ci-health.yml :alt: CI 健康状况

SageMaker Python SDK 是一个开源库，用于在 Amazon SageMaker 上训练和部署机器学习模型。

借助该 SDK，您可以使用流行的深度学习框架 Apache MXNet 和 PyTorch 来训练和部署模型。 您还可以使用 Amazon 算法 训练和部署模型， 这些算法是核心机器学习算法的可扩展实现，专为 SageMaker 和 GPU 训练进行了优化。 如果您拥有构建在与 SageMaker 兼容的 Docker 容器中的 自定义算法，也可以使用它们来训练和托管模型。

要安装 SageMaker Python SDK，请参阅 安装 SageMaker Python SDK <#installing-the-sagemaker-python-sdk>_。

❗🔥 SageMaker V3 发布

版本 3.0.0 是我们产品发展的一个重要里程碑。此次重大发布引入了现代化架构、性能提升以及强大的新功能，同时继续致力于提供卓越的用户体验和可靠性。

重要提示：请在升级前查看这些破坏性更改。

• 较旧的接口，如 Estimator、Model、Predictor 及其所有子类，在 V3 中将不再支持。
• 请参阅我们的 V3 示例文件夹 <https://github.com/aws/sagemaker-python-sdk/tree/master/v3-examples>__，以获取示例笔记本和使用模式。

迁移到 V3

升级到 3.x

要升级到最新版本的 SageMaker Python SDK 3.x：

::

pip install --upgrade sagemaker

如果您希望降级到 2.x 版本：

::

pip install sagemaker==2.*

请参阅 SageMaker V2 示例 <#sagemaker-v2-examples>__ 以获取 V2 的文档和示例。

3.x 的主要优势

• 模块化架构：核心、训练和推理功能分别由独立的 PyPI 包提供

  • sagemaker-core <https://pypi.org/project/sagemaker-core/>__
  • sagemaker-train <https://pypi.org/project/sagemaker-train/>__
  • sagemaker-serve <https://pypi.org/project/sagemaker-serve/>__
  • sagemaker-mlops <https://pypi.org/project/sagemaker-mlops/>__

• 统一的训练与推理：单个类（ModelTrainer、ModelBuilder）取代了多个框架特定的类

• 面向对象的 API：结构化的接口，自动生成与 AWS API 对齐的配置

• 简化的工作流程：减少了样板代码，界面更加直观

训练体验

V3 引入了统一的 ModelTrainer 类，以降低模型训练初始设置和部署的复杂性。这取代了 V2 中的 Estimator 类以及框架特定的类（PyTorchEstimator、SKLearnEstimator 等）。

此示例展示了如何使用自定义训练容器，并从 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])

更多示例： SageMaker V3 示例 <#sagemaker-v3-examples>__

推理体验

V3 引入了统一的 ModelBuilder 类，用于模型部署和推理。这取代了 V2 中的 Model 类以及框架特定的类（PyTorchModel、TensorFlowModel、SKLearnModel、XGBoostModel 等）。

此示例展示了如何部署一个已训练好的模型以进行实时推理。

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(...)

更多示例： SageMaker V3 示例 <#sagemaker-v3-examples>__

SageMaker V3 示例

训练示例

#. 自定义分布式训练示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/training-examples/custom-distributed-training-example.ipynb>__ #. 分布式本地训练示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/training-examples/distributed-local-training-example.ipynb>__ #. 超参数训练示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/training-examples/hyperparameter-training-example.ipynb>__ #. JumpStart 训练示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/training-examples/jumpstart-training-example.ipynb>__ #. 本地训练示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/training-examples/local-training-example.ipynb>__

推理示例

#. HuggingFace 示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/inference-examples/huggingface-example.ipynb>__ #. 进程内模式示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/inference-examples/in-process-mode-example.ipynb>__ #. 推理规范示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/inference-examples/inference-spec-example.ipynb>__ #. JumpStart 端到端训练示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/inference-examples/jumpstart-e2e-training-example.ipynb>__ #. JumpStart 示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/inference-examples/jumpstart-example.ipynb>__ #. 本地模式示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/inference-examples/local-mode-example.ipynb>__ #. 优化示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/inference-examples/optimize-example.ipynb>__ #. 训练与推理端到端示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/inference-examples/train-inference-e2e-example.ipynb>__

ML 操作示例

#. V3 超参数调优示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/ml-ops-examples/v3-hyperparameter-tuning-example/v3-hyperparameter-tuning-example.ipynb>__ #. V3 超参数调优流水线 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/ml-ops-examples/v3-hyperparameter-tuning-example/v3-hyperparameter-tuning-pipeline.ipynb>__ #. V3 模型注册表示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/ml-ops-examples/v3-model-registry-example/v3-model-registry-example.ipynb>__ #. V3 PyTorch 处理示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/ml-ops-examples/v3-processing-job-pytorch/v3-pytorch-processing-example.ipynb>__ #. V3 流水线训练并创建注册表 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/ml-ops-examples/v3-pipeline-train-create-registry.ipynb>__ #. V3 Sklearn 处理作业 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/ml-ops-examples/v3-processing-job-sklearn.ipynb>__ #. V3 SageMaker Clarify <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/ml-ops-examples/v3-sagemaker-clarify.ipynb>__ #. V3 转换作业示例 <https://github.com/aws/sagemaker-python-sdk/blob/master/v3-examples/ml-ops-examples/v3-transform-job-example.ipynb>__

寻找 V2 示例？ 请参阅下方的 SageMaker V2 示例 <#sagemaker-v2-examples>__。

安装 SageMaker Python SDK

SageMaker Python SDK 已发布到 PyPI，您可以通过以下 pip 命令安装最新版本： ::

pip install sagemaker==<来自 https://pypi.org/project/sagemaker/ 的最新版本>

您也可以通过克隆此仓库并在仓库根目录下运行 pip 安装命令来从源代码安装：

::

git clone https://github.com/aws/sagemaker-python-sdk.git
cd sagemaker-python-sdk
pip install .

支持的操作系统

SageMaker Python SDK 支持 Unix/Linux 和 Mac。

支持的 Python 版本

SageMaker Python SDK 已在以下 Python 版本上进行测试：

• Python 3.9
• Python 3.10
• Python 3.11
• Python 3.12

遥测

`sagemaker` 库启用了遥测功能，以帮助我们更好地了解用户需求、诊断问题并推出新功能。该遥测会跟踪各种 SageMaker 功能的使用情况。

如果您希望选择退出遥测，只需在 SDK 默认配置中将 `TelemetryOptOut` 参数设置为 `true` 即可。有关详细说明，请访问 `使用 SageMaker Python SDK 配置和使用默认值 <https://sagemaker.readthedocs.io/en/stable/overview.html#configuring-and-using-defaults-with-the-sagemaker-python-sdk>`__。

AWS 权限

作为一项托管服务，Amazon SageMaker 会在由 Amazon SageMaker 管理的 AWS 硬件上代表您执行操作。 Amazon SageMaker 只能执行用户允许的操作。 有关所需权限的更多信息，请参阅 AWS 文档 <https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-roles.html>__。

除了使用 SageMaker 所需的权限外，SageMaker Python SDK 不应需要任何额外的权限。 但是，如果您使用的是带有路径的 IAM 角色，则应授予 iam:GetRole 权限。

许可

SageMaker Python SDK 采用 Apache 2.0 许可证授权。版权归 Amazon.com, Inc. 或其关联公司所有。保留所有权利。许可证可在以下网址获取：
http://aws.amazon.com/apache2.0/

运行测试

SageMaker Python SDK 包含单元测试和集成测试。

您可以运行 :code:pip install --upgrade .[test] 或对于 Zsh 用户：:code:pip install --upgrade .\[test\] 来安装运行测试所需的库。

单元测试

我们使用 tox 运行单元测试，tox 是一个可以针对多个 Python 版本运行单元测试，并确保代码符合我们的编码规范的工具。我们使用 所有支持的 Python 版本 <#supported-python-versions>__ 运行 tox，因此要以与我们相同的配置运行单元测试，您需要安装这些 Python 版本的解释器。

要使用 tox 运行单元测试，运行以下命令：

::

tox tests/unit

集成测试

要运行集成测试，必须满足以下先决条件：

1. 环境中已提供 AWS 账户凭证，以便 boto3 客户端使用。
2. AWS 账户拥有名为 :code:SageMakerRole 的 IAM 角色。 该角色应附加 AmazonSageMakerFullAccess 策略，以及具有 使用 Elastic Inference 所需权限 <https://docs.aws.amazon.com/sagemaker/latest/dg/ei-setup.html>__ 的策略。
3. 要运行 remote_function 测试，需要创建一个 dummy ecr 仓库。可以通过运行以下命令创建： :code:aws ecr create-repository --repository-name remote-function-dummy-container

我们建议您有选择地运行自己感兴趣的集成测试。您可以通过单个测试函数名称进行筛选：

::

tox -- -k 'test_i_care_about'

您也可以运行所有集成测试，只需运行以下命令即可，该命令会按顺序运行所有测试，可能需要一些时间：

::

tox -- tests/integ

您还可以并行运行它们：

::

tox -- -n auto tests/integ

Git 钩子

要在 .githooks 目录中启用所有 Git 钩子，请在仓库目录中运行以下命令：

::

    find .git/hooks -type l -exec rm {} \;
    find .githooks -type f -exec ln -sf ../../{} .git/hooks/ \;

要启用单个 Git 钩子，只需将其从 .githooks/ 目录移动到 .git/hooks/ 目录即可。

构建 Sphinx 文档

设置 Python 环境，并安装 doc/requirements.txt 中列出的依赖项：

::

# conda
conda create -n sagemaker python=3.12
conda activate sagemaker
conda install sphinx=5.1.1 sphinx_rtd_theme=0.5.0

# pip
pip install -r doc/requirements.txt

克隆或分叉仓库，并安装本地版本：

::

pip install --upgrade .

然后进入 sagemaker-python-sdk/doc 目录并运行：

::

make html

您可以通过编辑 doc 目录中的 .rst 文件来修改文档中任何页面的模板，然后再次运行 make html。

使用 Python Web 服务器预览站点：

::

cd _build/html
python -m http.server 8000

访问 http://localhost:8000 即可查看网站。

SageMaker SparkML 服务

借助 SageMaker SparkML 服务，您现在可以在 SageMaker 中对 SparkML 模型进行预测。要在 SageMaker 中托管 SparkML 模型，该模型应使用 MLeap 库进行序列化。

有关 MLeap 的更多信息，请参阅 https://github.com/combust/mleap 。

支持的主要 Spark 版本：3.3（MLeap 版本 - 0.20.0）

以下是如何创建 SparkMLModel 类的实例，并使用 deploy() 方法创建端点的示例，该端点可用于对您训练好的 SparkML 模型进行预测。

.. code:: python

sparkml_model = SparkMLModel(model_data='s3://path/to/model.tar.gz', env={'SAGEMAKER_SPARKML_SCHEMA': schema})
model_name = 'sparkml-model'
endpoint_name = 'sparkml-endpoint'
predictor = sparkml_model.deploy(initial_instance_count=1, instance_type='ml.c4.xlarge', endpoint_name=endpoint_name)

模型部署完成后，我们可以使用如下格式的 CSV 负载调用端点：

.. code:: python

payload = 'field_1,field_2,field_3,field_4,field_5'
predictor.predict(payload)

有关不同 content-type 和 Accept 格式以及 SageMaker SparkML 服务所识别的 schema 结构的更多信息，请参阅 SageMaker SparkML 服务容器_。

.. _SageMaker SparkML 服务容器: https://github.com/aws/sagemaker-sparkml-serving-container

SageMaker V2 示例

#. 使用 SageMaker Python SDK https://sagemaker.readthedocs.io/en/stable/overview.html #. 使用 MXNet https://sagemaker.readthedocs.io/en/stable/using_mxnet.html #. 使用 TensorFlow https://sagemaker.readthedocs.io/en/stable/using_tf.html #. 使用 Chainer https://sagemaker.readthedocs.io/en/stable/using_chainer.html #. 使用 PyTorch https://sagemaker.readthedocs.io/en/stable/using_pytorch.html #. 使用 Scikit-learn https://sagemaker.readthedocs.io/en/stable/using_sklearn.html #. 使用 XGBoost https://sagemaker.readthedocs.io/en/stable/using_xgboost.html #. SageMaker 强化学习估算器 https://sagemaker.readthedocs.io/en/stable/using_rl.html #. SageMaker SparkML 服务 <#sagemaker-sparkml-serving> #. Amazon SageMaker 内置算法估算器 <src/sagemaker/amazon/README.rst> #. 使用 SageMaker 算法估算器 https://sagemaker.readthedocs.io/en/stable/overview.html#using-sagemaker-algorithmestimators #. 消费 SageMaker 模型包 https://sagemaker.readthedocs.io/en/stable/overview.html#consuming-sagemaker-model-packages #. 使用 SageMaker 估算器的 BYO Docker 容器 https://sagemaker.readthedocs.io/en/stable/overview.html#byo-docker-containers-with-sagemaker-estimators #. SageMaker 自动模型调优 https://sagemaker.readthedocs.io/en/stable/overview.html#sagemaker-automatic-model-tuning #. SageMaker 批量转换 https://sagemaker.readthedocs.io/en/stable/overview.html#sagemaker-batch-transform #. 使用 VPC 进行安全的训练和推理 https://sagemaker.readthedocs.io/en/stable/overview.html#secure-training-and-inference-with-vpc #. BYO 模型 https://sagemaker.readthedocs.io/en/stable/overview.html#byo-model #. 推理管道 https://sagemaker.readthedocs.io/en/stable/overview.html#inference-pipelines #. Apache Airflow 中的 Amazon SageMaker 操作符 https://sagemaker.readthedocs.io/en/stable/using_workflow.html #. SageMaker 自动驾驶 <src/sagemaker/automl/README.rst> #. 模型监控 https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_model_monitoring.html #. SageMaker 调试器 https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_debugger.html #. SageMaker 处理 https://sagemaker.readthedocs.io/en/stable/amazon_sagemaker_processing.html

🚀 V3 现已支持模型微调

我们很高兴地宣布，SageMaker Python SDK V3 现已支持模型微调功能！

新增内容

四个用于微调基础模型的新训练器类：

• SFTTrainer - 监督式微调
• DPOTrainer - 直接偏好优化
• RLAIFTrainer - 基于人工智能反馈的强化学习
• RLVRTrainer - 基于可验证奖励的强化学习

快速示例

.. 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()

主要特性

• ✨ LoRA 和全量微调
• 📊 MLflow 集成，提供实时指标
• 🚀 可部署至 SageMaker 或 Bedrock
• 📈 内置评估（11 个基准测试）
• ☁️ 无服务器训练

开始使用

.. code:: python

pip install sagemaker>=3.1.0

📓 示例笔记本 <https://github.com/aws/sagemaker-python-sdk/tree/master/v3-examples/model-customization-examples>__

SageMaker Python SDK 快速上手指南

SageMaker Python SDK 是一个开源库，用于在 Amazon SageMaker 上训练和部署机器学习模型。最新版本（V3）引入了现代化的架构，通过统一的 ModelTrainer 和 ModelBuilder 类简化了工作流。

环境准备

系统要求

• 操作系统：支持 Unix/Linux 和 macOS。
• Python 版本：支持 Python 3.9, 3.10, 3.11, 3.12。

前置依赖

• AWS 凭证：确保已配置 AWS CLI 或设置了环境变量 (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION)。
• IAM 权限：运行代码的用户角色需要具备 SageMaker 相关操作权限（如 sagemaker:CreateTrainingJob, sagemaker:CreateEndpoint 等）。如果使用带路径的 IAM 角色，还需授予 iam:GetRole 权限。

安装步骤

推荐使用 pip 进行安装。国内开发者若遇到下载速度慢的问题，可使用清华或阿里云镜像源加速。

方式一：使用 PyPI 安装（推荐）

标准安装：

pip install sagemaker

使用国内镜像源加速安装：

pip install sagemaker -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：当前主要版本为 V3。如需使用旧版 V2 接口，请指定版本：pip install sagemaker==2.*。

方式二：从源码安装

git clone https://github.com/aws/sagemaker-python-sdk.git
cd sagemaker-python-sdk
pip install .

基本使用

SageMaker Python SDK V3 提供了更简洁的面向对象 API。以下是训练和推理的最简示例。

1. 模型训练 (Training)

V3 使用统一的 ModelTrainer 类替代了旧版的 Estimator 及其框架特定子类。

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

# 初始化训练器
trainer = ModelTrainer(
    training_image="my-training-image",  # 替换为你的训练容器镜像 URI
    role="arn:aws:iam::123456789012:role/SageMakerRole"  # 替换为你的 IAM 角色 ARN
)

# 配置输入数据
train_data = InputData(
    channel_name="training",
    data_source="s3://my-bucket/train"  # 替换为你的 S3 训练数据路径
)

# 启动训练任务
trainer.train(input_data_config=[train_data])

2. 模型部署与推理 (Inference)

V3 使用统一的 ModelBuilder 类替代了旧版的 Model 及其框架特定子类。

from sagemaker.serve import ModelBuilder

# 初始化模型构建器
model_builder = ModelBuilder(
    model="my-model",  # 替换为你的模型名称或标识
    model_path="s3://my-bucket/model.tar.gz"  # 替换为你的模型文件 S3 路径
)

# 构建并部署端点
endpoint = model_builder.build()

# 调用端点进行推理
# result = endpoint.invoke(...) 
# 请根据实际模型输入格式传递数据

提示：更多高级用法（如分布式训练、超参数调优、JumpStart 集成等）请参考官方 V3 示例仓库。