Session

class sagemaker.session.LogState

Bases: object

STARTING = 1
WAIT_IN_PROGRESS = 2
TAILING = 3
JOB_COMPLETE = 4
COMPLETE = 5
class sagemaker.session.Session(boto_session=None, sagemaker_client=None, sagemaker_runtime_client=None)

Bases: object

Manage interactions with the Amazon SageMaker APIs and any other AWS services needed.

This class provides convenient methods for manipulating entities and resources that Amazon SageMaker uses, such as training jobs, endpoints, and input datasets in S3.

AWS service calls are delegated to an underlying Boto3 session, which by default is initialized using the AWS configuration chain. When you make an Amazon SageMaker API call that accesses an S3 bucket location and one is not specified, the Session creates a default bucket based on a naming convention which includes the current AWS account ID.

Initialize a SageMaker Session.

Parameters:
  • boto_session (boto3.session.Session) – The underlying Boto3 session which AWS service calls are delegated to (default: None). If not provided, one is created with default AWS configuration chain.
  • sagemaker_client (boto3.SageMaker.Client) – Client which makes Amazon SageMaker service calls other than InvokeEndpoint (default: None). Estimators created using this Session use this client. If not provided, one will be created using this instance’s boto_session.
  • sagemaker_runtime_client (boto3.SageMakerRuntime.Client) – Client which makes InvokeEndpoint calls to Amazon SageMaker (default: None). Predictors created using this Session use this client. If not provided, one will be created using this instance’s boto_session.
boto_region_name
upload_data(path, bucket=None, key_prefix='data')

Upload local file or directory to S3.

If a single file is specified for upload, the resulting S3 object key is {key_prefix}/{filename} (filename does not include the local path, if any specified).

If a directory is specified for upload, the API uploads all content, recursively, preserving relative structure of subdirectories. The resulting object key names are: {key_prefix}/{relative_subdirectory_path}/filename.

Parameters:
  • path (str) – Path (absolute or relative) of local file or directory to upload.
  • bucket (str) – Name of the S3 Bucket to upload to (default: None). If not specified, the default bucket of the Session is used. If the bucket does not exist, the Session creates the bucket.
  • key_prefix (str) – Optional S3 object key name prefix (default: ‘data’). S3 uses the prefix to create a directory structure for the bucket content that it display in the S3 console.
Returns:

The S3 URI of the uploaded file(s). If a file is specified in the path argument, the URI format is:

s3://{bucket name}/{key_prefix}/{original_file_name}. If a directory is specified in the path argument, the URI format is s3://{bucket name}/{key_prefix}.

Return type:

str

default_bucket()

Return the name of the default bucket to use in relevant Amazon SageMaker interactions.

Returns:The name of the default bucket, which is of the form: sagemaker-{region}-{AWS account ID}.
Return type:str
train(image, input_mode, input_config, role, job_name, output_config, resource_config, hyperparameters, stop_condition, tags)

Create an Amazon SageMaker training job.

Parameters:
  • image (str) – Docker image containing training code.
  • input_mode (str) –

    The input mode that the algorithm supports. Valid modes:

    • ’File’ - Amazon SageMaker copies the training dataset from the S3 location to
      a directory in the Docker container.
    • ’Pipe’ - Amazon SageMaker streams data directly from S3 to the container via a Unix-named pipe.
  • input_config (list) – A list of Channel objects. Each channel is a named input source. Please refer to the format details described: https://botocore.readthedocs.io/en/latest/reference/services/sagemaker.html#SageMaker.Client.create_training_job
  • 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. You must grant sufficient permissions to this role.
  • job_name (str) – Name of the training job being created.
  • output_config (dict) – The S3 URI where you want to store the training results and optional KMS key ID.
  • resource_config (dict) –

    Contains values for ResourceConfig:

    • instance_count (int): Number of EC2 instances to use for training.
      The key in resource_config is ‘InstanceCount’.
    • instance_type (str): Type of EC2 instance to use for training, for example, ‘ml.c4.xlarge’.
      The key in resource_config is ‘InstanceType’.
  • hyperparameters (dict) – Hyperparameters for model training. The hyperparameters are made accessible as a dict[str, str] to the training code on SageMaker. For convenience, this accepts other types for keys and values, but str() will be called to convert them before training.
  • stop_condition (dict) – Defines when training shall finish. Contains entries that can be understood by the service like MaxRuntimeInSeconds.
  • tags (list[dict]) – List of tags for labeling a training job. For more, see https://docs.aws.amazon.com/sagemaker/latest/dg/API_Tag.html.
Returns:

ARN of the training job, if it is created.

Return type:

str

