{"id":25999838,"url":"https://github.com/NVlabs/MambaVision","last_synced_at":"2025-03-05T18:41:50.399Z","repository":{"id":247864654,"uuid":"813220336","full_name":"NVlabs/MambaVision","owner":"NVlabs","description":"Official PyTorch Implementation of MambaVision: A Hybrid Mamba-Transformer Vision Backbone","archived":false,"fork":false,"pushed_at":"2025-02-09T18:36:55.000Z","size":682,"stargazers_count":898,"open_issues_count":21,"forks_count":44,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-02-09T19:32:14.247Z","etag":null,"topics":["deep-learning","foundation-models","huggingface-transformers","hybrid-models","image-classification","mamba","self-attention","transformers","vision-transformer","visual-recognition"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2407.08083","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NVlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-10T17:46:08.000Z","updated_at":"2025-02-09T18:36:59.000Z","dependencies_parsed_at":"2024-12-18T19:26:17.451Z","dependency_job_id":"93ea6532-bb9e-43b5-b58d-1f79cb29ec34","html_url":"https://github.com/NVlabs/MambaVision","commit_stats":null,"previous_names":["nvlabs/mambavision"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVlabs%2FMambaVision","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVlabs%2FMambaVision/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVlabs%2FMambaVision/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVlabs%2FMambaVision/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NVlabs","download_url":"https://codeload.github.com/NVlabs/MambaVision/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242083058,"owners_count":20069232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","foundation-models","huggingface-transformers","hybrid-models","image-classification","mamba","self-attention","transformers","vision-transformer","visual-recognition"],"created_at":"2025-03-05T18:40:48.326Z","updated_at":"2025-03-05T18:41:50.391Z","avatar_url":"https://github.com/NVlabs.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# MambaVision: A Hybrid Mamba-Transformer Vision Backbone\n\nOfficial PyTorch implementation of [**MambaVision: A Hybrid Mamba-Transformer Vision Backbone**](https://arxiv.org/abs/2407.08083).\n\n\n[![Star on GitHub](https://img.shields.io/github/stars/NVlabs/MambaVision.svg?style=social)](https://github.com/NVlabs/MambaVision/stargazers)\n\n[Ali Hatamizadeh](https://research.nvidia.com/person/ali-hatamizadeh) and\n[Jan Kautz](https://jankautz.com/). \n\nFor business inquiries, please visit our website and submit the form: [NVIDIA Research Licensing](https://www.nvidia.com/en-us/research/inquiries/)\n\n--- \n\nMambaVision demonstrates a strong performance by achieving a new SOTA Pareto-front in\nterms of Top-1 accuracy and throughput. \n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/NVlabs/MambaVision/assets/26806394/79dcf841-3966-4b77-883d-76cd5e1d4320\" width=62% height=62% \nclass=\"center\"\u003e\n\u003c/p\u003e\n\nWe introduce a novel mixer block by creating a symmetric path without SSM to enhance the modeling of global context: \n\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/NVlabs/MambaVision/assets/26806394/295c0984-071e-4c84-b2c8-9059e2794182\" width=32% height=32% \nclass=\"center\"\u003e\n\u003c/p\u003e\n\n\n\nMambaVision has a hierarchical architecture that employs both self-attention and mixer blocks:\n\n![teaser](./mambavision/assets/arch.png)\n\n\n## 💥 News 💥\n- **[02.26.2025]** MambaVision has been accepted to CVPR 2025 ! \n\n- **[07.24.2024]** MambaVision [Hugging Face](https://huggingface.co/collections/nvidia/mambavision-66943871a6b36c9e78b327d3) models are released ! \n\n- **[07.14.2024]** We added support for processing any resolution images.\n\n- **[07.12.2024]** [Paper](https://arxiv.org/abs/2407.08083) is now available on arXiv !\n\n- **[07.11.2024]** [Mambavision pip package](https://pypi.org/project/mambavision/) is released !\n\n- **[07.10.2024]** We have released the code and model checkpoints for Mambavision !\n\n## Quick Start\n\n\n### Hugging Face (Classification + Feature extraction)\n\nPretrained 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: \n\n```bash\npip install mambavision\n```\n\nThe model can be simply imported:\n\n\n```python\n\u003e\u003e\u003e from transformers import AutoModelForImageClassification\n\n\u003e\u003e\u003e model = AutoModelForImageClassification.from_pretrained(\"nvidia/MambaVision-T-1K\", trust_remote_code=True)\n```\n\nWe demonstrate an end-to-end image classification example in the following.\n\nGiven the following image from [COCO dataset](https://cocodataset.org/#home)  val set as an input:\n\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://cdn-uploads.huggingface.co/production/uploads/64414b62603214724ebd2636/4duSnqLf4lrNiAHczSmAN.jpeg\" width=70% height=70% \nclass=\"center\"\u003e\n\u003c/p\u003e\n\n\nThe following snippet can be used:\n\n```python\nfrom transformers import AutoModelForImageClassification\nfrom PIL import Image\nfrom timm.data.transforms_factory import create_transform\nimport requests\n\nmodel = AutoModelForImageClassification.from_pretrained(\"nvidia/MambaVision-T-1K\", trust_remote_code=True)\n\n# eval mode for inference\nmodel.cuda().eval()\n\n# prepare image for the model\nurl = 'http://images.cocodataset.org/val2017/000000020247.jpg'\nimage = Image.open(requests.get(url, stream=True).raw)\ninput_resolution = (3, 224, 224)  # MambaVision supports any input resolutions\n\ntransform = create_transform(input_size=input_resolution,\n                             is_training=False,\n                             mean=model.config.mean,\n                             std=model.config.std,\n                             crop_mode=model.config.crop_mode,\n                             crop_pct=model.config.crop_pct)\n\ninputs = transform(image).unsqueeze(0).cuda()\n# model inference\noutputs = model(inputs)\nlogits = outputs['logits'] \npredicted_class_idx = logits.argmax(-1).item()\nprint(\"Predicted class:\", model.config.id2label[predicted_class_idx])\n```\n\nThe predicted label is brown bear, bruin, Ursus arctos.\n\n\nYou 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. \n\nThe following snippet can be used for feature extraction:\n\n```Python\nfrom transformers import AutoModel\nfrom PIL import Image\nfrom timm.data.transforms_factory import create_transform\nimport requests\n\nmodel = AutoModel.from_pretrained(\"nvidia/MambaVision-T-1K\", trust_remote_code=True)\n\n# eval mode for inference\nmodel.cuda().eval()\n\n# prepare image for the model\nurl = 'http://images.cocodataset.org/val2017/000000020247.jpg'\nimage = Image.open(requests.get(url, stream=True).raw)\ninput_resolution = (3, 224, 224)  # MambaVision supports any input resolutions\n\ntransform = create_transform(input_size=input_resolution,\n                             is_training=False,\n                             mean=model.config.mean,\n                             std=model.config.std,\n                             crop_mode=model.config.crop_mode,\n                             crop_pct=model.config.crop_pct)\ninputs = transform(image).unsqueeze(0).cuda()\n# model inference\nout_avg_pool, features = model(inputs)\nprint(\"Size of the averaged pool features:\", out_avg_pool.size())  # torch.Size([1, 640])\nprint(\"Number of stages in extracted features:\", len(features)) # 4 stages\nprint(\"Size of extracted features in stage 1:\", features[0].size()) # torch.Size([1, 80, 56, 56])\nprint(\"Size of extracted features in stage 4:\", features[3].size()) # torch.Size([1, 640, 7, 7])\n```\n\nCurrently, 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).\n\n### Classification (pip package)\n\nWe can also import pre-trained MambaVision models from the pip package with **a few lines of code**:\n\n```bash\npip install mambavision\n```\n\nA pretrained MambaVision model with default hyper-parameters can be created as in:\n\n```python\n\u003e\u003e\u003e from mambavision import create_model\n\n# Define mamba_vision_T model\n\n\u003e\u003e\u003e model = create_model('mamba_vision_T', pretrained=True, model_path=\"/tmp/mambavision_tiny_1k.pth.tar\")\n```\n\nAvailable list of pretrained models include `mamba_vision_T`, `mamba_vision_T2`, `mamba_vision_S`, `mamba_vision_B`, `mamba_vision_L` and `mamba_vision_L2`.  \n\nWe can also simply test the model by passing a dummy image with **any resolution**. The output is the logits:\n\n```python\n\u003e\u003e\u003e import torch\n\n\u003e\u003e\u003e image = torch.rand(1, 3, 512, 224).cuda() # place image on cuda\n\u003e\u003e\u003e model = model.cuda() # place model on cuda\n\u003e\u003e\u003e output = model(image) # output logit size is [1, 1000]\n```\n\nUsing the pretrained models from our pip package, you can simply run validation:\n\n```\npython validate_pip_model.py --model mamba_vision_T --data_dir=$DATA_PATH --batch-size $BS \n``` \n\n## FAQ\n\n1. Does MambaVision support processing images with any input resolutions ? \n\nYes ! you can pass images with any arbitrary resolutions without the need to change the model.\n\n\n2. Can I apply MambaVision for downstream tasks like detection, segmentation ? \n\nYes ! 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. \n\n\n3. I am interested in re-implementing MambaVision in my own repository. Can we use the pretrained weights ? \n\nYes ! 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. \n\n## Results + Pretrained Models\n\n### ImageNet-1K\n**MambaVision ImageNet-1K Pretrained Models**\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eName\u003c/th\u003e\n    \u003cth\u003eAcc@1(%)\u003c/th\u003e\n    \u003cth\u003eAcc@5(%)\u003c/th\u003e\n    \u003cth\u003eThroughput(Img/Sec)\u003c/th\u003e\n    \u003cth\u003eResolution\u003c/th\u003e\n    \u003cth\u003e#Params(M)\u003c/th\u003e\n    \u003cth\u003eFLOPs(G)\u003c/th\u003e\n    \u003cth\u003eDownload\u003c/th\u003e\n  \u003c/tr\u003e\n\n\u003ctr\u003e\n    \u003ctd\u003eMambaVision-T\u003c/td\u003e\n    \u003ctd\u003e82.3\u003c/td\u003e\n    \u003ctd\u003e96.2\u003c/td\u003e\n    \u003ctd\u003e6298\u003c/td\u003e\n    \u003ctd\u003e224x224\u003c/td\u003e\n    \u003ctd\u003e31.8\u003c/td\u003e\n    \u003ctd\u003e4.4\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://huggingface.co/nvidia/MambaVision-T-1K/resolve/main/mambavision_tiny_1k.pth.tar\"\u003emodel\u003c/a\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n    \u003ctd\u003eMambaVision-T2\u003c/td\u003e\n    \u003ctd\u003e82.7\u003c/td\u003e\n    \u003ctd\u003e96.3\u003c/td\u003e\n    \u003ctd\u003e5990\u003c/td\u003e\n    \u003ctd\u003e224x224\u003c/td\u003e\n    \u003ctd\u003e35.1\u003c/td\u003e\n    \u003ctd\u003e5.1\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://huggingface.co/nvidia/MambaVision-T2-1K/resolve/main/mambavision_tiny2_1k.pth.tar\"\u003emodel\u003c/a\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n    \u003ctd\u003eMambaVision-S\u003c/td\u003e\n    \u003ctd\u003e83.3\u003c/td\u003e\n    \u003ctd\u003e96.5\u003c/td\u003e\n    \u003ctd\u003e4700\u003c/td\u003e\n    \u003ctd\u003e224x224\u003c/td\u003e\n    \u003ctd\u003e50.1\u003c/td\u003e\n    \u003ctd\u003e7.5\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://huggingface.co/nvidia/MambaVision-S-1K/resolve/main/mambavision_small_1k.pth.tar\"\u003emodel\u003c/a\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n    \u003ctd\u003eMambaVision-B\u003c/td\u003e\n    \u003ctd\u003e84.2\u003c/td\u003e\n    \u003ctd\u003e96.9\u003c/td\u003e\n    \u003ctd\u003e3670\u003c/td\u003e\n    \u003ctd\u003e224x224\u003c/td\u003e\n    \u003ctd\u003e97.7\u003c/td\u003e\n    \u003ctd\u003e15.0\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://huggingface.co/nvidia/MambaVision-B-1K/resolve/main/mambavision_base_1k.pth.tar\"\u003emodel\u003c/a\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n    \u003ctd\u003eMambaVision-L\u003c/td\u003e\n    \u003ctd\u003e85.0\u003c/td\u003e\n    \u003ctd\u003e97.1\u003c/td\u003e\n    \u003ctd\u003e2190\u003c/td\u003e\n    \u003ctd\u003e224x224\u003c/td\u003e\n    \u003ctd\u003e227.9\u003c/td\u003e\n    \u003ctd\u003e34.9\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://huggingface.co/nvidia/MambaVision-L-1K/resolve/main/mambavision_large_1k.pth.tar\"\u003emodel\u003c/a\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n    \u003ctd\u003eMambaVision-L2\u003c/td\u003e\n    \u003ctd\u003e85.3\u003c/td\u003e\n    \u003ctd\u003e97.2\u003c/td\u003e\n    \u003ctd\u003e1021\u003c/td\u003e\n    \u003ctd\u003e224x224\u003c/td\u003e\n    \u003ctd\u003e241.5\u003c/td\u003e\n    \u003ctd\u003e37.5\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://huggingface.co/nvidia/MambaVision-L2-1K/resolve/main/mambavision_large2_1k.pth.tar\"\u003emodel\u003c/a\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003c/table\u003e\n\n## Installation\n\nWe 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:\n\n```bash\npip install -r requirements.txt\n```\n\n## Evaluation\n\nThe MambaVision models can be evaluated on ImageNet-1K validation set using the following: \n\n```\npython validate.py \\\n--model \u003cmodel-name\u003e\n--checkpoint \u003ccheckpoint-path\u003e\n--data_dir \u003cimagenet-path\u003e\n--batch-size \u003cbatch-size-per-gpu\n``` \n\nHere `--model` is the MambaVision variant (e.g. `mambavision_tiny_1k`), `--checkpoint` is the path to pretrained model weights, `--data_dir` is the path to ImageNet-1K validation set and `--batch-size` is the number of batch size. We also provide a sample script [here](./mambavision/validate.sh). \n\n## Citation\n\nIf you find MambaVision to be useful for your work, please consider citing our paper: \n\n```\n@article{hatamizadeh2024mambavision,\n  title={MambaVision: A Hybrid Mamba-Transformer Vision Backbone},\n  author={Hatamizadeh, Ali and Kautz, Jan},\n  journal={arXiv preprint arXiv:2407.08083},\n  year={2024}\n}\n```\n\n## Star History\n\n[![Stargazers repo roster for @NVlabs/MambaVision](https://bytecrank.com/nastyox/reporoster/php/stargazersSVG.php?user=NVlabs\u0026repo=MambaVision)](https://github.com/NVlabs/MambaVision/stargazers)\n\n\n[![Star History Chart](https://api.star-history.com/svg?repos=NVlabs/MambaVision\u0026type=Date)](https://star-history.com/#NVlabs/MambaVision\u0026Date)\n\n\n## Licenses\n\nCopyright © 2024, NVIDIA Corporation. All rights reserved.\n\nThis work is made available under the NVIDIA Source Code License-NC. Click [here](LICENSE) to view a copy of this license.\n\nThe pre-trained models are shared under [CC-BY-NC-SA-4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.\n\nFor license information regarding the timm repository, please refer to its [repository](https://github.com/rwightman/pytorch-image-models).\n\nFor license information regarding the ImageNet dataset, please see the [ImageNet official website](https://www.image-net.org/). \n\n## Acknowledgement\nThis repository is built on top of the [timm](https://github.com/huggingface/pytorch-image-models) repository. We thank [Ross Wrightman](https://rwightman.com/) for creating and maintaining this high-quality library.  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNVlabs%2FMambaVision","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNVlabs%2FMambaVision","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNVlabs%2FMambaVision/lists"}