Registry / aws / sagemaker-inference

sagemaker-inference

JSON →
library1.10.1pypypi✓ verified 89d ago

The sagemaker-inference toolkit is an open-source Python library designed to simplify the creation of serving containers for machine learning models on Amazon SageMaker. It provides a model serving stack built on Multi Model Server (MMS), enabling users to easily implement custom inference logic. The current version is 1.10.1, with a regular release cadence addressing bug fixes and new features, including support for newer Python versions and improved dependency management.

pip install sagemaker-inference
INSTALL
IMPORT
SIG · SAGEMAKER-INFERENC
S
sagemaker-inference
awspythonv1.10.1
Install
10.7s avg
Import
983ms
Disk
265MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.10.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.014s · 266.1MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 10.7s · import 0.951s · 257MB
265MB installed
● package 265MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DefaultInferenceHandler
✓ from sagemaker_inference.default_inference_handler import DefaultInferenceHandler
Base class for custom inference handlers, commonly extended to implement `model_fn`, `input_fn`, `predict_fn`, and `output_fn`.
model_server
✓ from sagemaker_inference import model_server
Used to start the underlying model server within the container's entrypoint.
Transformer
✓ from sagemaker_inference.transformer import Transformer
Used in the handler service to wrap the custom inference handler.
DefaultHandlerService
✓ from sagemaker_inference.default_handler_service import DefaultHandlerService
Base class for the handler service, which orchestrates the model server and the inference handler.

This quickstart demonstrates the core pattern for using `sagemaker-inference` to create a custom inference handler. It defines a `CustomInferenceHandler` class that extends `DefaultInferenceHandler`, overriding `model_fn`, `input_fn`, `predict_fn`, and `output_fn`. These functions are responsible for loading the model, deserializing input, making predictions, and serializing output, respectively. This file would typically be part of your model archive within a SageMaker custom container.