tune(job_name, strategy, objective_type, objective_metric_name, max_jobs, max_parallel_jobs, parameter_ranges, static_hyperparameters, image, input_mode, metric_definitions, role, input_config, output_config, resource_config, stop_condition, tags)

Create an Amazon SageMaker hyperparameter tuning job

Parameters:
  • job_name (str) – Name of the tuning job being created.
  • strategy (str) – Strategy to be used for hyperparameter estimations.
  • objective_type (str) – The type of the objective metric for evaluating training jobs. This value can be either ‘Minimize’ or ‘Maximize’.
  • objective_metric_name (str) – Name of the metric for evaluating training jobs.
  • max_jobs (int) – Maximum total number of training jobs to start for the hyperparameter tuning job.
  • max_parallel_jobs (int) – Maximum number of parallel training jobs to start.
  • parameter_ranges (dict) – Dictionary of parameter ranges. These parameter ranges can be one of three types: Continuous, Integer, or Categorical.
  • static_hyperparameters (dict) – Hyperparameters for model training. These hyperparameters remain unchanged across all of the training jobs for the hyperparameter tuning job. The hyperparameters are made accessible as a dictionary for the training code on SageMaker.
  • image (str) – Docker image containing training code.
  • input_mode (str) –

    The input mode that the algorithm supports. Valid modes:

    • ’File’ - Amazon SageMaker copies the training dataset from the S3 location to
      a directory in the Docker container.
    • ’Pipe’ - Amazon SageMaker streams data directly from S3 to the container via a Unix-named pipe.
  • metric_definitions (list[dict]) – A list of dictionaries that defines the metric(s) used to evaluate the training jobs. Each dictionary contains two keys: ‘Name’ for the name of the metric, and ‘Regex’ for the regular expression used to extract the metric from the logs. This should be defined only for hyperparameter tuning jobs that don’t use an Amazon algorithm.
  • 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. You must grant sufficient permissions to this role.
  • input_config (list) – A list of Channel objects. Each channel is a named input source. Please refer to the format details described: https://botocore.readthedocs.io/en/latest/reference/services/sagemaker.html#SageMaker.Client.create_training_job
  • output_config (dict) – The S3 URI where you want to store the training results and optional KMS key ID.
  • resource_config (dict) –

    Contains values for ResourceConfig:

    • instance_count (int): Number of EC2 instances to use for training.
      The key in resource_config is ‘InstanceCount’.
    • instance_type (str): Type of EC2 instance to use for training, for example, ‘ml.c4.xlarge’.
      The key in resource_config is ‘InstanceType’.
  • stop_condition (dict) – When training should finish, e.g. MaxRuntimeInSeconds.
  • tags (list[dict]) – List of tags for labeling the tuning job. For more, see https://docs.aws.amazon.com/sagemaker/latest/dg/API_Tag.html.
stop_tuning_job(name)

Stop the Amazon SageMaker hyperparameter tuning job with the specified name.

Parameters:name (str) – Name of the Amazon SageMaker hyperparameter tuning job.
Raises:ClientError – If an error occurs while trying to stop the hyperparameter tuning job.
create_model(name, role, primary_container)

Create an Amazon SageMaker Model.

Specify the S3 location of the model artifacts and Docker image containing the inference code. Amazon SageMaker uses this information to deploy the model in Amazon SageMaker.

Parameters:
  • name (str) – Name of the Amazon SageMaker Model to create.
  • 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. You must grant sufficient permissions to this role.
  • primary_container (str or dict[str, str]) – Docker image which defines the inference code. You can also specify the return value of sagemaker.container_def(), which is used to create more advanced container configurations, including model containers which need artifacts from S3.
Returns:

Name of the Amazon SageMaker Model created.

Return type:

str

create_model_from_job(training_job_name, name=None, role=None, primary_container_image=None, model_data_url=None, env={})

Create an Amazon SageMaker Model from a SageMaker Training Job.

Parameters:
  • training_job_name (str) – The Amazon SageMaker Training Job name.
  • name (str) – The name of the SageMaker Model to create (default: None). If not specified, the training job name is used.
  • role (str) – The ExecutionRoleArn IAM Role ARN for the Model, specified either by an IAM role name or role ARN. If None, the RoleArn from the SageMaker Training Job will be used.
  • primary_container_image (str) – The Docker image reference (default: None). If None, it defaults to the Training Image in training_job_name.
  • model_data_url (str) – S3 location of the model data (default: None). If None, defaults to the ModelS3Artifacts of training_job_name.
  • env (dict[string,string]) – Model environment variables (default: {}).
Returns:

The name of the created Model.

Return type:

str

create_endpoint_config(name, model_name, initial_instance_count, instance_type)

Create an Amazon SageMaker endpoint configuration.

