Metadata-Version: 2.4
Name: xslim
Version: 2.1.0
Summary: XSlim is an offline quantization toolkit based on PPQ for ONNX models.
Author-email: SpacemiT <xslim@spacemit.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/spacemit-com/xslim
Project-URL: Repository, https://github.com/spacemit-com/xslim
Project-URL: Documentation, https://github.com/spacemit-com/xslim/tree/main/doc
Project-URL: Issues, https://github.com/spacemit-com/xslim/issues
Keywords: onnx,quantization,ptq,fp16,dynamic-quantization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.0
Requires-Dist: protobuf
Requires-Dist: torch>=2.0.0
Requires-Dist: torchvision
Requires-Dist: tqdm
Requires-Dist: pandas
Requires-Dist: opencv-python
Requires-Dist: onnx<1.22.0,>=1.21.0
Requires-Dist: tabulate
Requires-Dist: onnxruntime<=1.24.3,>=1.24.0
Requires-Dist: onnx-graphsurgeon>=0.6.1
Requires-Dist: onnxconverter_common>=1.16.0
Requires-Dist: loguru
Requires-Dist: onnxslim==0.1.87
Dynamic: license-file

# XSlim

[中文版](README_zh.md) | English

[![Version](https://img.shields.io/badge/version-2.1.0-blue.svg)](https://github.com/spacemit-com/xslim/releases)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-%3E%3D3.9-blue.svg)](https://www.python.org/)

**XSlim** is a Post-Training Quantization (PTQ) tool developed by [SpacemiT](https://www.spacemit.com). It integrates chip-optimized quantization strategies and provides a unified interface for ONNX model quantization via JSON configuration files.

---

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [Samples](#samples)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [License](#license)

## Features

- **INT8 / FP16 / Dynamic Quantization** – multiple precision levels for different deployment scenarios
- **JSON-driven configuration** – simple, declarative quantization setup
- **Python API & CLI** – use as a library or from the command line
- **Custom preprocessing** – plug in your own preprocessing functions
- **Expanded ONNX operator coverage** – run Graphwise Analysis and quantization on models that use common arithmetic, activation, comparison, reduction, dropout, and opset-24 `Pad` patterns
- **Automatic YOLO decode fusion** – fuse supported YOLO decode subgraphs into a single `spacemit_functions.YoloDecode` node
- **ONNX Function-aware export** – preserve embedded FunctionProto definitions and emit required custom-domain imports automatically
- **ONNX-based workflow** – built on the ONNX ecosystem

## Installation

```bash
python -m pip install xslim
```

Or install from source:

```bash
git clone https://github.com/spacemit-com/xslim.git
cd xslim
python -m pip install .
```

For local development, use an editable install:

```bash
python -m pip install -e .
```

Build metadata is defined in `pyproject.toml`, and the import package lives under the standard `src/` layout. To build source and wheel distributions locally:

```bash
python -m pip install --upgrade build
python -m build
```

## Quick Start

### Python API

```python
import xslim

# Using a JSON config file
xslim.quantize_onnx_model("config.json")

# Using a dict
config = {
    "model_parameters": {
        "onnx_model": "model.onnx",
        "working_dir": "./output"
    },
    "calibration_parameters": {
        "input_parameters": [{
            "mean_value": [123.675, 116.28, 103.53],
            "std_value": [58.395, 57.12, 57.375],
            "color_format": "rgb",
            "preprocess_file": "PT_IMAGENET",
            "data_list_path": "./calib_img_list.txt"
        }]
    }
}
xslim.quantize_onnx_model(config)

# You can also pass the model path and output path directly
xslim.quantize_onnx_model("config.json", "input.onnx", "output.onnx")
```

### Command Line

```bash
# Installed CLI entry point
xslim --config config.json

# Module entry point also remains available
python -m xslim --config config.json

# Specify input and output model paths
xslim -c config.json -i input.onnx -o output.onnx

# Dynamic quantization (no config file needed)
xslim -i input.onnx -o output.onnx --dynq

# FP16 conversion (no config file needed)
xslim -i input.onnx -o output.onnx --fp16

# Convert the default ai.onnx opset to a target version
xslim -i input.onnx -o output.onnx --opset 20

# ONNX simplification only (no config file needed)
xslim -i input.onnx -o output.onnx
```

For config-free dynamic quantization and FP16 conversion, you can exclude operators with comma-separated names or types:

```bash
xslim -i input.onnx -o output.onnx --dynq --ignore_op_types Softmax,LayerNormalization
xslim -i input.onnx -o output.onnx --fp16 --ignore_op_names /model/head/MatMul
```

Static INT8 quantization expects a floating-point input model. If the model already contains `QuantizeLinear` or `DequantizeLinear`, XSlim stops with a clear error instead of quantizing an already-quantized graph again.

For supported YOLO exports, no extra switch is required: XSlim will try to fuse decode-heavy post-processing into `spacemit_functions.YoloDecode` during simplification and keep the corresponding ONNX `FunctionProto` in the exported model.

## Documentation

- [Configuration Reference](doc/configuration.md) – Full description of all JSON configuration options
- [Examples](doc/examples.md) – Step-by-step guides for INT8, FP16, dynamic quantization, custom preprocessing, and more
- [Accuracy Tuning Guide](doc/accuracy_tuning.md) – How to diagnose and improve quantization accuracy

## Samples

See the [samples](samples/) directory for ready-to-run examples covering ResNet-18, MobileNet V3, BERT, and more. YOLO-specific usage notes are documented in the examples and accuracy-tuning guides.

## Changelog

For a full list of published versions, see the [Releases](https://github.com/spacemit-com/xslim/releases) page. The summary below is synchronized with that release history; `2.1.0` is the current in-tree development version and has not been published yet.

| Version | Highlights |
| --- | --- |
| 2.1.0 | Current in-tree development version; add automatic `spacemit_functions.YoloDecode` fusion for supported YOLO exports, preserve custom ONNX `FunctionProto` definitions during quantization/export, improve opset-24/custom-domain handling coverage, expand ONNX operator execution/socket coverage, support scalar and axes-input reduce kernels, and reject static re-quantization of models that already contain `QuantizeLinear` / `DequantizeLinear` |
| [2.0.14](https://github.com/spacemit-com/xslim/releases/tag/2.0.14) | Latest published release; add configurable default `ai.onnx` opset conversion for quantization and conversion workflows |
| [2.0.13](https://github.com/spacemit-com/xslim/releases/tag/2.0.13) | Upgrade the default ONNX opset to 24, standardize operator domains, and align version metadata with the 2.0.12 release |
| [2.0.12](https://github.com/spacemit-com/xslim/releases/tag/2.0.12) | Complete README changelog/release metadata, add accuracy-tuning docs and README links, introduce the xslim-accuracy-tuning GitHub skill, add YOLO truncation guidance, and rename input parameters for consistency |
| [2.0.11](https://github.com/spacemit-com/xslim/releases/tag/2.0.11) | Fix Pad/missing-input handling, add Or/Einsum/Selu support, normalize Conv/ConvTranspose kernel shapes, and raise minimum Python to 3.9 |
| [2.0.10](https://github.com/spacemit-com/xslim/releases/tag/2.0.10) | Align release metadata, improve CI/test coverage, normalize missing default ONNX opset before dynamic quantization, and refine shape inference handling |
| [2.0.9](https://github.com/spacemit-com/xslim/releases/tag/2.0.9) | Add documentation, preserve tensor dtype metadata during FP16 conversion, and restore compatibility with onnxslim 0.1.87 |
| [2.0.8](https://github.com/spacemit-com/xslim/releases/tag/2.0.8) | Improve packaging/CI, add torch executor operator coverage, add PyPI publish workflow, and centralize version metadata |
| [2.0.7](https://github.com/spacemit-com/xslim/releases/tag/2.0.7) | Fix FP16 conversion bug on complex models |
| [2.0.6](https://github.com/spacemit-com/xslim/releases/tag/2.0.6) | Fix metadata props deletion; default CLI behavior changed to model simplification (use `--dynq` for dynamic quantization) |

## Contributing

Contributions are welcome! Please open an [issue](https://github.com/spacemit-com/xslim/issues) or submit a [pull request](https://github.com/spacemit-com/xslim/pulls).

## License

This project is licensed under the [Apache License 2.0](LICENSE).