import os import json from sagemaker_inference.default_inference_handler import DefaultInferenceHandler from sagemaker_inference import content_types, decoder, encoder class CustomInferenceHandler(DefaultInferenceHandler): def default_model_fn(self, model_dir, context=None): """Loads a dummy model for demonstration. In a real scenario, this would load your actual trained model from `model_dir`. """ print(f"Loading model from: {model_dir}") # Simulate loading a model artifact # For example, if you had a 'model.pkl' in model_dir # model_path = os.path.join(model_dir, 'model.pkl') # model = joblib.load(model_path) return {"status": "model_loaded", "path": model_dir} def default_input_fn(self, input_data, content_type, context=None): """Deserializes the input data from the request. Supports JSON and CSV. """ if content_type == content_types.JSON: return decoder.decode(input_data, content_type) elif content_type == content_types.CSV: # Assuming CSV is a simple string for this example return input_data.decode('utf-8').split(',') else: raise ValueError(f"Unsupported content type: {content_type}") def default_predict_fn(self, data, model, context=None): """Makes a dummy prediction based on the input data and the loaded model. """ print(f"Performing prediction with model: {model} and data: {data}") if isinstance(data, dict) and 'instances' in data: # Assume a common inference request format predictions = [item * 2 for item in data['instances']] elif isinstance(data, list): predictions = [item + "_processed" for item in data] else: predictions = f"Processed: {data}" return {"predictions": predictions} def default_output_fn(self, prediction, accept, context=None): """Serializes the prediction result to the requested accept type. Supports JSON. """ if accept == content_types.JSON: return encoder.encode(prediction, accept) else: raise ValueError(f"Unsupported accept type: {accept}") # To run this in a SageMaker container, you would have a Dockerfile # that installs sagemaker-inference and multi-model-server, copies this file # as 'inference.py' and sets up the entrypoint to start the model server. # e.g., using sagemaker_inference.model_server.start_model_server() # Example of how to manually test the handler (not typically run directly in a quickstart) if __name__ == '__main__': handler = CustomInferenceHandler() model = handler.default_model_fn('/opt/ml/model') # Simulates model_dir test_json_input = json.dumps({"instances": [1, 2, 3]}).encode('utf-8') json_data = handler.default_input_fn(test_json_input, content_types.JSON) json_prediction = handler.default_predict_fn(json_data, model) json_output = handler.default_output_fn(json_prediction, content_types.JSON) print(f"JSON Inference Result: {json_output.decode('utf-8')}") test_csv_input = b'hello,world' csv_data = handler.default_input_fn(test_csv_input, content_types.CSV) csv_prediction = handler.default_predict_fn(csv_data, model) csv_output = handler.default_output_fn(csv_prediction, content_types.JSON) # Output as JSON for simplicity print(f"CSV Inference Result: {csv_output.decode('utf-8')}")
Debug
Known issues
breakingHandler functions (`model_fn`, `input_fn`, `predict_fn`, `output_fn`) were updated in v1.7.0 to optionally accept a `context` object. If you were using older versions and had strict function signatures without `context`, this update might require changes, though omitting `context` from the declaration is still supported if not needed.
fix
Review your custom inference handler function signatures. If `context` is not used, you can omit it. If you wish to use it, ensure your signatures include `context=None` as the last parameter (e.g., `def model_fn(model_dir, context=None):`).
affects: >=1.7.0
gotchaPersistent 'psutil.ZombieProcess: PID still exists but it's a zombie' errors can occur, leading to endpoint instability or restarts. This was a known issue with specific `psutil` versions and PyTorch inference images.
fix
Upgrade `sagemaker-inference` to version 1.10.1 or higher, as a fix for this zombie process exception was included. Also, ensure your base Docker image and `psutil` version are compatible and updated.
affects: <1.10.1
gotchaWhen using custom Docker containers with `sagemaker-inference`, the `multi-model-server` (MMS) must be explicitly installed within your Dockerfile. Forgetting this can lead to the model server failing to start.
fix
Add `RUN pip install multi-model-server sagemaker-inference` to your Dockerfile. Also, ensure your container exposes port 8080 and handles `/ping` and `/invocations` routes.
affects: All versions
gotchaCustom Python dependencies specified in `requirements.txt` might fail to install if they are hosted in a private repository like AWS CodeArtifact without proper configuration.
fix
For `sagemaker-inference` versions 1.10.0 and above, configure CodeArtifact access using specific environment variables as detailed in AWS documentation. For older versions or other private repos, you might need to manually configure `pip` with `--extra-index-url` or package dependencies.
affects: <1.10.0
Errors
Common errors & fixes
psutil.ZombieProcess: PID still exists but it's a zombie
A race condition or issue in process monitoring within the model server, often related to the `psutil` library, causing the inference process to incorrectly identify a running process as a zombie. This was particularly prevalent in certain PyTorch inference containers.
fix
Update `sagemaker-inference` to version 1.10.1 or newer. If using PyTorch, ensure your PyTorch inference DLC version is recent enough to include the fix.
ModelError: An error occurred (ModelError) when calling the InvokeEndpoint operation: Received client error (413) from primary and could not load the entire response body
This error (HTTP 413 Payload Too Large) typically indicates that the inference request payload size exceeds the server's configured limit, or less commonly, that a worker timeout occurred if the payload is within limits.
fix
Increase the `SAGEMAKER_MAX_REQUEST_SIZE` environment variable for your endpoint. If the payload is small, check `SAGEMAKER_MODEL_SERVER_TIMEOUT_SECONDS` (introduced in v1.9.3) and `InvocationTimeoutSeconds` on the endpoint, and increase worker count if necessary. [cite: GitHub releases, 24]
ModuleNotFoundError: No module named 'sagemaker_inference'
The `sagemaker-inference` library is not installed in the Python environment of your SageMaker container or local setup.
fix
Ensure `pip install sagemaker-inference` is executed in your Dockerfile (for containers) or local development environment. If using a custom Dockerfile, verify the `RUN pip install ...` command is correctly placed before your Python code runs.
Upgrade
Version history
1.10.1latest on PyPI · released Oct 25, 2023
Audit
Dependencies
multi-model-serverrequiredThe inference toolkit's serving stack is built on Multi Model Server (MMS). While not a direct Python dependency for `sagemaker-inference` itself, MMS must be installed in the Docker container for the toolkit to function.
retryingoptionalVersion 1.9.1 relaxed the dependency on 'retrying', indicating it's used internally for robustness, particularly in starting the model server.
Agent activity
33 hits · last 30 days
node
28
OpenAI (training)
1
Resources
sagemaker-inference — pip install sagemaker-inference · libregistry