Registry / ai-ml / optimum-quanto

optimum-quanto

JSON →
library0.2.7pypypi✓ verified 85d ago

Optimum Quanto is a PyTorch quantization backend for Hugging Face Optimum, enabling efficient training and inference of large language models (LLMs) and other neural networks with reduced precision (e.g., 8-bit integers or 8-bit floats). It focuses on model optimization for hardware acceleration by integrating with PyTorch's native quantization functionalities. The current version is 0.2.7. As a rapidly evolving library deeply integrated with the Hugging Face ecosystem and PyTorch's quantization efforts, its release cadence is generally frequent, often tied to major Optimum or PyTorch updates.

pip install optimum-quanto
INSTALL
IMPORT
SIG · OPTIMUM-QUANTO
O
optimum-quanto
ai-mlpythonv0.2.7
Install
69.8s avg
Import
6990ms
Disk
4890MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.7 · 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
glibc
py 3.10
✕ build_error
✓ 80.6s
py 3.11
✕ build_error
✓ 73.05s
py 3.12
✕ build_error
✓ 64.65s
py 3.13
✕ build_error
✓ 61.05s
py 3.9
✕ build_error
✕ timeout
4890MB installed
● package 4890MB
Code
Verified usage

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

quantize
from optimum.quanto import quantize
The primary function to apply quantization to a PyTorch module or its submodules.
freeze
from optimum.quanto import freeze
Used to 'freeze' quantized weights, making them immutable and often enabling further performance optimizations for inference.
set_qtype
from optimum.quanto import set_qtype
Function to dynamically set the quantization type (e.g., int8, float8) for specific modules or layers.

This quickstart demonstrates how to load a pre-trained Hugging Face Transformers model, apply 8-bit integer quantization using `optimum-quanto`'s `quantize` function, and then `freeze` the model for efficient inference. It concludes with a basic text generation example to verify functionality. Ensure a compatible PyTorch version and potentially a CUDA-enabled GPU for best results.

import torch from transformers import AutoModelForCausalLM, AutoTokenizer from optimum.quanto import quantize, freeze # Load a pre-trained model (using a small one for quick execution) model_id = "TinyLlama/TinyLlama-1.1B-Chat-v1.0" tokenizer = AutoTokenizer.from_pretrained(model_id) # Ensure model is on a GPU if available, or compatible dtype device = "cuda" if torch.cuda.is_available() else "cpu" model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float16).to(device) # Define the target quantization type (e.g., 8-bit integer) qtype = torch.int8 # Apply quantization to the model # This converts weights to quantized tensors according to qtype quantize(model, qtype=qtype) # Freeze the quantized model for efficient inference # This makes weights immutable and enables further backend optimizations freeze(model) print(f"Model quantized to {qtype} and frozen on {device}.") # Example inference with the quantized model inputs = tokenizer("Hello, my name is", return_tensors="pt").to(device) with torch.no_grad(): outputs = model.generate(**inputs, max_new_tokens=20, do_sample=True, top_k=50, top_p=0.95) print("Generated text:") print(tokenizer.decode(outputs[0].cpu(), skip_special_tokens=True))
Debug
Known issues
breakingOptimum Quanto has strict compatibility requirements with PyTorch versions. Specifically, `torch` versions `2.2.0`, `2.2.1`, and `2.2.2` are explicitly known to be incompatible and will cause runtime errors or incorrect behavior.
fix
Before installing, ensure your `torch` installation meets the requirements specified by `optimum-quanto`. Explicitly install a compatible version (e.g., `pip install torch==2.1.2` or `pip install torch==2.3.0` for CUDA).
affects: All versions of `optimum-quanto` dependent on `torch` versions 2.2.x.
gotchaQuantization, especially to lower precision types like int8 or float8, inherently involves a trade-off where model accuracy or performance on downstream tasks might degrade. This is an expected consequence of reducing the model's precision.
fix
Always evaluate your quantized model thoroughly on a representative validation dataset. If accuracy degradation is unacceptable, consider using Quantization-Aware Training (QAT) or opting for higher precision quantization (e.g., float16 if available) if your hardware supports it.
affects: All versions
gotchaThe primary performance benefits of `optimum-quanto` (e.g., speedups from INT8 or FP8) are often contingent on specific hardware acceleration (e.g., NVIDIA GPUs with Tensor Cores or specific CPU instruction sets). Running quantized models on incompatible hardware might not yield expected speedups or could even be slower than the float32 baseline.
fix
Verify that your target deployment hardware supports the desired quantization precision. Consult `quanto` and PyTorch documentation for recommended hardware configurations and validate performance through profiling on your specific device.
affects: All versions
gotchaAfter applying `quantize()` to a model, it is crucial to also call `freeze()` on the model, especially when preparing it for inference. Forgetting to freeze can prevent essential backend optimizations from taking effect, leading to suboptimal performance or incorrect behavior in some scenarios.
fix
Always include `freeze(model)` after `quantize(model, ...)` in your model preparation pipeline for inference. This ensures that the weights are finalized and enables the backend to apply its full set of optimizations.
affects: All versions
Errors
Common errors & fixes
ImportError: cannot import name 'quantize' from 'optimum.quanto' (...)
`optimum-quanto` is not installed, or the `optimum` package itself is too old and does not include the `quanto` subpackage.
fix
Ensure `optimum-quanto` is installed (`pip install optimum-quanto`) and that your `optimum` package is updated to a compatible version (`pip install --upgrade optimum`).
RuntimeError: The installed version of PyTorch (X.Y.Z) is not supported by optimum-quanto. Please install a compatible version (e.g., >=2.0.0, !=2.2.0, !=2.2.1, !=2.2.2).
Attempting to use `optimum-quanto` with a PyTorch version that is explicitly blacklisted due to known compatibility issues.
fix
Uninstall the problematic PyTorch version and install a compatible one. For example: `pip uninstall torch torchvision torchaudio` followed by `pip install torch==2.1.2 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` (adjust CUDA version if necessary) or `pip install torch==2.3.0`.
ValueError: 'float8_e4m3fn' is not a valid QuantizationType for device 'cpu'
Attempting to use a specific, hardware-dependent quantization type (like `float8`) on a device that does not support it (e.g., CPU) or without the necessary software/driver configurations (e.g., specific CUDA compute capability).
fix
Either ensure you are running on compatible GPU hardware with appropriate drivers and PyTorch build, or switch to a more broadly supported quantization type for your device, such as `torch.int8`.
Upgrade
Version history
0.2.7latest on PyPI · released Mar 6, 2025
Audit
Dependencies
optimumrequiredCore Hugging Face Optimum library, providing common interfaces for model loading and optimization. Specific version requirements for compatibility.
torchrequiredPrimary deep learning framework. Specific versions are explicitly excluded due to known compatibility issues with quanto's quantization implementations.
transformersrequiredHugging Face Transformers library, commonly used for loading pre-trained models that will be quantized.
Agent activity
14 hits · last 30 days
node
13
OpenAI (training)
1
Resources
optimum-quanto — pip install optimum-quanto · libregistry