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

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.