Deserializers

Implements base methods for deserializing data returned from an inference endpoint.

class sagemaker.base_deserializers.BaseDeserializer

Bases: ABC

Abstract base class for creation of new deserializers.

Provides a skeleton for customization requiring the overriding of the method deserialize and the class attribute ACCEPT.

abstract deserialize(stream, content_type)

Deserialize data received from an inference endpoint.

Parameters:

stream (botocore.response.StreamingBody) – Data to be deserialized.
content_type (str) – The MIME type of the data.

Returns:

The data deserialized into an object.

Return type:

object

abstract property ACCEPT: The content types that are expected from the inference endpoint.

class sagemaker.base_deserializers.SimpleBaseDeserializer(accept='*/*')

Bases: BaseDeserializer

Abstract base class for creation of new deserializers.

This class extends the API of :class:~`sagemaker.deserializers.BaseDeserializer` with more user-friendly options for setting the ACCEPT content type header, in situations where it can be provided at init and freely updated.

Initialize a SimpleBaseDeserializer instance.

Parameters:: accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: “/”).

property ACCEPT: The tuple of possible content types that are expected from the inference endpoint.

class sagemaker.base_deserializers.StringDeserializer(encoding='UTF-8', accept='application/json')

Bases: SimpleBaseDeserializer

Deserialize data from an inference endpoint into a decoded string.

Initialize a StringDeserializer instance.

Parameters:

encoding (str) – The string encoding to use (default: UTF-8).
accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: “application/json”).

deserialize(stream, content_type)

Deserialize data from an inference endpoint into a decoded string.

Parameters:

stream (botocore.response.StreamingBody) – Data to be deserialized.
content_type (str) – The MIME type of the data.

Returns:

The data deserialized into a decoded string.

Return type:

str

class sagemaker.base_deserializers.BytesDeserializer(accept='*/*')

Bases: SimpleBaseDeserializer

Deserialize a stream of bytes into a bytes object.

Initialize a SimpleBaseDeserializer instance.

Parameters:: accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: “/”).

deserialize(stream, content_type)

Read a stream of bytes returned from an inference endpoint.

Parameters:

stream (botocore.response.StreamingBody) – A stream of bytes.
content_type (str) – The MIME type of the data.

Returns:

The bytes object read from the stream.

Return type:

bytes

class sagemaker.base_deserializers.CSVDeserializer(encoding='utf-8', accept='text/csv')

Bases: SimpleBaseDeserializer

Deserialize a stream of bytes into a list of lists.

Consider using :class:~`sagemaker.deserializers.NumpyDeserializer` or :class:~`sagemaker.deserializers.PandasDeserializer` instead, if you’d like to convert text/csv responses directly into other data types.

Initialize a CSVDeserializer instance.

Parameters:

encoding (str) – The string encoding to use (default: “utf-8”).
accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: “text/csv”).

deserialize(stream, content_type)

Deserialize data from an inference endpoint into a list of lists.

Parameters:

stream (botocore.response.StreamingBody) – Data to be deserialized.
content_type (str) – The MIME type of the data.

Returns:

The data deserialized into a list of lists representing the: contents of a CSV file.

Return type:

list

class sagemaker.base_deserializers.StreamDeserializer(accept='*/*')

Bases: SimpleBaseDeserializer

Directly return the data and content-type received from an inference endpoint.

It is the user’s responsibility to close the data stream once they’re done reading it.

Initialize a SimpleBaseDeserializer instance.

Parameters:: accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: “/”).

deserialize(stream, content_type)

Returns a stream of the response body and the MIME type of the data.

Parameters:

stream (botocore.response.StreamingBody) – A stream of bytes.
content_type (str) – The MIME type of the data.

Returns:

A two-tuple containing the stream and content-type.

Return type:

tuple

class sagemaker.base_deserializers.NumpyDeserializer(dtype=None, accept='application/x-npy', allow_pickle=False)

Bases: SimpleBaseDeserializer

Deserialize a stream of data in .npy, .npz or UTF-8 CSV/JSON format to a numpy array.

Note that when using application/x-npz archive format, the result will usually be a dictionary-like object containing multiple arrays (as per numpy.load()) - instead of a single array.

Initialize a NumpyDeserializer instance.

Parameters:

dtype (str) – The dtype of the data (default: None).
accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: “application/x-npy”).
allow_pickle (bool) – Allow loading pickled object arrays (default: False).

deserialize(stream, content_type)

Deserialize data from an inference endpoint into a NumPy array.

Parameters:

stream (botocore.response.StreamingBody) – Data to be deserialized.
content_type (str) – The MIME type of the data.

Returns:

The data deserialized into a NumPy array.

Return type:

numpy.ndarray

class sagemaker.base_deserializers.JSONDeserializer(accept='application/json')

Bases: SimpleBaseDeserializer

Deserialize JSON data from an inference endpoint into a Python object.

Initialize a JSONDeserializer instance.

Parameters:: accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: “application/json”).

deserialize(stream, content_type)

Deserialize JSON data from an inference endpoint into a Python object.

Parameters:

stream (botocore.response.StreamingBody) – Data to be deserialized.
content_type (str) – The MIME type of the data.

Returns:

The JSON-formatted data deserialized into a Python object.

Return type:

object

class sagemaker.base_deserializers.PandasDeserializer(accept=('text/csv', 'application/json'))

Bases: SimpleBaseDeserializer

Deserialize CSV or JSON data from an inference endpoint into a pandas dataframe.

Initialize a PandasDeserializer instance.

Parameters:: accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: (“text/csv”,”application/json”)).

deserialize(stream, content_type)

Deserialize CSV or JSON data from an inference endpoint into a pandas dataframe.