The endpoint configuration identifies the Amazon SageMaker model (created using the CreateModel API) and the hardware configuration on which to deploy the model. Provide this endpoint configuration to the CreateEndpoint API, which then launches the hardware and deploys the model.

Parameters:
  • name (str) – Name of the Amazon SageMaker endpoint configuration to create.
  • model_name (str) – Name of the Amazon SageMaker Model.
  • initial_instance_count (int) – Minimum number of EC2 instances to launch. The actual number of active instances for an endpoint at any given time varies due to autoscaling.
  • instance_type (str) – Type of EC2 instance to launch, for example, ‘ml.c4.xlarge’.
Returns:

Name of the endpoint point configuration created.

Return type:

str

create_endpoint(endpoint_name, config_name, wait=True)

Create an Amazon SageMaker Endpoint according to the endpoint configuration specified in the request.

Once the Endpoint is created, client applications can send requests to obtain inferences. The endpoint configuration is created using the CreateEndpointConfig API.

Parameters:
  • endpoint_name (str) – Name of the Amazon SageMaker Endpoint being created.
  • config_name (str) – Name of the Amazon SageMaker endpoint configuration to deploy.
  • wait (bool) – Whether to wait for the endpoint deployment to complete before returning (default: True).
Returns:

Name of the Amazon SageMaker Endpoint created.

Return type:

str

delete_endpoint(endpoint_name)

Delete an Amazon SageMaker Endpoint.

Parameters:endpoint_name (str) – Name of the Amazon SageMaker Endpoint to delete.
wait_for_job(job, poll=5)

Wait for an Amazon SageMaker training job to complete.

Parameters:
  • job (str) – Name of the training job to wait for.
  • poll (int) – Polling interval in seconds (default: 5).
Returns:

Return value from the DescribeTrainingJob API.

Return type:

(dict)

Raises:

ValueError – If the training job fails.

wait_for_tuning_job(job, poll=5)

Wait for an Amazon SageMaker hyperparameter tuning job to complete.

Parameters:
  • job (str) – Name of the tuning job to wait for.
  • poll (int) – Polling interval in seconds (default: 5).
Returns:

Return value from the DescribeHyperParameterTuningJob API.

Return type:

(dict)

Raises:

ValueError – If the hyperparameter tuning job fails.

wait_for_endpoint(endpoint, poll=5)

Wait for an Amazon SageMaker endpoint deployment to complete.

Parameters:
  • endpoint (str) – Name of the Endpoint to wait for.
  • poll (int) – Polling interval in seconds (default: 5).
Returns:

Return value from the DescribeEndpoint API.

Return type:

dict

endpoint_from_job(job_name, initial_instance_count, instance_type, deployment_image=None, name=None, role=None, wait=True, model_environment_vars=None)

Create an Endpoint using the results of a successful training job.

Specify the job name, Docker image containing the inference code, and hardware configuration to deploy the model. Internally the API, creates an Amazon SageMaker model (that describes the model artifacts and the Docker image containing inference code), endpoint configuration (describing the hardware to deploy for hosting the model), and creates an Endpoint (launches the EC2 instances and deploys the model on them). In response, the API returns the endpoint name to which you can send requests for inferences.

Parameters:
  • job_name (str) – Name of the training job to deploy the results of.
  • initial_instance_count (int) – Minimum number of EC2 instances to launch. The actual number of active instances for an endpoint at any given time varies due to autoscaling.
  • instance_type (str) – Type of EC2 instance to deploy to an endpoint for prediction, for example, ‘ml.c4.xlarge’.
  • deployment_image (str) – The Docker image which defines the inference code to be used as the entry point for accepting prediction requests. If not specified, uses the image used for the training job.
  • name (str) – Name of the Endpoint to create. If not specified, uses the training job name.
  • 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. You must grant sufficient permissions to this role.
  • wait (bool) – Whether to wait for the endpoint deployment to complete before returning (default: True).
  • model_environment_vars (dict[str, str]) – Environment variables to set on the model container (default: None).
Returns:

Name of the Endpoint that is created.

Return type:

str

endpoint_from_model_data(model_s3_location, deployment_image, initial_instance_count, instance_type, name=None, role=None, wait=True, model_environment_vars=None)

Create and deploy to an Endpoint using existing model data stored in S3.

Parameters:
  • model_s3_location (str) – S3 URI of the model artifacts to use for the endpoint.
  • deployment_image (str) – The Docker image which defines the runtime code to be used as the entry point for accepting prediction requests.
  • initial_instance_count (int) – Minimum number of EC2 instances to launch. The actual number of active instances for an endpoint at any given time varies due to autoscaling.
  • instance_type (str) – Type of EC2 instance to deploy to an endpoint for prediction, e.g. ‘ml.c4.xlarge’.
  • name (str) – Name of the Endpoint to create. If not specified, uses a name generated by combining the image name with a timestamp.
  • 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. You must grant sufficient permissions to this role.
  • wait (bool) – Whether to wait for the endpoint deployment to complete before returning (default: True).
  • model_environment_vars (dict[str, str]) – Environment variables to set on the model container (default: None).
