https://github.com/NVlabs/MambaVision
Official PyTorch Implementation of MambaVision: A Hybrid Mamba-Transformer Vision Backbone
https://github.com/NVlabs/MambaVision
deep-learning foundation-models huggingface-transformers hybrid-models image-classification mamba self-attention transformers vision-transformer visual-recognition
Last synced: 7 months ago
JSON representation
Official PyTorch Implementation of MambaVision: A Hybrid Mamba-Transformer Vision Backbone
- Host: GitHub
- URL: https://github.com/NVlabs/MambaVision
- Owner: NVlabs
- License: other
- Created: 2024-06-10T17:46:08.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-09T18:36:55.000Z (8 months ago)
- Last Synced: 2025-02-09T19:32:14.247Z (8 months ago)
- Topics: deep-learning, foundation-models, huggingface-transformers, hybrid-models, image-classification, mamba, self-attention, transformers, vision-transformer, visual-recognition
- Language: Python
- Homepage: https://arxiv.org/abs/2407.08083
- Size: 666 KB
- Stars: 898
- Watchers: 17
- Forks: 44
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MambaVision: A Hybrid Mamba-Transformer Vision Backbone
Official PyTorch implementation of [**MambaVision: A Hybrid Mamba-Transformer Vision Backbone**](https://arxiv.org/abs/2407.08083).
[](https://github.com/NVlabs/MambaVision/stargazers)
[Ali Hatamizadeh](https://research.nvidia.com/person/ali-hatamizadeh) and
[Jan Kautz](https://jankautz.com/).
For business inquiries, please visit our website and submit the form: [NVIDIA Research Licensing](https://www.nvidia.com/en-us/research/inquiries/)
---
MambaVision demonstrates a strong performance by achieving a new SOTA Pareto-front in
terms of Top-1 accuracy and throughput.
We introduce a novel mixer block by creating a symmetric path without SSM to enhance the modeling of global context:
MambaVision has a hierarchical architecture that employs both self-attention and mixer blocks:
## 💥 News 💥
- **[02.26.2025]** MambaVision has been accepted to CVPR 2025 !
- **[07.24.2024]** MambaVision [Hugging Face](https://huggingface.co/collections/nvidia/mambavision-66943871a6b36c9e78b327d3) models are released !
- **[07.14.2024]** We added support for processing any resolution images.
- **[07.12.2024]** [Paper](https://arxiv.org/abs/2407.08083) is now available on arXiv !
- **[07.11.2024]** [Mambavision pip package](https://pypi.org/project/mambavision/) is released !
- **[07.10.2024]** We have released the code and model checkpoints for Mambavision !
## Quick Start
### Hugging Face (Classification + Feature extraction)
Pretrained MambaVision models can be simply used via [Hugging Face](https://huggingface.co/collections/nvidia/mambavision-66943871a6b36c9e78b327d3) library with **a few lines of code**. First install the requirements:
```bash
pip install mambavision
```
The model can be simply imported:
```python
>>> from transformers import AutoModelForImageClassification
>>> model = AutoModelForImageClassification.from_pretrained("nvidia/MambaVision-T-1K", trust_remote_code=True)
```
We demonstrate an end-to-end image classification example in the following.
Given the following image from [COCO dataset](https://cocodataset.org/#home) val set as an input:
The following snippet can be used:
```python
from transformers import AutoModelForImageClassification
from PIL import Image
from timm.data.transforms_factory import create_transform
import requests
model = AutoModelForImageClassification.from_pretrained("nvidia/MambaVision-T-1K", trust_remote_code=True)
# eval mode for inference
model.cuda().eval()
# prepare image for the model
url = 'http://images.cocodataset.org/val2017/000000020247.jpg'
image = Image.open(requests.get(url, stream=True).raw)
input_resolution = (3, 224, 224) # MambaVision supports any input resolutions
transform = create_transform(input_size=input_resolution,
is_training=False,
mean=model.config.mean,
std=model.config.std,
crop_mode=model.config.crop_mode,
crop_pct=model.config.crop_pct)
inputs = transform(image).unsqueeze(0).cuda()
# model inference
outputs = model(inputs)
logits = outputs['logits']
predicted_class_idx = logits.argmax(-1).item()
print("Predicted class:", model.config.id2label[predicted_class_idx])
```
The predicted label is brown bear, bruin, Ursus arctos.
You can also use Hugging Face MambaVision models for feature extraction. The model provides the outputs of each stage of model (hierarchical multi-scale features in 4 stages) as well as the final averaged-pool features that are flattened. The former is used for downstream tasks such as classification and detection.
The following snippet can be used for feature extraction:
```Python
from transformers import AutoModel
from PIL import Image
from timm.data.transforms_factory import create_transform
import requests
model = AutoModel.from_pretrained("nvidia/MambaVision-T-1K", trust_remote_code=True)
# eval mode for inference
model.cuda().eval()
# prepare image for the model
url = 'http://images.cocodataset.org/val2017/000000020247.jpg'
image = Image.open(requests.get(url, stream=True).raw)
input_resolution = (3, 224, 224) # MambaVision supports any input resolutions
transform = create_transform(input_size=input_resolution,
is_training=False,
mean=model.config.mean,
std=model.config.std,
crop_mode=model.config.crop_mode,
crop_pct=model.config.crop_pct)
inputs = transform(image).unsqueeze(0).cuda()
# model inference
out_avg_pool, features = model(inputs)
print("Size of the averaged pool features:", out_avg_pool.size()) # torch.Size([1, 640])
print("Number of stages in extracted features:", len(features)) # 4 stages
print("Size of extracted features in stage 1:", features[0].size()) # torch.Size([1, 80, 56, 56])
print("Size of extracted features in stage 4:", features[3].size()) # torch.Size([1, 640, 7, 7])
```
Currently, we offer [MambaVision-T-1K](https://huggingface.co/nvidia/MambaVision-T-1K), [MambaVision-T2-1K](https://huggingface.co/nvidia/MambaVision-T2-1K), [MambaVision-S-1K](https://huggingface.co/nvidia/MambaVision-S-1K), [MambaVision-B-1K](https://huggingface.co/nvidia/MambaVision-B-1K), [MambaVision-L-1K](https://huggingface.co/nvidia/MambaVision-L-1K) and [MambaVision-L2-1K](https://huggingface.co/nvidia/MambaVision-L2-1K) on Hugging Face. All models can also be viewed [here](https://huggingface.co/collections/nvidia/mambavision-66943871a6b36c9e78b327d3).
### Classification (pip package)
We can also import pre-trained MambaVision models from the pip package with **a few lines of code**:
```bash
pip install mambavision
```
A pretrained MambaVision model with default hyper-parameters can be created as in:
```python
>>> from mambavision import create_model
# Define mamba_vision_T model
>>> model = create_model('mamba_vision_T', pretrained=True, model_path="/tmp/mambavision_tiny_1k.pth.tar")
```
Available list of pretrained models include `mamba_vision_T`, `mamba_vision_T2`, `mamba_vision_S`, `mamba_vision_B`, `mamba_vision_L` and `mamba_vision_L2`.
We can also simply test the model by passing a dummy image with **any resolution**. The output is the logits:
```python
>>> import torch
>>> image = torch.rand(1, 3, 512, 224).cuda() # place image on cuda
>>> model = model.cuda() # place model on cuda
>>> output = model(image) # output logit size is [1, 1000]
```
Using the pretrained models from our pip package, you can simply run validation:
```
python validate_pip_model.py --model mamba_vision_T --data_dir=$DATA_PATH --batch-size $BS
```
## FAQ
1. Does MambaVision support processing images with any input resolutions ?
Yes ! you can pass images with any arbitrary resolutions without the need to change the model.
2. Can I apply MambaVision for downstream tasks like detection, segmentation ?
Yes ! we are working to have it released very soon. But employing MambaVision backbones for these tasks is very similar to other models in `mmseg` or `mmdet` packages. In addition, MambaVision [Hugging Face](https://huggingface.co/collections/nvidia/mambavision-66943871a6b36c9e78b327d3) models provide feature extraction capablity which can be used for downstream tasks. Please see the above example.
3. I am interested in re-implementing MambaVision in my own repository. Can we use the pretrained weights ?
Yes ! the pretrained weights are released under [CC-BY-NC-SA-4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). Please submit an issue in this repo and we will add your repository to the README of our codebase and properly acknowledge your efforts.
## Results + Pretrained Models
### ImageNet-1K
**MambaVision ImageNet-1K Pretrained Models**
Name
Acc@1(%)
Acc@5(%)
Throughput(Img/Sec)
Resolution
#Params(M)
FLOPs(G)
Download
MambaVision-T
82.3
96.2
6298
224x224
31.8
4.4
model
MambaVision-T2
82.7
96.3
5990
224x224
35.1
5.1
model
MambaVision-S
83.3
96.5
4700
224x224
50.1
7.5
model
MambaVision-B
84.2
96.9
3670
224x224
97.7
15.0
model
MambaVision-L
85.0
97.1
2190
224x224
227.9
34.9
model
MambaVision-L2
85.3
97.2
1021
224x224
241.5
37.5
model
## Installation
We provide a [docker file](./Dockerfile). In addition, assuming that a recent [PyTorch](https://pytorch.org/get-started/locally/) package is installed, the dependencies can be installed by running:
```bash
pip install -r requirements.txt
```
## Evaluation
The MambaVision models can be evaluated on ImageNet-1K validation set using the following:
```
python validate.py \
--model
--checkpoint
--data_dir
--batch-size