Model¶
-
class
sagemaker.model.
Model
(image_uri, model_data=None, role=None, predictor_cls=None, env=None, name=None, vpc_config=None, sagemaker_session=None, enable_network_isolation=False, model_kms_key=None, image_config=None)¶ Bases:
sagemaker.model.ModelBase
A SageMaker
Model
that can be deployed to anEndpoint
.Initialize an SageMaker
Model
.- Parameters
image_uri (str) – A Docker image URI.
model_data (str) – The S3 location of a SageMaker model data
.tar.gz
file (default: None).role (str) – 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 it needs to access some AWS resources. It can be null if this is being used to create a Model to pass to a
PipelineModel
which has its own Role field. (default: None)predictor_cls (callable[string, sagemaker.session.Session]) – A function to call to create a predictor (default: None). If not None,
deploy
will return the result of invoking this function on the created endpoint name.env (dict[str, str]) – Environment variables to run with
image_uri
when hosted in SageMaker (default: None).name (str) – The model name. If None, a default model name will be selected on each
deploy
.vpc_config (dict[str, list[str]]) – The VpcConfig set on the model (default: None) * ‘Subnets’ (list[str]): List of subnet ids. * ‘SecurityGroupIds’ (list[str]): List of security group ids.
sagemaker_session (sagemaker.session.Session) – A SageMaker Session object, used for SageMaker interactions (default: None). If not specified, one is created using the default AWS configuration chain.
enable_network_isolation (Boolean) – Default False. if True, enables network isolation in the endpoint, isolating the model container. No inbound or outbound network calls can be made to or from the model container.
model_kms_key (str) – KMS key ARN used to encrypt the repacked model archive file if the model is repacked
image_config (dict[str, str]) – Specifies whether the image of model container is pulled from ECR, or private registry in your VPC. By default it is set to pull model container image from ECR. (default: None).
-
register
(content_types, response_types, inference_instances, transform_instances, model_package_name=None, model_package_group_name=None, image_uri=None, model_metrics=None, metadata_properties=None, marketplace_cert=False, approval_status=None, description=None)¶ Creates a model package for creating SageMaker models or listing on Marketplace.
- Parameters
content_types (list) – The supported MIME types for the input data (default: None).
response_types (list) – The supported MIME types for the output data (default: None).
inference_instances (list) – A list of the instance types that are used to generate inferences in real-time (default: None).
transform_instances (list) – A list of the instance types on which a transformation job can be run or on which an endpoint can be deployed (default: None).
model_package_name (str) – Model Package name, exclusive to model_package_group_name, using model_package_name makes the Model Package un-versioned (default: None).
model_package_group_name (str) – Model Package Group name, exclusive to model_package_name, using model_package_group_name makes the Model Package versioned (default: None).
image_uri (str) – Inference image uri for the container. Model class’ self.image will be used if it is None (default: None).
model_metrics (ModelMetrics) – ModelMetrics object (default: None).
metadata_properties (MetadataProperties) – MetadataProperties object (default: None).
marketplace_cert (bool) – A boolean value indicating if the Model Package is certified for AWS Marketplace (default: False).
approval_status (str) – Model Approval Status, values can be “Approved”, “Rejected”, or “PendingManualApproval” (default: “PendingManualApproval”).
description (str) – Model Package description (default: None).
- Returns
A sagemaker.model.ModelPackage instance.
-
prepare_container_def
(instance_type=None, accelerator_type=None)¶ Return a dict created by
sagemaker.container_def()
.It is used for deploying this model to a specified instance type.
Subclasses can override this to provide custom container definitions for deployment to a specific instance type. Called by
deploy()
.- Parameters
- Returns
A container definition object usable with the CreateModel API.
- Return type
-
enable_network_isolation
()¶ Whether to enable network isolation when creating this Model
- Returns
If network isolation should be enabled or not.
- Return type
-
package_for_edge
(output_path, model_name, model_version, role=None, job_name=None, resource_key=None, s3_kms_key=None, tags=None)¶ Package this
Model
with SageMaker Edge.Creates a new EdgePackagingJob and wait for it to finish. model_data will now point to the packaged artifacts.
- Parameters
output_path (str) – Specifies where to store the packaged model
role (str) – Execution role
model_name (str) – the name to attach to the model metadata
model_version (str) – the version to attach to the model metadata
job_name (str) – The name of the edge packaging job
resource_key (str) – the kms key to encrypt the disk with
s3_kms_key (str) – the kms key to encrypt the output with
tags (list[dict]) – List of tags for labeling an edge packaging job. For more, see https://docs.aws.amazon.com/sagemaker/latest/dg/API_Tag.html.
- Returns
A SageMaker
Model
object. SeeModel()
for full details.- Return type
-
compile
(target_instance_family, input_shape, output_path, role, tags=None, job_name=None, compile_max_run=900, framework=None, framework_version=None, target_platform_os=None, target_platform_arch=None, target_platform_accelerator=None, compiler_options=None)¶ Compile this
Model
with SageMaker Neo.- Parameters
target_instance_family (str) – Identifies the device that you want to run your model after compilation, for example: ml_c5. For allowed strings see https://docs.aws.amazon.com/sagemaker/latest/dg/API_OutputConfig.html. Alternatively, you can select an OS, Architecture and Accelerator using
target_platform_os
,target_platform_arch
, andtarget_platform_accelerator
.input_shape (dict) – Specifies the name and shape of the expected inputs for your trained model in json dictionary form, for example: {‘data’: [1,3,1024,1024]}, or {‘var1’: [1,1,28,28], ‘var2’: [1,1,28,28]}
output_path (str) – Specifies where to store the compiled model
role (str) – Execution role
tags (list[dict]) – List of tags for labeling a compilation job. For more, see https://docs.aws.amazon.com/sagemaker/latest/dg/API_Tag.html.
job_name (str) – The name of the compilation job
compile_max_run (int) – Timeout in seconds for compilation (default: 15 * 60). After this amount of time Amazon SageMaker Neo terminates the compilation job regardless of its current status.
framework (str) – The framework that is used to train the original model. Allowed values: ‘mxnet’, ‘tensorflow’, ‘keras’, ‘pytorch’, ‘onnx’, ‘xgboost’
framework_version (str) – The version of framework, for example: ‘1.5’ for PyTorch
target_platform_os (str) – Target Platform OS, for example: ‘LINUX’. For allowed strings see https://docs.aws.amazon.com/sagemaker/latest/dg/API_OutputConfig.html. It can be used instead of target_instance_family by setting target_instance family to None.
target_platform_arch (str) – Target Platform Architecture, for example: ‘X86_64’. For allowed strings see https://docs.aws.amazon.com/sagemaker/latest/dg/API_OutputConfig.html. It can be used instead of target_instance_family by setting target_instance family to None.
target_platform_accelerator (str, optional) – Target Platform Accelerator, for example: ‘NVIDIA’. For allowed strings see https://docs.aws.amazon.com/sagemaker/latest/dg/API_OutputConfig.html. It can be used instead of target_instance_family by setting target_instance family to None.
compiler_options (dict, optional) – Additional parameters for compiler. Compiler Options are TargetPlatform / target_instance_family specific. See https://docs.aws.amazon.com/sagemaker/latest/dg/API_OutputConfig.html for details.
- Returns
A SageMaker
Model
object. SeeModel()
for full details.- Return type
-
deploy
(initial_instance_count, instance_type, serializer=None, deserializer=None, accelerator_type=None, endpoint_name=None, tags=None, kms_key=None, wait=True, data_capture_config=None, **kwargs)¶ Deploy this
Model
to anEndpoint
and optionally return aPredictor
.Create a SageMaker
Model
andEndpointConfig
, and deploy anEndpoint
from thisModel
. Ifself.predictor_cls
is not None, this method returns a the result of invokingself.predictor_cls
on the created endpoint name.The name of the created model is accessible in the
name
field of thisModel
after deploy returnsThe name of the created endpoint is accessible in the
endpoint_name
field of thisModel
after deploy returns.- Parameters
initial_instance_count (int) – The initial number of instances to run in the
Endpoint
created from thisModel
.instance_type (str) – The EC2 instance type to deploy this Model to. For example, ‘ml.p2.xlarge’, or ‘local’ for local mode.
serializer (
BaseSerializer
) – A serializer object, used to encode data for an inference endpoint (default: None). Ifserializer
is not None, thenserializer
will override the default serializer. The default serializer is set by thepredictor_cls
.deserializer (
BaseDeserializer
) – A deserializer object, used to decode data from an inference endpoint (default: None). Ifdeserializer
is not None, thendeserializer
will override the default deserializer. The default deserializer is set by thepredictor_cls
.accelerator_type (str) – Type of Elastic Inference accelerator to deploy this model for model loading and inference, for example, ‘ml.eia1.medium’. If not specified, no Elastic Inference accelerator will be attached to the endpoint. For more information: https://docs.aws.amazon.com/sagemaker/latest/dg/ei.html
endpoint_name (str) – The name of the endpoint to create (default: None). If not specified, a unique endpoint name will be created.
tags (List[dict[str, str]]) – The list of tags to attach to this specific endpoint.
kms_key (str) – The ARN of the KMS key that is used to encrypt the data on the storage volume attached to the instance hosting the endpoint.
wait (bool) – Whether the call should wait until the deployment of this model completes (default: True).
data_capture_config (sagemaker.model_monitor.DataCaptureConfig) – Specifies configuration related to Endpoint data capture for use with Amazon SageMaker Model Monitoring. Default: None.
- Returns
- Invocation of
self.predictor_cls
on the created endpoint name, ifself.predictor_cls
is not None. Otherwise, return None.
- Return type
callable[string, sagemaker.session.Session] or None
-
transformer
(instance_count, instance_type, strategy=None, assemble_with=None, output_path=None, output_kms_key=None, accept=None, env=None, max_concurrent_transforms=None, max_payload=None, tags=None, volume_kms_key=None)¶ Return a
Transformer
that uses this Model.- Parameters
instance_count (int) – Number of EC2 instances to use.
instance_type (str) – Type of EC2 instance to use, for example, ‘ml.c4.xlarge’.
strategy (str) – The strategy used to decide how to batch records in a single request (default: None). Valid values: ‘MultiRecord’ and ‘SingleRecord’.
assemble_with (str) – How the output is assembled (default: None). Valid values: ‘Line’ or ‘None’.
output_path (str) – S3 location for saving the transform result. If not specified, results are stored to a default bucket.
output_kms_key (str) – Optional. KMS key ID for encrypting the transform output (default: None).
accept (str) – The accept header passed by the client to the inference endpoint. If it is supported by the endpoint, it will be the format of the batch transform output.
env (dict) – Environment variables to be set for use during the transform job (default: None).
max_concurrent_transforms (int) – The maximum number of HTTP requests to be made to each individual transform container at one time.
max_payload (int) – Maximum size of the payload in a single HTTP request to the container in MB.
tags (list[dict]) – List of tags for labeling a transform job. If none specified, then the tags used for the training job are used for the transform job.
volume_kms_key (str) – Optional. KMS key ID for encrypting the volume attached to the ML compute instance (default: None).
-
delete_model
()¶ Delete an Amazon SageMaker Model.
- Raises
ValueError – if the model is not created yet.
-
class
sagemaker.model.
FrameworkModel
(model_data, image_uri, role, entry_point, source_dir=None, predictor_cls=None, env=None, name=None, container_log_level=20, code_location=None, sagemaker_session=None, dependencies=None, git_config=None, **kwargs)¶ Bases:
sagemaker.model.Model
A Model for working with an SageMaker
Framework
.This class hosts user-defined code in S3 and sets code location and configuration in model environment variables.
Initialize a
FrameworkModel
.- Parameters
model_data (str) – The S3 location of a SageMaker model data
.tar.gz
file.image_uri (str) – A Docker image URI.
role (str) – An IAM role name or ARN for SageMaker to access AWS resources on your behalf.
entry_point (str) –
Path (absolute or relative) to the Python source file which should be executed as the entry point to model hosting. If
source_dir
is specified, thenentry_point
must point to a file located at the root ofsource_dir
. If ‘git_config’ is provided, ‘entry_point’ should be a relative location to the Python source file in the Git repo.Example
With the following GitHub repo directory structure:
>>> |----- README.md >>> |----- src >>> |----- inference.py >>> |----- test.py
You can assign entry_point=’src/inference.py’.
source_dir (str) –
Path (absolute, relative or an S3 URI) to a directory with any other training source code dependencies aside from the entry point file (default: None). If
source_dir
is an S3 URI, it must point to a tar.gz file. Structure within this directory are preserved when training on Amazon SageMaker. If ‘git_config’ is provided, ‘source_dir’ should be a relative location to a directory in the Git repo. If the directory points to S3, no code will be uploaded and the S3 location will be used instead.Example
With the following GitHub repo directory structure:
>>> |----- README.md >>> |----- src >>> |----- inference.py >>> |----- test.py
You can assign entry_point=’inference.py’, source_dir=’src’.
predictor_cls (callable[string, sagemaker.session.Session]) – A function to call to create a predictor (default: None). If not None,
deploy
will return the result of invoking this function on the created endpoint name.env (dict[str, str]) – Environment variables to run with
image_uri
when hosted in SageMaker (default: None).name (str) – The model name. If None, a default model name will be selected on each
deploy
.container_log_level (int) – Log level to use within the container (default: logging.INFO). Valid values are defined in the Python logging module.
code_location (str) – Name of the S3 bucket where custom code is uploaded (default: None). If not specified, default bucket created by
sagemaker.session.Session
is used.sagemaker_session (sagemaker.session.Session) – A SageMaker Session object, used for SageMaker interactions (default: None). If not specified, one is created using the default AWS configuration chain.
A list of paths to directories (absolute or relative) with any additional libraries that will be exported to the container (default: []). The library folders will be copied to SageMaker in the same folder where the entrypoint is copied. If ‘git_config’ is provided, ‘dependencies’ should be a list of relative locations to directories with any additional libraries needed in the Git repo. If the
`source_dir`
points to S3, code will be uploaded and the S3 location will be used instead.Example
The following call
>>> Model(entry_point='inference.py', ... dependencies=['my/libs/common', 'virtual-env'])
results in the following inside the container:
>>> $ ls
>>> opt/ml/code >>> |------ inference.py >>> |------ common >>> |------ virtual-env
This is not supported with “local code” in Local Mode.
Git configurations used for cloning files, including
repo
,branch
,commit
,2FA_enabled
,username
,password
andtoken
. Therepo
field is required. All other fields are optional.repo
specifies the Git repository where your training script is stored. If you don’t providebranch
, the default value ‘master’ is used. If you don’t providecommit
, the latest commit in the specified branch is used. .. admonition:: ExampleThe following config:
>>> git_config = {'repo': 'https://github.com/aws/sagemaker-python-sdk.git', >>> 'branch': 'test-branch-git-config', >>> 'commit': '329bfcf884482002c05ff7f44f62599ebc9f445a'}
results in cloning the repo specified in ‘repo’, then checkout the ‘master’ branch, and checkout the specified commit.
2FA_enabled
,username
,password
andtoken
are used for authentication. For GitHub (or other Git) accounts, set2FA_enabled
to ‘True’ if two-factor authentication is enabled for the account, otherwise set it to ‘False’. If you do not provide a value for2FA_enabled
, a default value of ‘False’ is used. CodeCommit does not support two-factor authentication, so do not provide “2FA_enabled” with CodeCommit repositories.For GitHub and other Git repos, when SSH URLs are provided, it doesn’t matter whether 2FA is enabled or disabled; you should either have no passphrase for the SSH key pairs, or have the ssh-agent configured so that you will not be prompted for SSH passphrase when you do ‘git clone’ command with SSH URLs. When HTTPS URLs are provided: if 2FA is disabled, then either token or username+password will be used for authentication if provided (token prioritized); if 2FA is enabled, only token will be used for authentication if provided. If required authentication info is not provided, python SDK will try to use local credentials storage to authenticate. If that fails either, an error message will be thrown.
For CodeCommit repos, 2FA is not supported, so ‘2FA_enabled’ should not be provided. There is no token in CodeCommit, so ‘token’ should not be provided too. When ‘repo’ is an SSH URL, the requirements are the same as GitHub-like repos. When ‘repo’ is an HTTPS URL, username+password will be used for authentication if they are provided; otherwise, python SDK will try to use either CodeCommit credential helper or local credential storage for authentication.
**kwargs – Keyword arguments passed to the superclass
Model
.
Tip
You can find additional parameters for initializing this class at
Model
.-
prepare_container_def
(instance_type=None, accelerator_type=None)¶ Return a container definition with framework configuration.
Framework configuration is set in model environment variables. This also uploads user-supplied code to S3.
- Parameters
- Returns
A container definition object usable with the CreateModel API.
- Return type
-
class
sagemaker.model.
ModelPackage
(role, model_data=None, algorithm_arn=None, model_package_arn=None, **kwargs)¶ Bases:
sagemaker.model.Model
A SageMaker
Model
that can be deployed to anEndpoint
.Initialize a SageMaker ModelPackage.
- Parameters
role (str) – 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 it needs to access an AWS resource.
model_data (str) – The S3 location of a SageMaker model data
.tar.gz
file. Must be provided if algorithm_arn is provided.algorithm_arn (str) – algorithm arn used to train the model, can be just the name if your account owns the algorithm. Must also provide
model_data
.model_package_arn (str) – An existing SageMaker Model Package arn, can be just the name if your account owns the Model Package.
model_data
is not required.**kwargs – Additional kwargs passed to the Model constructor.
-
sagemaker.serverless.model.
LambdaModel
¶ alias of
sagemaker.deprecations.deprecation_warning.<locals>.deprecate.<locals>.wrapper