Returns:

Name of the Endpoint that is created.

Return type:

str

endpoint_from_production_variants(name, production_variants, wait=True)

Create an SageMaker Endpoint from a list of production variants.

Parameters:
  • name (str) – The name of the Endpoint to create.
  • production_variants (list[dict[str, str]]) – The list of production variants to deploy.
  • wait (bool) – Whether to wait for the endpoint deployment to complete before returning (default: True).
Returns:

The name of the created Endpoint.

Return type:

str

expand_role(role)

Expand an IAM role name into an ARN.

If the role is already in the form of an ARN, then the role is simply returned. Otherwise we retrieve the full ARN and return it.

Parameters:role (str) – An AWS IAM role (either name or full ARN).
Returns:The corresponding AWS IAM role ARN.
Return type:str
get_caller_identity_arn()

Returns the ARN user or role whose credentials are used to call the API. :returns: The ARN uer or role :rtype: (str)

logs_for_job(job_name, wait=False, poll=10)

Display the logs for a given training job, optionally tailing them until the job is complete. If the output is a tty or a Jupyter cell, it will be color-coded based on which instance the log entry is from.

Parameters:
  • job_name (str) – Name of the training job to display the logs for.
  • wait (bool) – Whether to keep looking for new log entries until the job completes (default: False).
  • poll (int) – The interval in seconds between polling for new log entries and job completion (default: 5).
Raises:

ValueError – If waiting and the training job fails.

sagemaker.session.container_def(image, model_data_url=None, env=None)

Create a definition for executing a container as part of a SageMaker model.

Parameters:
  • image (str) – Docker image to run for this container.
  • model_data_url (str) – S3 URI of data required by this container, e.g. SageMaker training job model artifacts (default: None).
  • env (dict[str, str]) – Environment variables to set inside the container (default: None).
Returns:

A complete container definition object usable with the CreateModel API.

Return type:

dict[str, str]

sagemaker.session.production_variant(model_name, instance_type, initial_instance_count=1, variant_name='AllTraffic', initial_weight=1)

Create a production variant description suitable for use in a ProductionVariant list as part of a CreateEndpointConfig request.

Parameters:
  • model_name (str) – The name of the SageMaker model this production variant references.
  • instance_type (str) – The EC2 instance type for this production variant. For example, ‘ml.c4.8xlarge’.
  • initial_instance_count (int) – The initial instance count for this production variant (default: 1).
  • variant_name (string) – The VariantName of this production variant (default: ‘AllTraffic’).
  • initial_weight (int) – The relative InitialVariantWeight of this production variant (default: 1).
Returns:

An SageMaker ProductionVariant description

Return type:

dict[str, str]

sagemaker.session.get_execution_role(sagemaker_session=None)

Return the role ARN whose credentials are used to call the API. Throws an exception if :param sagemaker_session: Current sagemaker session :type sagemaker_session: Session

Returns:The role ARN
Return type:(str)
class sagemaker.session.s3_input(s3_data, distribution='FullyReplicated', compression=None, content_type=None, record_wrapping=None, s3_data_type='S3Prefix')

Bases: object

Amazon SageMaker channel configurations for S3 data sources.

config

dict[str, dict] – A SageMaker DataSource referencing a SageMaker S3DataSource.

Create a definition for input data used by an SageMaker training job.

See AWS documentation on the CreateTrainingJob API for more details on the parameters.

Parameters:
  • s3_data (str) – Defines the location of s3 data to train on.
  • distribution (str) – Valid values: ‘FullyReplicated’, ‘ShardedByS3Key’ (default: ‘FullyReplicated’).
  • compression (str) – Valid values: ‘Gzip’, ‘Bzip2’, ‘Lzop’ (default: None).
  • content_type (str) – MIME type of the input data (default: None).
  • record_wrapping (str) – Valid values: ‘RecordIO’ (default: None).
  • s3_data_type (str) – Value values: ‘S3Prefix’, ‘ManifestFile’. If ‘S3Prefix’, s3_data defines a prefix of s3 objects to train on. All objects with s3 keys beginning with s3_data will be used to train. If ‘ManifestFile’, then s3_data defines a single s3 manifest file, listing each s3 object to train on. The Manifest file format is described in the SageMaker API documentation: https://docs.aws.amazon.com/sagemaker/latest/dg/API_S3DataSource.html