Model Archiver

1.0.3 · maintenance · verified Thu Apr 16

Model Archiver is a Python library and command-line tool used for creating archives of trained neural network models. These archives, typically with a .mar extension, are specifically structured to be consumed by the MXNet-Model-Server for efficient inference. The PyPI package (version 1.0.3) serves as a standalone tool, although its core functionality has largely evolved into 'torch-model-archiver' for the 'TorchServe' (formerly 'Multi-Model-Server') ecosystem.

Common errors

```
model-archiver: command not found
```
cause The `model-archiver` executable is not in your system's PATH, or the package was not installed correctly.

fix Ensure `model-archiver` is installed via `pip install model-archiver`. If it is, locate your Python's script directory (e.g., `~/.local/bin` on Linux or `Scripts` in your virtual environment on Windows) and add it to your system's PATH, or explicitly call it using `python -m model_archiver.model_packaging`.
```
Model archive fails with missing dependencies: No module named 'your_dependency'
```
cause Your model's handler or auxiliary scripts require Python packages that are not part of the standard Python library or already installed in the serving environment, and these were not included in the archive.

fix Provide a `requirements.txt` file listing all custom Python dependencies and pass it to `model-archiver` using the `--extra-files` argument (e.g., `--extra-files requirements.txt`). For packages not on PyPI, include their source or wheel files directly via `--extra-files` and handle installation within your custom handler's `initialize` method if necessary.
```
Error: Signature file not found or invalid format.
```
cause The `signature.json` file, which describes model inputs and outputs for MXNet-Model-Server, is either missing from your model artifacts or is malformed.

fix Ensure a valid `signature.json` file is present in your `--model-path` directory. Refer to the MXNet-Model-Server documentation for the correct `signature.json` format. It defines the expected inputs and outputs for your model.
```
Error: "No handler defined for model" when deploying .tar.gz to SageMaker multi-model endpoint, even with handler in archive.
```
cause SageMaker multi-model endpoints might treat a `.tar.gz` file as raw model artifacts rather than a model archive, failing to correctly extract and register the handler specified within.

fix When creating the archive for SageMaker multi-model endpoints, use `model-archiver` with `--archive-format no-archive`. Then, manually compress the resulting directory into a `.tar.gz` ensuring that the `MAR-INF` (manifest) directory is at the root level of the tarball. SageMaker needs to decompress directly to your model files and handler, not an extra parent directory.

Warnings

breaking The `model-archiver` PyPI package (version 1.0.3) is primarily designed for the legacy MXNet-Model-Server. For modern deep learning model serving, particularly with PyTorch, the actively maintained and recommended tool is `torch-model-archiver`, which is part of the `TorchServe` ecosystem (evolved from Multi-Model-Server).
Fix: For new projects or PyTorch models, consider using `pip install torch-model-archiver` and the associated `torch-model-archiver` CLI. This provides access to the latest features, bug fixes, and active community support.
gotcha The `model-archiver` is predominantly a command-line interface tool. While it exposes Python modules, its intended usage for creating model archives is through its CLI. Programmatic invocation of its internal functions is less common and may have limited dedicated documentation.
Fix: For packaging models, rely on the `model-archiver` command-line tool. If programmatic integration is essential, consult the source code on GitHub for direct API usage patterns, focusing on the `model_archiver.mar` module.
gotcha When packaging ONNX models, additional dependencies (`protobuf` compiler, `onnx`, `mxnet`) are not installed by default with `model-archiver`. Without these, ONNX model packaging will fail.
Fix: Before archiving ONNX models, manually install the required libraries: `pip install protobuf onnx mxnet` (or the specific MXNet variant like `mxnet-cu101`). Ensure a protobuf compiler is also available in your environment.
gotcha Handling complex model project structures (e.g., multiple interdependent Python files in subdirectories) within the handler can lead to import errors. The archiving process might flatten directory structures, causing Python's import mechanism to fail.
Fix: For complex dependencies, either package them as a Python egg/wheel and include it via `--extra-files`, or adjust your handler to manually manage the Python path or use relative imports carefully. Alternatively, provide a `requirements.txt` with your `model-archiver` command for dependencies available on PyPI.

Install

pip install model-archiver Install stable release

Imports

ModelArchiver
```
from model_archiver.mar import ModelArchiver
```
While a programmatic interface exists, `model-archiver` is primarily designed for command-line use. Direct import of internal classes is less common for end-user model archiving.

Quickstart

Create a model archive (.mar file) for an MXNet model. This command packages your model artifacts, a custom handler script (`my_handler.py`), and any extra files (like `requirements.txt` or configuration files) into a single archive. The generated .mar file is then placed in the specified `export-path`. Ensure your handler script correctly implements the `initialize`, `preprocess`, `inference`, and `postprocess` methods for your specific model.

model-archiver --model-name my_mxnet_model \
               --version 1.0 \
               --model-path ./path_to_model_artifacts/ \
               --handler my_handler.py \
               --extra-files requirements.txt,config.json \
               --export-path ./model_store/

# Example `my_handler.py` (simplified structure):
# class MXNetHandler:
#     def __init__(self):
#         self.model = None
#     def initialize(self, context):
#         properties = context.system_properties
#         model_dir = properties.get("model_dir")
#         # Load model, e.g., using MXNet's gluon.nn
#         # self.model = gluon.nn.load_param(os.path.join(model_dir, 'model_params.params'))
#     def preprocess(self, data):
#         # Preprocess input data
#         return data
#     def inference(self, data):
#         # Perform inference using self.model
#         return self.model(data)
#     def postprocess(self, data):
#         # Postprocess inference results
#         return data

view raw JSON →