If the data is JSON, the data should be formatted in the ‘columns’ orient. See https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_json.html

Parameters:

stream (botocore.response.StreamingBody) – Data to be deserialized.
content_type (str) – The MIME type of the data.

Returns:

The data deserialized into a pandas DataFrame.

Return type:

pandas.DataFrame

class sagemaker.base_deserializers.JSONLinesDeserializer(accept='application/jsonlines')

Bases: SimpleBaseDeserializer

Deserialize JSON lines data from an inference endpoint.

Initialize a JSONLinesDeserializer instance.

Parameters:: accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: (“text/csv”,”application/json”)).

deserialize(stream, content_type)

Deserialize JSON lines data from an inference endpoint.

See https://docs.python.org/3/library/json.html#py-to-json-table to understand how JSON values are converted to Python objects.

Parameters:

stream (botocore.response.StreamingBody) – Data to be deserialized.
content_type (str) – The MIME type of the data.

Returns:

A list of JSON serializable objects.

Return type:

list

class sagemaker.base_deserializers.TorchTensorDeserializer(accept='tensor/pt')

Bases: SimpleBaseDeserializer

Deserialize stream to torch.Tensor.

Parameters:

stream (botocore.response.StreamingBody) – Data to be deserialized.
content_type (str) – The MIME type of the data.

Returns:

The data deserialized into a torch Tensor.

Return type:

torch.Tensor

Initialize a SimpleBaseDeserializer instance.

Parameters:: accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: “/”).

deserialize(stream, content_type='tensor/pt')

Deserialize streamed data to TorchTensor

See https://pytorch.org/docs/stable/generated/torch.from_numpy.html

Parameters:

stream (botocore.response.StreamingBody) – Data to be deserialized.
content_type (str) – The MIME type of the data.

Returns:

A list of TorchTensor serializable objects.

Return type:

list

class sagemaker.base_deserializers.RecordDeserializer(accept='application/x-recordio-protobuf')

Bases: SimpleBaseDeserializer

Deserialize RecordIO Protobuf data from an inference endpoint.

Initialize a RecordDeserializer instance.

Parameters:: accept (union[str, tuple[str]]) – The MIME type (or tuple of allowable MIME types) that is expected from the inference endpoint (default: “application/x-recordio-protobuf”).

deserialize(data, content_type)

Deserialize RecordIO Protobuf data from an inference endpoint.

Parameters:

data (object) – The protobuf message to deserialize.
content_type (str) – The MIME type of the data.

Returns:

A list of records.

Return type:

list

Implements methods for deserializing data returned from an inference endpoint.

sagemaker.deserializers.retrieve_options(region=None, model_id=None, model_version=None, hub_arn=None, tolerate_vulnerable_model=False, tolerate_deprecated_model=False, sagemaker_session=<sagemaker.session.Session object>)

Retrieves the supported deserializers for the model matching the given arguments.

Parameters:

region (str) – The AWS Region for which to retrieve the supported deserializers. Defaults to None.
model_id (str) – The model ID of the model for which to retrieve the supported deserializers. (Default: None).
model_version (str) – The version of the model for which to retrieve the supported deserializers. (Default: None).
hub_arn (str) – The arn of the SageMaker Hub for which to retrieve model details from. (Default: None).
tolerate_vulnerable_model (bool) – True if vulnerable versions of model specifications should be tolerated (exception not raised). If False, raises an exception if the script used by this version of the model has dependencies with known security vulnerabilities. (Default: False).
tolerate_deprecated_model (bool) – True if deprecated models should be tolerated (exception not raised). False if these models should raise an exception. (Default: False).
sagemaker_session (sagemaker.session.Session) – A SageMaker Session object, used for SageMaker interactions. If not specified, one is created using the default AWS configuration chain. (Default: sagemaker.jumpstart.constants.DEFAULT_JUMPSTART_SAGEMAKER_SESSION).

Returns:

The supported deserializers to use for the model.

Return type:

List[BaseDeserializer]

Raises:

ValueError – If the combination of arguments specified is not supported.

sagemaker.deserializers.retrieve_default(region=None, model_id=None, model_version=None, hub_arn=None, tolerate_vulnerable_model=False, tolerate_deprecated_model=False, sagemaker_session=<sagemaker.session.Session object>, model_type=JumpStartModelType.OPEN_WEIGHTS, config_name=None)

Retrieves the default deserializer for the model matching the given arguments.

Parameters:

region (str) – The AWS Region for which to retrieve the default deserializer. Defaults to None.
model_id (str) – The model ID of the model for which to retrieve the default deserializer. (Default: None).
model_version (str) – The version of the model for which to retrieve the default deserializer. (Default: None).
hub_arn (str) – The arn of the SageMaker Hub for which to retrieve model details from. (Default: None).
tolerate_vulnerable_model (bool) – True if vulnerable versions of model specifications should be tolerated (exception not raised). If False, raises an exception if the script used by this version of the model has dependencies with known security vulnerabilities. (Default: False).
tolerate_deprecated_model (bool) – True if deprecated models should be tolerated (exception not raised). False if these models should raise an exception. (Default: False).
sagemaker_session (sagemaker.session.Session) – A SageMaker Session object, used for SageMaker interactions. If not specified, one is created using the default AWS configuration chain. (Default: sagemaker.jumpstart.constants.DEFAULT_JUMPSTART_SAGEMAKER_SESSION).
config_name (Optional[str]) – Name of the JumpStart Model config to apply. (Default: None).
model_type (JumpStartModelType) –

Returns:

The default deserializer to use for the model.

Return type:

BaseDeserializer

Raises:

ValueError – If the combination of arguments specified is not supported.